ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update and correct documentation for utils functions

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-08-29 23:51:46 -04:00
parent 9c404e02fd
commit ceeaf1e988
2 changed files with 92 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
doc/src/pg_developer.rst
View File

@ -753,8 +753,8 @@ reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior. reduces redundant implementations and encourages consistent behavior.
I/O functions with validity check I/O with status check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are wrappers around the corresponding C library calls like These are wrappers around the corresponding C library calls like
``fgets()`` or ``fread()``. They will check if there were errors ``fgets()`` or ``fread()``. They will check if there were errors
@ -771,19 +771,21 @@ indicating the name of the problematic file, if possible.
String to number conversions with validity check String to number conversions with validity check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are functions equivalent to those in the ``Force`` class that These functions should be used to convert strings to numbers. They are
were implemented with the aim to replace and supersede those. Unlike are strongly preferred over C library calls like ``atoi()`` or
the versions in ``Force``, these can be used in cases where only
a single MPI rank is trying to convert strings to numbers, as you
can select through an argument, whether ``Error->all()`` or ``Error->one()``
should be called on improper strings.
These functions are preferred over C library calls like ``atoi()`` or
``atof()`` since they check if the **entire** provided string is a valid ``atof()`` since they check if the **entire** provided string is a valid
(floating-point or integer) number, and will error out instead of silently (floating-point or integer) number, and will error out instead of
return the result of a partial conversion or zero in cases where the silently returning the result of a partial conversion or zero in cases
string is not a valid number. This behavior allows to more easily detect where the string is not a valid number. This behavior allows to more
typos or issues when processing input files. easily detect typos or issues when processing input files.
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 :cpp:func:`is_integer` and :cpp:func:`is_double` for
testing strings for compliance without conversion.
.. doxygenfunction:: numeric .. doxygenfunction:: numeric
:project: progguide :project: progguide
@ -798,8 +800,9 @@ typos or issues when processing input files.
:project: progguide :project: progguide
String processing functions String processing
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
The following are functions to help with processing strings The following are functions to help with processing strings
and parsing files or arguments. and parsing files or arguments.
@ -833,8 +836,8 @@ and parsing files or arguments.
.. doxygenfunction:: is_double .. doxygenfunction:: is_double
:project: progguide :project: progguide
Filename and path functions File and path functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: guesspath .. doxygenfunction:: guesspath
:project: progguide :project: progguide
@ -869,8 +872,8 @@ Potential file functions
.. doxygenfunction:: open_potential .. doxygenfunction:: open_potential
:project: progguide :project: progguide
Argument processing functions Argument processing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: bounds .. doxygenfunction:: bounds
:project: progguide :project: progguide

135
src/utils.h
View File

@ -133,62 +133,59 @@ namespace LAMMPS_NS {
/** Convert a string to an integer number while checking /** Convert a string to an integer number while checking
* if it is a valid integer number (tagint) * if it is a valid integer number (tagint)
* *
* \param file name of source file for error message * \param file name of source file for error message
* \param line line number in source file for error message * \param line line number in source file for error message
* \param str string to be converted to number * \param str string to be converted to number
* \param do_abort determines whether to call Error::one() or Error::all() * \param do_abort determines whether to call Error::one() or Error::all()
* \param lmp pointer to top-level LAMMPS class instance * \param lmp pointer to top-level LAMMPS class instance
* \return integer number (tagint) * \return integer number (tagint) */
*/
tagint tnumeric(const char *file, int line, const char *str, tagint tnumeric(const char *file, int line, const char *str,
bool do_abort, LAMMPS *lmp); bool do_abort, LAMMPS *lmp);
/** Compute index bounds derived from a string with a possible wildcard /** Compute index bounds derived from a string with a possible wildcard
* *
\verbatim embed:rst * This functions processes the string in *str* and set the values of *nlo*
* and *nhi* according to the following five cases:
*
* - a single number *i*: nlo = i; nhi = i;
* - a single asterisk \*: nlo = nmin; nhi = nmax;
* - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax;
* - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i;
* - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j;
*
* \param file name of source file for error message
* \param line line number in source file for error message
* \param str string to be processed
* \param nmin smallest possible lower bound
* \param nmax largest allowed upper bound
* \param nlo lower bound
* \param nhi upper bound
* \param error pointer to Error class for out-of-bounds messages */
This functions processes the string in *str* and set the values of *nlo*
and *nhi* according to the following five cases:
#. a single number *i*: nlo = i; nhi = i;
#. a single asterisk *\*\ *: nlo = nmin; nhi = nmax;
#. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax;
#. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i;
#. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j;
\endverbatim
* \param file name of source file for error message
* \param line line number in source file for error message
* \param str string to be processed
* \param nmin smallest possible lower bound
* \param nmax largest allowed upper bound
* \param nlo lower bound
* \param nhi upper bound
* \param error pointer to Error class for out-of-bounds error message
*/
void bounds(const char *file, int line, char *str, void bounds(const char *file, int line, char *str,
int nmin, int nmax, int &nlo, int &nhi, Error *error); int nmin, int nmax, int &nlo, int &nhi, Error *error);
/** Compute index bounds derived from a string with a possible wildcard /** Compute index bounds derived from a string with a possible wildcard
* *
\verbatim embed:rst * This functions processes the string in *str* and set the values of *nlo*
This functions processes the string in *str* and set the values of *nlo* * and *nhi* according to the following five cases:
and *nhi* according to the following five cases: *
#. a single number *i*: nlo = i; nhi = i; * - a single number *i*: nlo = i; nhi = i;
#. a single asterisk *\*\ *: nlo = nmin; nhi = nmax; * - a single asterisk \*: nlo = nmin; nhi = nmax;
#. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax; * - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax;
#. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i; * - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i;
#. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j; * - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j;
\endverbatim *
* \param file name of source file for error message
* \param line line number in source file for error message
* \param str string to be processed
* \param nmin smallest possible lower bound
* \param nmax largest allowed upper bound
* \param nlo lower bound
* \param nhi upper bound
* \param error pointer to Error class for out-of-bounds messages */
* \param file name of source file for error message
* \param line line number in source file for error message
* \param str string to be processed
* \param nmin smallest possible lower bound
* \param nmax largest allowed upper bound
* \param nlo lower bound
* \param nhi upper bound
* \param error pointer to Error class for out-of-bounds error message
*/
void boundsbig(const char *file, int line, char *str, void boundsbig(const char *file, int line, char *str,
bigint nmin, bigint nmax, bigint &nlo, bigint &nhi, bigint nmin, bigint nmax, bigint &nlo, bigint &nhi,
Error *error); Error *error);
@ -209,15 +206,15 @@ and *nhi* according to the following five cases:
* caller. Otherwise arg and earg will point to the same address * caller. Otherwise arg and earg will point to the same address
* and no explicit de-allocation is needed by the caller. * and no explicit de-allocation is needed by the caller.
* *
* \param file name of source file for error message * \param file name of source file for error message
* \param line line number in source file for error message * \param line line number in source file for error message
* \param narg number of arguments in current list * \param narg number of arguments in current list
* \param arg argument list, possibly containing wildcards * \param arg argument list, possibly containing wildcards
* \param mode select between global vectors(=0) and arrays (=1) * \param mode select between global vectors(=0) and arrays (=1)
* \param earg new argument list with wildcards expanded * \param earg new argument list with wildcards expanded
* \param lmp pointer to top-level LAMMPS class instance * \param lmp pointer to top-level LAMMPS class instance
* \return number of arguments in expanded list * \return number of arguments in expanded list */
*/
int expand_args(const char *file, int line, int narg, char **arg, int expand_args(const char *file, int line, int narg, char **arg,
int mode, char **&earg, LAMMPS *lmp); int mode, char **&earg, LAMMPS *lmp);
@ -326,7 +323,7 @@ and *nhi* according to the following five cases:
bool file_is_readable(const std::string &path); bool file_is_readable(const std::string &path);
/** Determine full path of potential file. If file is not found in current directory, /** Determine full path of potential file. If file is not found in current directory,
* search LAMMPS_POTENTIALS folder * search directories listed in LAMMPS_POTENTIALS environment variable
* *
* \param path file path * \param path file path
* \return full path to potential file * \return full path to potential file
@ -369,19 +366,25 @@ and *nhi* according to the following five cases:
/** Open a potential file as specified by *name* /** Open a potential file as specified by *name*
* *
\verbatim embed:rst * If opening the file directly fails, the function will search for
If opening the file directly fails, it will search for it in the folder(s) * it in the list of folder pointed to by the environment variable
pointed to by the environment variable LAMMPS_POTENTIALS. * LAMMPS_POTENTIALS (if it is set).
If the potential file has a ``UNITS`` tag in the first line, its
value is compared to the current :doc:`unit style <units>` setting.
\endverbatim
* *
* \param name file- or pathname of the potential file * If the potential file has a ``UNITS`` tag in the first line, the
* \param lmp pointer to top-level LAMMPS class instance * tag's value is compared to the current unit style setting.
* \param auto_convert pointer to automatic unit conversion bitmask * The behavior of the function then depends on the value of the
* \return FILE pointer of the opened potential file or NULL * *auto_convert* parameter. If it is ``NULL``, then the unit values
*/ * must match or else the open will fail with an error. Otherwise
* the bitmask that *auto_convert* points to is used check for
* compatibility with possible automatic conversions by the calling
* function. If compatible, the bitmask is set to the required
* conversion or ``NOCONVERT``.
*
* \param name file- or pathname of the potential file
* \param lmp pointer to top-level LAMMPS class instance
* \param auto_convert pointer to unit conversion bitmask or NULL
* \return FILE pointer of the opened potential file or NULL*/
FILE *open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert); FILE *open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert);
/** Convert a time string to seconds /** Convert a time string to seconds