ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

move versionadded tags to the top, replace some missed TBD with version info

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-06-08 13:11:19 -04:00
parent 3f6032e80d
commit b093f1aac1
3 changed files with 125 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
src/library.cpp
View File

@ -247,6 +247,8 @@ void *lammps_open_no_mpi(int argc, char **argv, void **ptr)
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
This function is a version of :cpp:func:`lammps_open`, that uses an
integer for the MPI communicator as the MPI Fortran interface does. It
is used in the :f:func:`lammps` constructor of the LAMMPS Fortran
@ -257,8 +259,6 @@ communicator with ``MPI_Comm_f2c()`` and then calls
If for some reason the creation or initialization of the LAMMPS instance
fails a null pointer is returned.
.. versionadded:: 18Sep2020
*See also*
:cpp:func:`lammps_open_fortran`, :cpp:func:`lammps_open_no_mpi`
@ -304,13 +304,13 @@ void lammps_close(void *handle)
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
The MPI standard requires that any MPI application must call
``MPI_Init()`` exactly once before performing any other MPI function
calls. This function checks, whether MPI is already initialized and
calls ``MPI_Init()`` in case it is not.
.. versionadded:: 18Sep2020
\endverbatim */
void lammps_mpi_init()
@ -333,6 +333,8 @@ void lammps_mpi_init()
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
The MPI standard requires that any MPI application calls
``MPI_Finalize()`` before exiting. Even if a calling program does not
do any MPI calls, MPI is still initialized internally to avoid errors
@ -341,8 +343,6 @@ before exiting the program to wait until all (parallel) tasks are
completed and then MPI is cleanly shut down. After calling this
function no more MPI calls may be made.
.. versionadded:: 18Sep2020
*See also*
:cpp:func:`lammps_kokkos_finalize`, :cpp:func:`lammps_python_finalize`
\endverbatim */
@ -366,6 +366,8 @@ void lammps_mpi_finalize()
*
\verbatim embed:rst
.. versionadded:: 2Jul2021
The Kokkos library may only be initialized once during the execution of
a process. This is done automatically the first time Kokkos
functionality is used. This requires that the Kokkos environment
@ -373,8 +375,6 @@ must be explicitly shut down after any LAMMPS instance using it is
closed (to release associated resources).
After calling this function no Kokkos functionality may be used.
.. versionadded:: 2Jul2021
*See also*
:cpp:func:`lammps_mpi_finalize`, :cpp:func:`lammps_python_finalize`
\endverbatim */
@ -390,6 +390,8 @@ void lammps_kokkos_finalize()
*
\verbatim embed:rst
.. versionadded:: 20Sep2021
This function resets and clears an embedded Python environment
by calling the `Py_Finalize() function
<https://docs.python.org/3/c-api/init.html#c.Py_FinalizeEx>`_
@ -409,8 +411,6 @@ after calling Py_Finalize().
This function can be called to explicitly clear the Python
environment in case it is safe to do so.
.. versionadded:: 20Sep2021
*See also*
:cpp:func:`lammps_mpi_finalize`, :cpp:func:`lammps_kokkos_finalize`
\endverbatim */
@ -427,6 +427,8 @@ void lammps_python_finalize()
*
\verbatim embed:rst
.. versionadded:: 3Nov2022
This function is a wrapper around functions in the ``Error`` to print an
error message and then stop LAMMPS.
@ -435,8 +437,6 @@ of constants from :cpp:enum:`_LMP_ERROR_CONST`. If the value does not
match any valid combination of constants a warning is printed and the
function returns.
.. versionadded:: 3Nov2022
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance
@ -979,6 +979,8 @@ void lammps_reset_box(void *handle, double *boxlo, double *boxhi,
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
This function will retrieve memory usage information for the current
LAMMPS instance or process. The *meminfo* buffer will be filled with
3 different numbers (if supported by the operating system). The first
@ -991,8 +993,6 @@ third number is the maximum amount of RAM (not swap) used by the process
so far. If any of the two latter parameters is not supported by the operating
system it will be set to zero.
.. versionadded:: 18Sep2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance
@ -1012,6 +1012,8 @@ void lammps_memory_usage(void *handle, double *meminfo)
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
This will take the LAMMPS "world" communicator and convert it to an
integer using ``MPI_Comm_c2f()``, so it is equivalent to the
corresponding MPI communicator in Fortran. This way it can be safely
@ -1020,8 +1022,6 @@ to the C language representation use ``MPI_Comm_f2c()``.
If LAMMPS was compiled with MPI_STUBS, this function returns -1.
.. versionadded:: 18Sep2020
*See also*
:cpp:func:`lammps_open_fortran`
@ -1284,13 +1284,13 @@ int lammps_extract_setting(void *handle, const char *keyword)
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
This function returns an integer that encodes the data type of the global
property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
values. Callers of :cpp:func:`lammps_extract_global` can use this information
to then decide how to cast the ``void *`` pointer and access the data.
.. versionadded:: 18Sep2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance (unused)
@ -1773,13 +1773,13 @@ void *lammps_extract_global(void *handle, const char *name)
*
\verbatim embed:rst
.. versionadded:: 18Sep2020
This function returns an integer that encodes the data type of the per-atom
property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
values. Callers of :cpp:func:`lammps_extract_atom` can use this information
to then decide how to cast the ``void *`` pointer and access the data.
.. versionadded:: 18Sep2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance
@ -2308,13 +2308,13 @@ void *lammps_extract_variable(void *handle, const char *name, const char *group)
*
\verbatim embed:rst
.. versionadded:: 3Nov2022
This function returns an integer that encodes the data type of the variable
with the specified name. See :cpp:enum:`_LMP_VAR_CONST` for valid values.
Callers of :cpp:func:`lammps_extract_variable` can use this information to
decide how to cast the ``void *`` pointer and access the data.
.. versionadded:: 3Nov2022
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance
@ -3166,6 +3166,8 @@ void lammps_scatter_atoms_subset(void *handle, const char *name, int type,
*
\verbatim embed:rst
.. versionadded:: 28Jul2021
This function copies the list of all bonds into a buffer provided by
the calling code. The buffer will be filled with bond type, bond atom 1,
bond atom 2 for each bond. Thus the buffer has to be allocated to the
@ -3180,8 +3182,6 @@ When running in parallel, the data buffer must be allocated on **all**
MPI ranks and will be filled with the information for **all** bonds
in the system.
.. versionadded:: 28Jul2021
Below is a brief C code demonstrating accessing this collected bond information.
.. code-block:: c
@ -3277,6 +3277,8 @@ void lammps_gather_bonds(void *handle, void *data)
*
\verbatim embed:rst
.. versionadded:: 8Feb2023
This function copies the list of all angles into a buffer provided by
the calling code. The buffer will be filled with angle type, angle atom 1,
angle atom 2, angle atom 3 for each angle. Thus the buffer has to be allocated to the
@ -3291,8 +3293,6 @@ When running in parallel, the data buffer must be allocated on **all**
MPI ranks and will be filled with the information for **all** angles
in the system.
.. versionadded:: 8Feb2023
Below is a brief C code demonstrating accessing this collected angle information.
.. code-block:: c
@ -3388,6 +3388,8 @@ void lammps_gather_angles(void *handle, void *data)
*
\verbatim embed:rst
.. versionadded:: 8Feb2023
This function copies the list of all dihedrals into a buffer provided by
the calling code. The buffer will be filled with dihedral type, dihedral atom 1,
dihedral atom 2, dihedral atom 3, dihedral atom 4 for each dihedral.
@ -3403,8 +3405,6 @@ When running in parallel, the data buffer must be allocated on **all**
MPI ranks and will be filled with the information for **all** dihedrals
in the system.
.. versionadded:: 8Feb2023
Below is a brief C code demonstrating accessing this collected dihedral information.
.. code-block:: c
@ -3500,6 +3500,8 @@ void lammps_gather_dihedrals(void *handle, void *data)
*
\verbatim embed:rst
.. versionadded:: 8Feb2023
This function copies the list of all impropers into a buffer provided by
the calling code. The buffer will be filled with improper type, improper atom 1,
improper atom 2, improper atom 3, improper atom 4 for each improper.
@ -3515,8 +3517,6 @@ When running in parallel, the data buffer must be allocated on **all**
MPI ranks and will be filled with the information for **all** impropers
in the system.
.. versionadded:: 8Feb2023
Below is a brief C code demonstrating accessing this collected improper information.
.. code-block:: c
@ -5310,6 +5310,8 @@ int lammps_version(void *handle)
*
\verbatim embed:rst
.. versionadded:: 9Oct2020
The :cpp:func:`lammps_get_os_info` function can be used to retrieve
detailed information about the hosting operating system and
compiler/runtime.
@ -5318,8 +5320,6 @@ A suitable buffer for a C-style string has to be provided and its length.
The assembled text will be truncated to not overflow this buffer. The
string is typically a few hundred bytes long.
.. versionadded:: 9Oct2020
\endverbatim
*
* \param buffer string buffer to copy the information to
@ -5548,6 +5548,8 @@ int lammps_config_accelerator(const char *package,
*
\verbatim embed:rst
.. versionadded:: 14May2021
The :cpp:func:`lammps_has_gpu_device` function checks at runtime if
an accelerator device is present that can be used with the
:doc:`GPU package <Speed_gpu>`. If at least one suitable device is
@ -5557,8 +5559,6 @@ More detailed information about the available device or devices can
be obtained by calling the
:cpp:func:`lammps_get_gpu_device_info` function.
.. versionadded:: 14May2021
\endverbatim
*
* \return 1 if viable device is available, 0 if not. */
@ -5572,6 +5572,8 @@ int lammps_has_gpu_device()
*
\verbatim embed:rst
.. versionadded:: 14May2021
The :cpp:func:`lammps_get_gpu_device_info` function can be used to retrieve
detailed information about any accelerator devices that are viable for use
with the :doc:`GPU package <Speed_gpu>`. It will produce a string that is
@ -5583,8 +5585,6 @@ A suitable buffer for a C-style string has to be provided and its length.
The assembled text will be truncated to not overflow this buffer. This
string can be several kilobytes long, if multiple devices are present.
.. versionadded:: 14May2021
\endverbatim
*
* \param buffer string buffer to copy the information to
@ -5681,12 +5681,13 @@ int lammps_style_name(void *handle, const char *category, int idx,
/** Check if a specific ID exists in the current LAMMPS instance
*
\verbatim embed:rst
.. versionadded:: 9Oct2020
This function checks if the current LAMMPS instance a *category* ID of
the given *name* exists. Valid categories are: *compute*\ , *dump*\ ,
*fix*\ , *group*\ , *molecule*\ , *region*\ , and *variable*\ .
.. versionadded:: 9Oct2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -5720,13 +5721,14 @@ int lammps_has_id(void *handle, const char *category, const char *name) {
/** Count the number of IDs of a category.
*
\verbatim embed:rst
.. versionadded:: 9Oct2020
This function counts how many IDs in the provided *category*
are defined in the current LAMMPS instance.
Please see :cpp:func:`lammps_has_id` for a list of valid
categories.
.. versionadded:: 9Oct2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -5758,6 +5760,9 @@ int lammps_id_count(void *handle, const char *category) {
/** Look up the name of an ID by index in the list of IDs of a given category.
*
\verbatim embed:rst
.. versionadded:: 9Oct2020
This function copies the name of the *category* ID with the index
*idx* into the provided C-style string buffer. The length of the buffer
must be provided as *buf_size* argument. If the name of the style
@ -5765,8 +5770,6 @@ exceeds the length of the buffer, it will be truncated accordingly.
If the index is out of range, the function returns 0 and *buffer* is
set to an empty string, otherwise 1.
.. versionadded:: 9Oct2020
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -5829,10 +5832,11 @@ int lammps_id_name(void *handle, const char *category, int idx, char *buffer, in
/** Count the number of loaded plugins
*
\verbatim embed:rst
This function counts how many plugins are currently loaded.
.. versionadded:: 10Mar2021
This function counts how many plugins are currently loaded.
\endverbatim
*
* \return number of loaded plugins
@ -5851,6 +5855,9 @@ int lammps_plugin_count()
/** Look up the info of a loaded plugin by its index in the list of plugins
*
\verbatim embed:rst
.. versionadded:: 10Mar2021
This function copies the name of the *style* plugin with the index
*idx* into the provided C-style string buffer. The length of the buffer
must be provided as *buf_size* argument. If the name of the style
@ -5858,8 +5865,6 @@ exceeds the length of the buffer, it will be truncated accordingly.
If the index is out of range, the function returns 0 and *buffer* is
set to an empty string, otherwise 1.
.. versionadded:: 10Mar2021
\endverbatim
*
* \param idx index of the plugin in the list all or *style* plugins
@ -6018,9 +6023,11 @@ void lammps_set_fix_external_callback(void *handle, const char *id, FixExternalF
\verbatim embed:rst
Fix :doc:`external <fix_external>` allows programs that are running LAMMPS through
its library interface to add or modify certain LAMMPS properties on specific
timesteps, similar to the way other fixes do.
.. versionadded:: 28Jul2021
Fix :doc:`external <fix_external>` allows programs that are running
LAMMPS through its library interface to add or modify certain LAMMPS
properties on specific timesteps, similar to the way other fixes do.
This function provides access to the per-atom force storage in a fix
external instance with the given fix-ID to be added to the individual
@ -6033,12 +6040,12 @@ 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, for example, :cpp:func:`lammps_extract_setting` to obtain the
number of local atoms `nlocal` and then assume the dimensions of the returned
force array as ``double force[nlocal][3]``.
You can use, for example, :cpp:func:`lammps_extract_setting` to obtain
the 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
:cpp:func:`lammps_set_fix_external_callback`. The main difference is
This is an alternative to the callback mechanism in fix external set up
by :cpp:func:`lammps_set_fix_external_callback`. The main difference is
that this mechanism can be used when forces are be pre-computed and the
control alternates between LAMMPS and the external code, while the
callback mechanism can call the external code to compute the force when
@ -6048,8 +6055,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6080,6 +6085,8 @@ double **lammps_fix_external_get_force(void *handle, const char *id)
\verbatim embed:rst
.. versionadded:: 28Jul2021
This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and
:cpp:func:`lammps_fix_external_get_force` to also set the contribution
to the global energy from the external code. The value of the *eng*
@ -6096,8 +6103,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6126,6 +6131,8 @@ void lammps_fix_external_set_energy_global(void *handle, const char *id, double
\verbatim embed:rst
.. versionadded:: 28Jul2021
This is a companion function to :cpp:func:`lammps_set_fix_external_callback`
and :cpp:func:`lammps_fix_external_get_force` to set the contribution to
the global virial from the external code.
@ -6144,8 +6151,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6174,6 +6179,8 @@ void lammps_fix_external_set_virial_global(void *handle, const char *id, double
\verbatim embed:rst
.. versionadded:: 28Jul2021
This is a companion function to :cpp:func:`lammps_set_fix_external_callback`
to set the per-atom energy contribution due to the fix from the external code
as part of the callback function. For this to work, the handle to the
@ -6192,8 +6199,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6222,6 +6227,8 @@ void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double
\verbatim embed:rst
.. versionadded:: 28Jul2021
This is a companion function to :cpp:func:`lammps_set_fix_external_callback`
to set the per-atom virial contribution due to the fix from the external code
as part of the callback function. For this to work, the handle to the
@ -6243,8 +6250,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6273,6 +6278,8 @@ void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double
\verbatim embed:rst
.. versionadded:: 28Jul2021
This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and
:cpp:func:`lammps_fix_external_get_force` to set the length of a global vector of
properties that will be stored with the fix via
@ -6287,8 +6294,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6317,6 +6322,8 @@ void lammps_fix_external_set_vector_length(void *handle, const char *id, int len
\verbatim embed:rst
.. versionadded:: 28Jul2021
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
@ -6340,8 +6347,6 @@ Please see the documentation for :doc:`fix external <fix_external>` for
more information about how to use the fix and how to couple it with an
external code.
.. versionadded:: 28Jul2021
\endverbatim
*
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
@ -6513,12 +6518,13 @@ int lammps_get_last_error_message(void *handle, char *buffer, int buf_size) {
/** Return API version of embedded Python interpreter
\verbatim embed:rst
.. versionadded:: 3Nov2022
This function is used by the ML-IAP python code (mliappy) to verify
the API version of the embedded python interpreter of the PYTHON
package. It returns -1 if the PYTHON package is not enabled.
.. versionadded:: 3Nov2022
\endverbatim
*
* \return PYTHON_API_VERSION constant of the python interpreter or -1 */