\(\renewcommand{\AA}{\text{Å}}\)
1.1.9. Utility functions
To simplify some tasks, the library interface contains these utility functions. They do not directly call the LAMMPS library.
The lammps_free()
function is a clean-up function to free
memory that the library had allocated previously via other function
calls. Look for notes in the descriptions of the individual commands
where such memory buffers were allocated that require the use of
lammps_free()
.
-
int lammps_encode_image_flags(int ix, int iy, int iz)
Encode three integer image flags into a single imageint.
The prototype for this function when compiling with
-DLAMMPS_BIGBIG
is:int64_t lammps_encode_image_flags(int ix, int iy, int iz);
This function performs the bit-shift, addition, and bit-wise OR operations necessary to combine the values of three integers representing the image flags in x-, y-, and z-direction. Unless LAMMPS is compiled with -DLAMMPS_BIGBIG, those integers are limited 10-bit signed integers [-512, 511]. Otherwise the return type changes from
int
toint64_t
and the valid range for the individual image flags becomes [-1048576,1048575], i.e. that of a 21-bit signed integer. There is no check on whether the arguments conform to these requirements.- Parameters:
ix – image flag value in x
iy – image flag value in y
iz – image flag value in z
- Returns:
encoded image flag integer
-
void lammps_decode_image_flags(int image, int *flags)
Decode a single image flag integer into three regular integers
The prototype for this function when compiling with
-DLAMMPS_BIGBIG
is:void lammps_decode_image_flags(int64_t image, int *flags);
This function does the reverse operation of
lammps_encode_image_flags()
and takes an image flag integer does the bit-shift and bit-masking operations to decode it and stores the resulting three regular integers into the buffer pointed to by flags.- Parameters:
image – encoded image flag integer
flags – pointer to storage where the decoded image flags are stored.
-
void lammps_set_fix_external_callback(void *handle, const char *id, FixExternalFnPtr funcptr, void *ptr)
Set up the callback function for a fix external instance with the given ID.
Fix external allows programs that are running LAMMPS through its library interface to modify certain LAMMPS properties on specific timesteps, similar to the way other fixes do.
This function sets the callback function for use with the “pf/callback” mode. The function has to have C language bindings with the prototype:
void func(void *ptr, bigint timestep, int nlocal, tagint *ids, double **x, double **fexternal);
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 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 from within the callback function.
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
lammps_fix_external_get_force()
.Please see the documentation for fix external for more information about how to use the fix and how to couple it with an external code.
Changed in version 28Jul2021.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
funcptr – pointer to callback function
ptr – pointer to object in calling code, passed to callback function as first argument
-
double **lammps_fix_external_get_force(void *handle, const char *id)
Get pointer to the force array storage in a fix external instance with the given ID.
New in version 28Jul2021.
Fix 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 atoms when using the “pf/array” mode. The fexternal array can be accessed like other “native” per-atom arrays accessible via the
lammps_extract_atom()
function. Please note that the array 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, for example,lammps_extract_setting()
to obtain the number of local atoms nlocal and then assume the dimensions of the returned force array asdouble force[nlocal][3]
.This is an alternative to the callback mechanism in fix external set up by
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 the fix is triggered and needs them.Please see the documentation for fix external for more information about how to use the fix and how to couple it with an external code.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
- Returns:
a pointer to the per-atom force array allocated by the fix
-
void lammps_fix_external_set_energy_global(void *handle, const char *id, double eng)
Set the global energy contribution for a fix external instance with the given ID.
New in version 28Jul2021.
This is a companion function to
lammps_set_fix_external_callback()
andlammps_fix_external_get_force()
to also set the contribution 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. The energy is in energy units as determined by the current 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 fix external for more information about how to use the fix and how to couple it with an external code.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
eng – total energy to be added to the global energy
-
void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng)
Set the per-atom energy contribution for a fix external instance with the given ID.
New in version 28Jul2021.
This is a companion function to
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.Please see the documentation for fix external for more information about how to use the fix and how to couple it with an external code.
Note
This function is fully independent from
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.- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
eng – pointer to array of length nlocal with the energy to be added to the per-atom energy
-
void lammps_fix_external_set_virial_global(void *handle, const char *id, double *virial)
Set the global virial contribution for a fix external instance with the given ID.
New in version 28Jul2021.
This is a companion function to
lammps_set_fix_external_callback()
andlammps_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 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 fix external for more information about how to use the fix and how to couple it with an external code.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
virial – the 6 global stress tensor components to be added to the global virial
-
void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial)
Set the per-atom virial contribution for a fix external instance with the given ID.
New in version 28Jul2021.
This is a companion function to
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.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 fix external for more information about how to use the fix and how to couple it with an external code.
Note
This function is fully independent from
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.- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
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_vector_length(void *handle, const char *id, int len)
Set the vector length for a global vector stored with fix external for analysis
New in version 28Jul2021.
This is a companion function to
lammps_set_fix_external_callback()
andlammps_fix_external_get_force()
to set the length of a global vector of properties that will be stored with the fix vialammps_fix_external_set_vector()
.This function needs to be called before a call to
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 fix external for more information about how to use the fix and how to couple it with an external code.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
len – length of the global vector to be stored with the fix
-
void lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val)
Store a global vector value for a fix external instance with the given ID.
New in version 28Jul2021.
This is a companion function to
lammps_set_fix_external_callback()
andlammps_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 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
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.Please see the documentation for fix external for more information about how to use the fix and how to couple it with an external code.
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
lammps_fix_external_set_vector_length()
.- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.id – fix ID of fix external instance
idx – 1-based index of in global vector
val – value to be stored in global vector
-
void lammps_flush_buffers(void *ptr)
Flush output buffers
This function can be used to flush buffered output to be written to screen and logfile pointers to simplify capturing output from LAMMPS library calls.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.
-
void lammps_free(void *ptr)
Free memory buffer allocated by LAMMPS.
Some of the LAMMPS C library interface functions return data as pointer to a buffer that has been allocated by LAMMPS or the library interface. This function can be used to delete those in order to avoid memory leaks.
- Parameters:
ptr – pointer to data allocated by LAMMPS
-
int lammps_is_running(void *handle)
Check if LAMMPS is currently inside a run or minimization
This function can be used from signal handlers or multi-threaded applications to determine if the LAMMPS instance is currently active.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
.- Returns:
0 if idle or >0 if active
-
void lammps_force_timeout(void *handle)
Force a timeout to stop an ongoing run cleanly.
This function can be used from signal handlers or multi-threaded applications to cleanly terminate an ongoing run.
- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
-
int lammps_has_error(void *handle)
Check if there is a (new) error message available
This function can be used to query if an error inside of LAMMPS has thrown a C++ exception.
Note
The handle pointer may be
NULL
for this function, as would be the case when a call to create a LAMMPS instance has failed. Then this function will not check the error status inside the LAMMPS instance, but instead would check the global error buffer of the library interface.Note
This function will always report “no error” when the LAMMPS library has been compiled without
-DLAMMPS_EXCEPTIONS
, which turns fatal errors aborting LAMMPS into C++ exceptions. You can use the library functionlammps_config_has_exceptions()
to check whether this is the case.- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
or NULL- Returns:
0 on no error, 1 on error.
-
int lammps_get_last_error_message(void *handle, char *buffer, int buf_size)
Copy the last error message into the provided buffer
This function can be used to retrieve the error message that was set in the event of an error inside of LAMMPS which resulted in a C++ exception. A suitable buffer for a C-style string has to be provided and its length. If the internally stored error message is longer, it will be truncated accordingly. The return value of the function corresponds to the kind of error: a “1” indicates an error that occurred on all MPI ranks and is often recoverable, while a “2” indicates an abort that would happen only in a single MPI rank and thus may not be recoverable, as other MPI ranks may be waiting on the failing MPI ranks to send messages.
Note
The handle pointer may be
NULL
for this function, as would be the case when a call to create a LAMMPS instance has failed. Then this function will not check the error buffer inside the LAMMPS instance, but instead would check the global error buffer of the library interface.Note
This function will do nothing when the LAMMPS library has been compiled without
-DLAMMPS_EXCEPTIONS
, which turns errors aborting LAMMPS into C++ exceptions. You can use the library functionlammps_config_has_exceptions()
to check whether this is the case.- Parameters:
handle – pointer to a previously created LAMMPS instance cast to
void *
or NULL.buffer – string buffer to copy the error message to
buf_size – size of the provided string buffer
- Returns:
1 when all ranks had the error, 2 on a single rank error.
-
int lammps_python_api_version()
Return API version of embedded Python interpreter
New in version 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.
- Returns:
PYTHON_API_VERSION constant of the python interpreter or -1