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

update embedded documentation for the library interface functions for accessing fix external

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-07-22 13:14:49 -04:00
parent aa885a9d8d
commit bb46dd7d1f
1 changed files with 87 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
src/library.cpp
View File

@ -4823,13 +4823,14 @@ mode. The function has to have C language bindings with the prototype:
The argument *ptr* to this function will be stored in fix external and The argument *ptr* to this function will be stored in fix external and
the passed as the first argument calling the callback function `func()`. the passed as the first argument calling the callback function `func()`.
This would usually be a pointer to the LAMMPS instance, i.e. the same This would usually be a pointer to the active LAMMPS instance, i.e. the same
pointer as the *handle* argument. This would be needed to call pointer as the *handle* argument. This would be needed to call
functions that set the global or per-atom energy or virial functions that set the global or per-atom energy or virial contributions
contributions. from within the callback function.
The callback mechanism is on of the two modes of fix external. The The callback mechanism is one of the two modes of how forces and can be
alternative is the array mode set up by :cpp:func:`lammps_fix_external_get_force`. applied to a simulation with the help of fix external. The alternative
is the array mode where you call :cpp:func:`lammps_fix_external_get_force`.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -4872,23 +4873,25 @@ Fix :doc:`external <fix_external>` allows programs that are running LAMMPS throu
its library interface to add or modify certain LAMMPS properties on specific its library interface to add or modify certain LAMMPS properties on specific
timesteps, similar to the way other fixes do. timesteps, similar to the way other fixes do.
This function provides access to the per-atom force storage in the fix This function provides access to the per-atom force storage in a fix
external instance to be added to the individual atoms when using the external instance with the given fix-ID to be added to the individual
"pf/array" mode. The *fexternal* array can be accessed similar to the atoms when using the "pf/array" mode. The *fexternal* array can be
"native" per-atom *arrays accessible via the accessed like other "native" per-atom arrays accessible via the
:cpp:func:`lammps_extract_atom` function. Please note that the array :cpp:func:`lammps_extract_atom` function. Please note that the array
stores forces for *local* atoms, in the order determined by the neighbor stores holds the forces for *local* atoms for each MPI ranks, in the
list build. Because the underlying data structures can change as well as order determined by the neighbor list build. Because the underlying
the order of atom as they migrate between MPI processes, this function data structures can change as well as the order of atom as they migrate
should be always called immediately before the forces are going to be between MPI processes because of the domain decomposition
set to get an up-to-date pointer. You can use parallelization, this function should be always called immediately
e.g. :cpp:func:`lammps_get_natoms` to obtain the number of local atoms before the forces are going to be set to get an up-to-date pointer.
and thus the dimensions of the returned force array (``double force[nlocal][3]``). You can use e.g. :cpp:func:`lammps_get_natoms` 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 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 :cpp:func:`lammps_set_fix_external_callback`. The main difference is
that this mechanism can be used when forces can be pre-computed and the that this mechanism can be used when forces are be pre-computed and the
control alternates between LAMMPS and the external command, while the control alternates between LAMMPS and the external code, while the
callback mechanism can call the external code to compute the force when callback mechanism can call the external code to compute the force when
the fix is triggered and needs them. the fix is triggered and needs them.
@ -4933,8 +4936,12 @@ This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and
to the global energy from the external code. The value of the *eng* to the global energy from the external code. The value of the *eng*
argument will be stored in the fix and applied on the current and all argument will be stored in the fix and applied on the current and all
following timesteps until changed by another call to this function. following timesteps until changed by another call to this function.
When running in parallel, the value is the per-MPI process contribution, The energy is in energy units as determined by the current :doc:`units <units>`
not the total energy. settings and is the **total** energy of the contribution. Thus when
running in parallel all MPI processes have to call this function with
the **same** value and this will be returned as scalar property of the
fix external instance when accessed in LAMMPS input commands or from
variables.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -4944,7 +4951,7 @@ external code.
* *
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``. * \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
* \param id fix ID of fix external instance * \param id fix ID of fix external instance
* \param eng energy to be added to the global energy */ * \param eng total energy to be added to the global energy */
void lammps_fix_external_set_energy_global(void *handle, const char *id, double eng) void lammps_fix_external_set_energy_global(void *handle, const char *id, double eng)
{ {
@ -4972,10 +4979,18 @@ void lammps_fix_external_set_energy_global(void *handle, const char *id, double
\verbatim embed:rst \verbatim embed:rst
This is a companion function to :cpp:func:`lammps_set_fix_external_callback` This is a companion function to :cpp:func:`lammps_set_fix_external_callback`
to set the contribution to the global virial from the external code and :cpp:func:`lammps_fix_external_get_force` to set the contribution to
as part of the callback function. For this to work, the handle to the the global virial from the external code.
LAMMPS object must be passed as the *ptr* argument when registering the
callback function. The 6 values of the *virial* array will be stored in the fix and applied
on the current and all following timesteps until changed by another call
to this function. The components of the virial need to be stored in the
order: *xx*, *yy*, *zz*, *xy*, *xz*, *yz*. In LAMMPS the virial is
stored internally as `stress*volume` in units of `pressure*volume` as
determined by the current :doc:`units <units>` settings and is the
**total** contribution. Thus when running in parallel all MPI processes
have to call this function with the **same** value and this will then
be added by fix external.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -5016,8 +5031,15 @@ 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 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 as part of the callback function. For this to work, the handle to the
LAMMPS object must be passed as the *ptr* argument when registering the LAMMPS object must be passed as the *ptr* argument when registering the
callback function. No check is made whether the sum of the callback function.
contributions are consistent with any global added energy.
.. note::
This function is fully independent from :cpp:func:`lammps_fix_external_set_energy_global`
and will **NOT** add any contributions to the global energy tally
and **NOT** check whether the sum of the contributions added here are
consistent with the global added energy.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -5027,7 +5049,7 @@ external code.
* *
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``. * \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
* \param id fix ID of fix external instance * \param id fix ID of fix external instance
* \param eng energy to be added to the per-atom energy */ * \param eng pointer to array of length nlocal with the energy to be added to the per-atom energy */
void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng) void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng)
{ {
@ -5058,8 +5080,18 @@ 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 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 as part of the callback function. For this to work, the handle to the
LAMMPS object must be passed as the *ptr* argument when registering the LAMMPS object must be passed as the *ptr* argument when registering the
callback function. No check is made whether the sum of the callback function.
contributions are consistent with any globally added virial components.
.. note::
This function is fully independent from :cpp:func:`lammps_fix_external_set_virial_global`
and will **NOT** add any contributions to the global virial tally
and **NOT** check whether the sum of the contributions added here are
consistent with the global added virial.
The order and units of the per-atom stress tensor elements are the same
as for the global virial. The code in fix external assumes the
dimensions of the per-atom virial array is ``double virial[nlocal][6]``.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -5069,7 +5101,7 @@ external code.
* *
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``. * \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
* \param id fix ID of fix external instance * \param id fix ID of fix external instance
* \param virial the 6 per-atom stress tensor components to be added to the per-atom virial */ * \param virial a list of nlocal entries with the 6 per-atom stress tensor components to be added to the per-atom virial */
void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial) void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial)
{ {
@ -5098,7 +5130,13 @@ void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double
This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and 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 :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 :cpp:func:`lammps_fix_external_set_vector`. properties that will be stored with the fix via
:cpp:func:`lammps_fix_external_set_vector`.
This function needs to be called **before** a call to
:cpp:func:`lammps_fix_external_set_vector` and **before** a run or minimize
command. When running in parallel it must be called from **all** MPI
processes and with the same length parameter.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -5137,8 +5175,22 @@ void lammps_fix_external_set_vector_length(void *handle, const char *id, int len
This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and 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 :cpp:func:`lammps_fix_external_get_force` to set the values of a global vector of
properties that will be stored with the fix. The length of the vector properties that will be stored with the fix. And can be accessed from
must be set beforehand with :cpp:func:`lammps_fix_external_set_vector_length`. within LAMMPS input commands (e.g. fix ave/time or variables) when used
in a vector context.
This function needs to be called **after** a call to
:cpp:func:`lammps_fix_external_set_vector_length` and the and **before** a run or minimize
command. When running in parallel it must be called from **all** MPI
processes and with the **same** index and value parameters. The value
is assumed to be extensive.
.. note::
The index in the *idx* parameter is 1-based, i.e. the first element
is set with idx = 1 and the last element of the vector with idx = N,
where N is the value of the *len* parameter of the call to
:cpp:func:`lammps_fix_external_set_vector_length`.
Please see the documentation for :doc:`fix external <fix_external>` for 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 more information about how to use the fix and how to couple it with an
@ -5148,7 +5200,7 @@ external code.
* *
* \param handle pointer to a previously created LAMMPS instance cast to ``void *``. * \param handle pointer to a previously created LAMMPS instance cast to ``void *``.
* \param id fix ID of fix external instance * \param id fix ID of fix external instance
* \param idx 1 based index of in global vector * \param idx 1-based index of in global vector
* \param val value to be stored in global vector */ * \param val value to be stored in global vector */
void lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val) void lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val)