<commit_before>// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2016 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii__grid_in_h
#define dealii__grid_in_h


#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/smartpointer.h>
#include <deal.II/base/point.h>
#include <iostream>
#include <vector>
#include <string>

DEAL_II_NAMESPACE_OPEN

template <int dim, int space_dim> class Triangulation;
template <int dim> struct CellData;

/**
 * This class implements an input mechanism for grid data. It allows to read a
 * grid structure into a triangulation object. At present, UCD (unstructured
 * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are
 * supported as input format for grid data. Any numerical data other than
 * geometric (vertex locations) and topological (how vertices form cells)
 * information is ignored.
 *
 * @note Since deal.II only supports line, quadrilateral and hexahedral
 * meshes, the functions in this class can only read meshes that consist
 * exclusively of such cells. If you absolutely need to work with a mesh that
 * uses triangles or tetrahedra, then your only option is to convert the mesh
 * to quadrilaterals and hexahedra. A tool that can do this is tethex, see
 * http://code.google.com/p/tethex/wiki/Tethex .
 *
 * The mesh you read will form the coarsest level of a @p Triangulation
 * object. As such, it must not contain hanging nodes or other forms or
 * adaptive refinement and strange things will happen if the mesh represented
 * by the input file does in fact have them. This is due to the fact that most
 * mesh description formats do not store neighborship information between
 * cells, so the grid reading functions have to regenerate it. They do so by
 * checking whether two cells have a common face. If there are hanging nodes
 * in a triangulation, adjacent cells have no common (complete) face, so the
 * grid reader concludes that the adjacent cells have no neighbors along these
 * faces and must therefore be at the boundary. In effect, an internal crack
 * of the domain is introduced this way. Since such cases are very hard to
 * detect (how is GridIn supposed to decide whether a place where the faces of
 * two small cells coincide with the face or a larger cell is in fact a
 * hanging node associated with local refinement, or is indeed meant to be a
 * crack in the domain?), the library does not make any attempt to catch such
 * situations, and you will get a triangulation that probably does not do what
 * you want. If your goal is to save and later read again a triangulation that
 * has been adaptively refined, then this class is not your solution; rather
 * take a look at the PersistentTriangulation class.
 *
 * @note It is not uncommon to experience unexpected problems when reading
 * generated meshes for the first time using this class. If this applies to
 * you, be sure to read the documentation right until the end, and also read
 * the documentation of the GridReordering class.
 *
 * To read grid data, the triangulation to be fed with has to be empty. When
 * giving a file which does not contain the assumed information or which does
 * not keep to the right format, the state of the triangulation will be
 * undefined afterwards. Upon input, only lines in one dimension and line and
 * quads in two dimensions are accepted. All other cell types (e.g. triangles
 * in two dimensions, quads and hexes in 3d) are rejected. The vertex and cell
 * numbering in the input file, which need not be consecutively, is lost upon
 * transfer to the triangulation object, since this one needs consecutively
 * numbered elements.
 *
 * Material indicators are accepted to denote the material ID of cells and to
 * denote boundary part indication for lines in 2D. Read the according
 * sections in the documentation of the Triangulation class for further
 * details.
 *
 *
 * <h3>Supported input formats</h3>
 *
 * At present, the following input formats are supported:
 * <ul>
 * <li> @p UCD (unstructured cell data) format: this format is used for grid
 * input as well as data output. If there are data vectors in the input file,
 * they are ignored, as we are only interested in the grid in this class. The
 * UCD format requires the vertices to be in following ordering: in 2d
 * @verbatim<commit_msg>Clarify the documentation of the GridIn class.<commit_after>// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2016 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii__grid_in_h
#define dealii__grid_in_h


#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/smartpointer.h>
#include <deal.II/base/point.h>
#include <iostream>
#include <vector>
#include <string>

DEAL_II_NAMESPACE_OPEN

template <int dim, int space_dim> class Triangulation;
template <int dim> struct CellData;

/**
 * This class implements an input mechanism for grid data. It allows to read a
 * grid structure into a triangulation object. At present, UCD (unstructured
 * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are
 * supported as input format for grid data. Any numerical data other than
 * geometric (vertex locations) and topological (how vertices form cells,
 * faces, and edges) information is ignored, but the readers for the various
 * formats generally do read information that associates material ids or
 * boundary ids to cells or faces (see @ref GlossMaterialId "this" and
 * @ref GlossBoundaryIndicator "this" glossary entry for more information).
 *
 * @note Since deal.II only supports line, quadrilateral and hexahedral
 * meshes, the functions in this class can only read meshes that consist
 * exclusively of such cells. If you absolutely need to work with a mesh that
 * uses triangles or tetrahedra, then your only option is to convert the mesh
 * to quadrilaterals and hexahedra. A tool that can do this is tethex, see
 * http://code.google.com/p/tethex/wiki/Tethex .
 *
 * The mesh you read will form the coarsest level of a @p Triangulation
 * object. As such, it must not contain hanging nodes or other forms of
 * adaptive refinement, or strange things will happen if the mesh represented
 * by the input file does in fact have them. This is due to the fact that most
 * mesh description formats do not store neighborship information between
 * cells, so the grid reading functions have to regenerate it. They do so by
 * checking whether two cells have a common face. If there are hanging nodes
 * in a triangulation, adjacent cells have no common (complete) face, so the
 * grid reader concludes that the adjacent cells have no neighbors along these
 * faces and must therefore be at the boundary. In effect, an internal crack
 * of the domain is introduced this way. Since such cases are very hard to
 * detect (how is GridIn supposed to decide whether a place where the faces of
 * two small cells coincide with the face or a larger cell is in fact a
 * hanging node associated with local refinement, or is indeed meant to be a
 * crack in the domain?), the library does not make any attempt to catch such
 * situations, and you will get a triangulation that probably does not do what
 * you want. If your goal is to save and later read again a triangulation that
 * has been adaptively refined, then this class is not your solution; rather
 * take a look at the PersistentTriangulation class.
 *
 * To read grid data, the triangulation to be filled has to be empty.
 * Upon calling the functions of this class, the input file may
 * contain only lines in one dimension; lines and quads in two
 * dimensions; and lines, quads, and hexes in three dimensions. All
 * other cell types (e.g. triangles in two dimensions, triangles or
 * tetrahedra in 3d) are rejected.  (Here, the "dimension" refers to
 * the dimensionality of the mesh; it may be embedded in a higher
 * dimensional space, such as a mesh on the two-dimensional surface of
 * the sphere embedded in 3d, or a 1d mesh that discretizes a line in
 * 3d.) The result will be a triangulation that consists of the cells
 * described in the input file, and to the degree possible with
 * material indicators and boundary indicators correctly set as
 * described in the input file.
 *
 * @note You can not expect vertex and cell numbers in the triangulation
 * to match those in the input file. (This is already clear based on the
 * fact that we number cells and vertices separately, whereas this is not
 * the case for some input file formats; some formats also do not require
 * consecutive numbering, or start numbering at indices other than zero.)
 *
 *
 * <h3>Supported input formats</h3>
 *
 * At present, the following input formats are supported:
 * <ul>
 * <li> @p UCD (unstructured cell data) format: this format is used for grid
 * input as well as data output. If there are data vectors in the input file,
 * they are ignored, as we are only interested in the grid in this class. The
 * UCD format requires the vertices to be in following ordering: in 2d
 * @verbatim
{'fraction_non_alphanumeric': 0.08259499901555424, 'fraction_numerical': 0.003150226422524119, 'mean_word_length': 3.424651567944251, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2110591', 'n_tokens_mistral': 2620, 'n_tokens_neox': 2530, 'n_words': 1523}