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

update documentation for writing plugins

Browse Source
This commit is contained in:
Axel Kohlmeyer
2025-06-11 03:40:33 -04:00
parent 30cc2570ad
commit 0fd7a40d92
2 changed files with 30 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
doc/src/Developer_plugins.rst
View File

@ -68,24 +68,25 @@ Members of ``lammpsplugin_t``
* - author * - author
- String with the name and email of the author - String with the name and email of the author
* - creator.v1 * - creator.v1
- Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, or command styles - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, command, or minimize styles
* - creator.v2 * - creator.v2
- Pointer to factory function for compute, fix, or region styles - Pointer to factory function for compute, fix, region, or run styles
* - handle * - handle
- Pointer to the open DSO file handle - Pointer to the open DSO file handle
Only one of the two alternate creator entries can be used at a time and Only one of the two alternate creator entries can be used at a time and
which of those is determined by the style of plugin. The "creator.v1" which of those is determined by the style of plugin. The "creator.v1"
element is for factory functions of supported styles computing forces element is for factory functions of supported styles computing forces
(i.e. pair, bond, angle, dihedral, or improper styles) or command styles (i.e. pair, bond, angle, dihedral, or improper styles), command styles,
and the function takes as single argument the pointer to the LAMMPS or minimize styles and the function takes as single argument the pointer
instance. The factory function is cast to the ``lammpsplugin_factory1`` to the LAMMPS instance. The factory function is cast to the
type before assignment. The "creator.v2" element is for factory ``lammpsplugin_factory1`` type before assignment. The "creator.v2"
functions creating an instance of a fix, compute, or region style and element is for factory functions creating an instance of a fix, compute,
takes three arguments: a pointer to the LAMMPS instance, an integer with region, or run style and takes three arguments: a pointer to the LAMMPS
the length of the argument list and a ``char **`` pointer to the list of instance, an integer with the length of the argument list and a ``char
arguments. The factory function pointer needs to be cast to the **`` pointer to the list of arguments. The factory function pointer
``lammpsplugin_factory2`` type before assignment. needs to be cast to the ``lammpsplugin_factory2`` type before
assignment.
Pair style example Pair style example
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
@ -247,8 +248,8 @@ DSO handle. The registration function is called with a pointer to the address
of this struct and the pointer of the LAMMPS class. The registration function of this struct and the pointer of the LAMMPS class. The registration function
will then add the factory function of the plugin style to the respective will then add the factory function of the plugin style to the respective
style map under the provided name. It will also make a copy of the struct style map under the provided name. It will also make a copy of the struct
in a list of all loaded plugins and update the reference counter for loaded in a global list of all loaded plugins and update the reference counter for
plugins from this specific DSO file. loaded plugins from this specific DSO file.
The pair style itself (i.e. the PairMorse2 class in this example) can be The pair style itself (i.e. the PairMorse2 class in this example) can be
written just like any other pair style that is included in LAMMPS. For written just like any other pair style that is included in LAMMPS. For
@ -263,6 +264,21 @@ the plugin will override the existing code. This can be used to modify
the behavior of existing styles or to debug new versions of them without the behavior of existing styles or to debug new versions of them without
having to re-compile or re-install all of LAMMPS. having to re-compile or re-install all of LAMMPS.
.. versionupdated:: 12Jun2025
When using the :doc:`clear <clear>` command, plugins are not unloaded
but restored to their respective style maps. This also applies when
multiple LAMMPS instances are created and deleted through the library
interface. The :doc:`plugin load <plugin>` load command may be issued
again, but for existing plugins they will be skipped. To replace
plugins they must be explicitly unloaded with :doc:`plugin unload
<plugin>`. When multiple LAMMPS instances are created concurrently, any
loaded plugins will be added to the global list of plugins, but are not
immediately available to any LAMMPS instance that was created before
loading the plugin. To "import" such plugins, the :doc:`plugin restore
<plugin>` may be used. Plugins are only removed when they are explicitly
unloaded or the LAMMPS interface is "finalized".
Compiling plugins Compiling plugins
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^

2
doc/src/plugin.rst
View File

@ -77,7 +77,7 @@ styles and names.
The *clear* command will unload all currently loaded plugins. The *clear* command will unload all currently loaded plugins.
.. versionadded:: TBD .. versionadded:: 12Jun2025
The *restore* command will restore all currently loaded plugins. The *restore* command will restore all currently loaded plugins.
This allows to "import" plugins into a different LAMMPS instance. This allows to "import" plugins into a different LAMMPS instance.