Merge pull request #4621 from akohlmey/plugin-add-run-min-style
Add support for run and minimize style plugins and refactor plugin handling to become global
This commit is contained in:
Axel Kohlmeyer
@ -31,3 +31,5 @@ OPT.
|
||||
* :doc:`pppm/dielectric <kspace_style>`
|
||||
* :doc:`pppm/electrode (i) <kspace_style>`
|
||||
* :doc:`scafacos <kspace_style>`
|
||||
* :doc:`zero <kspace_style>`
|
||||
|
||||
|
||||
@ -68,24 +68,25 @@ Members of ``lammpsplugin_t``
|
||||
* - author
|
||||
- String with the name and email of the author
|
||||
* - 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
|
||||
- Pointer to factory function for compute, fix, or region styles
|
||||
- Pointer to factory function for compute, fix, region, or run styles
|
||||
* - handle
|
||||
- Pointer to the open DSO file handle
|
||||
|
||||
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"
|
||||
element is for factory functions of supported styles computing forces
|
||||
(i.e. pair, bond, angle, dihedral, or improper styles) or command styles
|
||||
and the function takes as single argument the pointer to the LAMMPS
|
||||
instance. The factory function is cast to the ``lammpsplugin_factory1``
|
||||
type before assignment. The "creator.v2" element is for factory
|
||||
functions creating an instance of a fix, compute, or region style and
|
||||
takes three arguments: a pointer to the LAMMPS instance, an integer with
|
||||
the length of the argument list and a ``char **`` pointer to the list of
|
||||
arguments. The factory function pointer needs to be cast to the
|
||||
``lammpsplugin_factory2`` type before assignment.
|
||||
(i.e. pair, bond, angle, dihedral, or improper styles), command styles,
|
||||
or minimize styles and the function takes as single argument the pointer
|
||||
to the LAMMPS instance. The factory function is cast to the
|
||||
``lammpsplugin_factory1`` type before assignment. The "creator.v2"
|
||||
element is for factory functions creating an instance of a fix, compute,
|
||||
region, or run style and takes three arguments: a pointer to the LAMMPS
|
||||
instance, an integer with the length of the argument list and a ``char
|
||||
**`` pointer to the list of arguments. The factory function pointer
|
||||
needs to be cast to the ``lammpsplugin_factory2`` type before
|
||||
assignment.
|
||||
|
||||
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
|
||||
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
|
||||
in a list of all loaded plugins and update the reference counter for loaded
|
||||
plugins from this specific DSO file.
|
||||
in a global list of all loaded plugins and update the reference counter for
|
||||
loaded plugins from this specific DSO file.
|
||||
|
||||
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
|
||||
@ -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
|
||||
having to re-compile or re-install all of LAMMPS.
|
||||
|
||||
.. versionchanged:: 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
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@ -69,10 +69,11 @@ statement. Internally, it will call either
|
||||
:cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
|
||||
the C library API to create the class instance. All arguments are
|
||||
optional and :cpp:func:`lammps_mpi_init` will be called automatically
|
||||
if it is needed. Similarly, a possible call to
|
||||
:cpp:func:`lammps_mpi_finalize` is integrated into the :f:func:`close`
|
||||
function and triggered with the optional logical argument set to
|
||||
``.TRUE.``. Here is a simple example:
|
||||
if it is needed. Similarly, optional calls to
|
||||
:cpp:func:`lammps_mpi_finalize`, :cpp:func:`lammps_kokkos_finalize`,
|
||||
:cpp:func:`lammps_python_finalize`, and :cpp:func:`lammps_plugin_finalize`
|
||||
are integrated into the :f:func:`close` function and triggered with the
|
||||
optional logical argument set to ``.TRUE.``. Here is a simple example:
|
||||
|
||||
.. code-block:: fortran
|
||||
|
||||
@ -521,8 +522,8 @@ Procedures Bound to the :f:type:`lammps` Derived Type
|
||||
This method will close down the LAMMPS instance through calling
|
||||
:cpp:func:`lammps_close`. If the *finalize* argument is present and
|
||||
has a value of ``.TRUE.``, then this subroutine also calls
|
||||
:cpp:func:`lammps_kokkos_finalize` and
|
||||
:cpp:func:`lammps_mpi_finalize`.
|
||||
:cpp:func:`lammps_kokkos_finalize`, :cpp:func:`lammps_mpi_finalize`,
|
||||
:cpp:func:`lammps_python_finalize`, and :cpp:func:`lammps_plugin_finalize`.
|
||||
|
||||
:o finalize: shut down the MPI environment of the LAMMPS
|
||||
library if ``.TRUE.``.
|
||||
@ -530,6 +531,8 @@ Procedures Bound to the :f:type:`lammps` Derived Type
|
||||
:to: :cpp:func:`lammps_close`
|
||||
:to: :cpp:func:`lammps_mpi_finalize`
|
||||
:to: :cpp:func:`lammps_kokkos_finalize`
|
||||
:to: :cpp:func:`lammps_python_finalize`
|
||||
:to: :cpp:func:`lammps_plugin_finalize`
|
||||
|
||||
--------
|
||||
|
||||
|
||||
@ -11,6 +11,7 @@ This section documents the following functions:
|
||||
- :cpp:func:`lammps_mpi_finalize`
|
||||
- :cpp:func:`lammps_kokkos_finalize`
|
||||
- :cpp:func:`lammps_python_finalize`
|
||||
- :cpp:func:`lammps_plugin_finalize`
|
||||
- :cpp:func:`lammps_error`
|
||||
|
||||
--------------------
|
||||
@ -119,5 +120,10 @@ calling program.
|
||||
|
||||
-----------------------
|
||||
|
||||
.. doxygenfunction:: lammps_plugin_finalize
|
||||
:project: progguide
|
||||
|
||||
-----------------------
|
||||
|
||||
.. doxygenfunction:: lammps_error
|
||||
:project: progguide
|
||||
|
||||
@ -32,6 +32,7 @@
|
||||
.. index:: kspace_style msm/cg/omp
|
||||
.. index:: kspace_style msm/dielectric
|
||||
.. index:: kspace_style scafacos
|
||||
.. index:: kspace_style zero
|
||||
|
||||
kspace_style command
|
||||
====================
|
||||
@ -43,7 +44,7 @@ Syntax
|
||||
|
||||
kspace_style style value
|
||||
|
||||
* style = *none* or *ewald* or *ewald/dipole* or *ewald/dipole/spin* or *ewald/disp* or *ewald/disp/dipole* or *ewald/omp* or *ewald/electrode* or *pppm* or *pppm/cg* or *pppm/disp* or *pppm/tip4p* or *pppm/stagger* or *pppm/disp/tip4p* or *pppm/gpu* or *pppm/intel* or *pppm/disp/intel* or *pppm/kk* or *pppm/omp* or *pppm/cg/omp* or *pppm/disp/tip4p/omp* or *pppm/tip4p/omp* or *pppm/dielectic* or *pppm/disp/dielectric* or *pppm/electrode* or *pppm/electrode/intel* or *msm* or *msm/cg* or *msm/omp* or *msm/cg/omp* or *msm/dielectric* or *scafacos*
|
||||
* style = *none* or *ewald* or *ewald/dipole* or *ewald/dipole/spin* or *ewald/disp* or *ewald/disp/dipole* or *ewald/omp* or *ewald/electrode* or *pppm* or *pppm/cg* or *pppm/disp* or *pppm/tip4p* or *pppm/stagger* or *pppm/disp/tip4p* or *pppm/gpu* or *pppm/intel* or *pppm/disp/intel* or *pppm/kk* or *pppm/omp* or *pppm/cg/omp* or *pppm/disp/tip4p/omp* or *pppm/tip4p/omp* or *pppm/dielectic* or *pppm/disp/dielectric* or *pppm/electrode* or *pppm/electrode/intel* or *msm* or *msm/cg* or *msm/omp* or *msm/cg/omp* or *msm/dielectric* or *scafacos* or *zero*
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
@ -121,6 +122,7 @@ Syntax
|
||||
*scafacos* values = method accuracy
|
||||
method = fmm or p2nfft or p3m or ewald or direct
|
||||
accuracy = desired relative error in forces
|
||||
*zero* value = none
|
||||
|
||||
Examples
|
||||
""""""""
|
||||
@ -132,6 +134,7 @@ Examples
|
||||
kspace_style msm 1.0e-4
|
||||
kspace_style scafacos fmm 1.0e-4
|
||||
kspace_style none
|
||||
kspace_style zero
|
||||
|
||||
Used in input scripts:
|
||||
|
||||
@ -375,6 +378,13 @@ other ScaFaCoS options currently exposed to LAMMPS.
|
||||
|
||||
----------
|
||||
|
||||
.. versionadded:: 12Jun2025
|
||||
|
||||
The *zero* style does not do any calculations, but is compatible
|
||||
with all pair styles that require some version of a kspace style.
|
||||
|
||||
----------
|
||||
|
||||
The specified *accuracy* determines the relative RMS error in per-atom
|
||||
forces calculated by the long-range solver. It is set as a
|
||||
dimensionless number, relative to the force that two unit point
|
||||
|
||||
@ -10,16 +10,17 @@ Syntax
|
||||
|
||||
plugin command args
|
||||
|
||||
* command = *load* or *unload* or *list* or *clear*
|
||||
* command = *load* or *unload* or *list* or *clear* or *restore*
|
||||
* args = list of arguments for a particular plugin command
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
*load* file = load plugin(s) from shared object in *file*
|
||||
*unload* style name = unload plugin *name* of style *style*
|
||||
*style* = *pair* or *bond* or *angle* or *dihedral* or *improper* or *kspace* or *compute* or *fix* or *region* or *command*
|
||||
*style* = *pair* or *bond* or *angle* or *dihedral* or *improper* or *kspace* or *compute* or *fix* or *region* or *command* or *run* or *min*
|
||||
*list* = print a list of currently loaded plugins
|
||||
*clear* = unload all currently loaded plugins
|
||||
*restore* = restore all loaded plugins
|
||||
|
||||
Examples
|
||||
""""""""
|
||||
@ -31,6 +32,7 @@ Examples
|
||||
plugin unload command hello
|
||||
plugin list
|
||||
plugin clear
|
||||
plugin restore
|
||||
|
||||
Description
|
||||
"""""""""""
|
||||
@ -40,22 +42,46 @@ commands into a LAMMPS binary from so-called dynamic shared object (DSO)
|
||||
files. This enables to add new functionality to an existing LAMMPS
|
||||
binary without having to recompile and link the entire executable.
|
||||
|
||||
.. admonition:: Plugins are a global, per-executable property
|
||||
:class: Hint
|
||||
|
||||
Unlike most settings in LAMMPS, plugins are a per-executable global
|
||||
property. Loading a plugin means that it is not only available for
|
||||
the current LAMMPS instance but for all *future* LAMMPS instances.
|
||||
|
||||
After a :doc:`clear <clear>` command, all currently loaded plugins
|
||||
will be restored and do not need to be loaded again.
|
||||
|
||||
When using the library interface or the Python or Fortran module
|
||||
to create multiple concurrent LAMMPS instances, all plugins should
|
||||
be loaded by the first created LAMMPS instance as all future instances
|
||||
will inherit them. To import plugins that were loaded by a different
|
||||
LAMMPS instance, use the *restore* command.
|
||||
|
||||
|
||||
The *load* command will load and initialize all plugins contained in the
|
||||
plugin DSO with the given filename. A message with information the
|
||||
plugin style and name and more will be printed. Individual DSO files
|
||||
may contain multiple plugins. More details about how to write and
|
||||
plugin DSO with the given filename. A message with information about
|
||||
the plugin style and name and more will be printed. Individual DSO
|
||||
files may contain multiple plugins. If a plugin is already loaded
|
||||
it will be skipped. More details about how to write and
|
||||
compile the plugin DSO is given in programmer's guide part of the manual
|
||||
under :doc:`Developer_plugins`.
|
||||
|
||||
The *unload* command will remove the given style or the given name from
|
||||
the list of available styles. If the plugin style is currently in use,
|
||||
that style instance will be deleted.
|
||||
that style instance will be deleted and replaced by the default setting
|
||||
for that style.
|
||||
|
||||
The *list* command will print a list of the loaded plugins and their
|
||||
styles and names.
|
||||
|
||||
The *clear* command will unload all currently loaded plugins.
|
||||
|
||||
.. versionadded:: 12Jun2025
|
||||
|
||||
The *restore* command will restore all currently loaded plugins.
|
||||
This allows to "import" plugins into a different LAMMPS instance.
|
||||
|
||||
.. admonition:: Automatic loading of plugins
|
||||
:class: note
|
||||
|
||||
@ -79,7 +105,7 @@ If plugins access functions or classes from a package,
|
||||
LAMMPS must have been compiled with that package included.
|
||||
|
||||
Plugins are dependent on the LAMMPS binary interface (ABI)
|
||||
and particularly the MPI library used. So they are not guaranteed
|
||||
and particularly the MPI library used. So they are not guaranteed
|
||||
to work when the plugin was compiled with a different MPI library
|
||||
or different compilation settings or a different LAMMPS version.
|
||||
There are no checks, so if there is a mismatch the plugin object
|
||||
|
||||
Reference in New Issue
Block a user