From bb46dd7d1f765a3e9c5b926b102e59662ec39f9f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 22 Jul 2021 13:14:49 -0400 Subject: [PATCH] update embedded documentation for the library interface functions for accessing fix external --- src/library.cpp | 122 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 87 insertions(+), 35 deletions(-) diff --git a/src/library.cpp b/src/library.cpp index 0c897538a1..b9c2fbe4e9 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -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 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 -functions that set the global or per-atom energy or virial -contributions. +functions that set the global or per-atom energy or virial contributions +from within the callback function. -The callback mechanism is on of the two modes of fix external. The -alternative is the array mode set up by :cpp:func:`lammps_fix_external_get_force`. +The callback mechanism is one of the two modes of how forces and can be +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 ` for more information about how to use the fix and how to couple it with an @@ -4872,23 +4873,25 @@ Fix :doc:`external ` allows programs that are running LAMMPS throu 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 the fix -external instance to be added to the individual atoms when using the -"pf/array" mode. The *fexternal* array can be accessed similar to the -"native" per-atom *arrays accessible via the +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 +atoms when using the "pf/array" mode. The *fexternal* array can be +accessed like other "native" per-atom arrays accessible via the :cpp:func:`lammps_extract_atom` function. Please note that the array -stores forces for *local* atoms, in the order determined by the neighbor -list build. Because the underlying data structures can change as well as -the order of atom as they migrate between MPI processes, 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 -e.g. :cpp:func:`lammps_get_natoms` to obtain the number of local atoms -and thus the dimensions of the returned force array (``double force[nlocal][3]``). +stores holds the forces for *local* atoms for each MPI ranks, in the +order determined by the neighbor list build. Because the underlying +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 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 :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 -control alternates between LAMMPS and the external command, while the +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 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* argument will be stored in the fix and applied on the current and all following timesteps until changed by another call to this function. -When running in parallel, the value is the per-MPI process contribution, -not the total energy. +The energy is in energy units as determined by the current :doc:`units ` +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 ` for 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 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) { @@ -4972,10 +4979,18 @@ void lammps_fix_external_set_energy_global(void *handle, const char *id, double \verbatim embed:rst 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 -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 -callback function. +and :cpp:func:`lammps_fix_external_get_force` to set the contribution to +the global virial from the external code. + +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 ` 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 ` for 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 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 -callback function. No check is made whether the sum of the -contributions are consistent with any global added energy. +callback function. + +.. 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 ` for 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 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) { @@ -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 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 -callback function. No check is made whether the sum of the -contributions are consistent with any globally added virial components. +callback function. + +.. 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 ` for 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 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) { @@ -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 :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 ` for 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 :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 -must be set beforehand with :cpp:func:`lammps_fix_external_set_vector_length`. +properties that will be stored with the fix. And can be accessed from +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 ` for 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 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 */ void lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val)