\(\renewcommand{\AA}{\text{Å}}\)
1.1.8. Configuration information
This section documents the following functions:
lammps_gpu_device_info()
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.
#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 TBD: 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 vialammps_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 thenvc_get_device
orocl_get_device
orhip_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