\(\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 to int64_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.

Added 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 as double 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.

Added in version 28Jul2021.

This is a companion function to lammps_set_fix_external_callback() and lammps_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.

Added 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.

Added in version 28Jul2021.

This is a companion function to lammps_set_fix_external_callback() and 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 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.

Added 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

Added in version 28Jul2021.

This is a companion function to lammps_set_fix_external_callback() and lammps_fix_external_get_force() to set the length of a global vector of properties that will be stored with the fix via lammps_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.

Added in version 28Jul2021.

This is a companion function to lammps_set_fix_external_callback() and lammps_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.

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. If the buffer is a NULL pointer, then nothing will be copied. 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.

The buffer pointer may be NULL. This will clear any error status without copying the error message.

Parameters:

  • handle – pointer to a previously created LAMMPS instance cast to void * or NULL.

  • buffer – string buffer to copy the error message to, may be NULL

  • 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

Added 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