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

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.

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.

New in version 28Jul2021.

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.

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.

New in version 28Jul2021.

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.

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.

New in version 28Jul2021.

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.

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.

New in version 28Jul2021.

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

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.

New in version 28Jul2021.

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.

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.

New in version 28Jul2021.

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_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 cleanly stop an ongoing run

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

This function will always report “no error” when the LAMMPS library has been compiled without -DLAMMPS_EXCEPTIONS which turns fatal errors aborting LAMMPS into a C++ exceptions. You can use the library function lammps_config_has_exceptions() to check if this is the case.

Parameters

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

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

This function will do nothing when the LAMMPS library has been compiled without -DLAMMPS_EXCEPTIONS which turns errors aborting LAMMPS into a C++ exceptions. You can use the library function lammps_config_has_exceptions() to check if this is the case.

Parameters

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

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