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

4.14. Platform abstraction functions

The platform sub-namespace inside the LAMMPS_NS namespace provides a collection of wrapper and convenience functions and utilities that perform common tasks for which platform specific code would be required or for which a more high-level abstraction would be convenient and reduce duplicated code. This reduces redundant implementations and encourages consistent behavior and thus has some overlap with the “utils” sub-namespace.

4.14.1. Time functions

double LAMMPS_NS::platform::cputime()

Return the consumed CPU time for the current process in seconds

This is a wrapper around the POSIX function getrusage() and its Windows equivalent. It is to be used in a similar fashion than MPI_Wtime(). Its resolution may be rather low so it can only be trusted when observing processes consuming CPU time of at least a few seconds.

Returns:: used CPU time in seconds

double LAMMPS_NS::platform::walltime()

Return the wall clock state for the current process in seconds

This this clock is counting continuous time and is initialized during load of the executable/library. Its absolute value must be considered arbitrary and thus elapsed wall times are measured in taking differences. It is therefore to be used in a similar fashion as MPI_Wtime() but has a different offset, usually leading to better resolution.

Returns:: wall clock time in seconds

void LAMMPS_NS::platform::usleep(int usec)

Suspend execution for a microsecond interval

This emulates the usleep(3) BSD function call also mentioned in POSIX.1-2001. This is not a precise delay; it may be longer, but not shorter.

Parameters:: usec – length of delay in microseconds

4.14.2. Platform information functions

std::string LAMMPS_NS::platform::os_info()

Return string with the operating system version and architecture info

Returns:: string with info about the OS and the platform is is running on

std::string LAMMPS_NS::platform::compiler_info()

Return string with compiler version info

This function uses predefined compiler macros to identify Compilers and their version and configuration info.

Returns:: string with the compiler information text

std::string LAMMPS_NS::platform::cxx_standard()

Return string with C++ standard version used to compile LAMMPS.

This function uses predefined compiler macros to identify the C++ standard version used to compile LAMMPS with.

Returns:: string with the C++ standard version or “unknown”

std::string LAMMPS_NS::platform::openmp_standard()

Return string with OpenMP standard version info

This function uses predefined compiler macros to identify OpenMP support and the supported version of the standard.

Returns:: string with the openmp information text

std::string LAMMPS_NS::platform::mpi_vendor()

Return string with MPI vendor info

This function uses predefined macros to identify the vendor of the MPI library used.

Returns:: string with the MPI vendor information text

std::string LAMMPS_NS::platform::mpi_info(int &major, int &minor)

Return string with MPI version info

This function uses predefined macros and MPI function calls to identify the version of the MPI library used.

Parameters:

major – major version of the MPI standard (set on exit)
minor – minor version of the MPI standard (set on exit)

Returns:

string with the MPI version information text

std::string LAMMPS_NS::platform::compress_info()

Return string with list of available compression types and executables

This function tests which of the supported compression executables are available for reading or writing compressed files where supported.

Returns:: string with list of available compression tools

4.14.3. File and path functions and global constants

constexpr char LAMMPS_NS::platform::filepathsep[] = "/"

Platform specific file path component separator

This is a string with the character that separates directories and filename in paths on a platform. If multiple are characters are provided, the first is the preferred one.

constexpr char LAMMPS_NS::platform::pathvarsep = ':'

Platform specific path environment variable component separator

This is the character that separates entries in “PATH”-style environment variables.

const char *LAMMPS_NS::platform::guesspath(FILE *fp, char *buf, int len)

Try to detect pathname from FILE pointer

Currently only supported on Linux, MacOS, and Windows. Otherwise will report “(unknown)”.

On Linux the folder /proc/self/fd holds symbolic links to the actual pathnames associated with each open file descriptor of the current process. On MacOS the same kind of information can be obtained using fcntl(fd,F_GETPATH,buf). On Windows we use GetFinalPathNameByHandleA() which is available with Windows Vista and later. If the buffer is too small (< 16 bytes) a null pointer is returned.

This function is used to provide a filename with error messages in functions where the filename is not passed as an argument, but the FILE * pointer.

Parameters:

fp – FILE pointer struct from STDIO library for which we want to detect the name
buf – storage buffer for pathname. output will be truncated if not large enough
len – size of storage buffer. output will be truncated to this length - 1

Returns:

pointer to the storage buffer with path or a NULL pointer if buf is invalid or the buffer size is too small

std::string LAMMPS_NS::platform::path_basename(const std::string &path)

Strip off leading part of path, return just the filename

Parameters:: path – file path
Returns:: file name

std::string LAMMPS_NS::platform::path_join(const std::string &a, const std::string &b)

Join two pathname segments

This uses the forward slash ‘/’ character unless LAMMPS is compiled for Windows where it uses the backward slash ‘'

Parameters:

a – first path
b – second path

Returns:

combined path

bool LAMMPS_NS::platform::file_is_readable(const std::string &path)

Check if file exists and is readable

Parameters:: path – file path
Returns:: true if file exists and is readable

bool LAMMPS_NS::platform::is_console(FILE *fp)

Check if a file pointer may be connected to a console

Parameters:: fp – file pointer
Returns:: true if the file pointer is flagged as a TTY

double LAMMPS_NS::platform::disk_free(const std::string &path)

Return free disk space in bytes of file system pointed to by path

Returns -1.0 if the path is invalid or free space reporting not supported.

Parameters:: path – file or folder path in file system
Returns:

bool LAMMPS_NS::platform::path_is_directory(const std::string &path)

Check if a path is a directory

Parameters:: path – directory path
Returns:: true if the directory exists

std::string LAMMPS_NS::platform::current_directory()

Get string with path to the current directory

Returns:: path to the current directory or empty string

std::vector<std::string> LAMMPS_NS::platform::list_directory(const std::string &dir)

Get list of entries in a directory

This provides a list of strings of the entries in the directory without the leading path name while also skipping over “..” and “.”.

Parameters:: dir – path to directory
Returns:: vector with strings of all directory entries

int LAMMPS_NS::platform::chdir(const std::string &path)

Change current directory

Parameters:: path – new current working directory path
Returns:: -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS::platform::mkdir(const std::string &path)

Create a directory

Unlike the the mkdir() or _mkdir() functions of the C library, this function will also try to create non-existing sub-directories in case they don’t exist, and thus behave like the mkdir -p command rather than plain mkdir or `md.

Parameters:: path – directory path
Returns:: -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS::platform::rmdir(const std::string &path)

Delete a directory

Unlike the the rmdir() or _rmdir() functions of the C library, this function will check for the contents of the folder and recurse into any sub-folders, if necessary and delete all contained folders and their contents before deleting the folder path.

Parameters:: path – directory path
Returns:: -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS::platform::unlink(const std::string &path)

Delete a file

Parameters:: path – path to file to be deleted
Returns:: 0 on success, -1 on error

4.14.4. Standard I/O function wrappers

constexpr bigint LAMMPS_NS::platform::END_OF_FILE = -1: constant to seek to the end of the file

bigint LAMMPS_NS::platform::ftell(FILE *fp)

Get current file position

Parameters:: fp – FILE pointer of the given file
Returns:: current FILE pointer position cast to a bigint

int LAMMPS_NS::platform::fseek(FILE *fp, bigint pos)

Set absolute file position

If the absolute position is END_OF_FILE, then position at the end of the file.

Parameters:

fp – FILE pointer of the given file
pos – new position of the FILE pointer

Returns:

0 if successful, otherwise -1

int LAMMPS_NS::platform::ftruncate(FILE *fp, bigint length)

Truncate file to a given length and re-position file pointer

Parameters:

fp – FILE pointer of the given file
length – length to which the file is being truncated to

Returns:

0 if successful, otherwise -1

FILE *LAMMPS_NS::platform::popen(const std::string &cmd, const std::string &mode)

Open a pipe to a command for reading or writing

Parameters:

cmd – command for the pipe
mode – “r” for reading from cmd or “w” for writing to cmd

Returns:

file pointer to the pipe if successful or null

int LAMMPS_NS::platform::pclose(FILE *fp)

Close a previously opened pipe

Parameters:: fp – FILE pointer for the pipe
Returns:: exit status of the pipe command or -1 in case of errors

4.14.5. Environment variable functions

int LAMMPS_NS::platform::putenv(const std::string &vardef)

Add variable to the environment

Parameters:: vardef – variable name or variable definition (NAME=value)
Returns:: -1 if failure otherwise 0

int LAMMPS_NS::platform::unsetenv(const std::string &variable)

Delete variable from the environment

Parameters:: variable – variable name
Returns:: -1 if failure otherwise 0

std::vector<std::string> LAMMPS_NS::platform::list_pathenv(const std::string &var)

Get list of entries in a path environment variable

This provides a list of strings of the entries in an environment variable that is containing a “path” like “PATH” or “LD_LIBRARY_PATH”.

Parameters:: var – name of the environment variable
Returns:: vector with strings of all entries in that path variable

std::string LAMMPS_NS::platform::find_exe_path(const std::string &cmd)

Find pathname of an executable in the standard search path

This function will traverse the list of directories in the PATH environment variable and look for the executable cmd. If the file exists and is executable the full path is returned as string, otherwise and empty string is returned.

On Windows the cmd string must not include and extension as this function will automatically append the extensions “.exe”, “.com” and “.bat” and look for those paths. On Windows also the current directory is checked (and first), while otherwise not unless “.” exists in the PATH environment variable.

Because of the nature of the check, this will not detect shell functions built-in command or aliases.

Parameters:: cmd – name of command
Returns:: vector with strings of all directory entries

4.14.6. Dynamically loaded object or library functions

void *LAMMPS_NS::platform::dlopen(const std::string &fname)

Open a shared object file or library

Parameters:: fname – name or path of the shared object
Returns:: handle to the shared object or null

int LAMMPS_NS::platform::dlclose(void *handle)

Close a shared object

This releases the object corresponding to the provided handle. Resolved symbols associated with this handle may not be used after this call

Parameters:: handle – handle to an opened shared object
Returns:: 0 if successful, non-zero of not

void *LAMMPS_NS::platform::dlsym(void *handle, const std::string &symbol)

Resolve a symbol in shared object

Parameters:

handle – handle to an opened shared object
symbol – name of the symbol to extract

Returns:

pointer to the resolved symbol or null

std::string LAMMPS_NS::platform::dlerror()

Obtain error diagnostic info after dynamic linking function calls

Return a human-readable string describing the most recent error that occurred when using one of the functions for dynamic loading objects the last call to this function. The string is empty, if there was no error.

Returns:: string with error message or empty

4.14.7. Compressed file I/O functions

bool LAMMPS_NS::platform::has_compress_extension(const std::string &file)

Check if a file name ends in a known extension for a compressed file format

Currently supported file extensions are: .gz, .bz2, .zst, .xz, .lzma, lz4

Parameters:: file – name of the file to check
Returns:: true if the file has a known extension, otherwise false

FILE *LAMMPS_NS::platform::compressed_read(const std::string &file)

Open pipe to compressed text file for reading

Parameters:: file – name of the file to open
Returns:: FILE pointer to pipe using for reading the compressed file.

FILE *LAMMPS_NS::platform::compressed_write(const std::string &file)

Open pipe to compressed text file for writing

Parameters:: file – name of the file to open
Returns:: FILE pointer to pipe using for reading the compressed file.