Reference documentation for deal.II version Git 3fdf7d9 20170424 17:39:03 0400

Modules  
Boundary and manifold description for triangulations  
Iterators on meshlike containers  
Manifold description for triangulations  
Namespaces  
parallel::distributed::GridRefinement  
GridGenerator  
GridRefinement  
GridTools  
Keeping up with what happens to a triangulation  
enum  Triangulation< dim, spacedim >::CellStatus { Triangulation< dim, spacedim >::CELL_PERSIST, Triangulation< dim, spacedim >::CELL_REFINE, Triangulation< dim, spacedim >::CELL_COARSEN, Triangulation< dim, spacedim >::CELL_INVALID } 
Signals  Triangulation< dim, spacedim >::signals 
This module groups classes that have to do with the topology and geometry of meshes. A mesh can be thought of a collection of cells; if the mesh has been refined (possibly in an adaptive way), then this collection is grouped into a hierarchy of refinement levels. In addition to cells, the geometric objects that make up a triangulation are the faces of cells (and in 3d the edges of cells) as well as the vertices of the cells. Note that we abuse the word triangulation somewhat, since deal.II only implements triangulations made up of linear, quadrilateral, and hexahedral cells; triangles and tetrahedra are not supported.
This collection of cells is managed by the Triangulation class. It holds the relevant data in memory and offers interfaces to query it. Most things you want to do on cells are performed in loops over all cells. For this purpose, the Triangulation class offers the concept of iterators (see Iterators on meshlike containers): although implemented differently, they behave like pointers to cells or faces and can be queried for the geometric properties of cells as well as information like neighboring cells or faces of a cell.
It is worth noting that the Triangulation class only stores geometry (i.e. the location of vertices and cells) and topology of a mesh (i.e. which cells are neighbors of which other cells, etc). It has nothing to do with finite elements or degrees of freedom that might be defined on a mesh. These functions are performed by the DoFHandler class (see the Degrees of Freedom module) that gets a description of the finite element space and the allocates and manages degrees of freedom on vertices, faces, or cells, as described by the finite element class. This separation makes it possible to have multiple DoFHandler classes work on the same mesh at the same time.
There are three ways to create a mesh:
For the first case, the GridGenerator class provides functions that can generate the simplest and most common geometries automatically. For example, a rectangular (or brick) geometry as well as circles, spheres, or cylinders can be generate with the functions in this class. Most of the tutorial programs use this mechanism.
Secondly, it is possible to read in meshes from an input file in a number of different formats using the GridIn class. Using this class, it is possible to read meshes with several 10 or 100 thousand cells, although this is not really recommended: the power of adaptive finite element methods only comes to bear if the initial mesh is as coarse as possible and there is room for a number of adaptive refinement steps. If the initial mesh is too fine already, then one runs out of memory or compute time before adaptive mesh refinement is able to do much good. Nevertheless, the GridIn class can be used in cases of complicated geometries or for comparison or interaction with other programs that compute on meshes that are then exchanged through this class The step5 tutorial program shows how to use the GridIn class.
The third way is to create a mesh by hand, by building a data structure that describes the vertices and cells of a triangulation. This is useful in cases of moderate complexity where a mesh can still be built by hand without resorting to a mesh generator, but where the domain is not one of those already supported by the GridIn class. In this method, the data structure so built is handed to the create_triangulation() function of the Triangulation class. The step14 tutorial program shows how this can be done.
Meshes can be written to output files in a number of different formats. If this involves simulation results obtained on this mesh, then this is done using the DataOut class (described in more detail in the Graphical output module). On the other hand, if only the geometry and topology of the mesh is to be written to a file, the GridOut class can do this for you.
The GridTool class offers an assortment of functions that act on grids. For example, this includes moving around nodes, stretching or rotating entire triangulations, computing the diameter of a domain, or subdividing it into chunks of roughly equal size for parallel computations.
The GridRefinement class implements a number of mesh refinement algorithms, based on refinement indicators given to its member functions.
In addition to the above, there are a significant number of classes in this module that are only used in the internal data structures of mesh handling. They are generally in the internal namespace, and not meant for use in application code.
enum Triangulation::MeshSmoothing 
Declare some symbolic names for mesh smoothing algorithms. The meaning of these flags is documented in the Triangulation class.
Enumerator  

none 
No mesh smoothing at all, except that meshes have to remain one irregular. 
limit_level_difference_at_vertices 
It can be shown, that degradation of approximation occurs if the triangulation contains vertices which are member of cells with levels differing by more than one. One such example is the following: It would seem that in two space dimensions, the maximum jump in levels between cells sharing a common vertex is two (as in the example above). However, this is not true if more than four cells meet at a vertex. It is not uncommon that a coarse (initial) mesh contains vertices at which six or even eight cells meet, when small features of the domain have to be resolved even on the coarsest mesh. In that case, the maximum difference in levels is three or four, respectively. The problem gets even worse in three space dimensions. Looking at an interpolation of the second derivative of the finite element solution (assuming bilinear finite elements), one sees that the numerical solution is almost totally wrong, compared with the true second derivative. Indeed, on regular meshes, there exist sharp estimations that the H^{2}error is only of order one, so we should not be surprised; however, the numerical solution may show a value for the second derivative which may be a factor of ten away from the true value. These problems are located on the small cell adjacent to the center vertex, where cells of nonsubsequent levels meet, as well as on the upper and right neighbor of this cell (but with a less degree of deviation from the true value). If the smoothing indicator given to the constructor contains the bit for limit_level_difference_at_vertices, situations as the above one are eliminated by also marking the lower left cell for refinement. In case of anisotropic refinement, the level of a cell is not linked to the refinement of a cell as directly as in case of isotropic refinement. Furthermore, a cell can be strongly refined in one direction and not or at least much less refined in another. Therefore, it is very difficult to decide, which cases should be excluded from the refinement process. As a consequence, when using anisotropic refinement, the limit_level_difference_at_vertices flag must not be set. On the other hand, the implementation of multigrid methods in deal.II requires that this bit be set. 
eliminate_unrefined_islands 
Single cells which are not refined and are surrounded by cells which are refined usually also lead to a sharp decline in approximation properties locally. The reason is that the nodes on the faces between unrefined and refined cells are not real degrees of freedom but carry constraints. The patch without additional degrees of freedom is thus significantly larger then the unrefined cell itself. If in the parameter passed to the constructor the bit for eliminate_unrefined_islands is set, all cells which are not flagged for refinement but which are surrounded by more refined cells than unrefined cells are flagged for refinement. Cells which are not yet refined but flagged for that are accounted for the number of refined neighbors. Cells on the boundary are not accounted for at all. An unrefined island is, by this definition also a cell which (in 2D) is surrounded by three refined cells and one unrefined one, or one surrounded by two refined cells, one unrefined one and is at the boundary on one side. It is thus not a true island, as the name of the flag may indicate. However, no better name came to mind to the author by now. 
patch_level_1 
A triangulation of patch level 1 consists of patches, i.e. of cells that are refined once. This flag ensures that a mesh of patch level 1 is still of patch level 1 after coarsening and refinement. It is, however, the user's responsibility to ensure that the mesh is of patch level 1 before calling Triangulation::execute_coarsening_and_refinement() the first time. The easiest way to achieve this is by calling global_refine(1) straight after creation of the triangulation. It follows that if at least one of the children of a cell is or will be refined than all children need to be refined. If the patch_level_1 flag is set, than the flags eliminate_unrefined_islands, eliminate_refined_inner_islands and eliminate_refined_boundary_islands will be ignored as they will be fulfilled automatically. 
coarsest_level_1 
Each coarse grid cell is refined at least once, i.e. the triangulation might have active cells on level 1 but not on level 0. This flag ensures that a mesh which has coarsest_level_1 has still coarsest_level_1 after coarsening and refinement. It is, however, the user's responsibility to ensure that the mesh has coarsest_level_1 before calling execute_coarsening_and_refinement the first time. The easiest way to achieve this is by calling global_refine(1) straight after creation of the triangulation. It follows that active cells on level 1 may not be coarsened. The main use of this flag is to ensure that each cell has at least one neighbor in each coordinate direction (i.e. each cell has at least a left or right, and at least an upper or lower neighbor in 2d). This is a necessary precondition for some algorithms that compute finite differences between cells. The DerivativeApproximation class is one of these algorithms that require that a triangulation is coarsest_level_1 unless all cells already have at least one neighbor in each coordinate direction on the coarsest level. 
allow_anisotropic_smoothing 
This flag is not included in However, in many cases it is sufficient to refine the coarser of the two original cells in an anisotropic way to avoid the case of multiple hanging vertices on a single edge. Doing only the minimal anisotropic refinement can save cells and degrees of freedom. By specifying this flag, the library can produce these anisotropic refinements. The flag is not included by default since it may lead to anisotropically refined meshes even though no cell has ever been refined anisotropically explicitly by a user command. This surprising fact may lead to programs that do the wrong thing since they are not written for the additional cases that can happen with anisotropic meshes, see the discussion in the introduction to step30. 
eliminate_refined_inner_islands 
This algorithm seeks for isolated cells which are refined or flagged for refinement. This definition is unlike that for eliminate_unrefined_islands, which would mean that an island is defined as a cell which is refined but more of its neighbors are not refined than are refined. For example, in 2D, a cell's refinement would be reverted if at most one of its neighbors is also refined (or refined but flagged for coarsening). The reason for the change in definition of an island is, that this option would be a bit dangerous, since if you consider a chain of refined cells (e.g. along a kink in the solution), the cells at the two ends would be coarsened, after which the next outermost cells would need to be coarsened. Therefore, only one loop of flagging cells like this could be done to avoid eating up the whole chain of refined cells (`chain reaction'...). This algorithm also takes into account cells which are not actually refined but are flagged for refinement. If necessary, it takes away the refinement flag. Actually there are two versions of this flag, eliminate_refined_inner_islands and eliminate_refined_boundary_islands. There first eliminates islands defined by the definition above which are in the interior of the domain, while the second eliminates only those islands if the cell is at the boundary. The reason for this split of flags is that one often wants to eliminate such islands in the interior while those at the boundary may well be wanted, for example if one refines the mesh according to a criterion associated with a boundary integral or if one has rough boundary data. 
eliminate_refined_boundary_islands 
The result of this flag is very similar to eliminate_refined_inner_islands. See the documentation there. 
do_not_produce_unrefined_islands 
This flag prevents the occurrence of unrefined islands. In more detail: It prohibits the coarsening of a cell if 'most of the neighbors' will be refined after the step. 
smoothing_on_refinement 
This flag sums up all smoothing algorithms which may be performed upon refinement by flagging some more cells for refinement. 
smoothing_on_coarsening 
This flag sums up all smoothing algorithms which may be performed upon coarsening by flagging some more cells for coarsening. 
maximum_smoothing 
This flag includes all the above ones and therefore combines all smoothing algorithms implemented with the exception of anisotropic smoothing. 
enum Triangulation::CellStatus 
Used to inform functions in derived classes how the cell with the given cell_iterator is going to change. Note that this may me different than the refine_flag() and coarsen_flag() in the cell_iterator in parallel calculations because of refinement constraints that this machine does not see.

mutable 