\(\renewcommand{\AA}{\text{Å}}\)

1.1.8. Configuration information

This section documents the following functions:

These library functions can be used to query the LAMMPS library for compile time settings and included packages and styles. This enables programs that use the library interface to determine whether the linked LAMMPS library is compatible with the requirements of the application without crashing during the LAMMPS functions (e.g. due to missing pair styles from packages) or to choose between different options (e.g. whether to use lj/cut, lj/cut/opt, lj/cut/omp or lj/cut/intel). Most of the functions can be called directly without first creating a LAMMPS instance. While crashes within LAMMPS may be recovered from by enabling exceptions, avoiding them proactively is a safer approach.

Example for using configuration settings functions
#include "library.h"
#include <stdio.h>

int main(int argc, char **argv)
{
  void *handle;

  handle = lammps_open_no_mpi(0, NULL, NULL);
  lammps_file(handle, "in.missing");
  if (lammps_has_error(handle)) {
    char errmsg[256];
    int errtype;
    errtype = lammps_get_last_error_message(handle, errmsg, 256);
    fprintf(stderr, "LAMMPS failed with error: %s\n", errmsg);
    return 1;
  }
  /* write compressed dump file depending on available of options */
  if (lammps_has_style(handle, "dump", "atom/zstd")) {
    lammps_command(handle, "dump d1 all atom/zstd 100 dump.zst");
  } else if (lammps_has_style(handle, "dump", "atom/gz")) {
    lammps_command(handle, "dump d1 all atom/gz 100 dump.gz");
  } else if (lammps_config_has_gzip_support()) {
    lammps_command(handle, "dump d1 all atom 100 dump.gz");
  } else {
    lammps_command(handle, "dump d1 all atom 100 dump");
  }
  lammps_close(handle);
  return 0;
}
int lammps_version(void *handle)

Get numerical representation of the LAMMPS version date.

The lammps_version() function returns an integer representing the version of the LAMMPS code in the format YYYYMMDD. This can be used to implement backward compatibility in software using the LAMMPS library interface. The specific format guarantees, that this version number is growing with every new LAMMPS release.

Parameters:

handle – pointer to a previously created LAMMPS instance

Returns:

an integer representing the version data in the format YYYYMMDD

void lammps_get_os_info(char *buffer, int buf_size)

Get operating system and architecture information

New in version 9Oct2020.

The lammps_get_os_info() function can be used to retrieve detailed information about the hosting operating system and compiler/runtime.

A suitable buffer for a C-style string has to be provided and its length. The assembled text will be truncated to not overflow this buffer. The string is typically a few hundred bytes long.

Parameters:

  • buffer – string buffer to copy the information to

  • buf_size – size of the provided string buffer

int lammps_config_has_mpi_support()

This function is used to query whether LAMMPS was compiled with a real MPI library or in serial. For the real MPI library it reports the size of the MPI communicator in bytes (4 or 8), which allows to check for compatibility with a hosting code.

Returns:

0 when compiled with MPI STUBS, otherwise the MPI_Comm size in bytes

int lammps_config_has_gzip_support()

Check if the LAMMPS library supports reading or writing compressed files via a pipe to gzip or similar compression programs

Several LAMMPS commands (e.g., read_data command, write_data command, dump styles atom, custom, and xyz) support reading and writing compressed files via creating a pipe to the gzip program. This function checks whether this feature was enabled at compile time. It does not check whether``gzip`` or any other supported compression programs themselves are installed and usable.

Returns:

1 if yes, otherwise 0

int lammps_config_has_png_support()

Check if the LAMMPS library supports writing PNG format images

The LAMMPS dump style image supports writing multiple image file formats. Most of them, however, need support from an external library, and using that has to be enabled at compile time. This function checks whether support for the PNG image file format is available in the current LAMMPS library.

Returns:

1 if yes, otherwise 0

int lammps_config_has_jpeg_support()

Check if the LAMMPS library supports writing JPEG format images

The LAMMPS dump style image supports writing multiple image file formats. Most of them, however, need support from an external library, and using that has to be enabled at compile time. This function checks whether support for the JPEG image file format is available in the current LAMMPS library.

Returns:

1 if yes, otherwise 0

int lammps_config_has_ffmpeg_support()

Check if the LAMMPS library supports creating movie files via a pipe to ffmpeg

The LAMMPS dump style movie supports generating movies from images on-the-fly via creating a pipe to the ffmpeg program. This function checks whether this feature was enabled at compile time. It does not check whether the ffmpeg itself is installed and usable.

Returns:

1 if yes, otherwise 0

int lammps_config_has_exceptions()

Check whether LAMMPS errors will throw C++ exceptions.

Deprecated since version 21Nov2023: LAMMPS has now exceptions always enabled, so this function will now always return 1 and can be removed from applications using the library interface.

In case of an error, LAMMPS will either abort or throw a C++ exception. The latter has to be enabled at compile time. This function checks if exceptions were enabled.

When using the library interface with C++ exceptions enabled, the library interface functions will “catch” them and the error status can then be checked by calling lammps_has_error() and the most recent error message can be retrieved via lammps_get_last_error_message(). This can allow to restart a calculation or delete and recreate the LAMMPS instance when C++ exceptions are enabled. One application of using exceptions this way is the LAMMPS shell. If C++ exceptions are disabled and an error happens during a call to LAMMPS, the application will terminate.

Returns:

1 if yes, otherwise 0

int lammps_config_has_package(const char*)

Check whether a specific package has been included in LAMMPS

This function checks whether the LAMMPS library in use includes the specific LAMMPS package provided as argument.

Parameters:

name – string with the name of the package

Returns:

1 if included, 0 if not.

int lammps_config_package_count()

Count the number of installed packages in the LAMMPS library.

This function counts how many LAMMPS packages are included in the LAMMPS library in use.

Returns:

number of packages included

int lammps_config_package_name(int, char*, int)

Get the name of a package in the list of installed packages in the LAMMPS library.

This function copies the name of the package with the index idx into the provided C-style string buffer. The length of the buffer must be provided as buf_size argument. If the name of the package exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an empty string, otherwise 1;

Parameters:

  • idx – index of the package in the list of included packages (0 <= idx < package count)

  • buffer – string buffer to copy the name of the package to

  • buf_size – size of the provided string buffer

Returns:

1 if successful, otherwise 0

int lammps_config_accelerator(const char*, const char*, const char*)

Check for compile time settings in accelerator packages included in LAMMPS.

This function checks availability of compile time settings of included accelerator packages in LAMMPS. Supported packages names are “GPU”, “KOKKOS”, “INTEL”, and “OPENMP”. Supported categories are “api” with possible settings “cuda”, “hip”, “phi”, “pthreads”, “opencl”, “openmp”, and “serial”, and “precision” with possible settings “double”, “mixed”, and “single”. If the combination of package, category, and setting is available, the function returns 1, otherwise 0.

Parameters:

  • package – string with the name of the accelerator package

  • category – string with the category name of the setting

  • setting – string with the name of the specific setting

Returns:

1 if available, 0 if not.

int lammps_has_gpu_device()

Check for presence of a viable GPU package device

New in version 14May2021.

The lammps_has_gpu_device() function checks at runtime if an accelerator device is present that can be used with the GPU package. If at least one suitable device is present the function will return 1, otherwise 0.

More detailed information about the available device or devices can be obtained by calling the lammps_get_gpu_device_info() function.

Returns:

1 if viable device is available, 0 if not.

void lammps_get_gpu_device_info(char *buffer, int buf_size)

Get GPU package device information

New in version 14May2021.

The lammps_get_gpu_device_info() function can be used to retrieve detailed information about any accelerator devices that are viable for use with the GPU package. It will produce a string that is equivalent to the output of the nvc_get_device or ocl_get_device or hip_get_device tools that are compiled alongside LAMMPS if the GPU package is enabled.

A suitable buffer for a C-style string has to be provided and its length. The assembled text will be truncated to not overflow this buffer. This string can be several kilobytes long, if multiple devices are present.

Parameters:

  • buffer – string buffer to copy the information to

  • buf_size – size of the provided string buffer

int lammps_has_style(void*, const char*, const char*)

Check if a specific style has been included in LAMMPS

This function checks if the LAMMPS library in use includes the specific style of a specific category provided as an argument. Valid categories are: atom, integrate, minimize, pair, bond, angle, dihedral, improper, kspace, compute, fix, region, dump, and command.

Parameters:

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

  • category – category of the style

  • name – name of the style

Returns:

1 if included, 0 if not.

int lammps_style_count(void*, const char*)

Count the number of styles of category in the LAMMPS library.

This function counts how many styles in the provided category are included in the LAMMPS library in use. Please see lammps_has_style() for a list of valid categories.

Parameters:

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

  • category – category of styles

Returns:

number of styles in category

int lammps_style_name(void*, const char*, int, char*, int)

Look up the name of a style by index in the list of style of a given category in the LAMMPS library.

This function copies the name of the category style with the index idx into the provided C-style string buffer. The length of the buffer must be provided as buf_size argument. If the name of the style exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an empty string, otherwise 1.

Parameters:

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

  • category – category of styles

  • idx – index of the style in the list of category styles (0 <= idx < style count)

  • buffer – string buffer to copy the name of the style to

  • buf_size – size of the provided string buffer

Returns:

1 if successful, otherwise 0

int lammps_has_id(void*, const char*, const char*)

Check if a specific ID exists in the current LAMMPS instance

New in version 9Oct2020.

This function checks if the current LAMMPS instance a category ID of the given name exists. Valid categories are: compute, dump, fix, group, molecule, region, and variable.

Parameters:

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

  • category – category of the id

  • name – name of the id

Returns:

1 if included, 0 if not.

int lammps_id_count(void*, const char*)

Count the number of IDs of a category.

New in version 9Oct2020.

This function counts how many IDs in the provided category are defined in the current LAMMPS instance. Please see lammps_has_id() for a list of valid categories.

Parameters:

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

  • category – category of IDs

Returns:

number of IDs in category

int lammps_id_name(void*, const char*, int, char*, int)

Look up the name of an ID by index in the list of IDs of a given category.

New in version 9Oct2020.

This function copies the name of the category ID with the index idx into the provided C-style string buffer. The length of the buffer must be provided as buf_size argument. If the name of the style exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an empty string, otherwise 1.

Parameters:

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

  • category – category of IDs

  • idx – index of the ID in the list of category styles (0 <= idx < count)

  • buffer – string buffer to copy the name of the style to

  • buf_size – size of the provided string buffer

Returns:

1 if successful, otherwise 0