# Utility functions The `utils` sub-namespace inside the `LAMMPS_NS` namespace provides a collection of convenience functions and utilities that perform common tasks that are required repeatedly throughout the LAMMPS code like reading or writing to files with error checking or translation of strings into specific types of numbers with checking for validity. This reduces redundant implementations and encourages consistent behavior and thus has some overlap with the [\"platform\" sub-namespace](Developer_platform). ## I/O with status check and similar functions The the first two functions are wrappers around the corresponding C library calls `fgets()` or `fread()`. They will check if there were errors on reading or an unexpected end-of-file state was reached. In that case, the functions will stop with an error message, indicating the name of the problematic file, if possible unless the *error* argument is a NULL pointer. The `utils::fgets_trunc() `{.interpreted-text role="cpp:func"}\_\_ function will work similar for `fgets()` but it will read in a whole line (i.e. until the end of line or end of file), but store only as many characters as will fit into the buffer including a final newline character and the terminating NULL byte. If the line in the file is longer it will thus be truncated in the buffer. This function is used by `utils::read_lines_from_file() `{.interpreted-text role="cpp:func"}\_\_ to read individual lines but make certain they follow the size constraints. The `utils::read_lines_from_file() `{.interpreted-text role="cpp:func"}\_\_ function will read the requested number of lines of a maximum length into a buffer and will return 0 if successful or 1 if not. It also guarantees that all lines are terminated with a newline character and the entire buffer with a NULL character. ------------------------------------------------------------------------ ::: {.doxygenfunction project="progguide"} sfgets ::: ::: {.doxygenfunction project="progguide"} sfread ::: ::: {.doxygenfunction project="progguide"} fgets_trunc ::: ::: {.doxygenfunction project="progguide"} read_lines_from_file ::: ------------------------------------------------------------------------ ## String to number conversions with validity check These functions should be used to convert strings to numbers. They are are strongly preferred over C library calls like `atoi()` or `atof()` since they check if the **entire** string is a valid (floating-point or integer) number, and will error out instead of silently returning the result of a partial conversion or zero in cases where the string is not a valid number. This behavior improves detecting typos or issues when processing input files. Similarly the `utils::logical() `{.interpreted-text role="cpp:func"}\_\_ function will convert a string into a boolean and will only accept certain words. The *do_abort* flag should be set to `true` in case this function is called only on a single MPI rank, as that will then trigger the a call to `Error::one()` for errors instead of `Error::all()` and avoids a \"hanging\" calculation when run in parallel. Please also see `utils::is_integer() `{.interpreted-text role="cpp:func"}\_\_ and `utils::is_double() `{.interpreted-text role="cpp:func"}\_\_ for testing strings for compliance without conversion. ------------------------------------------------------------------------ ::: {.doxygenfunction project="progguide"} numeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS*lmp) ::: ::: {.doxygenfunction project="progguide"} numeric(const char *file, int line, const char*str, bool do_abort, LAMMPS \*lmp) ::: ::: {.doxygenfunction project="progguide"} inumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS*lmp) ::: ::: {.doxygenfunction project="progguide"} inumeric(const char *file, int line, const char*str, bool do_abort, LAMMPS \*lmp) ::: ::: {.doxygenfunction project="progguide"} bnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS*lmp) ::: ::: {.doxygenfunction project="progguide"} bnumeric(const char *file, int line, const char*str, bool do_abort, LAMMPS \*lmp) ::: ::: {.doxygenfunction project="progguide"} tnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS*lmp) ::: ::: {.doxygenfunction project="progguide"} tnumeric(const char *file, int line, const char*str, bool do_abort, LAMMPS \*lmp) ::: ::: {.doxygenfunction project="progguide"} logical(const char *file, int line, const std::string &str, bool do_abort, LAMMPS*lmp) ::: ::: {.doxygenfunction project="progguide"} logical(const char *file, int line, const char*str, bool do_abort, LAMMPS \*lmp) ::: ## String processing The following are functions to help with processing strings and parsing files or arguments. ------------------------------------------------------------------------ ::: {.doxygenfunction project="progguide"} strdup ::: ::: {.doxygenfunction project="progguide"} lowercase ::: ::: {.doxygenfunction project="progguide"} uppercase ::: ::: {.doxygenfunction project="progguide"} trim ::: ::: {.doxygenfunction project="progguide"} trim_comment ::: ::: {.doxygenfunction project="progguide"} strip_style_suffix ::: ::: {.doxygenfunction project="progguide"} star_subst ::: ::: {.doxygenfunction project="progguide"} has_utf8 ::: ::: {.doxygenfunction project="progguide"} utf8_subst ::: ::: {.doxygenfunction project="progguide"} count_words(const char \*text) ::: ::: {.doxygenfunction project="progguide"} count_words(const std::string &text) ::: ::: {.doxygenfunction project="progguide"} count_words(const std::string &text, const std::string &separators) ::: ::: {.doxygenfunction project="progguide"} trim_and_count_words ::: ::: {.doxygenfunction project="progguide"} join_words ::: ::: {.doxygenfunction project="progguide"} split_words ::: ::: {.doxygenfunction project="progguide"} split_lines ::: ::: {.doxygenfunction project="progguide"} strmatch ::: ::: {.doxygenfunction project="progguide"} strfind ::: ::: {.doxygenfunction project="progguide"} is_integer ::: ::: {.doxygenfunction project="progguide"} is_double ::: ::: {.doxygenfunction project="progguide"} is_id ::: ::: {.doxygenfunction project="progguide"} is_type ::: ## Potential file functions ::: {.doxygenfunction project="progguide"} get_potential_file_path ::: ::: {.doxygenfunction project="progguide"} get_potential_date ::: ::: {.doxygenfunction project="progguide"} get_potential_units ::: ::: {.doxygenfunction project="progguide"} get_supported_conversions ::: ::: {.doxygenfunction project="progguide"} get_conversion_factor ::: ::: {.doxygenfunction project="progguide"} open_potential(const std::string &name, LAMMPS *lmp, int*auto_convert) ::: ## Argument processing ::: {.doxygenfunction project="progguide"} bounds ::: ::: {.doxygenfunction project="progguide"} expand_args ::: ::: {.doxygenfunction project="progguide"} parse_grid_id ::: ::: {.doxygenfunction project="progguide"} expand_type ::: ## Convenience functions ::: {.doxygenfunction project="progguide"} logmesg(LAMMPS \*lmp, const std::string &format, Args&&\... args) ::: ::: {.doxygenfunction project="progguide"} logmesg(LAMMPS \*lmp, const std::string &mesg) ::: ::: {.doxygenfunction project="progguide"} errorurl ::: ::: {.doxygenfunction project="progguide"} missing_cmd_args ::: ::: {.doxygenfunction project="progguide"} flush_buffers(LAMMPS \*lmp) ::: ::: {.doxygenfunction project="progguide"} getsyserror ::: ::: {.doxygenfunction project="progguide"} check_packages_for_style ::: ::: {.doxygenfunction project="progguide"} timespec2seconds ::: ::: {.doxygenfunction project="progguide"} date2num ::: ::: {.doxygenfunction project="progguide"} current_date ::: ## Customized standard functions ::: {.doxygenfunction project="progguide"} binary_search ::: ::: {.doxygenfunction project="progguide"} merge_sort ::: ------------------------------------------------------------------------ # Special Math functions The `MathSpecial` namespace implements a selection of custom and optimized mathematical functions for a variety of applications. ::: {.doxygenfunction project="progguide"} factorial ::: ::: {.doxygenfunction project="progguide"} exp2_x86 ::: ::: {.doxygenfunction project="progguide"} fm_exp ::: ::: {.doxygenfunction project="progguide"} my_erfcx ::: ::: {.doxygenfunction project="progguide"} expmsq ::: ::: {.doxygenfunction project="progguide"} square ::: ::: {.doxygenfunction project="progguide"} cube ::: ::: {.doxygenfunction project="progguide"} powsign ::: ::: {.doxygenfunction project="progguide"} powint ::: ::: {.doxygenfunction project="progguide"} powsinxx ::: ------------------------------------------------------------------------ # Tokenizer classes The purpose of the tokenizer classes is to simplify the recurring task of breaking lines of text down into words and/or numbers. Traditionally, LAMMPS code would be using the `strtok()` function from the C library for that purpose, but that function has two significant disadvantages: 1) it cannot be used concurrently from different LAMMPS instances since it stores its status in a global variable and 2) it modifies the string that it is processing. These classes were implemented to avoid both of these issues and also to reduce the amount of code that needs to be written. The basic procedure is to create an instance of the tokenizer class with the string to be processed as an argument and then do a loop until all available tokens are read. The constructor has a default set of separator characters, but that can be overridden. The default separators are all \"whitespace\" characters, i.e. the space character, the tabulator character, the carriage return character, the linefeed character, and the form feed character. ``` {.c++ caption="Tokenizer class example listing entries of the PATH environment variable"} #include "tokenizer.h" #include #include #include using namespace LAMMPS_NS; int main(int, char **) { const char *path = getenv("PATH"); if (path != nullptr) { Tokenizer p(path,":"); while (p.has_next()) std::cout << "Entry: " << p.next() << "\n"; } return 0; } ``` Most tokenizer operations cannot fail except for `LAMMPS_NS::Tokenizer::next`{.interpreted-text role="cpp:func"} (when used without first checking with `LAMMPS_NS::Tokenizer::has_next`{.interpreted-text role="cpp:func"}) and `LAMMPS_NS::Tokenizer::skip`{.interpreted-text role="cpp:func"}. In case of failure, the class will throw an exception, so you may need to wrap the code using the tokenizer into a `try` / `catch` block to handle errors. The `LAMMPS_NS::ValueTokenizer`{.interpreted-text role="cpp:class"} class may also throw an exception when a (type of) number is requested as next token that is not compatible with the string representing the next word. ``` {.c++ caption="ValueTokenizer class example with exception handling"} #include "tokenizer.h" #include #include #include using namespace LAMMPS_NS; int main(int, char **) { const char *text = "1 2 3 4 5 20.0 21 twentytwo 2.3"; double num1(0),num2(0),num3(0),num4(0); ValueTokenizer t(text); // read 4 doubles after skipping over 5 numbers try { t.skip(5); num1 = t.next_double(); num2 = t.next_double(); num3 = t.next_double(); num4 = t.next_double(); } catch (TokenizerException &e) { std::cout << "Reading numbers failed: " << e.what() << "\n"; } std::cout << "Values: " << num1 << " " << num2 << " " << num3 << " " << num4 << "\n"; return 0; } ``` This code example should produce the following output: ``` Reading numbers failed: Not a valid floating-point number: 'twentytwo' Values: 20 21 0 0 ``` ------------------------------------------------------------------------ ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::Tokenizer ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::TokenizerException ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::ValueTokenizer ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::InvalidIntegerException ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::InvalidFloatException ::: ------------------------------------------------------------------------ # Argument parsing classes The purpose of argument parsing classes it to simplify and unify how arguments of commands in LAMMPS are parsed and to make abstractions of repetitive tasks. The `LAMMPS_NS::ArgInfo`{.interpreted-text role="cpp:class"} class provides an abstraction for parsing references to compute or fix styles, variables or custom integer or double properties handled by [fix property/atom](fix_property_atom). These would start with a \"c\_\", \"f\_\", \"v\_\", \"d\_\", \"d2\_\", \"i\_\", or \"i2\_\" followed by the ID or name of than instance and may be postfixed with one or two array indices \"\[\\]\" with numbers \> 0. A typical code segment would look like this: ``` {.c++ caption="Usage example for ArgInfo class"} int nvalues = 0; for (iarg = 0; iarg < nargnew; iarg++) { ArgInfo argi(arg[iarg]); which[nvalues] = argi.get_type(); argindex[nvalues] = argi.get_index1(); ids[nvalues] = argi.copy_name(); if ((which[nvalues] == ArgInfo::UNKNOWN) || (which[nvalues] == ArgInfo::NONE) || (argi.get_dim() > 1)) error->all(FLERR,"Illegal compute XXX command"); nvalues++; } ``` ------------------------------------------------------------------------ ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::ArgInfo ::: ------------------------------------------------------------------------ # File reader classes The purpose of the file reader classes is to simplify the recurring task of reading and parsing files. They can use the `ValueTokenizer `{.interpreted-text role="cpp:class"}\_\_ class to process the read in text. The `TextFileReader `{.interpreted-text role="cpp:class"}\_\_ is a more general version while `PotentialFileReader `{.interpreted-text role="cpp:class"}\_\_ is specialized to implement the behavior expected for looking up and reading/parsing files with potential parameters in LAMMPS. The potential file reader class requires a LAMMPS instance, requires to be run on MPI rank 0 only, will use the `utils::get_potential_file_path `{.interpreted-text role="cpp:func"}\_\_ function to look up and open the file, and will call the `LAMMPS_NS::Error`{.interpreted-text role="cpp:class"} class in case of failures to read or to convert numbers, so that LAMMPS will be aborted. ``` {.c++ caption="Use of PotentialFileReader class in pair style coul/streitz"} PotentialFileReader reader(lmp, file, "coul/streitz"); char * line; while((line = reader.next_line(NPARAMS_PER_LINE))) { try { ValueTokenizer values(line); std::string iname = values.next_string(); int ielement; for (ielement = 0; ielement < nelements; ielement++) if (iname == elements[ielement]) break; if (nparams == maxparam) { maxparam += DELTA; params = (Param *) memory->srealloc(params,maxparam*sizeof(Param), "pair:params"); } params[nparams].ielement = ielement; params[nparams].chi = values.next_double(); params[nparams].eta = values.next_double(); params[nparams].gamma = values.next_double(); params[nparams].zeta = values.next_double(); params[nparams].zcore = values.next_double(); } catch (TokenizerException & e) { error->one(FLERR, e.what()); } nparams++; } ``` A file that would be parsed by the reader code fragment looks like this: # DATE: 2015-02-19 UNITS: metal CONTRIBUTOR: Ray Shan CITATION: Streitz and Mintmire, Phys Rev B, 50, 11996-12003 (1994) # # X (eV) J (eV) gamma (1/\AA) zeta (1/\AA) Z (e) Al 0.000000 10.328655 0.000000 0.968438 0.763905 O 5.484763 14.035715 0.000000 2.143957 0.000000 ------------------------------------------------------------------------ ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::TextFileReader ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::PotentialFileReader ::: ------------------------------------------------------------------------ # Memory pool classes The memory pool classes are used for cases where otherwise many small memory allocations would be needed and where the data would be either all used or all freed. One example for that is the storage of neighbor lists. The memory management strategy is based on the assumption that allocations will be in chunks of similar sizes. The allocation is then not done per individual call for a reserved chunk of memory, but for a \"page\" that can hold multiple chunks of data. A parameter for the maximum chunk size must be provided, as that is used to determine whether a new page of memory must be used. The `MyPage `{.interpreted-text role="cpp:class"}\_\_ class offers two ways to reserve a chunk: 1) with `MyPage::get() `{.interpreted-text role="cpp:func"}\_\_ the chunk size needs to be known in advance, 2) with `MyPage::vget() `{.interpreted-text role="cpp:func"}\_\_ a pointer to the next chunk is returned, but its size is registered later with `MyPage::vgot() `{.interpreted-text role="cpp:func"}\_\_. ``` {.c++ caption="Example of using :cpp:class:`MyPage `__"} #include "my_page.h" using namespace LAMMPS_NS; MyPage *dpage = new MyPage; // max size of chunk: 256, size of page: 10240 doubles (=81920 bytes) dpage->init(256,10240); double **build_some_lists(int num) { dpage->reset(); double **dlist = new double*[num]; for (int i=0; i < num; ++i) { double *dptr = dpage.vget(); int jnum = 0; for (int j=0; j < jmax; ++j) { // compute some dvalue for eligible loop index j dptr[j] = dvalue; ++jnum; } if (dpage.status() != 0) { // handle out of memory or jnum too large errors } dpage.vgot(jnum); dlist[i] = dptr; } return dlist; } ``` ------------------------------------------------------------------------ ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::MyPage ::: ::: {.doxygenclass project="progguide" members=""} LAMMPS_NS::MyPoolChunk ::: ------------------------------------------------------------------------ # Eigensolver functions The `MathEigen` sub-namespace of the `LAMMPS_NS` namespace contains functions and classes for eigensolvers. Currently only the `jacobi3 function `{.interpreted-text role="cpp:func"}\_\_ is used in various places in LAMMPS. That function is built on top of a group of more generic eigensolvers that are maintained in the `math_eigen_impl.h` header file. This header contains the implementation of three template classes: 1. \"Jacobi\" calculates all of the eigenvalues and eigenvectors of a dense, symmetric, real matrix. 2. The \"PEigenDense\" class only calculates the principal eigenvalue (ie. the largest or smallest eigenvalue), and its corresponding eigenvector. However it is much more efficient than \"Jacobi\" when applied to large matrices (larger than 13x13). PEigenDense also can understand complex-valued Hermitian matrices. 3. The \"LambdaLanczos\" class is a generalization of \"PEigenDense\" which can be applied to arbitrary sparse matrices. The \"math_eigen_impl.h\" code is an amalgamation of [jacobi_pd](https://github.com/jewettaij/jacobi_pd)\_ by Andrew Jewett at Scripps Research (under CC0-1.0 license) and [Lambda Lanczos](https://github.com/mrcdr/lambda-lanczos)\_ by Yuya Kurebayashi at Tohoku University (under MIT license) ------------------------------------------------------------------------ ::: {.doxygenfunction project="progguide"} MathEigen::jacobi3(double const *const*mat, double *eval, double*\*evec) ::: ::: {.doxygenfunction project="progguide"} MathEigen::jacobi3(double const mat\[3\]\[3\], double \*eval, double evec\[3\]\[3\]) ::: ------------------------------------------------------------------------ # Communication buffer coding with *ubuf* {#communication_buffer_coding_with_ubuf} LAMMPS uses communication buffers where it collects data from various class instances and then exchanges the data with neighboring subdomains. For simplicity those buffers are defined as `double` buffers and used for doubles and integer numbers. This presents a unique problem when 64-bit integers are used. While the storage needed for a `double` is also 64-bit, it cannot be used by a simple assignment. To get around that limitation, LAMMPS uses the `ubuf `{.interpreted-text role="cpp:union"}\_\_ union. It is used in the various \"pack\" and \"unpack\" functions in the LAMMPS classes to store and retrieve integers that may be 64-bit from the communication buffers. ------------------------------------------------------------------------ ::: {.doxygenunion project="progguide"} LAMMPS_NS::ubuf :::