Reference documentation for deal.II version Git 4a2ac69 2017-09-19 13:41:17 -0400
Public Types | Public Member Functions | Static Public Member Functions | Static Protected Member Functions | Protected Attributes | Static Private Member Functions | Private Attributes | List of all members
GridIn< dim, spacedim > Class Template Reference

#include <deal.II/grid/grid_in.h>

Public Types

enum  Format {
  Default, unv, ucd, abaqus,
  dbmesh, xda, msh, netcdf,
  tecplot, vtk
}
 

Public Member Functions

 GridIn ()
 
void attach_triangulation (Triangulation< dim, spacedim > &tria)
 
void read (std::istream &in, Format format=Default)
 
void read (const std::string &in, Format format=Default)
 
void read_vtk (std::istream &in)
 
void read_unv (std::istream &in)
 
void read_ucd (std::istream &in, const bool apply_all_indicators_to_manifolds=false)
 
void read_abaqus (std::istream &in, const bool apply_all_indicators_to_manifolds=false)
 
void read_dbmesh (std::istream &in)
 
void read_xda (std::istream &in)
 
void read_msh (std::istream &in)
 
void read_netcdf (const std::string &filename)
 
void read_tecplot (std::istream &in)
 

Static Public Member Functions

static std::string default_suffix (const Format format)
 
static Format parse_format (const std::string &format_name)
 
static std::string get_format_names ()
 
static::ExceptionBase & ExcUnknownSectionType (int arg1)
 
static::ExceptionBase & ExcUnknownElementType (int arg1)
 
static::ExceptionBase & ExcUnknownIdentifier (std::string arg1)
 
static::ExceptionBase & ExcNoTriangulationSelected ()
 
static::ExceptionBase & ExcInvalidVertexIndex (int arg1, int arg2)
 
static::ExceptionBase & ExcInvalidVertexIndexGmsh (int arg1, int arg2, int arg3)
 
static::ExceptionBase & ExcInvalidDBMeshFormat ()
 
static::ExceptionBase & ExcInvalidDBMESHInput (std::string arg1)
 
static::ExceptionBase & ExcDBMESHWrongDimension (int arg1)
 
static::ExceptionBase & ExcInvalidGMSHInput (std::string arg1)
 
static::ExceptionBase & ExcGmshUnsupportedGeometry (int arg1)
 
static::ExceptionBase & ExcGmshNoCellInformation ()
 

Static Protected Member Functions

static void debug_output_grid (const std::vector< CellData< dim > > &cells, const std::vector< Point< spacedim > > &vertices, std::ostream &out)
 

Protected Attributes

SmartPointer< Triangulation< dim, spacedim >, GridIn< dim, spacedim > > tria
 

Static Private Member Functions

static void skip_empty_lines (std::istream &in)
 
static void skip_comment_lines (std::istream &in, const char comment_start)
 
static void parse_tecplot_header (std::string &header, std::vector< unsigned int > &tecplot2deal, unsigned int &n_vars, unsigned int &n_vertices, unsigned int &n_cells, std::vector< unsigned int > &IJK, bool &structured, bool &blocked)
 

Private Attributes

Format default_format
 

Detailed Description

template<int dim, int spacedim = dim>
class GridIn< dim, spacedim >

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 this and 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, available here.

The mesh you read will form the coarsest level of a 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.)

Supported input formats

At present, the following input formats are supported:

Structure of input grid data. The GridReordering class

It is your duty to use a correct numbering of vertices in the cell list, i.e. for lines in 1d, you have to first give the vertex with the lower coordinate value, then that with the higher coordinate value. For quadrilaterals in two dimensions, the vertex indices in the quad list have to be such that the vertices are numbered in counter-clockwise sense.

In two dimensions, another difficulty occurs, which has to do with the sense of a quadrilateral. A quad consists of four lines which have a direction, which is by definition as follows:

*   3-->--2
*   |     |
*   ^     ^
*   |     |
*   0-->--1
* 

Now, two adjacent cells must have a vertex numbering such that the direction of the common side is the same. For example, the following two quads

*   3---4---5
*   |   |   |
*   0---1---2
* 

may be characterised by the vertex numbers (0 1 4 3) and (1 2 5 4), since the middle line would get the direction 1->4 when viewed from both cells. The numbering (0 1 4 3) and (5 4 1 2) would not be allowed, since the left quad would give the common line the direction 1->4, while the right one would want to use 4->1, leading to an ambiguity. The Triangulation object is capable of detecting this special case, which can be eliminated by rotating the indices of the right quad by two. However, it would not know what to do if you gave the vertex indices (4 1 2 5), since then it would have to rotate by one element or three, the decision which to take is not yet implemented.

There are more ambiguous cases, where the triangulation may not know what to do at all without the use of sophisticated algorithms. Furthermore, similar problems exist in three space dimensions, where faces and lines have orientations that need to be taken care of.

For this reason, the read_* functions of this class that read in grids in various input formats call the GridReordering class to bring the order of vertices that define the cells into an ordering that satisfies the requirements of the Triangulation class. Be sure to read the documentation of that class if you experience unexpected problems when reading grids through this class.

Dealing with distorted mesh cells

For each of the mesh reading functions, the last call is always to Triangulation::create_triangulation(). That function checks whether all the cells it creates as part of the coarse mesh are distorted or not (where distortion here means that the Jacobian of the mapping from the reference cell to the real cell has a non-positive determinant, i.e. the cell is pinched or twisted; see the entry on distorted cells in the glossary). If it finds any such cells, it throws an exception. This exception is not caught in the grid reader functions of the current class, and so will propagate through to the function that called it. There, you can catch and ignore the exception if you are certain that there is no harm in dealing with such cells. If you were not aware that your mesh had such cells, your results will likely be of dubious quality at best if you ignore the exception.

Author
Wolfgang Bangerth, 1998, 2000, Luca Heltai, 2004, 2007, Jean-Paul Pelteret 2015, Timo Heister 2015, Krzysztof Bzowski, 2015

Definition at line 300 of file grid_in.h.

Constructor & Destructor Documentation

template<int dim, int spacedim>
GridIn< dim, spacedim >::GridIn ( )

Constructor.

Definition at line 84 of file grid_in.cc.

Member Function Documentation

template<int dim, int spacedim>
void GridIn< dim, spacedim >::attach_triangulation ( Triangulation< dim, spacedim > &  tria)

Attach this triangulation to be fed with the grid data.

Definition at line 90 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read ( std::istream &  in,
Format  format = Default 
)

Read from the given stream. If no format is given, GridIn::Format::Default is used.

Definition at line 2785 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read ( const std::string &  in,
Format  format = Default 
)

Open the file given by the string and call the previous function read(). This function uses the PathSearch mechanism to find files. The file class used is MESH.

Definition at line 2752 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_vtk ( std::istream &  in)

Read grid data from an vtk file. Numerical data is ignored.

Author
Mayank Sabharwal, Andreas Putz, 2013

Definition at line 98 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_unv ( std::istream &  in)

Read grid data from an unv file as generated by the Salome mesh generator. Numerical data is ignored.

Note the comments on generating this file format in the general documentation of this class.

Definition at line 385 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_ucd ( std::istream &  in,
const bool  apply_all_indicators_to_manifolds = false 
)

Read grid data from an ucd file. Numerical data is ignored. It is not possible to use a ucd file to set both boundary_id and manifold_id for the same cell. Yet it is possible to use the flag apply_all_indicators_to_manifolds to decide if the indicators in the file refer to manifolds (flag set to true) or boundaries (flag set to false).

Definition at line 621 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_abaqus ( std::istream &  in,
const bool  apply_all_indicators_to_manifolds = false 
)

Read grid data from an Abaqus file. Numerical and constitutive data is ignored. As in the case of the ucd file format, it is possible to use the flag apply_all_indicators_to_manifolds to decide if the indicators in the file refer to manifolds (flag set to true) or boundaries (flag set to false).

Note
The current implementation of this mesh reader is suboptimal, and may therefore be slow for large meshes.
Usage tips for Cubit:
  • Multiple material-id's can be defined in the mesh. This is done by specifying blocksets in the pre-processor.
  • Arbitrary surface boundaries can be defined in the mesh. This is done by specifying sidesets in the pre-processor. In particular, boundaries are not confined to just surfaces (in 3d) individual element faces can be added to the sideset as well. This is useful when a boundary condition is to be applied on a complex shape boundary that is difficult to define using "surfaces" alone. Similar can be done in 2d.
Compatibility information for this file format is listed below.
  • Files generated in Abaqus CAE 6.12 have been verified to be correctly imported, but older (or newer) versions of Abaqus may also generate valid input decks.
  • Files generated using Cubit 11.x, 12.x, 13.x, 14.x and 15.x are valid, but only when using a specific set of export steps. These are as follows:
    • Go to "Analysis setup mode" by clicking on the disc icon in the toolbar on the right.
    • Select "Export Mesh" under "Operation" by clicking on the necessary icon in the toolbar on the right.
    • Select an output file. In Cubit version 11.0 and 12.0 it might be necessary to click on the browse button and type it in the dialogue that pops up.
    • Select the dimension to output in.
    • Tick the overwrite box.
    • If using Cubit v12.0 onwards, uncheck the box "Export using Cubit ID's". An invalid file will encounter errors if this box is left checked.
    • Click apply.

Definition at line 855 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_dbmesh ( std::istream &  in)

Read grid data from a file containing data in the DB mesh format.

Definition at line 900 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_xda ( std::istream &  in)

Read grid data from a file containing data in the XDA format.

Definition at line 1066 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_msh ( std::istream &  in)

Read grid data from an msh file, either version 1 or version 2 of that file format. The GMSH formats are documented at http://www.geuz.org/gmsh/.

Note
The input function of deal.II does not distinguish between newline and other whitespace. Therefore, deal.II will be able to read files in a slightly more general format than Gmsh.

Definition at line 1224 of file grid_in.cc.

template<int dim, int spacedim = dim>
void GridIn< dim, spacedim >::read_netcdf ( const std::string &  filename)

Read grid data from a NetCDF file. The only data format currently supported is the TAU grid format.

This function requires the library to be linked with the NetCDF library.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::read_tecplot ( std::istream &  in)

Read grid data from a file containing tecplot ASCII data. This also works in the absence of any tecplot installation.

Definition at line 2539 of file grid_in.cc.

template<int dim, int spacedim>
std::string GridIn< dim, spacedim >::default_suffix ( const Format  format)
static

Return the standard suffix for a file in this format.

Definition at line 2841 of file grid_in.cc.

template<int dim, int spacedim>
GridIn< dim, spacedim >::Format GridIn< dim, spacedim >::parse_format ( const std::string &  format_name)
static

Return the enum Format for the format name.

Definition at line 2873 of file grid_in.cc.

template<int dim, int spacedim>
std::string GridIn< dim, spacedim >::get_format_names ( )
static

Return a list of implemented input formats. The different names are separated by vertical bar signs (`|') as used by the ParameterHandler classes.

Definition at line 2929 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::debug_output_grid ( const std::vector< CellData< dim > > &  cells,
const std::vector< Point< spacedim > > &  vertices,
std::ostream &  out 
)
staticprotected

This function can write the raw cell data objects created by the read_* functions in Gnuplot format to a stream. This is sometimes handy if one would like to see what actually was created, if it is known that the data is not correct in some way, but the Triangulation class refuses to generate a triangulation because of these errors. In particular, the output of this class writes out the cell numbers along with the direction of the faces of each cell. In particular the latter information is needed to verify whether the cell data objects follow the requirements of the ordering of cells and their faces, i.e. that all faces need to have unique directions and specified orientations with respect to neighboring cells (see the documentations to this class and the GridReordering class).

The output of this function consists of vectors for each line bounding the cells indicating the direction it has with respect to the orientation of this cell, and the cell number. The whole output is in a form such that it can be read in by Gnuplot and generate the full plot without further ado by the user.

Definition at line 2599 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::skip_empty_lines ( std::istream &  in)
staticprivate

Skip empty lines in the input stream, i.e. lines that contain either nothing or only whitespace.

Definition at line 2546 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::skip_comment_lines ( std::istream &  in,
const char  comment_start 
)
staticprivate

Skip lines of comment that start with the indicated character (e.g. #) following the point where the given input stream presently is. After the call to this function, the stream is at the start of the first line after the comment lines, or at the same position as before if there were no lines of comments.

Definition at line 2575 of file grid_in.cc.

template<int dim, int spacedim>
void GridIn< dim, spacedim >::parse_tecplot_header ( std::string &  header,
std::vector< unsigned int > &  tecplot2deal,
unsigned int &  n_vars,
unsigned int &  n_vertices,
unsigned int &  n_cells,
std::vector< unsigned int > &  IJK,
bool &  structured,
bool &  blocked 
)
staticprivate

This function does the nasty work (due to very lax conventions and different versions of the tecplot format) of extracting the important parameters from a tecplot header, contained in the string header. The other variables are output variables, their value has no influence on the function execution..

Definition at line 2105 of file grid_in.cc.

Member Data Documentation

template<int dim, int spacedim = dim>
SmartPointer<Triangulation<dim,spacedim>,GridIn<dim,spacedim> > GridIn< dim, spacedim >::tria
protected

Store address of the triangulation to be fed with the data read in.

Definition at line 565 of file grid_in.h.

template<int dim, int spacedim = dim>
Format GridIn< dim, spacedim >::default_format
private

Input format used by read() if no format is given.

Definition at line 628 of file grid_in.h.


The documentation for this class was generated from the following files: