Data parsing

Routines for reading simple column data into LookupTable1D are available. This is typically used, e.g., when parsing transport coefficients or other types of data requires by a computer simulation.

Tip

The DataParser C++ API is found at https://chombo-discharge.github.io/chombo-discharge/doxygen/html/namespaceDataParser.html.

Currently, three types of file reads are supported:

Read column data, where the user can specify the columns that are parsed into a lookup table.

These files can be arranged in the form
```
0.0 1.0
1.0 2.0
2.0 3.0
```
It is also possible to restrict which rows that are read, by specifying string identifiers on the line preceding the data and on the line immediately after the data.

Important

After parsing into a LookupTable1D, the user must regularize the table in order to use the interpolation functions. See Regularize table.

Read particle data, where the particle data is in a \((x,y,z,w)\) file format, where \(w\) is the particle weight.

The function signatures for reading this type of data are:

/*!
  @brief Simple file parser which reads a file and puts the data into two columns (a lookup table). 
  @details This will read ASCII row/column data into a LookupTable1D (which is a simple x-y data structure). The user can specify which columns
  to use as the x and y coordinates in the LookupTable1D. If the user ask for a column that does not exist in the input file, the data will not be read
  into the LookupTable1D. 
  @param[in] a_fileName    Input file name. Must be an ASCII file organized into rows and columns. 
  @param[in] a_xColumn     Which column to use as the x-column. 
  @param[in] a_yColumn     Which column to use as the y-column. 
  @param[in] a_ignoreChars Characters indicating comments in the file. Lines starting with these characters are ignored. 
  @note xColumn = 0 is the FIRST column, xColumn=1 is the SECOND column and so on. 
*/
LookupTable1D<Real, 1>
simpleFileReadASCII(const std::string       a_fileName,
                    const int               a_xColumn     = 0,
                    const int               a_yColumn     = 1,
                    const std::vector<char> a_ignoreChars = {'#', '/'});

/*!
  @brief Simple ASCII file parser which reads a file and puts the data into two columns (a lookup table)
  @details This version can read a partial file. It will ignore all lines until the a_startRead string is
  encountered. After that, it will read files as usual, skipping lines that begin with comments. Empty lines
  are NOT skipped, since an empty line typically identifies the end of a field from e.g. BOLSIG outputs. Instead
  to stop reading when an empty line is encountered, one can use a_stopRead="". 
  @param[in] a_fileName    Input file name. Must be an ASCII file organized into rows and columns. 
  @param[in] a_startRead   Identifier where we start parsing lines into the table
  @param[in] a_stopRead    Identifier where we stop parsing lines into the table
  @param[in] a_xColumn     Which column to use as the x-column. 
  @param[in] a_yColumn     Which column to use as the y-column. 
  @param[in] a_ignoreChars Characters indicating comments in the file. Lines starting with these characters are ignored. 
*/
LookupTable1D<Real, 1>
fractionalFileReadASCII(const std::string       a_fileName,
                        const std::string       a_startRead,
                        const std::string       a_stopRead,
                        const int               a_xColumn     = 0,
                        const int               a_yColumn     = 1,
                        const std::vector<char> a_ignoreChars = {'#', '/'});

/*!
  @brief Simple file parser which will read particles (position/weight) from an ASCII file. 
  @details Particles should be arranged as rows, e.g. in the form
  x   y   z   w
  0.0 0.0 0.0 1
  @param[in] a_fileName    Input file name. Must be an ASCII file organized into rows and columns. 
  @param[in] a_xColumn     Column containing the x-coordinate
  @param[in] a_yColumn     Column containing the y-coordinate
  @param[in] a_zColumn     Column containing the z-coordinate
  @param[in] a_wColumn     Column containing the particle weight
  @param[in] a_ignoreChars Characters indicating comments in the file. Lines starting with these characters are ignored. 
*/
List<PointParticle>
readPointParticlesASCII(const std::string       a_fileName,
                        const unsigned int      a_xColumn     = 0,
                        const unsigned int      a_yColumn     = 1,
                        const unsigned int      a_zColumn     = 2,
                        const unsigned int      a_wColumn     = 3,
                        const std::vector<char> a_ignoreChars = {'#', '/'});

Read triangle mesh data from PLY or VTK files, returning a list of Triangle objects with per-vertex scalar metadata. The file type is inferred from the extension (.ply/.PLY or .vtk/.VTK). A named per-vertex scalar property (e.g., a PLY vertex property or VTK point-data scalar) is read as the vertex metadata; if the identifier is not found, a warning is issued and metadata defaults to zero. Non-triangular facets are skipped with a warning.

The function signature is:

/*!
  @brief Read a PLY or VTK triangle mesh file and return a list of Triangle objects.
  @details Reads vertex positions and face connectivity from the file. If a_vertexDataIdentifier
  matches a named per-vertex scalar property in the file (a PLY vertex property or a VTK
  point-data scalar), that data is stored as the vertex metadata on each Triangle via
  setVertexData(). If the identifier is not found, a warning is issued and all vertex data
  values are set to zero.

  Non-triangular facets are skipped with a warning. The file type is inferred from the
  extension (.ply / .PLY or .vtk / .VTK); any other extension results in a fatal error.

  @param[in] a_filename             Path to the input mesh file.
  @param[in] a_vertexDataIdentifier Name of the per-vertex scalar property to read as
                                    Triangle vertex metadata.
  @return Vector of fully initialised Triangle objects, sorted in file order.
*/
std::vector<std::shared_ptr<Triangle>>
readTriangles(const std::string a_filename, const std::string a_vertexDataIdentifier);

Note

Triangle objects are returned in file order. To perform efficient spatial queries (e.g., finding the closest triangle to a point), pass the result to a TriangleCollection.