diff --git a/python/lammps/core.py b/python/lammps/core.py index 932d4b863c..b15ddf9302 100644 --- a/python/lammps/core.py +++ b/python/lammps/core.py @@ -506,9 +506,9 @@ class lammps(object): def error(self, error_type, error_text): """Forward error to the LAMMPS Error class. - This is a wrapper around the :cpp:func:`lammps_error` function of the C-library interface. + .. versionadded:: 3Nov2022 - .. versionadded:: TBD + This is a wrapper around the :cpp:func:`lammps_error` function of the C-library interface. :param error_type: :type error_type: int @@ -1343,6 +1343,8 @@ class lammps(object): def gather_bonds(self): """Retrieve global list of bonds + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_gather_bonds` function of the C-library interface. @@ -1350,8 +1352,6 @@ class lammps(object): flat list of ctypes integer values with the bond type, bond atom1, bond atom2 for each bond. - .. versionadded:: 28Jul2021 - :return: a tuple with the number of bonds and a list of c_int or c_long :rtype: (int, 3*nbonds*c_tagint) """ @@ -1366,6 +1366,8 @@ class lammps(object): def gather_angles(self): """Retrieve global list of angles + .. versionadded:: 8Feb2023 + This is a wrapper around the :cpp:func:`lammps_gather_angles` function of the C-library interface. @@ -1373,8 +1375,6 @@ class lammps(object): flat list of ctypes integer values with the angle type, angle atom1, angle atom2, angle atom3 for each angle. - .. versionadded:: TBD - :return: a tuple with the number of angles and a list of c_int or c_long :rtype: (int, 4*nangles*c_tagint) """ @@ -1389,6 +1389,8 @@ class lammps(object): def gather_dihedrals(self): """Retrieve global list of dihedrals + .. versionadded:: 8Feb2023 + This is a wrapper around the :cpp:func:`lammps_gather_dihedrals` function of the C-library interface. @@ -1396,8 +1398,6 @@ class lammps(object): flat list of ctypes integer values with the dihedral type, dihedral atom1, dihedral atom2, dihedral atom3, dihedral atom4 for each dihedral. - .. versionadded:: TBD - :return: a tuple with the number of dihedrals and a list of c_int or c_long :rtype: (int, 5*ndihedrals*c_tagint) """ @@ -1412,6 +1412,8 @@ class lammps(object): def gather_impropers(self): """Retrieve global list of impropers + .. versionadded:: 8Feb2023 + This is a wrapper around the :cpp:func:`lammps_gather_impropers` function of the C-library interface. @@ -1419,8 +1421,6 @@ class lammps(object): flat list of ctypes integer values with the improper type, improper atom1, improper atom2, improper atom3, improper atom4 for each improper. - .. versionadded:: TBD - :return: a tuple with the number of impropers and a list of c_int or c_long :rtype: (int, 5*nimpropers*c_tagint) """ @@ -1659,13 +1659,13 @@ class lammps(object): def is_running(self): """ Report whether being called from a function during a run or a minimization + .. versionadded:: 9Oct2020 + Various LAMMPS commands must not be called during an ongoing run or minimization. This property allows to check for that. This is a wrapper around the :cpp:func:`lammps_is_running` function of the library interface. - .. versionadded:: 9Oct2020 - :return: True when called during a run otherwise false :rtype: bool """ @@ -1676,12 +1676,13 @@ class lammps(object): def force_timeout(self): """ Trigger an immediate timeout, i.e. a "soft stop" of a run. + .. versionadded:: 9Oct2020 + This function allows to cleanly stop an ongoing run or minimization at the next loop iteration. This is a wrapper around the :cpp:func:`lammps_force_timeout` function of the library interface. - .. versionadded:: 9Oct2020 """ self.lib.lammps_force_timeout(self.lmp) @@ -1764,11 +1765,11 @@ class lammps(object): def has_package(self, name): """ Report if the named package has been enabled in the LAMMPS shared library. + .. versionadded:: 3Nov2022 + This is a wrapper around the :cpp:func:`lammps_config_has_package` function of the library interface. - .. versionadded:: TBD - :param name: name of the package :type name: string @@ -1908,11 +1909,11 @@ class lammps(object): def has_id(self, category, name): """Returns whether a given ID name is available in a given category + .. versionadded:: 9Oct2020 + This is a wrapper around the function :cpp:func:`lammps_has_id` of the library interface. - .. versionadded:: 9Oct2020 - :param category: name of category :type category: string :param name: name of the ID @@ -1928,11 +1929,11 @@ class lammps(object): def available_ids(self, category): """Returns a list of IDs available for a given category + .. versionadded:: 9Oct2020 + This is a wrapper around the functions :cpp:func:`lammps_id_count()` and :cpp:func:`lammps_id_name()` of the library interface. - .. versionadded:: 9Oct2020 - :param category: name of category :type category: string @@ -1955,11 +1956,11 @@ class lammps(object): def available_plugins(self, category): """Returns a list of plugins available for a given category + .. versionadded:: 10Mar2021 + This is a wrapper around the functions :cpp:func:`lammps_plugin_count()` and :cpp:func:`lammps_plugin_name()` of the library interface. - .. versionadded:: 10Mar2021 - :return: list of style/name pairs of loaded plugins :rtype: list """ @@ -2024,11 +2025,11 @@ class lammps(object): def fix_external_get_force(self, fix_id): """Get access to the array with per-atom forces of a fix external instance with a given fix ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_get_force` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :return: requested data @@ -2043,11 +2044,11 @@ class lammps(object): def fix_external_set_energy_global(self, fix_id, eng): """Set the global energy contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_energy_global` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param eng: potential energy value to be added by fix external @@ -2062,11 +2063,11 @@ class lammps(object): def fix_external_set_virial_global(self, fix_id, virial): """Set the global virial contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_virial_global` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param eng: list of 6 floating point numbers with the virial to be added by fix external @@ -2082,11 +2083,11 @@ class lammps(object): def fix_external_set_energy_peratom(self, fix_id, eatom): """Set the per-atom energy contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_energy_peratom` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param eatom: list of potential energy values for local atoms to be added by fix external @@ -2105,11 +2106,11 @@ class lammps(object): def fix_external_set_virial_peratom(self, fix_id, vatom): """Set the per-atom virial contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_virial_peratom` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param vatom: list of natoms lists with 6 floating point numbers to be added by fix external @@ -2137,11 +2138,11 @@ class lammps(object): def fix_external_set_vector_length(self, fix_id, length): """Set the vector length for a global vector stored with fix external for analysis + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_vector_length` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param length: length of the global vector @@ -2155,11 +2156,11 @@ class lammps(object): def fix_external_set_vector(self, fix_id, idx, val): """Store a global vector value for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This is a wrapper around the :cpp:func:`lammps_fix_external_set_vector` function of the C-library interface. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param idx: 1-based index of the value in the global vector diff --git a/python/lammps/numpy_wrapper.py b/python/lammps/numpy_wrapper.py index 8286fb9a5c..f3ea0fdf8e 100644 --- a/python/lammps/numpy_wrapper.py +++ b/python/lammps/numpy_wrapper.py @@ -262,12 +262,12 @@ class numpy_wrapper: def gather_bonds(self): """Retrieve global list of bonds as NumPy array + .. versionadded:: 28Jul2021 + This is a wrapper around :py:meth:`lammps.gather_bonds() ` It behaves the same as the original method, but returns a NumPy array instead of a ``ctypes`` list. - .. versionadded:: 28Jul2021 - :return: the requested data as a 2d-integer numpy array :rtype: numpy.array(nbonds,3) """ @@ -280,12 +280,12 @@ class numpy_wrapper: def gather_angles(self): """ Retrieve global list of angles as NumPy array + .. versionadded:: 8Feb2023 + This is a wrapper around :py:meth:`lammps.gather_angles() ` It behaves the same as the original method, but returns a NumPy array instead of a ``ctypes`` list. - .. versionadded:: TBD - :return: the requested data as a 2d-integer numpy array :rtype: numpy.array(nangles,4) """ @@ -298,12 +298,12 @@ class numpy_wrapper: def gather_dihedrals(self): """ Retrieve global list of dihedrals as NumPy array + .. versionadded:: 8Feb2023 + This is a wrapper around :py:meth:`lammps.gather_dihedrals() ` It behaves the same as the original method, but returns a NumPy array instead of a ``ctypes`` list. - .. versionadded:: TBD - :return: the requested data as a 2d-integer numpy array :rtype: numpy.array(ndihedrals,5) """ @@ -316,12 +316,12 @@ class numpy_wrapper: def gather_impropers(self): """ Retrieve global list of impropers as NumPy array + .. versionadded:: 8Feb2023 + This is a wrapper around :py:meth:`lammps.gather_impropers() ` It behaves the same as the original method, but returns a NumPy array instead of a ``ctypes`` list. - .. versionadded:: TBD - :return: the requested data as a 2d-integer numpy array :rtype: numpy.array(nimpropers,5) """ @@ -334,13 +334,13 @@ class numpy_wrapper: def fix_external_get_force(self, fix_id): """Get access to the array with per-atom forces of a fix external instance with a given fix ID. + .. versionchanged:: 28Jul2021 + This function is a wrapper around the :py:meth:`lammps.fix_external_get_force() ` method. It behaves the same as the original method, but returns a NumPy array instead of a ``ctypes`` pointer. - .. versionchanged:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :return: requested data @@ -356,13 +356,13 @@ class numpy_wrapper: def fix_external_set_energy_peratom(self, fix_id, eatom): """Set the per-atom energy contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This function is an alternative to :py:meth:`lammps.fix_external_set_energy_peratom() ` method. It behaves the same as the original method, but accepts a NumPy array instead of a list as argument. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param eatom: per-atom potential energy @@ -383,13 +383,13 @@ class numpy_wrapper: def fix_external_set_virial_peratom(self, fix_id, vatom): """Set the per-atom virial contribution for a fix external instance with the given ID. + .. versionadded:: 28Jul2021 + This function is an alternative to :py:meth:`lammps.fix_external_set_virial_peratom() ` method. It behaves the same as the original method, but accepts a NumPy array instead of a list as argument. - .. versionadded:: 28Jul2021 - :param fix_id: Fix-ID of a fix external instance :type: string :param eatom: per-atom potential energy diff --git a/src/library.cpp b/src/library.cpp index cf5d131ba6..24a8afa7c7 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -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 `_ @@ -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 `. 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 `. 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 */