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

add documentation for potential file reader

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-08-31 07:31:28 -04:00
parent 33f2cbc713
commit c84033677c
5 changed files with 98 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/doxygen/Doxyfile.in
View File

@ -426,6 +426,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/tokenizer.h \
@LAMMPS_SOURCE_DIR@/text_file_reader.cpp \
@LAMMPS_SOURCE_DIR@/text_file_reader.h \
@LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \
@LAMMPS_SOURCE_DIR@/potential_file_reader.h \
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

19
doc/src/pg_developer.rst
View File

@ -1005,9 +1005,18 @@ File reader classes
====================
The purpose of the file reader classes is to simplify the recurring task
of reading and parsing files. They are built on top of the tokenizer
classes discussed in the previous section, but include operations that
are optimized for processing larger chunks of data more efficiently.
of reading and parsing files. They can use the
:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in
text. The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general
version while :cpp:class:`LAMMPS_NS::PotentialFileReader` 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 :cpp:func:`utils::get_potential_file_path` function to look up and
open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
case of failures to read or to convert numbers, so that LAMMPS will be
aborted.
----------
@ -1015,3 +1024,7 @@ are optimized for processing larger chunks of data more efficiently.
:project: progguide
:members:
.. doxygenclass:: LAMMPS_NS::PotentialFileReader
:project: progguide
:members:

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -2916,6 +2916,7 @@ strstr
Stukowski
Su
subbox
Subclassed
subcutoff
subcycle
subcycling

76
src/potential_file_reader.cpp
View File

@ -29,6 +29,19 @@
using namespace LAMMPS_NS;
/** Class for reading and parsing LAMMPS potential files
*
* The value of the class member variable *ignore_comments* controls
* whether any text following the pound sign (#) should be ignored (true)
* or not (false). Default: true, i.e. ignore.
*
* \param lmp Pointer to LAMMPS instance
* \param filename Name of file to be read
* \param potential_name Name of potential style for error messages
* \param auto_convert Bitmask of supported unit conversions
*
* \sa TextFileReader */
PotentialFileReader::PotentialFileReader(LAMMPS *lmp,
const std::string &filename,
const std::string &potential_name,
@ -53,14 +66,21 @@ PotentialFileReader::PotentialFileReader(LAMMPS *lmp,
}
}
/** Closes the file */
PotentialFileReader::~PotentialFileReader() {
delete reader;
}
/** Set comment (= text after '#') handling preference for the file to be read
*
* \param value Comment text is ignored if true, or not if false */
void PotentialFileReader::ignore_comments(bool value) {
reader->ignore_comments = value;
}
/** Read a line but ignore its content */
void PotentialFileReader::skip_line() {
try {
reader->skip_line();
@ -69,6 +89,17 @@ void PotentialFileReader::skip_line() {
}
}
/** Read the next line(s) until *nparams* words have been read.
*
* This reads a line and counts the words in it, if the number
* is less than the requested number, it will read the next
* line, as well. Output will be a string with all read lines
* combined. The purpose is to somewhat replicate the reading
* behavior of formatted files in Fortran.
*
* \param nparams Number of words that must be read. Default: 0
* \return String with the concatenated text */
char *PotentialFileReader::next_line(int nparams) {
try {
return reader->next_line(nparams);
@ -78,6 +109,15 @@ char *PotentialFileReader::next_line(int nparams) {
return nullptr;
}
/** Read lines until *n* doubles have been read and stored in array *list*
*
* This reads lines from the file using the next_line() function,
* and splits them into floating-point numbers using the
* ValueTokenizer class and stores the number is the provided list.
*
* \param list Pointer to array with suitable storage for *n* doubles
* \param n Number of doubles to be read */
void PotentialFileReader::next_dvector(double * list, int n) {
try {
return reader->next_dvector(list, n);
@ -86,6 +126,16 @@ void PotentialFileReader::next_dvector(double * list, int n) {
}
}
/** Read text until *nparams* words are read and passed to a tokenizer object for custom parsing.
*
* This reads lines from the file using the next_line() function,
* and splits them into floating-point numbers using the
* ValueTokenizer class and stores the number is the provided list.
*
* \param nparams Number of words to be read
* \param separators String with list of separators.
* \return ValueTokenizer object for read in text */
ValueTokenizer PotentialFileReader::next_values(int nparams, const std::string & separators) {
try {
return reader->next_values(nparams, separators);
@ -95,6 +145,10 @@ ValueTokenizer PotentialFileReader::next_values(int nparams, const std::string &
return ValueTokenizer("");
}
/** Read next line and convert first word to a double
*
* \return Value of first word in line as double */
double PotentialFileReader::next_double() {
try {
char * line = reader->next_line(1);
@ -105,6 +159,10 @@ double PotentialFileReader::next_double() {
return 0.0;
}
/** Read next line and convert first word to an int
*
* \return Value of first word in line as int */
int PotentialFileReader::next_int() {
try {
char * line = reader->next_line(1);
@ -115,6 +173,10 @@ int PotentialFileReader::next_int() {
return 0;
}
/** Read next line and convert first word to a tagint
*
* \return Value of first word in line as tagint */
tagint PotentialFileReader::next_tagint() {
try {
char * line = reader->next_line(1);
@ -125,6 +187,10 @@ tagint PotentialFileReader::next_tagint() {
return 0;
}
/** Read next line and convert first word to a bigint
*
* \return Value of first word in line as bigint */
bigint PotentialFileReader::next_bigint() {
try {
char * line = reader->next_line(1);
@ -135,6 +201,10 @@ bigint PotentialFileReader::next_bigint() {
return 0;
}
/** Read next line and return first word
*
* \return First word of read in line */
std::string PotentialFileReader::next_string() {
try {
char * line = reader->next_line(1);
@ -145,6 +215,12 @@ std::string PotentialFileReader::next_string() {
return "";
}
/** Look up and open the potential file
*
* \param path Path of the potential file to open
* \return Pointer to TextFileReader object created
* \sa TextFileReader */
TextFileReader *PotentialFileReader::open_potential(const std::string &path) {
std::string filepath = utils::get_potential_file_path(path);

6
src/tokenizer.cpp
View File

@ -58,7 +58,7 @@ Tokenizer::Tokenizer(Tokenizer && rhs) :
reset();
}
/*! Reposition the tokenizer state to the first word,
/*! Re-position the tokenizer state to the first word,
* i.e. the first non-separator character */
void Tokenizer::reset() {
start = text.find_first_not_of(separators);
@ -150,8 +150,8 @@ std::vector<std::string> Tokenizer::as_vector() {
/*! Class for reading text with numbers
*
* \param str string to be processed
* \param separators string with separator characters (default: " \t\r\n\f")
* \param str String to be processed
* \param separators String with separator characters (default: " \t\r\n\f")
*
* \sa Tokenizer InvalidIntegerException InvalidFloatException */