Reference documentation for deal.II version 8.1.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Functions
GridRefinement Namespace Reference

Functions

template<int dim, class Vector , int spacedim>
void refine_and_coarsen_fixed_number (Triangulation< dim, spacedim > &tria, const Vector &criteria, const double top_fraction_of_cells, const double bottom_fraction_of_cells, const unsigned int max_n_cells=std::numeric_limits< unsigned int >::max())
 
template<int dim, class Vector , int spacedim>
void refine_and_coarsen_fixed_fraction (Triangulation< dim, spacedim > &tria, const Vector &criteria, const double top_fraction, const double bottom_fraction, const unsigned int max_n_cells=std::numeric_limits< unsigned int >::max())
 
template<int dim, class Vector , int spacedim>
void refine_and_coarsen_optimize (Triangulation< dim, spacedim > &tria, const Vector &criteria, const unsigned int order=2)
 
template<int dim, class Vector , int spacedim>
void refine (Triangulation< dim, spacedim > &tria, const Vector &criteria, const double threshold, const unsigned int max_to_mark=numbers::invalid_unsigned_int)
 
template<int dim, class Vector , int spacedim>
void coarsen (Triangulation< dim, spacedim > &tria, const Vector &criteria, const double threshold)
 
 DeclException0 (ExcNegativeCriteria)
 
 DeclException0 (ExcInvalidParameterValue)
 

Detailed Description

Collection of functions controlling refinement and coarsening of Triangulation objects.

The functions in this namespace are in two classes. There are the auxiliary functions refine() and coarsen(). More important for users are the other functions, which implement refinement strategies, as being found in the literature on adaptive finite element methods. For mathematical discussion of these methods, consider works by Dörfler, Morin, Nochetto, Rannacher, Stevenson and many more.

Author
Wolfgang Bangerth, Thomas Richter, Guido Kanschat 1998, 2000, 2009

Function Documentation

template<int dim, class Vector , int spacedim>
void GridRefinement::refine_and_coarsen_fixed_number ( Triangulation< dim, spacedim > &  tria,
const Vector criteria,
const double  top_fraction_of_cells,
const double  bottom_fraction_of_cells,
const unsigned int  max_n_cells = std::numeric_limits< unsigned int >::max() 
)

This function provides a refinement strategy with predictable growth of the mesh.

The function takes a vector of refinement criteria and two values between zero and one denoting the fractions of cells to be refined and coarsened. It flags cells for further processing by Triangulation::execute_coarsening_and_refinement() according to the following greedy algorithm:

  1. Sort the cells according to descenting values of criteria.

  2. Set the refinement threshold to be the criterion belonging to the cell at position top_fraction_of_cells times Triangulation::n_active_cells().

  3. Set the coarsening threshold accordingly using the cell bottom_fraction_of_cells times Triangulation::n_active_cells() from the end of the sorted list.

  4. Use these two thresholds in calls to refine() and coarsen(), respectively.

As an example, with no coarsening, setting top_fraction_of_cells to 1/3 will result in approximately doubling the number of cells in two dimensions. The same effect in three dimensions is achieved by refining 1/7th of the cells. These values are good initial guesses, but should be adjusted depending on the singularity of approximated function.

The sorting of criteria is not done actually, since we only need the threshold values in order to call refine() and coarsen(). The order of cells with higher and of those with lower criteria is irrelevant. Getting this value is accomplished by the nth_element function of the C++ standard library, which takes only linear time in the number of elements, rather than N log N for sorting all values.

Warning
This function only sets the coarsening and refinement flags. The mesh is not changed until you call Triangulation::execute_coarsening_and_refinement().
  • criteria: the refinement criterion computed on each mesh cell. Entries may not be negative.
  • top_fraction_of_cells is the fraction of cells to be refined. If this number is zero, no cells will be refined. If it equals one, the result will be flagging for global refinement.
  • bottom_fraction_of_cells is the fraction of cells to be coarsened. If this number is zero, no cells will be coarsened.
  • max_n_cells can be used to specify a maximal number of cells. If this number is going to be exceeded upon refinement, then refinement and coarsening fractions are going to be adjusted in an attempt to reach the maximum number of cells. Be aware though that through proliferation of refinement due to Triangulation::MeshSmoothing, this number is only an indicator. The default value of this argument is to impose no limit on the number of cells.
template<int dim, class Vector , int spacedim>
void GridRefinement::refine_and_coarsen_fixed_fraction ( Triangulation< dim, spacedim > &  tria,
const Vector criteria,
const double  top_fraction,
const double  bottom_fraction,
const unsigned int  max_n_cells = std::numeric_limits< unsigned int >::max() 
)

This function provides a refinement strategy controlling the reduction of the error estimate.

Also known as the bulk criterion, this function computes the thresholds for refinement and coarsening such that the criteria of cells getting flagged for refinement make up for a certain fraction of the total error. We explain its operation for refinement, coarsening works analogously.

Let cK be the criterion of cell K. Then the total error estimate is computed by the formula

\[ E = \sum_{K\in \cal T} c_K. \]

If 0 < a < 1 is top_fraction, then we refine the smallest subset $\cal M$ of the Triangulation $\cal T$ such that

\[ a E \le \sum_{K\in \cal M} c_K \]

The algorithm is performed by the greedy algorithm described in refine_and_coarsen_fixed_number().

Note
The often used formula with squares on the left and right is recovered by actually storing the square of cK in the vector criteria.

From the point of view of implementation, this time we really need to sort the array of criteria. Just like the other strategy described above, this function only computes the threshold values and then passes over to refine() and coarsen().

  • criteria: the refinement criterion computed on each mesh cell. Entries may not be negative.
  • top_fraction is the fraction of the total estimate which should be refined. If this number is zero, no cells will be refined. If it equals one, the result will be flagging for global refinement.
  • bottom_fraction is the fraction of the estimate coarsened. If this number is zero, no cells will be coarsened.
  • max_n_cells can be used to specify a maximal number of cells. If this number is going to be exceeded upon refinement, then refinement and coarsening fractions are going to be adjusted in an attempt to reach the maximum number of cells. Be aware though that through proliferation of refinement due to Triangulation::MeshSmoothing, this number is only an indicator. The default value of this argument is to impose no limit on the number of cells.
template<int dim, class Vector , int spacedim>
void GridRefinement::refine_and_coarsen_optimize ( Triangulation< dim, spacedim > &  tria,
const Vector criteria,
const unsigned int  order = 2 
)

Refine the triangulation by flagging certain cells to reach an optimal grid: We try to minimize the error multiplied with the number of cells in the new grid. All cells with large error indicator are refined to generate an optimal grid in the above sense. We assume that the error in one cell is reduced to 1-2^{-order} after refinement, if 'order' is the expected order of convergence. This expected order of convergence must be passed as an argument but is defaulted to 2. The new triangulation has ( $2^d-1$) new cells for every flagged cell (the original cell is replaced by $2^d$ cells but it then made inactive).

Refer to the general doc of this class for more information.

template<int dim, class Vector , int spacedim>
void GridRefinement::refine ( Triangulation< dim, spacedim > &  tria,
const Vector criteria,
const double  threshold,
const unsigned int  max_to_mark = numbers::invalid_unsigned_int 
)

Flag all mesh cells for which the value in criteria exceeds threshold for refinement, but only flag up to max_to_mark cells.

The vector criteria contains a nonnegative value for each active cell, ordered in the canonical order of of Triangulation::active_cell_iterator.

The cells are only flagged for refinement, they are not actually refined. To do so, you have to call Triangulation::execute_coarsening_and_refinement().

This function does not implement a refinement strategy, it is more a helper function for the actual strategies.

template<int dim, class Vector , int spacedim>
void GridRefinement::coarsen ( Triangulation< dim, spacedim > &  tria,
const Vector criteria,
const double  threshold 
)

Flag all mesh cells for which the value in criteria is less than threshold for coarsening.

The vector criteria contains a nonnegative value for each active cell, ordered in the canonical order of of Triangulation::active_cell_iterator.

The cells are only flagged for coarsening, they are not actually coarsened. To do so, you have to call Triangulation::execute_coarsening_and_refinement().

This function does not implement a refinement strategy, it is more a helper function for the actual strategies.

GridRefinement::DeclException0 ( ExcNegativeCriteria  )

An exception thrown if the vector with cell criteria contains negative values

GridRefinement::DeclException0 ( ExcInvalidParameterValue  )

One of the threshold parameters causes trouble. Or the refinement and coarsening thresholds overlap.