/**
- * Return the corresponding index in the AnyData object supplied to the
- * last initialize(). It is an error if initialize() has not been called
- * before.
+ * Return the corresponding index in the AnyData object supplied to the last
+ * initialize(). It is an error if initialize() has not been called before.
*
* Indices are in the same order as the calls to add().
*/
* objects. All vectors of <tt>in</tt> are forwarded to the inner Operator
* objects, with additional information added as follows.
*
- * When calling (*#residual)(), the AnyData <tt>in</tt> given to the
- * Newton iteration is prepended by a vector <tt>"Newton iterate"</tt>, the
- * current value of the Newton iterate, which can be used to evaluate the
- * residual at this point.
+ * When calling (*#residual)(), the AnyData <tt>in</tt> given to the Newton
+ * iteration is prepended by a vector <tt>"Newton iterate"</tt>, the current
+ * value of the Newton iterate, which can be used to evaluate the residual
+ * at this point.
*
* For the call to (*#inverse_derivative), the vector <tt>"Newton
* residual"</tt> is inserted before <tt>"Newton iterate"</tt>.
* #op_implicit.
*
* @param out in its first argument must contain a pointer to a VectorType
- * instance, which contains the initial value when the operator is
- * called. It contains the final value when the operator returns.
+ * instance, which contains the initial value when the operator is called.
+ * It contains the final value when the operator returns.
*/
virtual void operator() (AnyData &out, const AnyData &in);
* stepping strategy.
*
* @param[in] step The size of the first step, which may be overwritten by
- * the time stepping strategy.
+ * the time stepping strategy.
*/
void start_step (const double step);
/**
* Class that issues the set commands for AlignedVector.
*
- * @tparam initialize_memory Sets whether the the
- * set command should initialize memory (with a call to the copy
- * constructor) or rather use the copy assignment operator. A template is
- * necessary to select the appropriate operation since some classes might
- * define only one of those two operations.
+ * @tparam initialize_memory Sets whether the the set command should
+ * initialize memory (with a call to the copy constructor) or rather use the
+ * copy assignment operator. A template is necessary to select the
+ * appropriate operation since some classes might define only one of those
+ * two operations.
*
* @relates AlignedVector
*/
/**
- * A class that represents a window of memory locations of type
- * @p ElementType and presents it as if it was an array that
- * can be accessed via an <code>operator[]</code>. In essence,
- * this class is nothing more than just a pointer to the first
- * location and an integer that represents the length of the array
- * in elements. The memory remains owned by whoever allocated it,
- * as this class does not take over ownership.
+ * A class that represents a window of memory locations of type @p ElementType
+ * and presents it as if it was an array that can be accessed via an
+ * <code>operator[]</code>. In essence, this class is nothing more than just a
+ * pointer to the first location and an integer that represents the length of
+ * the array in elements. The memory remains owned by whoever allocated it, as
+ * this class does not take over ownership.
*
- * The advantage of using this class is that you don't have to pass
- * around pairs of pointers and that <code>operator[]</code> checks
- * for the validity of the index with which you subscript this
- * array view.
+ * The advantage of using this class is that you don't have to pass around
+ * pairs of pointers and that <code>operator[]</code> checks for the validity
+ * of the index with which you subscript this array view.
*
* This class can handle views to both non-constant and constant memory
- * locations. If you want to represent a view of a constant array,
- * then the template argument type of this class needs to be
- * @p const as well. The following code snippet gives an example:
+ * locations. If you want to represent a view of a constant array, then the
+ * template argument type of this class needs to be @p const as well. The
+ * following code snippet gives an example:
* @code
* std::vector<int> array = get_data(); // a writable array
*
* int element_7 = const_view[2]; // returns 42
* const_view[2] = 42; // error, can't write into this view
* @endcode
- * In either case, accessing an element of a view does not change
- * the ArrayView object itself, and consequently ArrayView::operator[]
- * is a @p const function. This corresponds to the notion that a view
- * simply represents a, well, "view" of memory that is owned by
- * someone else. Thus, accessing elements of the view changes the
- * memory managed by some other object, but not the view itself, allowing
- * us to make ArrayView::operator[] a @p const member function. This is
- * in contrast to, say, std::vector, which manages the memory it points
- * to and changing an element of the std::vector therefore changes the
- * std::vector object itself -- consequently, the std::vector::operator[]
- * is non-@p const.
+ * In either case, accessing an element of a view does not change the
+ * ArrayView object itself, and consequently ArrayView::operator[] is a @p
+ * const function. This corresponds to the notion that a view simply
+ * represents a, well, "view" of memory that is owned by someone else. Thus,
+ * accessing elements of the view changes the memory managed by some other
+ * object, but not the view itself, allowing us to make ArrayView::operator[]
+ * a @p const member function. This is in contrast to, say, std::vector, which
+ * manages the memory it points to and changing an element of the std::vector
+ * therefore changes the std::vector object itself -- consequently, the
+ * std::vector::operator[] is non-@p const.
*
* @ingroup data
* @author Wolfgang Bangerth, 2015
{
public:
/**
- * A typedef that denotes the "value_type" of this container-like
- * class, i.e., the type of the element it "stores" or points to.
+ * A typedef that denotes the "value_type" of this container-like class,
+ * i.e., the type of the element it "stores" or points to.
*/
typedef ElementType value_type;
* Constructor.
*
* @param[in] starting_element A pointer to the first element of the array
- * this object should represent.
+ * this object should represent.
* @param[in] n_elements The length (in elements) of the chunk of memory
- * this object should represent.
+ * this object should represent.
*
- * @note The object that is constructed from these arguments has no knowledge
- * how large the object into which it points really is. As a consequence,
- * whenever you call ArrayView::operator[], the array view can check that
- * the given index is within the range of the view, but it can't check
- * that the view is indeed a subset of the valid range of elements of
- * the underlying object that allocated that range. In other words, you
- * need to ensure that the range of the view specified by the two arguments
- * to this constructor is in fact a subset of the elements of the array
- * into which it points. The appropriate way to do this is to use the
- * make_array_view() functions.
+ * @note The object that is constructed from these arguments has no
+ * knowledge how large the object into which it points really is. As a
+ * consequence, whenever you call ArrayView::operator[], the array view can
+ * check that the given index is within the range of the view, but it can't
+ * check that the view is indeed a subset of the valid range of elements of
+ * the underlying object that allocated that range. In other words, you need
+ * to ensure that the range of the view specified by the two arguments to
+ * this constructor is in fact a subset of the elements of the array into
+ * which it points. The appropriate way to do this is to use the
+ * make_array_view() functions.
*/
ArrayView (value_type *starting_element,
const std::size_t n_elements);
/**
* Copy constructor from array views that point to non-@p const elements. If
* the current object will point to non-@p const elements, then this is a
- * straight forward copy constructor. On the other hand, if the current type's
- * @p ElementType template argument is a @p const qualified type, then the
- * current constructor is a conversion constructor that converts a
+ * straight forward copy constructor. On the other hand, if the current
+ * type's @p ElementType template argument is a @p const qualified type,
+ * then the current constructor is a conversion constructor that converts a
* non-@p const view to a @p const view, akin to converting a non-@p const
* pointer to a @p const pointer.
*/
std::size_t size() const;
/**
- * Return a reference to the $i$th element of the range
- * represented by the current object.
+ * Return a reference to the $i$th element of the range represented by the
+ * current object.
*
- * This function is marked as @p const because it does not change
- * the <em>view object</em>. It may however return a reference to
- * a non-@p const memory location depending on whether the template
- * type of the class is @p const or not.
+ * This function is marked as @p const because it does not change the
+ * <em>view object</em>. It may however return a reference to a non-@p const
+ * memory location depending on whether the template type of the class is @p
+ * const or not.
*/
value_type &operator[] (const std::size_t i) const;
private:
/**
- * A pointer to the first element of the range of locations in
- * memory that this object represents.
+ * A pointer to the first element of the range of locations in memory that
+ * this object represents.
*/
value_type *const starting_element;
/**
- * Create a view to an entire std::vector object. This is equivalent
- * to initializing an ArrayView object with a pointer to the first
- * element and the size of the given argument.
+ * Create a view to an entire std::vector object. This is equivalent to
+ * initializing an ArrayView object with a pointer to the first element and
+ * the size of the given argument.
*
- * This function is used for non-@p const references to objects of vector type.
- * Such objects contain elements that can be written to. Consequently, the return
- * type of this function is a view to a set of writable objects.
+ * This function is used for non-@p const references to objects of vector
+ * type. Such objects contain elements that can be written to. Consequently,
+ * the return type of this function is a view to a set of writable objects.
*
- * @param[in] vector The vector for which we want to have an array
- * view object. The array view corresponds to the <em>entire</em>
- * vector.
+ * @param[in] vector The vector for which we want to have an array view
+ * object. The array view corresponds to the <em>entire</em> vector.
*
* @relates ArrayView
*/
/**
- * Create a view to an entire std::vector object. This is equivalent
- * to initializing an ArrayView object with a pointer to the first
- * element and the size of the given argument.
+ * Create a view to an entire std::vector object. This is equivalent to
+ * initializing an ArrayView object with a pointer to the first element and
+ * the size of the given argument.
*
* This function is used for @p const references to objects of vector type
- * because they contain immutable elements. Consequently, the return type
- * of this function is a view to a set of @p const objects.
+ * because they contain immutable elements. Consequently, the return type of
+ * this function is a view to a set of @p const objects.
*
- * @param[in] vector The vector for which we want to have an array
- * view object. The array view corresponds to the <em>entire</em>
- * vector.
+ * @param[in] vector The vector for which we want to have an array view
+ * object. The array view corresponds to the <em>entire</em> vector.
*
* @relates ArrayView
*/
/**
- * Create a view to a part of a std::vector object. This is equivalent
- * to initializing the ArrayView object with a pointer to the
- * @p starting_index-th element and the @p size_of_view as the length of the view.
+ * Create a view to a part of a std::vector object. This is equivalent to
+ * initializing the ArrayView object with a pointer to the @p starting_index-
+ * th element and the @p size_of_view as the length of the view.
*
- * This function is used for non-@p const references to objects of vector type.
- * Such objects contain elements that can be written to. Consequently, the return
- * type of this function is a view to a set of writable objects.
+ * This function is used for non-@p const references to objects of vector
+ * type. Such objects contain elements that can be written to. Consequently,
+ * the return type of this function is a view to a set of writable objects.
*
- * @param[in] vector The vector for which we want to have an array
- * view object.
- * @param[in] starting_index The index of the first element of the
- * vector that will be part of this view.
+ * @param[in] vector The vector for which we want to have an array view
+ * object.
+ * @param[in] starting_index The index of the first element of the vector that
+ * will be part of this view.
* @param[in] size_of_view
*
* @pre <code>starting_index + size_of_view <= vector.size()</code>
/**
- * Create a view to a part of a std::vector object. This is equivalent
- * to initializing the ArrayView object with a pointer to the
- * @p starting_index-th element and the @p size_of_view as the length of the view.
+ * Create a view to a part of a std::vector object. This is equivalent to
+ * initializing the ArrayView object with a pointer to the @p starting_index-
+ * th element and the @p size_of_view as the length of the view.
*
* This function is used for @p const references to objects of vector type
- * because they contain immutable elements. Consequently, the return type
- * of this function is a view to a set of @p const objects.
+ * because they contain immutable elements. Consequently, the return type of
+ * this function is a view to a set of @p const objects.
*
- * @param[in] vector The vector for which we want to have an array
- * view object.
- * @param[in] starting_index The index of the first element of the
- * vector that will be part of this view.
+ * @param[in] vector The vector for which we want to have an array view
+ * object.
+ * @param[in] starting_index The index of the first element of the vector that
+ * will be part of this view.
* @param[in] size_of_view
*
* @pre <code>starting_index + size_of_view <= vector.size()</code>
/**
- * Create a view to an entire row of a Table<2> object. This is equivalent
- * to initializing an ArrayView object with a pointer to the first
- * element of the given row, and the length of the row as the length
- * of the view.
+ * Create a view to an entire row of a Table<2> object. This is equivalent to
+ * initializing an ArrayView object with a pointer to the first element of the
+ * given row, and the length of the row as the length of the view.
*
* This function is used for non-@p const references to objects of Table type.
* Such objects contain elements that can be written to. Consequently, the
* return type of this function is a view to a set of writable objects.
*
- * @param[in] table The Table for which we want to have an array
- * view object. The array view corresponds to an <em>entire</em>
- * row.
+ * @param[in] table The Table for which we want to have an array view object.
+ * The array view corresponds to an <em>entire</em> row.
* @param[in] row The index of the row into the table to which this view
- * should correspond.
+ * should correspond.
*
* @relates ArrayView
*/
/**
- * Create a view to an entire row of a Table<2> object. This is equivalent
- * to initializing an ArrayView object with a pointer to the first
- * element of the given row, and the length of the row as the length
- * of the view.
+ * Create a view to an entire row of a Table<2> object. This is equivalent to
+ * initializing an ArrayView object with a pointer to the first element of the
+ * given row, and the length of the row as the length of the view.
*
* This function is used for @p const references to objects of Table type
- * because they contain immutable elements. Consequently, the return type
- * of this function is a view to a set of @p const objects.
+ * because they contain immutable elements. Consequently, the return type of
+ * this function is a view to a set of @p const objects.
*
- * @param[in] table The Table for which we want to have an array
- * view object. The array view corresponds to an <em>entire</em>
- * row.
+ * @param[in] table The Table for which we want to have an array view object.
+ * The array view corresponds to an <em>entire</em> row.
* @param[in] row The index of the row into the table to which this view
- * should correspond.
+ * should correspond.
*
* @relates ArrayView
*/
* Such objects contain elements that can be written to. Consequently, the
* return type of this function is a view to a set of writable objects.
*
- * @param[in] table The Table for which we want to have an array
- * view object. The array view corresponds to an <em>entire</em>
- * row.
+ * @param[in] table The Table for which we want to have an array view object.
+ * The array view corresponds to an <em>entire</em> row.
* @param[in] row The index of the row into the table to which this view
- * should correspond.
- * @param[in] starting_column The index of the column into the given row
- * of the table that corresponds to the first element of this view.
- * @param[in] size_of_view The number of elements this view should have.
- * This corresponds to the number of columns in the current row to
- * which the view should correspond.
+ * should correspond.
+ * @param[in] starting_column The index of the column into the given row of
+ * the table that corresponds to the first element of this view.
+ * @param[in] size_of_view The number of elements this view should have. This
+ * corresponds to the number of columns in the current row to which the view
+ * should correspond.
*
* @relates ArrayView
*/
* Create a view to (a part of) a row of a Table<2> object.
*
* This function is used for @p const references to objects of Table type
- * because they contain immutable elements. Consequently, the return type
- * of this function is a view to a set of @p const objects.
+ * because they contain immutable elements. Consequently, the return type of
+ * this function is a view to a set of @p const objects.
*
- * @param[in] table The Table for which we want to have an array
- * view object. The array view corresponds to an <em>entire</em>
- * row.
+ * @param[in] table The Table for which we want to have an array view object.
+ * The array view corresponds to an <em>entire</em> row.
* @param[in] row The index of the row into the table to which this view
- * should correspond.
- * @param[in] starting_column The index of the column into the given row
- * of the table that corresponds to the first element of this view.
- * @param[in] size_of_view The number of elements this view should have.
- * This corresponds to the number of columns in the current row to
- * which the view should correspond.
+ * should correspond.
+ * @param[in] starting_column The index of the column into the given row of
+ * the table that corresponds to the first element of this view.
+ * @param[in] size_of_view The number of elements this view should have. This
+ * corresponds to the number of columns in the current row to which the view
+ * should correspond.
*
* @relates ArrayView
*/
#ifndef DEAL_II_HAVE_COMPLEX_OPERATOR_OVERLOADS
/**
- * Provide an <tt>operator*</tt> that operates on mixed complex floating
- * point types. Annoyingly, the standard library does not provide such an
+ * Provide an <tt>operator*</tt> that operates on mixed complex floating point
+ * types. Annoyingly, the standard library does not provide such an
* operator...
*
* @relates ProductType
/**
* Provide an <tt>operator*</tt> for a scalar multiplication of a complex
- * floating point type with a different real floating point type.
- * Annoyingly, the standard library does not provide such an operator...
+ * floating point type with a different real floating point type. Annoyingly,
+ * the standard library does not provide such an operator...
*
* @relates EnableIfScalar
* @relates ProductType
/**
* Default colorization function. This one does what one usually wants: It
* shifts colors from black (lowest value) through blue, green and red to
- * white (highest value). For the exact definition of the color scale refer
- * to the implementation.
+ * white (highest value). For the exact definition of the color scale
+ * refer to the implementation.
*
* This function was originally written by Stefan Nauber.
*/
const char *zone_name;
/**
- * Solution time for each zone in a strand. This value must be non-negative,
- * otherwise it will not be written to file. Do not assign any value for this
- * in case of a static zone.
+ * Solution time for each zone in a strand. This value must be non-
+ * negative, otherwise it will not be written to file. Do not assign any
+ * value for this in case of a static zone.
*/
double solution_time;
* declared somewhere before the object data. This may be in an external
* data file or at the beginning of the output file. Setting the
* <tt>external_data</tt> flag to false, an standard camera, light and
- * texture (scaled to fit the scene) is added to the output file. Set to true
- * an include file "data.inc" is included. This file is not generated by
- * deal and has to include camera, light and the texture definition Tex.
+ * texture (scaled to fit the scene) is added to the output file. Set to
+ * true an include file "data.inc" is included. This file is not generated
+ * by deal and has to include camera, light and the texture definition Tex.
*
* You need povray (>=3.0) to render the scene. The minimum options for
* povray are:
* functions are always used to map the reference dim-dimensional cell into
* spacedim-dimensional space. For such objects, the first derivative of the
* function is a linear map from ${\mathbb R}^{\text{dim}}$ to ${\mathbb
- * R}^{\text{spacedim}}$, i.e., it can be represented as a matrix
- * in ${\mathbb R}^{\text{spacedim}\times \text{dim}}$. This makes sense
- * since one would represent the first derivative, $\nabla f(\mathbf x)$
- * with $\mathbf x\in {\mathbb R}^{\text{dim}}$, in such a way that the
- * directional derivative in direction $\mathbf d\in {\mathbb R}^{\text{dim}}$
- * so that
+ * R}^{\text{spacedim}}$, i.e., it can be represented as a matrix in ${\mathbb
+ * R}^{\text{spacedim}\times \text{dim}}$. This makes sense since one would
+ * represent the first derivative, $\nabla f(\mathbf x)$ with $\mathbf x\in
+ * {\mathbb R}^{\text{dim}}$, in such a way that the directional derivative in
+ * direction $\mathbf d\in {\mathbb R}^{\text{dim}}$ so that
* @f{align*}{
* \nabla f(\mathbf x) \mathbf d
* = \lim_{\varepsilon\rightarrow 0}
* \frac{f(\mathbf x + \varepsilon \mathbf d) - f(\mathbf x)}{\varepsilon},
* @f}
* i.e., one needs to be able to multiply the matrix $\nabla f(\mathbf x)$ by
- * a vector in ${\mathbb R}^{\text{dim}}$, and the result is a difference
- * of function values, which are in ${\mathbb R}^{\text{spacedim}}$. Consequently,
- * the matrix must be of size $\text{spacedim}\times\text{dim}$.
+ * a vector in ${\mathbb R}^{\text{dim}}$, and the result is a difference of
+ * function values, which are in ${\mathbb R}^{\text{spacedim}}$.
+ * Consequently, the matrix must be of size $\text{spacedim}\times\text{dim}$.
*
* Similarly, the second derivative is a bilinear map from ${\mathbb
* R}^{\text{dim}} \times {\mathbb R}^{\text{dim}}$ to ${\mathbb
* R}^{\text{spacedim}}$, which one can think of a rank-3 object of size
* $\text{spacedim}\times\text{dim}\times\text{dim}$.
*
- * In deal.II we represent these derivatives
- * using objects of type DerivativeForm@<1,dim,spacedim,Number@>,
+ * In deal.II we represent these derivatives using objects of type
+ * DerivativeForm@<1,dim,spacedim,Number@>,
* DerivativeForm@<2,dim,spacedim,Number@> and so on.
*
* @author Sebastian Pauletti, 2011, Luca Heltai, 2015
"information.");
/**
- * Some of our numerical classes allow for setting all entries to zero
- * using the assignment operator <tt>=</tt>.
+ * Some of our numerical classes allow for setting all entries to zero using
+ * the assignment operator <tt>=</tt>.
*
* In many cases, this assignment operator makes sense <b>only</b> for the
* argument zero. In other cases, this exception is thrown.
std::vector<Vector<Number> > &values) const;
/**
- * Compute the Hessian of a given component at point <tt>p</tt>,
- * that is the gradient of the gradient of the function.
+ * Compute the Hessian of a given component at point <tt>p</tt>, that is the
+ * gradient of the gradient of the function.
*/
virtual SymmetricTensor<2,dim,Number> hessian (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Hessian of all components at point <tt>p</tt> and store
- * them in <tt>values</tt>.
+ * Compute the Hessian of all components at point <tt>p</tt> and store them
+ * in <tt>values</tt>.
*/
virtual void vector_hessian (const Point<dim> &p,
std::vector<SymmetricTensor<2,dim,Number> > &values) const;
{
public:
/**
- * Constructor; set values of all components to the provided one. The default number
- * of components is one.
+ * Constructor; set values of all components to the provided one. The
+ * default number of components is one.
*/
ConstantFunction (const Number value,
const unsigned int n_components = 1);
/**
- * Constructor; takes an <tt>std::vector<Number></tt> object as an argument. The number
- * of components is determined by <tt>values.size()</tt>.
+ * Constructor; takes an <tt>std::vector<Number></tt> object as an argument.
+ * The number of components is determined by <tt>values.size()</tt>.
*/
ConstantFunction (const std::vector<Number> &values);
/**
- * Constructor; takes an <tt>Vector<Number></tt> object as an argument. The number
- * of components is determined by <tt>values.size()</tt>.
+ * Constructor; takes an <tt>Vector<Number></tt> object as an argument. The
+ * number of components is determined by <tt>values.size()</tt>.
*/
ConstantFunction (const Vector<Number> &values);
/**
- * Substitute function value with value of a <tt>ConstantFunction@<dim, Number@></tt>
- * object and keep the current selection pattern.
+ * Substitute function value with value of a <tt>ConstantFunction@<dim,
+ * Number@></tt> object and keep the current selection pattern.
*
- * This is useful if you want to have different values in different components since the
- * provided constructors of <tt>ComponentSelectFunction@<dim, Number@></tt>
- * class can only have same value for all components.
+ * This is useful if you want to have different values in different
+ * components since the provided constructors of
+ * <tt>ComponentSelectFunction@<dim, Number@></tt> class can only have same
+ * value for all components.
*
- * @note: we copy the underlying component value data from @p f from its beginning.
- * So the number of components of @p f cannot be less than the calling object.
+ * @note: we copy the underlying component value data from @p f from its
+ * beginning. So the number of components of @p f cannot be less than the
+ * calling object.
*/
virtual void substitute_function_value_with (const ConstantFunction<dim, Number> &f);
* here, the given function object is still a scalar function (i.e. it has a
* single value at each space point) but that the Function object generated is
* vector valued. The number of vector components is specified in the
- * constructor, where one also selects a single one of these vector
- * components that should be filled by the passed object. The result is a
- * vector Function object that returns zero in each component except the
- * single selected one where it returns the value returned by the given as the
- * first argument to the constructor.
+ * constructor, where one also selects a single one of these vector components
+ * that should be filled by the passed object. The result is a vector Function
+ * object that returns zero in each component except the single selected one
+ * where it returns the value returned by the given as the first argument to
+ * the constructor.
*
* @note In the above discussion, note the difference between the (scalar)
* "function object" (i.e., a C++ object <code>x</code> that can be called as
/**
- * Member function <tt>vector_value_list </tt> is the interface for giving
- *
a list of points (<code>vector<Point<dim> ></code>) of which to evaluate
- * using the <tt>vector_value</tt> member function. Again, this function
- * is written so as to not replicate the function definition but passes
- * each point on to <tt>vector_value</tt> to be evaluated.
+ * Member function <tt>vector_value_list </tt> is the interface for giving a
+ * list of points (<code>vector<Point<dim> ></code>) of which to evaluate
+ * using the <tt>vector_value</tt> member function. Again, this function is
+ * written so as to not replicate the function definition but passes each
+ * point on to <tt>vector_value</tt> to be evaluated.
*/
template <int dim, typename Number>
void VectorFunctionFromTensorFunction<dim, Number>::vector_value_list (
* class are a subset.
*
* There are two ways to iterate over the IndexSets: First, begin() and end()
- * allow iteration over individual indices in the set. Second, begin_interval()
- * and end_interval() allow iteration over the half-open ranges as described
- * above.
+ * allow iteration over individual indices in the set. Second,
+ * begin_interval() and end_interval() allow iteration over the half-open
+ * ranges as described above.
*
* The data structures used in this class along with a rationale can be found
* in the
* Add a whole set of indices described by dereferencing every element of
* the iterator range <code>[begin,end)</code>.
*
- * @param[in] begin Iterator to the first element of range of indices
- * to be added
- * @param[in] end The past-the-end iterator for the range of elements
- * to be added.
- * @pre The condition <code>begin@<=end</code> needs to be satisfied.
+ * @param[in] begin Iterator to the first element of range of indices to be
+ * added
+ * @param[in] end The past-the-end iterator for the range of elements to be
+ * added. @pre The condition <code>begin@<=end</code> needs to be satisfied.
*/
template <typename ForwardIterator>
void add_indices (const ForwardIterator &begin,
unsigned int n_intervals () const;
/**
- * This function returns the local index of the beginning of the largest range.
+ * This function returns the local index of the beginning of the largest
+ * range.
*/
unsigned int largest_range_starting_index() const;
ElementIterator end() const;
/**
- * Return the index of the last index in this interval.
- */
+ * Return the index of the last index in this interval.
+ */
size_type last() const;
private:
/**
* Maximum number of levels to be printed on the console. The default is 0,
- * which will not generate any output. This function
- * allows one to restrict console output to the highest levels of
- * iterations. Only output with less than <tt>n</tt> prefixes is
- * printed. By calling this function with <tt>n=0</tt>, no console output
- * will be written. See step-3 for an example usage of this method.
+ * which will not generate any output. This function allows one to restrict
+ * console output to the highest levels of iterations. Only output with less
+ * than <tt>n</tt> prefixes is printed. By calling this function with
+ * <tt>n=0</tt>, no console output will be written. See step-3 for an
+ * example usage of this method.
*
* The previous value of this parameter is returned.
*/
* free to implement them and send them to us for inclusion.
*
* @ingroup memory
- * @author Wolfgang Bangerth, documentation updated by Guido Kanschat, David Wells
+ * @author Wolfgang Bangerth, documentation updated by Guido Kanschat, David
+ * Wells
* @date 2000, 2015
*/
namespace MemoryConsumption
/**
* Return the number of MPI processes there exist in the given
* @ref GlossMPICommunicator "communicator"
- * object. If this is
- * a sequential job, it returns 1.
+ * object. If this is a sequential job, it returns 1.
*/
unsigned int n_mpi_processes (const MPI_Comm &mpi_communicator);
* @ref GlossMPIRank "rank of the present MPI process"
* in the space of processes described by the given
* @ref GlossMPICommunicator "communicator".
- * This will be a unique value for
- * each process between zero and (less than) the number of all processes
- * (given by get_n_mpi_processes()).
+ * This will be a unique value for each process between zero and (less
+ * than) the number of all processes (given by get_n_mpi_processes()).
*/
unsigned int this_mpi_process (const MPI_Comm &mpi_communicator);
*
* @param mpi_comm A
* @ref GlossMPICommunicator "communicator"
- * that describes
- * the processors that are going to communicate with each other.
+ * that describes the processors that are going to communicate with each
+ * other.
*
* @param destinations The list of processors the current process wants to
* send information to. This list need not be sorted in any way. If it
/**
* Given a
* @ref GlossMPICommunicator "communicator",
- * generate a new
- * communicator that contains the
- * same set of processors but that has a different, unique identifier.
+ * generate a new communicator that contains the same set of processors
+ * but that has a different, unique identifier.
*
* This functionality can be used to ensure that different objects, such
* as distributed matrices, each have unique communicators over which they
* Return the sum over all processors of the value @p t. This function is
* collective over all processors given in the
* @ref GlossMPICommunicator "communicator".
- * If deal.II is
- * not configured for use of MPI, this function simply returns the value
- * of @p t. This function corresponds to the <code>MPI_Allreduce</code>
- * function, i.e. all processors receive the result of this operation.
+ * If deal.II is not configured for use of MPI, this function simply
+ * returns the value of @p t. This function corresponds to the
+ * <code>MPI_Allreduce</code> function, i.e. all processors receive the
+ * result of this operation.
*
* @note Sometimes, not all processors need a result and in that case one
* would call the <code>MPI_Reduce</code> function instead of the
* Return the maximum over all processors of the value @p t. This function
* is collective over all processors given in the
* @ref GlossMPICommunicator "communicator".
- * If deal.II
- * is not configured for use of MPI, this function simply returns the
- * value of @p t. This function corresponds to the
+ * If deal.II is not configured for use of MPI, this function simply
+ * returns the value of @p t. This function corresponds to the
* <code>MPI_Allreduce</code> function, i.e. all processors receive the
* result of this operation.
*
* Return the minimum over all processors of the value @p t. This function
* is collective over all processors given in the
* @ref GlossMPICommunicator "communicator".
- * If deal.II
- * is not configured for use of MPI, this function simply returns the
- * value of @p t. This function corresponds to the
+ * If deal.II is not configured for use of MPI, this function simply
+ * returns the value of @p t. This function corresponds to the
* <code>MPI_Allreduce</code> function, i.e. all processors receive the
* result of this operation.
*
* Returns sum, average, minimum, maximum, processor id of minimum and
* maximum as a collective operation of on the given MPI
* @ref GlossMPICommunicator "communicator"
- * @p mpi_communicator.
- * Each processor's value is given in @p my_value and
+ * @p mpi_communicator. Each processor's value is given in @p my_value and
* the result will be returned. The result is available on all machines.
*
* @note Sometimes, not all processors need a result and in that case one
/**
- * Constructor made private because no instance of this class needs to
- * be constructed as all members are static.
+ * Constructor made private because no instance of this class needs to be
+ * constructed as all members are static.
*/
MultithreadInfo ();
static unsigned int n_max_threads;
/**
- * Variable representing the number of cores in the system. This is computed by
- * get_n_cpus() and is returned by n_cores().
+ * Variable representing the number of cores in the system. This is computed
+ * by get_n_cpus() and is returned by n_cores().
*/
static const unsigned int n_cpus;
};
* course commas are not allowed inside the values given to the constructor.
*
* For example, if the string to the constructor was <tt>"ucd|gmv|eps"</tt>,
- * then the following would be legal inputs: "eps", "gmv, eps",
- * or "".
+ * then the following would be legal inputs: "eps", "gmv, eps", or "".
*/
class MultipleSelection : public PatternBase
{
std::string get_current_full_path (const std::string &name) const;
/**
- * Scan one line of input. <tt>input_filename</tt> and <tt>current_line_n</tt>
- * are the name of the input file and the current number of the line presently
- * scanned (for the logs if there are messages). Return <tt>false</tt> if line
- * contained stuff that could not be understood, the uppermost subsection was
- * to be left by an <tt>END</tt> or <tt>end</tt> statement, a value for a
- * non-declared entry was given or the entry value did not match the regular
- * expression. <tt>true</tt> otherwise.
+ * Scan one line of input. <tt>input_filename</tt> and
+ * <tt>current_line_n</tt> are the name of the input file and the current
+ * number of the line presently scanned (for the logs if there are
+ * messages). Return <tt>false</tt> if line contained stuff that could not
+ * be understood, the uppermost subsection was to be left by an <tt>END</tt>
+ * or <tt>end</tt> statement, a value for a non-declared entry was given or
+ * the entry value did not match the regular expression. <tt>true</tt>
+ * otherwise.
*
* The function modifies its argument, but also takes it by value, so the
* caller's variable is not changed.
/**
* Return the scalar product of this point vector with itself, i.e. the
- * square, or the square of the norm. In case of a complex number type it
- * is equivalent to the contraction of this point vector with a complex
+ * square, or the square of the norm. In case of a complex number type it is
+ * equivalent to the contraction of this point vector with a complex
* conjugate of itself.
*
* @note This function is equivalent to
std::vector<Tensor<4,dim> > &fourth_derivatives) const;
/**
- * Computes the value of the <tt>i</tt>th polynomial at unit point <tt>p</tt>.
+ * Computes the value of the <tt>i</tt>th polynomial at unit point
+ * <tt>p</tt>.
*
* Consider using compute() instead.
*/
const Point<dim> &p) const;
/**
- * Computes the gradient of the <tt>i</tt>th polynomial at
- * unit point <tt>p</tt>.
+ * Computes the gradient of the <tt>i</tt>th polynomial at unit point
+ * <tt>p</tt>.
*
* Consider using compute() instead.
*/
* Static function used in the constructor to compute the number of
* polynomials.
*
- * @warning The argument `n` is not the maximal degree, but the
- * number of onedimensional polynomials, thus the degree plus one.
+ * @warning The argument `n` is not the maximal degree, but the number of
+ * onedimensional polynomials, thus the degree plus one.
*/
static unsigned int compute_n_pols (const unsigned int n);
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements Bernstein basis polynomials of desire degree as described in
- * http://www.idav.ucdavis.edu/education/CAGDNotes/Bernstein-Polynomials.pdf
- * in the paragraph "Converting from the Bernstein Basis to the Power Basis".
+ * This class implements Bernstein basis polynomials of desire degree as
+ * described in http://www.idav.ucdavis.edu/education/CAGDNotes/Bernstein-
+ * Polynomials.pdf in the paragraph "Converting from the Bernstein Basis to
+ * the Power Basis".
*
* They are used to create the Bernstein finite element FE_Bernstein.
*
* Basis for polynomial space on the unit square used for lowest order
* Rannacher Turek element.
*
- * The i-th basis function is the dual basis element corresponding to
- * the dof which evaluates the function's mean value across the i-th
- * face. The numbering can be found in GeometryInfo.
+ * The i-th basis function is the dual basis element corresponding to the dof
+ * which evaluates the function's mean value across the i-th face. The
+ * numbering can be found in GeometryInfo.
*
* @ingroup Polynomials
* @author Patrick Esser
* @date 2015
- **/
+ */
template <int dim>
class PolynomialsRannacherTurek
{
static const unsigned int dimension = dim;
/**
- * Constructor, checking that the basis is implemented in this
- * dimension.
+ * Constructor, checking that the basis is implemented in this dimension.
*/
PolynomialsRannacherTurek();
- /** Value of basis function @p i at @p p.
- */
+ /**
+ * Value of basis function @p i at @p p.
+ */
double compute_value(const unsigned int i,
const Point<dim> &p) const;
Tensor<order,dim> compute_derivative (const unsigned int i,
const Point<dim> &p) const;
- /** Gradient of basis function @p i at @p p.
- */
+ /**
+ * Gradient of basis function @p i at @p p.
+ */
Tensor<1, dim> compute_grad(const unsigned int i,
const Point<dim> &p) const;
- /** Gradient of gradient of basis function @p i at @p p.
- */
+ /**
+ * Gradient of gradient of basis function @p i at @p p.
+ */
Tensor<2, dim> compute_grad_grad(const unsigned int i,
const Point<dim> &p) const;
/**
- * Compute values and derivatives of all basis functions at @p
- * unit_point.
+ * Compute values and derivatives of all basis functions at @p unit_point.
*
- * Size of the vectors must be either equal to the number of
- * polynomials or zero. A size of zero means that we are not
- * computing the vector entries.
+ * Size of the vectors must be either equal to the number of polynomials or
+ * zero. A size of zero means that we are not computing the vector entries.
*/
void compute(const Point<dim> &unit_point,
std::vector<double> &values,
/**
* Telles quadrature of arbitrary order.
*
- * The coefficients of these quadrature rules are computed using
- * a non linear change of variables starting from a Gauss-Legendre
- * quadrature formula.
- * This is done using a cubic polynomial,
- * $n = a x^3 + b x^2 + c x + d$
- * in order to integrate
- * a singular integral, with singularity at a given point x_0.
+ * The coefficients of these quadrature rules are computed using a non linear
+ * change of variables starting from a Gauss-Legendre quadrature formula. This
+ * is done using a cubic polynomial, $n = a x^3 + b x^2 + c x + d$ in order to
+ * integrate a singular integral, with singularity at a given point x_0.
*
- * We start from a Gauss Quadrature Formula with arbitrary
- * function. Then we apply the cubic variable change.
- * In the paper, J.C.F.Telles:A Self-Adaptive Co-ordinate Transformation
- * For Efficient Numerical Evaluation of General Boundary Element Integrals.
- * International Journal for Numerical Methods in Engineering, vol 24,
- * pages 959–973. year 1987, the author applies the transformation on the
- * reference cell $[-1, 1]$ getting
+ * We start from a Gauss Quadrature Formula with arbitrary function. Then we
+ * apply the cubic variable change. In the paper, J.C.F.Telles:A Self-Adaptive
+ * Co-ordinate Transformation For Efficient Numerical Evaluation of General
+ * Boundary Element Integrals. International Journal for Numerical Methods in
+ * Engineering, vol 24, pages 959–973. year 1987, the author applies the
+ * transformation on the reference cell $[-1, 1]$ getting
* @f{align*}{
* n(1) &= 1, \\ n(-1) &= -1, \\ \frac{dn}{dx} &= 0 \text{ at }
* x = x_0, \\ \frac{d^2n}{dx^2} &= 0 \text{ at } x = x_0
* q &= (\Gamma-\bar{\Gamma})^3 + \bar{\Gamma}
* \frac{\bar{\Gamma}^2+3}{1+3\bar{\Gamma}^2}
* @f}
- * Since the library assumes $[0,1]$ as reference interval, we will map
- * these values on the proper reference interval in the implementation.
+ * Since the library assumes $[0,1]$ as reference interval, we will map these
+ * values on the proper reference interval in the implementation.
*
- * This variable change can be used to integrate singular integrals.
- * One example is $f(x)/|x-x_0|$ on the reference interval $[0,1]$,
- * where $x_0$ is given at construction time, and is the location of the
- * singularity $x_0$, and $f(x)$ is a smooth non singular function.
+ * This variable change can be used to integrate singular integrals. One
+ * example is $f(x)/|x-x_0|$ on the reference interval $[0,1]$, where $x_0$ is
+ * given at construction time, and is the location of the singularity $x_0$,
+ * and $f(x)$ is a smooth non singular function.
*
* Singular quadrature formula are rather expensive, nevertheless Telles'
- * quadrature formula are much easier to compute with respect to other singular
- * integration techniques as Lachat-Watson.
+ * quadrature formula are much easier to compute with respect to other
+ * singular integration techniques as Lachat-Watson.
*
* We have implemented the case for $dim = 1$. When we deal the case $dim >1$
* we have computed the quadrature formula has a tensorial product of one
- * dimensional Telles' quadrature formulas considering the different components
- * of the singularity.
+ * dimensional Telles' quadrature formulas considering the different
+ * components of the singularity.
*
* The weights and functions for Gauss Legendre formula have been tabulated up
* to order 12.
{
public:
/**
- * A constructor that takes a quadrature formula and a singular point as
- * argument. The quadrature formula will be mapped using Telles' rule. Make
- * sure that the order of the quadrature rule is appropriate for the
- * singularity in question.
- **/
+ * A constructor that takes a quadrature formula and a singular point as
+ * argument. The quadrature formula will be mapped using Telles' rule. Make
+ * sure that the order of the quadrature rule is appropriate for the
+ * singularity in question.
+ */
QTelles (const Quadrature<1> &base_quad, const Point<dim> &singularity);
/**
- * A variant of above constructor that takes as parameters the order @p n
- * and location of a singularity. A Gauss Legendre quadrature of order n
- * will be used
- **/
+ * A variant of above constructor that takes as parameters the order @p n
+ * and location of a singularity. A Gauss Legendre quadrature of order n
+ * will be used
+ */
QTelles (const unsigned int n, const Point<dim> &singularity);
};
/*@}*/
/**
-* Gauss-Chebyshev quadrature rules integrate the weighted product
-* $\int_{-1}^1 f(x) w(x) dx$ with weight given by:
-* $w(x) = 1/\sqrt{1-x^2}$. The nodes and weights are known analytically,
-* and are exact for monomials up to the order $2n-1$, where $n$ is the number
-* of quadrature points.
-* Here we rescale the quadrature formula so that it is defined on
-* the interval $[0,1]$ instead of $[-1,1]$. So the quadrature formulas
-* integrate exactly the integral $\int_0^1 f(x) w(x) dx$ with the weight:
-* $w(x) = 1/sqrt{x(1-x)}$.
-* For details see:
-* M. Abramowitz & I.A. Stegun: Handbook of Mathematical Functions, par. 25.4.38
-*
-* @author Giuseppe Pitton, Luca Heltai 2015
-**/
+ * Gauss-Chebyshev quadrature rules integrate the weighted product
+ * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$.
+ * The nodes and weights are known analytically, and are exact for monomials
+ * up to the order $2n-1$, where $n$ is the number of quadrature points. Here
+ * we rescale the quadrature formula so that it is defined on the interval
+ * $[0,1]$ instead of $[-1,1]$. So the quadrature formulas integrate exactly
+ * the integral $\int_0^1 f(x) w(x) dx$ with the weight: $w(x) =
+ * 1/sqrt{x(1-x)}$. For details see: M. Abramowitz & I.A. Stegun: Handbook of
+ * Mathematical Functions, par. 25.4.38
+ *
+ * @author Giuseppe Pitton, Luca Heltai 2015
+ */
template <int dim>
class QGaussChebyshev : public Quadrature<dim>
{
/**
-* Gauss-Radau-Chebyshev quadrature rules integrate the weighted product
-* $\int_{-1}^1 f(x) w(x) dx$ with weight given by:
-* $w(x) = 1/\sqrt{1-x^2}$ with the additional constraint that a quadrature point
-* lies at one of the two extrema of the interval.
-* The nodes and weights are known analytically,
-* and are exact for monomials up to the order $2n-2$, where $n$ is the number
-* of quadrature points. Here we rescale the quadrature formula so that it is defined on
-* the interval $[0,1]$ instead of $[-1,1]$. So the quadrature formulas
-* integrate exactly the integral $\int_0^1 f(x) w(x) dx$ with the weight:
-* $w(x) = 1/sqrt{x(1-x)}$. By default the quadrature is constructed with the
-* left endpoint as quadrature node, but the quadrature node can be imposed at the
-* right endpoint through the variable ep that can assume the values left or right.
-*
-* @author Giuseppe Pitton, Luca Heltai 2015
-**/
+ * Gauss-Radau-Chebyshev quadrature rules integrate the weighted product
+ * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$
+ * with the additional constraint that a quadrature point lies at one of the
+ * two extrema of the interval. The nodes and weights are known analytically,
+ * and are exact for monomials up to the order $2n-2$, where $n$ is the number
+ * of quadrature points. Here we rescale the quadrature formula so that it is
+ * defined on the interval $[0,1]$ instead of $[-1,1]$. So the quadrature
+ * formulas integrate exactly the integral $\int_0^1 f(x) w(x) dx$ with the
+ * weight: $w(x) = 1/sqrt{x(1-x)}$. By default the quadrature is constructed
+ * with the left endpoint as quadrature node, but the quadrature node can be
+ * imposed at the right endpoint through the variable ep that can assume the
+ * values left or right.
+ *
+ * @author Giuseppe Pitton, Luca Heltai 2015
+ */
template <int dim>
class QGaussRadauChebyshev : public Quadrature<dim>
{
};
/**
-* Gauss-Lobatto-Chebyshev quadrature rules integrate the weighted product
-* $\int_{-1}^1 f(x) w(x) dx$ with weight given by:
-* $w(x) = 1/\sqrt{1-x^2}$, with the additional constraint that two of the quadrature
-* points are located at the endpoints of the quadrature interval.
-* The nodes and weights are known analytically,
-* and are exact for monomials up to the order $2n-3$, where $n$ is the number
-* of quadrature points.
-* Here we rescale the quadrature formula so that it is defined on
-* the interval $[0,1]$ instead of $[-1,1]$. So the quadrature formulas
-* integrate exactly the integral $\int_0^1 f(x) w(x) dx$ with the weight:
-* $w(x) = 1/sqrt{x(1-x)}$.
-* For details see:
-* M. Abramowitz & I.A. Stegun: Handbook of Mathematical Functions, par. 25.4.40
-*
-* @author Giuseppe Pitton, Luca Heltai 2015
-**/
+ * Gauss-Lobatto-Chebyshev quadrature rules integrate the weighted product
+ * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$,
+ * with the additional constraint that two of the quadrature points are
+ * located at the endpoints of the quadrature interval. The nodes and weights
+ * are known analytically, and are exact for monomials up to the order $2n-3$,
+ * where $n$ is the number of quadrature points. Here we rescale the
+ * quadrature formula so that it is defined on the interval $[0,1]$ instead of
+ * $[-1,1]$. So the quadrature formulas integrate exactly the integral
+ * $\int_0^1 f(x) w(x) dx$ with the weight: $w(x) = 1/sqrt{x(1-x)}$. For
+ * details see: M. Abramowitz & I.A. Stegun: Handbook of Mathematical
+ * Functions, par. 25.4.40
+ *
+ * @author Giuseppe Pitton, Luca Heltai 2015
+ */
template <int dim>
class QGaussLobattoChebyshev : public Quadrature<dim>
{
namespace internal
{
/**
- * A namespace for the implementation of functions that create
- * signaling NaN objects. This is where the Utilities::signaling_nan()
- * function calls into.
+ * A namespace for the implementation of functions that create signaling
+ * NaN objects. This is where the Utilities::signaling_nan() function
+ * calls into.
*/
namespace SignalingNaN
{
/**
- * A general template for classes that know how to initialize
- * objects of type @p T with signaling NaNs to denote invalid
- * values.
+ * A general template for classes that know how to initialize objects of
+ * type @p T with signaling NaNs to denote invalid values.
*
* The real implementation of this class happens in (partial)
- * specializations for particular values of the template
- * argument @p T.
+ * specializations for particular values of the template argument @p T.
*/
template <typename T>
struct NaNInitializer;
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a @p float value equal to
- * the invalid signaling NaN.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a @p float value equal to the invalid signaling
+ * NaN.
*/
template <>
struct NaNInitializer<float>
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a @p double value equal to
- * the invalid signaling NaN.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a @p double value equal to the invalid
+ * signaling NaN.
*/
template <>
struct NaNInitializer<double>
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a Tensor<1,dim> value whose
- * components are invalid signaling NaN values.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a Tensor<1,dim> value whose components are
+ * invalid signaling NaN values.
*/
template <int dim, typename T>
struct NaNInitializer<Tensor<1,dim,T> >
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a Tensor<rank,dim> value whose
- * components are invalid signaling NaN values.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a Tensor<rank,dim> value whose components are
+ * invalid signaling NaN values.
*/
template <int rank, int dim, typename T>
struct NaNInitializer<Tensor<rank,dim,T> >
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a SymmetricTensor<rank,dim>
- * value whose components are invalid signaling NaN values.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a SymmetricTensor<rank,dim> value whose
+ * components are invalid signaling NaN values.
*/
template <int rank, int dim, typename T>
struct NaNInitializer<SymmetricTensor<rank,dim,T> >
/**
- * A specialization of the general NaNInitializer class that
- * provides a function that returns a
- * DerivativeForm<order,dim,spacedim> value whose components are
- * invalid signaling NaN values.
+ * A specialization of the general NaNInitializer class that provides a
+ * function that returns a DerivativeForm<order,dim,spacedim> value
+ * whose components are invalid signaling NaN values.
*/
template <int order, int dim, int spacedim, typename T>
struct NaNInitializer<DerivativeForm<order,dim,spacedim,T> >
/**
- * Provide an object of type @p T filled with a signaling NaN that
- * will cause an exception when used in a computation. The content
- * of these objects is a "signaling NaN" ("NaN" stands for "not a
- * number", and "signaling" implies that at least on platforms where
- * this is supported, any arithmetic operation using them terminates
- * the program). The purpose of such objects is to use them as
- * markers for uninitialized objects and arrays that are required to
- * be filled in other places, and to trigger an error when this
- * later initialization does not happen before the first use.
+ * Provide an object of type @p T filled with a signaling NaN that will
+ * cause an exception when used in a computation. The content of these
+ * objects is a "signaling NaN" ("NaN" stands for "not a number", and
+ * "signaling" implies that at least on platforms where this is supported,
+ * any arithmetic operation using them terminates the program). The purpose
+ * of such objects is to use them as markers for uninitialized objects and
+ * arrays that are required to be filled in other places, and to trigger an
+ * error when this later initialization does not happen before the first
+ * use.
*
* @tparam T The type of the returned invalid object. This type can either
- * be a scalar, or of type Tensor, SymmetricTensor, or DerivativeForm.
- * Other types may be supported if there is a corresponding
- * specialization of the internal::SignalingNaN::NaNInitializer class
- * for this type.
+ * be a scalar, or of type Tensor, SymmetricTensor, or DerivativeForm. Other
+ * types may be supported if there is a corresponding specialization of the
+ * internal::SignalingNaN::NaNInitializer class for this type.
*
* @note Because the type @p T is not used as a function argument, the
- * compiler cannot deduce it from the type of arguments. Consequently,
- * you have to provide it explicitly. For example, the line
+ * compiler cannot deduce it from the type of arguments. Consequently, you
+ * have to provide it explicitly. For example, the line
* @code
* Tensor<1,dim> tensor = Utilities::signaling_nan<Tensor<1,dim> >();
* @endcode
- * initializes a tensor with invalid values.
+ * initializes a tensor with invalid values.
*/
template <class T>
T
* constant objects also.
*
* In multithreaded mode, this counter may be modified by different threads.
- * We thus have to mark it <tt>volatile</tt>. However, this is
- * counter-productive in non-MT mode since it may pessimize code. So use the macro
+ * We thus have to mark it <tt>volatile</tt>. However, this is counter-
+ * productive in non-MT mode since it may pessimize code. So use the macro
* defined in <tt>deal.II/base/config.h</tt> to selectively add volatility.
*/
mutable DEAL_VOLATILE unsigned int counter;
/**
- * Subtraction of a general Tensor with a SymmetricTensor of equal rank.
- * The result is a general Tensor.
+ * Subtraction of a general Tensor with a SymmetricTensor of equal rank. The
+ * result is a general Tensor.
*
* @relates SymmetricTensor
*/
* <code>std_cxx11::tuple</code> with arguments equal to the iterator types.
*
* The individual iterators can be accessed using
- * <code>std_cxx11::get<X>(synchronous_iterator.iterators)</code> where X is the
- * number corresponding to the desired iterator.
+ * <code>std_cxx11::get<X>(synchronous_iterator.iterators)</code> where X is
+ * the number corresponding to the desired iterator.
*
* This type, and the helper functions associated with it, are used as the
* Value concept for the blocked_range type of the Threading Building Blocks.
void reset_values ();
/**
- * Set the dimensions of this object to the sizes given in the
- * argument, and newly allocate the required memory. If
- * <tt>omit_default_initialization</tt> is set to <tt>false</tt>,
- * all elements of the table are set to a default constructed object
- * for the element type. Otherwise the memory is left in an
- * uninitialized or otherwise undefined state.
+ * Set the dimensions of this object to the sizes given in the argument, and
+ * newly allocate the required memory. If
+ * <tt>omit_default_initialization</tt> is set to <tt>false</tt>, all
+ * elements of the table are set to a default constructed object for the
+ * element type. Otherwise the memory is left in an uninitialized or
+ * otherwise undefined state.
*/
void reinit (const TableIndices<N> &new_size,
const bool omit_default_initialization = false);
TableIndices();
/**
- * Convenience constructor that takes up to 9 arguments. It can be used
- * to populate a TableIndices object upon creation, either completely, or
+ * Convenience constructor that takes up to 9 arguments. It can be used to
+ * populate a TableIndices object upon creation, either completely, or
* partially.
*
- * Index entries that are not set by these arguments (either because
- * they are omitted, or because $N > 9$) are set to
+ * Index entries that are not set by these arguments (either because they
+ * are omitted, or because $N > 9$) are set to
* numbers::invalid_unsigned_int.
*
* Note that only the first <tt>N</tt> arguments are actually used.
/**
- * Output operator for TableIndices objects; reports them in a list like
- * this: <code>[i1,i2,...]</code>.
+ * Output operator for TableIndices objects; reports them in a list like this:
+ * <code>[i1,i2,...]</code>.
*
* @relates TableIndices
*/
/**
- * This class is a specialized version of the
- * <tt>Tensor<rank,dim,Number></tt> class. It handles tensors of rank zero,
- * i.e. scalars. The second template argument @p dim is ignored.
+ * This class is a specialized version of the <tt>Tensor<rank,dim,Number></tt>
+ * class. It handles tensors of rank zero, i.e. scalars. The second template
+ * argument @p dim is ignored.
*
* This class exists because in some cases we want to construct objects of
* type Tensor@<spacedim-dim,dim,Number@>, which should expand to scalars,
* Return a reference to the encapsulated Number object. Since rank-0
* tensors are scalars, this is a natural operation.
*
- * This is the const conversion operator that returns a read-only
- * reference.
+ * This is the const conversion operator that returns a read-only reference.
*/
operator const Number &() const;
Tensor<0,dim,Number> &operator = (const Tensor<0,dim,Number> &rhs);
/**
- * Assignment from tensors with different underlying scalar type.
- * This obviously requires that the @p OtherNumber type is convertible to @p
+ * Assignment from tensors with different underlying scalar type. This
+ * obviously requires that the @p OtherNumber type is convertible to @p
* Number.
*/
template <typename OtherNumber>
void clear ();
/**
- * Return the Frobenius-norm of a tensor, i.e. the square root of the sum
- * of the absolute squares of all entries. For the present case of rank-1
- * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the
- * vector.
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+ * the absolute squares of all entries. For the present case of rank-1
+ * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
*/
real_type norm () const;
/**
- * Return the square of the Frobenius-norm of a tensor, i.e. the sum of
- * the absolute squares of all entries.
+ * Return the square of the Frobenius-norm of a tensor, i.e. the sum of the
+ * absolute squares of all entries.
*/
real_type norm_square () const;
void serialize(Archive &ar, const unsigned int version);
/**
- * Internal type declaration that is used to specialize the return type
- * of operator[]() for Tensor<1,dim,Number>
+ * Internal type declaration that is used to specialize the return type of
+ * operator[]() for Tensor<1,dim,Number>
*/
typedef Number tensor_type;
/**
* Type of objects encapsulated by this container and returned by
- * operator[](). This is a tensor of lower rank for a general tensor, and
- * a scalar number type for Tensor<1,dim,Number>.
+ * operator[](). This is a tensor of lower rank for a general tensor, and a
+ * scalar number type for Tensor<1,dim,Number>.
*/
typedef typename Tensor<rank_-1,dim,Number>::tensor_type value_type;
void clear ();
/**
- * Return the Frobenius-norm of a tensor, i.e. the square root of the sum
- * of the absolute squares of all entries. For the present case of rank-1
- * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the
- * vector.
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+ * the absolute squares of all entries. For the present case of rank-1
+ * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
*/
typename numbers::NumberTraits<Number>::real_type norm() const;
/**
- * Return the square of the Frobenius-norm of a tensor, i.e. the sum of
- * the absolute squares of all entries.
+ * Return the square of the Frobenius-norm of a tensor, i.e. the sum of the
+ * absolute squares of all entries.
*/
typename numbers::NumberTraits<Number>::real_type norm_square() const;
void serialize(Archive &ar, const unsigned int version);
/**
- * Internal type declaration that is used to specialize the return type
- * of operator[]() for Tensor<1,dim,Number>
+ * Internal type declaration that is used to specialize the return type of
+ * operator[]() for Tensor<1,dim,Number>
*/
typedef Tensor<rank_, dim, Number> tensor_type;
/**
- * Scalar multiplication of a tensor of rank 0 with an object from the
- * left.
+ * Scalar multiplication of a tensor of rank 0 with an object from the left.
*
* This function unwraps the underlying @p Number stored in the Tensor and
* multiplies @p object with it.
/**
- * Scalar multiplication of a tensor of rank 0 with an object from the
- * right.
+ * Scalar multiplication of a tensor of rank 0 with an object from the right.
*
* This function unwraps the underlying @p Number stored in the Tensor and
* multiplies @p object with it.
* Scalar multiplication of two tensors of rank 0.
*
* This function unwraps the underlying objects of type @p Number and @p
- * OtherNumber that are stored within the Tensor and multiplies them.
- * It returns an unwrapped number of product type.
+ * OtherNumber that are stored within the Tensor and multiplies them. It
+ * returns an unwrapped number of product type.
*
* @relates Tensor<0,dim,Number>
*/
/**
- * The dot product (single contraction) for tensors: Return a tensor of
- * rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of
- * the last index of a tensor @p src1 of rank @p rank_1 with the first
- * index of a tensor @p src2 of rank @p rank_2:
+ * The dot product (single contraction) for tensors: Return a tensor of rank
+ * $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of the last
+ * index of a tensor @p src1 of rank @p rank_1 with the first index of a
+ * tensor @p src2 of rank @p rank_2:
* @f[
* \text{result}_{i_1,..,i_{r1},j_1,..,j_{r2}}
* = \sum_{k}
* multiplication operator for SymmetricTensor, which does the double
* contraction.
*
- * @note In case the contraction yields a tensor of rank 0 the scalar
- * number is returned as an unwrapped number type.
+ * @note In case the contraction yields a tensor of rank 0 the scalar number
+ * is returned as an unwrapped number type.
*
* @relates Tensor
* @author Matthias Maier, 2015
/**
- * Generic contraction of a pair of indices of two tensors of arbitrary
- * rank: Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that
- * is the contraction of index @p index_1 of a tensor @p src1 of rank
- * @p rank_1 with the index @p index_2 of a tensor @p src2 of rank @p rank_2:
+ * Generic contraction of a pair of indices of two tensors of arbitrary rank:
+ * Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the
+ * contraction of index @p index_1 of a tensor @p src1 of rank @p rank_1 with
+ * the index @p index_2 of a tensor @p src2 of rank @p rank_2:
* @f[
* \text{result}_{i_1,..,i_{r1},j_1,..,j_{r2}}
* = \sum_{k}
* @note The position of the index is counted from 0, i.e.,
* $0\le\text{index}_i<\text{range}_i$.
*
- * @note In case the contraction yields a tensor of rank 0 the scalar
- * number is returned as an unwrapped number type.
+ * @note In case the contraction yields a tensor of rank 0 the scalar number
+ * is returned as an unwrapped number type.
*
* @relates Tensor
* @author Matthias Maier, 2015
/**
- * Generic contraction of two pairs of indices of two tensors of
- * arbitrary rank: Return a tensor of rank
- * $(\text{rank}_1 + \text{rank}_2 - 4)$ that is the contraction of index
- * @p index_1 with index @p index_2, and index @p index_3 with index
- * @p index_4 of a tensor @p src1 of rank @p rank_1 and a tensor @p src2 of
- * rank @p rank_2:
+ * Generic contraction of two pairs of indices of two tensors of arbitrary
+ * rank: Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 4)$ that is
+ * the contraction of index @p index_1 with index @p index_2, and index @p
+ * index_3 with index @p index_4 of a tensor @p src1 of rank @p rank_1 and a
+ * tensor @p src2 of rank @p rank_2:
* @f[
* \text{result}_{i_1,..,i_{r1},j_1,..,j_{r2}}
* = \sum_{k, l}
* @f]
*
* If for example the first index (<code>index_1==0</code>) shall be
- * contracted with the third index (<code>index_2==2</code>), and the
- * second index (<code>index_3==1</code>) with the first index
- * (<code>index_4==0</code>) the invocation of this function is
- * this function is
+ * contracted with the third index (<code>index_2==2</code>), and the second
+ * index (<code>index_3==1</code>) with the first index
+ * (<code>index_4==0</code>) the invocation of this function is this function
+ * is
* @code
* contract<0, 2, 1, 0>(t1, t2);
* @endcode
* @note The position of the index is counted from 0, i.e.,
* $0\le\text{index}_i<\text{range}_i$.
*
- * @note In case the contraction yields a tensor of rank 0 the scalar
- * number is returned as an unwrapped number type.
+ * @note In case the contraction yields a tensor of rank 0 the scalar number
+ * is returned as an unwrapped number type.
*
* @relates Tensor
* @author Matthias Maier, 2015
/**
- * The scalar product, or (generalized) Frobenius inner product of two
- * tensors of equal rank: Return a scalar number that is the result of a
- * full contraction of a tensor @p left and @p right:
+ * The scalar product, or (generalized) Frobenius inner product of two tensors
+ * of equal rank: Return a scalar number that is the result of a full
+ * contraction of a tensor @p left and @p right:
* @f[
* \sum_{i_1,..,i_r}
* \text{left}_{i_1,..,i_r}
/**
- * Returns the cross product of 2 vectors in 3d. This function is defined
- * for all space dimensions to allow for dimension independent programming
- * (e.g. within switches over the space dimension), but may only be called
- * if the actual dimension of the arguments is three (e.g. from the
- * <tt>dim==3</tt> case in the switch).
+ * Returns the cross product of 2 vectors in 3d. This function is defined for
+ * all space dimensions to allow for dimension independent programming (e.g.
+ * within switches over the space dimension), but may only be called if the
+ * actual dimension of the arguments is three (e.g. from the <tt>dim==3</tt>
+ * case in the switch).
*
* @relates Tensor
* @author Guido Kanschat, 2001
DEAL_II_NAMESPACE_OPEN
/**
- * This namespace is a collection of algorithms working on generic
- * tensorial objects (of arbitrary rank).
+ * This namespace is a collection of algorithms working on generic tensorial
+ * objects (of arbitrary rank).
*
* The rationale to implement such functionality in a generic fashion in a
* separate namespace is
* - to easy code reusability and therefore avoid code duplication.
* - to have a well-defined interface that allows to exchange the low
- * level implementation.
+ * level implementation.
*
*
* A tensorial object has the notion of a rank and allows a rank-times
- * recursive application of the index operator, e.g., if <code>t</code> is
- * a tensorial object of rank 4, the following access is valid:
+ * recursive application of the index operator, e.g., if <code>t</code> is a
+ * tensorial object of rank 4, the following access is valid:
* @code
* t[1][2][1][4]
* @endcode
*
* deal.II has its own implementation for tensorial objects such as
- * dealii::Tensor<rank, dim, Number> and
- * dealii::SymmetricTensor<rank, dim, Number>
+ * dealii::Tensor<rank, dim, Number> and dealii::SymmetricTensor<rank, dim,
+ * Number>
*
* The methods and algorithms implemented in this namespace, however, are
- * fully generic. More precisely, it can operate on nested c-style arrays,
- * or on class types <code>T</code> with a minimal interface that provides
- * a local typedef <code>value_type</code> and an index operator
- * <code>operator[](unsigned int)</code> that returns a (const or
- * non-const) reference of <code>value_type</code>:
+ * fully generic. More precisely, it can operate on nested c-style arrays, or
+ * on class types <code>T</code> with a minimal interface that provides a
+ * local typedef <code>value_type</code> and an index operator
+ * <code>operator[](unsigned int)</code> that returns a (const or non-const)
+ * reference of <code>value_type</code>:
* @code
* template<...>
* class T
/**
- * This class provides a local typedef @p value_type denoting the
- * resulting type of an access with operator[](unsigned int). More
- * precisely, @p value_type will be
+ * This class provides a local typedef @p value_type denoting the resulting
+ * type of an access with operator[](unsigned int). More precisely, @p
+ * value_type will be
* - <code>T::value_type</code> if T is a tensorial class providing a
- * typedef <code>value_type</code> and does not have a const qualifier.
+ * typedef <code>value_type</code> and does not have a const qualifier.
* - <code>const T::value_type</code> if T is a tensorial class
- * providing a typedef <code>value_type</code> and does have a const
- * qualifier.
+ * providing a typedef <code>value_type</code> and does have a const
+ * qualifier.
* - <code>const T::value_type</code> if T is a tensorial class
- * providing a typedef <code>value_type</code> and does have a const
- * qualifier.
+ * providing a typedef <code>value_type</code> and does have a const
+ * qualifier.
* - <code>A</code> if T is of array type <code>A[...]</code>
* - <code>const A</code> if T is of array type <code>A[...]</code> and
- * does have a const qualifier.
+ * does have a const qualifier.
*/
template <typename T>
struct ValueType
/**
- * This class provides a local typedef @p value_type that is equal to
- * the typedef <code>value_type</code> after @p deref_steps
- * recursive dereferences via ```operator[](unsigned int)```.
- * Further, constness is preserved via the ValueType
- * type trait, i.e., if T is const, ReturnType<rank, T>::value_type
- * will also be const.
+ * This class provides a local typedef @p value_type that is equal to the
+ * typedef <code>value_type</code> after @p deref_steps recursive
+ * dereferences via ```operator[](unsigned int)```. Further, constness is
+ * preserved via the ValueType type trait, i.e., if T is const,
+ * ReturnType<rank, T>::value_type will also be const.
*/
template <int deref_steps, typename T>
struct ReturnType
/**
- * Provide a "tensorial view" to a reference @p t of a tensor object of
- * rank @p rank in which the index @p index is shifted to the
- * end. As an example consider a tensor of 5th order in dim=5 space
- * dimensions that can be accessed through 5 recursive
- * <code>operator[]()</code> invocations:
+ * Provide a "tensorial view" to a reference @p t of a tensor object of rank
+ * @p rank in which the index @p index is shifted to the end. As an example
+ * consider a tensor of 5th order in dim=5 space dimensions that can be
+ * accessed through 5 recursive <code>operator[]()</code> invocations:
* @code
* Tensor<5, dim> tensor;
* tensor[0][1][2][3][4] = 42.;
* @endcode
- * Index 1 (the 2nd index, count starts at 0) can now be shifted to the
- * end via
+ * Index 1 (the 2nd index, count starts at 0) can now be shifted to the end
+ * via
* @code
* auto tensor_view = reordered_index_view<1, 5>(tensor);
* tensor_view[0][2][3][4][1] == 42.; // is true
* example. The mechanism implemented by this function is available for
* fairly general tensorial types @p T.
*
- * The purpose of this reordering facility is to be able to contract over
- * an arbitrary index of two (or more) tensors:
+ * The purpose of this reordering facility is to be able to contract over an
+ * arbitrary index of two (or more) tensors:
* - reorder the indices in mind to the end of the tensors
* - use the contract function below that contracts the _last_ elements of
- * tensors.
+ * tensors.
*
* @note This function returns an internal class object consisting of an
* array subscript operator <code>operator[](unsigned int)</code> and a
* @tparam index The index to be shifted to the end. Indices are counted
* from 0, thus the valid range is $0\le\text{index}<\text{rank}$.
* @tparam rank Rank of the tensorial object @p t
- * @tparam T A tensorial object of rank @p rank. @p T must
- * provide a local typedef <code>value_type</code> and an index operator
- * <code>operator[]()</code> that returns a (const or non-const)
- * reference of <code>value_type</code>.
+ * @tparam T A tensorial object of rank @p rank. @p T must provide a local
+ * typedef <code>value_type</code> and an index operator
+ * <code>operator[]()</code> that returns a (const or non-const) reference
+ * of <code>value_type</code>.
*
* @author Matthias Maier, 2015
*/
* @endcode
* This is equivalent to <code>tensor[0][1][2][3][4] = 42.</code>.
*
- * @tparam T A tensorial object of rank @p rank. @p T must provide a
- * local typedef <code>value_type</code> and an index operator
- * <code>operator[]()</code> that returns a (const or non-const)
- * reference of <code>value_type</code>. Further, its tensorial rank must
- * be equal or greater than @p rank.
+ * @tparam T A tensorial object of rank @p rank. @p T must provide a local
+ * typedef <code>value_type</code> and an index operator
+ * <code>operator[]()</code> that returns a (const or non-const) reference
+ * of <code>value_type</code>. Further, its tensorial rank must be equal or
+ * greater than @p rank.
*
* @tparam ArrayType An array like object, such as std::array, or
* dealii::TableIndices that stores at least @p rank indices that can be
/**
* This function contracts two tensorial objects @p left and @p right and
- * stores the result in @p result. The contraction is done over the
- * _last_ @p no_contr indices of both tensorial objects:
+ * stores the result in @p result. The contraction is done over the _last_
+ * @p no_contr indices of both tensorial objects:
*
* @f[
* \text{result}_{i_1,..,i_{r1},j_1,..,j_{r2}}
* result[i_0]..[i_][j_0]..[j_] += left[i_0]..[i_][k_0]..[k_] * right[j_0]..[j_][k_0]..[k_];
* }
* @endcode
- * with r = rank_1 + rank_2 - 2 * no_contr, l = rank_1 - no_contr, l1 = rank_1,
- * and c = no_contr.
+ * with r = rank_1 + rank_2 - 2 * no_contr, l = rank_1 - no_contr, l1 =
+ * rank_1, and c = no_contr.
*
- * @note The Types @p T1, @p T2, and @p T3 must have rank
- * rank_1 + rank_2 - 2 * no_contr, rank_1, or rank_2, respectively.
- * Obviously, no_contr must be less or equal than rank_1 and rank_2.
+ * @note The Types @p T1, @p T2, and @p T3 must have rank rank_1 + rank_2 -
+ * 2 * no_contr, rank_1, or rank_2, respectively. Obviously, no_contr must
+ * be less or equal than rank_1 and rank_2.
*
* @author Matthias Maier, 2015
*/
* result += left[i_0]..[i_] * middle[i_0]..[i_][j_0]..[j_] * right[j_0]..[j_];
* @endcode
*
- * @note The Types @p T2, @p T3, and @p T4 must have
- * rank rank_1, rank_1 + rank_2, and rank_3, respectively. @p T1
- * must be a scalar type.
+ * @note The Types @p T2, @p T3, and @p T4 must have rank rank_1, rank_1 +
+ * rank_2, and rank_3, respectively. @p T1 must be a scalar type.
*
* @author Matthias Maier, 2015
*/
* function reordered_index_view(T &t).
*
* The problem is that when working with the actual tensorial types, we
- * have to return subtensors by reference - but sometimes, especially
- * for StoreIndex and ReorderedIndexView that return rvalues, we have
- * to return by value.
+ * have to return subtensors by reference - but sometimes, especially for
+ * StoreIndex and ReorderedIndexView that return rvalues, we have to
+ * return by value.
*/
template<typename T>
struct ReferenceType
* product <tt>sum<sub>i,j</sub> src1[i][j]*src2[i][j]</tt>.
*
* @deprecated Use the double_contract() function that takes indices as
- * template arguments and returns its result instead.
+ * template arguments and returns its result instead.
* @relates Tensor
*/
template <int dim, typename Number>
* analog operation between tensors of rank 4 and rank 2.
*
* @deprecated Use the double_contract() function that takes indices as
- * template arguments and returns its result instead.
+ * template arguments and returns its result instead.
* @relates Tensor
*/
template <int dim, typename Number>
/**
* Contract a tensor of rank 2 with a tensor of rank 2. The contraction is
* performed over index <tt>index1</tt> of the first tensor, and
- * <tt>index2</tt> of the second tensor. Note that the number of the index
- * is counted from 1 on, not from zero as usual.
+ * <tt>index2</tt> of the second tensor. Note that the number of the index is
+ * counted from 1 on, not from zero as usual.
*
* @deprecated Use the contract() function that takes indices as template
- * arguments and returns its result instead.
+ * arguments and returns its result instead.
* @relates Tensor
*/
template <int dim, typename Number>
* number of the index is counted from 1 on, not from zero as usual.
*
* @deprecated Use the contract() function that takes indices as template
- * arguments and returns its result instead.
+ * arguments and returns its result instead.
* @relates Tensor
*/
template <int dim, typename Number>
/**
* Contract a tensor of rank 3 with a tensor of rank 2. The contraction is
* performed over index <tt>index1</tt> of the first tensor, and
- * <tt>index2</tt> of the second tensor. Note that the number of the index
- * is counted from 1 on, not from zero as usual.
+ * <tt>index2</tt> of the second tensor. Note that the number of the index is
+ * counted from 1 on, not from zero as usual.
*
* @deprecated Use the contract() function that takes indices as template
- * arguments and returns its result instead.
+ * arguments and returns its result instead.
* @relates Tensor
*/
template <int dim, typename Number>
const unsigned int index2) DEAL_II_DEPRECATED;
/**
- * Single contraction for tensors: contract the last index of a tensor @p
- * src1 of rank @p rank_1 with the first index of a tensor @p src2 of rank
- * @p rank_2.
+ * Single contraction for tensors: contract the last index of a tensor @p src1
+ * of rank @p rank_1 with the first index of a tensor @p src2 of rank @p
+ * rank_2.
*
* @deprecated Use operator* instead. It denotes a single contraction.
* @relates Tensor
const Tensor<rank_2 ,dim, Number> &src2) DEAL_II_DEPRECATED;
/**
- * Contract a tensor of rank 1 with a tensor of rank 1 and return the
- * result.
+ * Contract a tensor of rank 1 with a tensor of rank 1 and return the result.
*
* @deprecated Use operator* instead. It denotes a single contraction.
* @relates Tensor
* Note, that using this function within a loop over all tensor product
* polynomials is not efficient, because then each derivative value of the
* underlying (one-dimensional) polynomials is (unnecessarily) computed
- * several times. Instead use the compute() function, see above, with
- * the size of the appropriate parameter set to n() to get the point value
- * of all tensor polynomials all at once and in a much more efficient way.
+ * several times. Instead use the compute() function, see above, with the
+ * size of the appropriate parameter set to n() to get the point value of
+ * all tensor polynomials all at once and in a much more efficient way.
*
* @tparam order The derivative order.
*/
* Note, that using this function within a loop over all tensor product
* polynomials is not efficient, because then each derivative value of the
* underlying (one-dimensional) polynomials is (unnecessarily) computed
- * several times. Instead use the compute() function, see above, with
- * the size of the appropriate parameter set to n() to get the point value
- * of all tensor polynomials all at once and in a much more efficient way.
+ * several times. Instead use the compute() function, see above, with the
+ * size of the appropriate parameter set to n() to get the point value of
+ * all tensor polynomials all at once and in a much more efficient way.
*
* @tparam order The derivative order.
*/
/**
* Tensor product of given polynomials and bubble functions of form
- * $(2*x_j-1)^{degree-1}\prod_{i=0}^{dim-1}(x_i(1-x_i))$. This class inherits most of its
- * functionality from TensorProductPolynomials. The bubble enrichments
- * are added for the last indices.
- * index.
+ * $(2*x_j-1)^{degree-1}\prod_{i=0}^{dim-1}(x_i(1-x_i))$. This class inherits
+ * most of its functionality from TensorProductPolynomials. The bubble
+ * enrichments are added for the last indices. index.
*
* @author Daniel Arndt, 2015
*/
{
public:
/**
- * Access to the dimension of
- * this object, for checking and
- * automatic setting of dimension
- * in other classes.
+ * Access to the dimension of this object, for checking and automatic
+ * setting of dimension in other classes.
*/
static const unsigned int dimension = dim;
const Point<dim> &p) const;
/**
- * Computes the order @p order derivative of the <tt>i</tt>th tensor
- * product polynomial at <tt>unit_point</tt>. Here <tt>i</tt> is given in
- * tensor product numbering.
+ * Computes the order @p order derivative of the <tt>i</tt>th tensor product
+ * polynomial at <tt>unit_point</tt>. Here <tt>i</tt> is given in tensor
+ * product numbering.
*
* Note, that using this function within a loop over all tensor product
* polynomials is not efficient, because then each derivative value of the
* underlying (one-dimensional) polynomials is (unnecessarily) computed
- * several times. Instead use the compute() function, see above, with
- * the size of the appropriate parameter set to n() to get the point value
- * of all tensor polynomials all at once and in a much more efficient way.
+ * several times. Instead use the compute() function, see above, with the
+ * size of the appropriate parameter set to n() to get the point value of
+ * all tensor polynomials all at once and in a much more efficient way.
*/
template <int order>
Tensor<order,dim> compute_derivative (const unsigned int i,
const Point<dim> &p) const;
/**
- * Returns the number of tensor product polynomials plus the bubble enrichments.
- * For <i>n</i> 1d polynomials this is <i>n<sup>dim</sup>+1</i> if the maximum
- * degree of the polynomials is one and <i>n<sup>dim</sup>+dim</i> otherwise.
+ * Returns the number of tensor product polynomials plus the bubble
+ * enrichments. For <i>n</i> 1d polynomials this is <i>n<sup>dim</sup>+1</i>
+ * if the maximum degree of the polynomials is one and
+ * <i>n<sup>dim</sup>+dim</i> otherwise.
*/
unsigned int n () const;
};
* Note, that using this function within a loop over all tensor product
* polynomials is not efficient, because then each derivative value of the
* underlying (one-dimensional) polynomials is (unnecessarily) computed
- * several times. Instead use the compute() function, see above, with
- * the size of the appropriate parameter set to n() to get the point value
- * of all tensor polynomials all at once and in a much more efficient way.
+ * several times. Instead use the compute() function, see above, with the
+ * size of the appropriate parameter set to n() to get the point value of
+ * all tensor polynomials all at once and in a much more efficient way.
*
* @tparam order The derivative order.
*/
* - HEUN_EULER (second order)
* - BOGACKI_SHAMPINE (third order)
* - DOPRI: Dormand-Prince (fifth order, method used by ode45 in
- * MATLAB)
+ * MATLAB)
* - FEHLBERG (fifth order)
* - CASH_KARP (firth order)
*/
{
/**
- * Convert a number @p value to a string, with as many digits as given to fill
- * with leading zeros.
+ * Convert a number @p value to a string, with as many digits as given to
+ * fill with leading zeros.
*
* If the second parameter is left at its default value, the number is not
* padded with leading zeros. The result is then the same as if the standard
* unsigned integers and long integers might experience an overflow.
*
* @note The use of this function is discouraged and users should use
- * <code>Utilities::to_string()</code> instead. In its current implementation
- * the function simply calls <code>to_string@<unsigned int@>()</code>.
+ * <code>Utilities::to_string()</code> instead. In its current
+ * implementation the function simply calls <code>to_string@<unsigned
+ * int@>()</code>.
*/
std::string
int_to_string (const unsigned int value,
const unsigned int digits = numbers::invalid_unsigned_int);
/**
- * Convert a number @p value to a string, with @p digits characters.
- * The string is padded with leading zeros, after a possible minus sign.
+ * Convert a number @p value to a string, with @p digits characters. The
+ * string is padded with leading zeros, after a possible minus sign.
* Therefore the total number of padding zeros is @p digits minus any signs,
* decimal points and digits of @p value.
*
unsigned int length);
/**
- * Conversion operator to an ArrayView object that represents
- * an array of non-const elements pointing to the same location
- * as the current object.
+ * Conversion operator to an ArrayView object that represents an array of
+ * non-const elements pointing to the same location as the current object.
*/
operator ArrayView<typename VectorType::value_type *> ();
/**
- * Conversion operator to an ArrayView object that represents
- * an array of const elements pointing to the same location
- * as the current object.
+ * Conversion operator to an ArrayView object that represents an array of
+ * const elements pointing to the same location as the current object.
*/
operator ArrayView<const typename VectorType::value_type *> () const;
unsigned int size() const;
/**
- * Return a reference to the $i$th element of the range
- * represented by the current object.
+ * Return a reference to the $i$th element of the range represented by the
+ * current object.
*/
typename VectorType::reference operator[] (unsigned int i);
/**
- * Return a @p const reference to the $i$th element of the range
- * represented by the current object.
+ * Return a @p const reference to the $i$th element of the range represented
+ * by the current object.
*/
typename VectorType::const_reference operator[] (unsigned int i) const;
/**
* This is an extension of dealii::Triangulation class to automatically
- * partition triangulation when run with MPI.
- * Different from the parallel::distributed::Triangulation, the entire mesh
- * is stored on each processor. However, cells are labeled according to
- * the id of the processor which "owns" them. The partitioning is done
- * automatically inside the DoFHandler by calling Metis.
- * This enables distributing DoFs among processors and therefore splitting
- * matrices and vectors across processors.
- * The usage of this class is demonstrated in Step-18.
+ * partition triangulation when run with MPI. Different from the
+ * parallel::distributed::Triangulation, the entire mesh is stored on each
+ * processor. However, cells are labeled according to the id of the
+ * processor which "owns" them. The partitioning is done automatically
+ * inside the DoFHandler by calling Metis. This enables distributing DoFs
+ * among processors and therefore splitting matrices and vectors across
+ * processors. The usage of this class is demonstrated in Step-18.
*
* @author Denis Davydov, 2015
* @ingroup distributed
/**
* Constructor.
*
- * If @p allow_aritifical_cells is true, this class will behave
- * similar to parallel::distributed::Triangulation in that there will be
- * locally owned, ghost and artificial cells.
+ * If @p allow_aritifical_cells is true, this class will behave similar
+ * to parallel::distributed::Triangulation in that there will be locally
+ * owned, ghost and artificial cells.
*
* Otherwise all non-locally owned cells are considered ghost.
*/
virtual ~Triangulation ();
/**
- * Coarsen and refine the mesh according to refinement and
- * coarsening flags set.
+ * Coarsen and refine the mesh according to refinement and coarsening
+ * flags set.
*
- * This step is equivalent to the dealii::Triangulation class
- * with an addition of calling dealii::GridTools::partition_triangulation() at the end.
+ * This step is equivalent to the dealii::Triangulation class with an
+ * addition of calling dealii::GridTools::partition_triangulation() at
+ * the end.
*/
virtual void execute_coarsening_and_refinement ();
/**
- * Create a triangulation.
- *
- * This function also partitions triangulation based on the
- * MPI communicator provided to constructor.
- */
+ * Create a triangulation.
+ *
+ * This function also partitions triangulation based on the MPI
+ * communicator provided to constructor.
+ */
virtual void create_triangulation (const std::vector< Point< spacedim > > &vertices,
const std::vector< CellData< dim > > &cells,
const SubCellData &subcelldata);
/**
* Return a vector of length Triangulation::n_active_cells() where each
- * element stores the subdomain id of the owner of this cell. The elements
- * of the vector are obviously the same as the subdomain ids for locally
- * owned and ghost cells, but are also correct for artificial cells that
- * do not store who the owner of the cell is in their subdomain_id field.
+ * element stores the subdomain id of the owner of this cell. The
+ * elements of the vector are obviously the same as the subdomain ids
+ * for locally owned and ghost cells, but are also correct for
+ * artificial cells that do not store who the owner of the cell is in
+ * their subdomain_id field.
*/
const std::vector<types::subdomain_id> &get_true_subdomain_ids_of_cells() const;
/**
- * Return allow_artificial_cells , namely true if artificial cells are allowed.
+ * Return allow_artificial_cells , namely true if artificial cells are
+ * allowed.
*/
bool with_artificial_cells() const;
/**
* A vector containing subdomain IDs of cells obtained by partitioning
- * using METIS. In case allow_artificial_cells is false, this vector
- * is consistent with IDs stored in cell->subdomain_id() of the triangulation
- * class. When allow_artificial_cells is true, cells which are artificial
- * will have cell->subdomain_id() == numbers::artificial;
+ * using METIS. In case allow_artificial_cells is false, this vector is
+ * consistent with IDs stored in cell->subdomain_id() of the
+ * triangulation class. When allow_artificial_cells is true, cells which
+ * are artificial will have cell->subdomain_id() == numbers::artificial;
*
* The original parition information is stored to allow using sequential
- * DoF distribution and partitioning functions with semi-artificial cells.
+ * DoF distribution and partitioning functions with semi-artificial
+ * cells.
*/
std::vector<types::subdomain_id> true_subdomain_ids_of_cells;
};
{
/**
- * Dummy class the compiler chooses for parallel shared
- * triangulations if we didn't actually configure deal.II with the
- * MPI library. The existence of this class allows us to refer
- * to parallel::shared::Triangulation objects throughout the
- * library even if it is disabled.
+ * Dummy class the compiler chooses for parallel shared triangulations if
+ * we didn't actually configure deal.II with the MPI library. The
+ * existence of this class allows us to refer to
+ * parallel::shared::Triangulation objects throughout the library even if
+ * it is disabled.
*
- * Since the constructor of this class is private, no such objects
- * can actually be created if MPI is not available.
+ * Since the constructor of this class is private, no such objects can
+ * actually be created if MPI is not available.
*/
template <int dim, int spacedim = dim>
class Triangulation : public dealii::parallel::Triangulation<dim,spacedim>
* interpolate() or deserialize() you need to supply distributed vectors
* without ghost elements.
*
- * <h3>Transferring a solution</h3> Here VectorType is your favorite vector
- * type, e.g. PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector,
- * or corresponding blockvectors.
+ * <h3>Transferring a solution</h3> Here VectorType is your favorite
+ * vector type, e.g. PETScWrappers::MPI::Vector,
+ * TrilinosWrappers::MPI::Vector, or corresponding blockvectors.
* @code
* SolutionTransfer<dim, VectorType> soltrans(dof_handler);
* // flag some cells for refinement
* this-@>locally_owned_subdomain()</code>), refinement and coarsening
* flags are only respected for those locally owned cells. Flags may be
* set on other cells as well (and may often, in fact, if you call
- * dealii::Triangulation::prepare_coarsening_and_refinement()) but will be
- * largely ignored: the decision to refine the global mesh will only be
- * affected by flags set on locally owned cells.
+ * dealii::Triangulation::prepare_coarsening_and_refinement()) but will
+ * be largely ignored: the decision to refine the global mesh will only
+ * be affected by flags set on locally owned cells.
*
- * @note This function by default partitions the mesh in such a way
- * that the number of cells on all processors is roughly equal.
- * If you want to set weights for partitioning, e.g. because some cells
- * are more expensive to compute than others, you can use the signal
- * cell_weight as documented in the dealii::Triangulation class. This
- * function will check whether a function is connected to the signal
- * and if so use it. If you prefer to repartition the mesh yourself at
- * user-defined intervals only, you can create your triangulation
- * object by passing the
- * parallel::distributed::Triangulation::no_automatic_repartitioning
- * flag to the constructor, which ensures that calling the current
- * function only refines and coarsens the triangulation, but doesn't
- * partition it. You can then call the repartition() function manually.
- * The usage of the cell_weights signal is identical in both cases,
- * if a function is connected to the signal it will be used to balance
- * the calculated weights, otherwise the number of cells is balanced.
+ * @note This function by default partitions the mesh in such a way that
+ * the number of cells on all processors is roughly equal. If you want
+ * to set weights for partitioning, e.g. because some cells are more
+ * expensive to compute than others, you can use the signal cell_weight
+ * as documented in the dealii::Triangulation class. This function will
+ * check whether a function is connected to the signal and if so use it.
+ * If you prefer to repartition the mesh yourself at user-defined
+ * intervals only, you can create your triangulation object by passing
+ * the parallel::distributed::Triangulation::no_automatic_repartitioning
+ * flag to the constructor, which ensures that calling the current
+ * function only refines and coarsens the triangulation, but doesn't
+ * partition it. You can then call the repartition() function manually.
+ * The usage of the cell_weights signal is identical in both cases, if a
+ * function is connected to the signal it will be used to balance the
+ * calculated weights, otherwise the number of cells is balanced.
*/
virtual void execute_coarsening_and_refinement ();
* dealing with data movement (SolutionTransfer, etc.).
*
* @note If no function is connected to the cell_weight signal described
- * in the dealii::Triangulation class, this function will balance the
- * number of cells on each processor. If one or more functions are
- * connected, it will calculate the sum of the weights and balance the
- * weights across processors. The only requirement on the weights is
- * that every cell's weight is positive and that the sum over all
- * weights on all processors can be formed using a 64-bit integer.
- * Beyond that, it is your choice how you want to interpret the weights.
- * A common approach is to consider the weights proportional to
- * the cost of doing computations on a cell, e.g., by summing
- * the time for assembly and solving. In practice, determining
- * this cost is of course not trivial since we don't solve on
- * isolated cells, but on the entire mesh. In such cases, one
- * could, for example, choose the weight equal to the number
- * of unknowns per cell (in the context of hp finite element
- * methods), or using a heuristic that estimates the cost on
- * each cell depending on whether, for example, one has to
- * run some expensive algorithm on some cells but not others
- * (such as forming boundary integrals during the assembly
- * only on cells that are actually at the boundary, or computing
- * expensive nonlinear terms only on some cells but not others,
- * e.g., in the elasto-plastic problem in step-42).
+ * in the dealii::Triangulation class, this function will balance the
+ * number of cells on each processor. If one or more functions are
+ * connected, it will calculate the sum of the weights and balance the
+ * weights across processors. The only requirement on the weights is
+ * that every cell's weight is positive and that the sum over all
+ * weights on all processors can be formed using a 64-bit integer.
+ * Beyond that, it is your choice how you want to interpret the weights.
+ * A common approach is to consider the weights proportional to the cost
+ * of doing computations on a cell, e.g., by summing the time for
+ * assembly and solving. In practice, determining this cost is of course
+ * not trivial since we don't solve on isolated cells, but on the entire
+ * mesh. In such cases, one could, for example, choose the weight equal
+ * to the number of unknowns per cell (in the context of hp finite
+ * element methods), or using a heuristic that estimates the cost on
+ * each cell depending on whether, for example, one has to run some
+ * expensive algorithm on some cells but not others (such as forming
+ * boundary integrals during the assembly only on cells that are
+ * actually at the boundary, or computing expensive nonlinear terms only
+ * on some cells but not others, e.g., in the elasto-plastic problem in
+ * step-42).
*/
void repartition ();
* GridTools::collect_periodic_faces.
*
* For more information on periodic boundary conditions see
- * GridTools::collect_periodic_faces, DoFTools::make_periodicity_constraints
- * and step-45.
+ * GridTools::collect_periodic_faces,
+ * DoFTools::make_periodicity_constraints and step-45.
*
* @note Before this function can be used the Triangulation has to be
* initialized and must not be refined. Calling this function more than
private:
/**
- * Override the function to update the number cache so we can fill
- * data like @p level_ghost_owners.
+ * Override the function to update the number cache so we can fill data
+ * like @p level_ghost_owners.
*
*/
virtual void update_number_cache ();
* repartition cycle. Note that the number of entries does not need to
* be equal to either n_active_cells or n_locally_owned_active_cells,
* because the triangulation is not updated yet. The weights are sorted
- * in the order that p4est will encounter them while iterating over them.
+ * in the order that p4est will encounter them while iterating over
+ * them.
*/
std::vector<unsigned int>
get_cell_weights();
{
/**
* This class describes the interface for all triangulation classes that
- * work in parallel, namely parallel::distributed::Triangulation
- * and parallel::shared::Triangulation.
+ * work in parallel, namely parallel::distributed::Triangulation and
+ * parallel::shared::Triangulation.
*/
template <int dim, int spacedim = dim>
class Triangulation : public dealii::Triangulation<dim,spacedim>
/**
- * Return the number of active cells in the triangulation that are
- * locally owned, i.e. that have a subdomain_id equal to
- * locally_owned_subdomain(). Note that there may be more active cells
- * in the triangulation stored on the present processor, such as for
- * example ghost cells, or cells further away from the locally owned
- * block of cells but that are needed to ensure that the triangulation
- * that stores this processor's set of active cells still remains
- * balanced with respect to the 2:1 size ratio of adjacent cells.
+ * Return the number of active cells in the triangulation that are locally
+ * owned, i.e. that have a subdomain_id equal to
+ * locally_owned_subdomain(). Note that there may be more active cells in
+ * the triangulation stored on the present processor, such as for example
+ * ghost cells, or cells further away from the locally owned block of
+ * cells but that are needed to ensure that the triangulation that stores
+ * this processor's set of active cells still remains balanced with
+ * respect to the 2:1 size ratio of adjacent cells.
*
* As a consequence of the remark above, the result of this function is
* always smaller or equal to the result of the function with the same
- * name in the ::Triangulation base class, which includes the active
- * ghost and artificial cells (see also
+ * name in the ::Triangulation base class, which includes the active ghost
+ * and artificial cells (see also
* @ref GlossArtificialCell
* and
* @ref GlossGhostCell).
unsigned int n_locally_owned_active_cells () const;
/**
- * Return the sum over all processors of the number of active cells
- * owned by each processor. This equals the overall number of active
- * cells in the triangulation.
+ * Return the sum over all processors of the number of active cells owned
+ * by each processor. This equals the overall number of active cells in
+ * the triangulation.
*/
virtual types::global_dof_index n_global_active_cells () const;
*
* @note: If @p i is contained in the list of processor @p j, then @p j
* will also be contained in the list of processor @p i.
- **/
+ */
const std::set<unsigned int> &ghost_owners () const;
/**
*
* @note: If @p i is contained in the list of processor @p j, then @p j
* will also be contained in the list of processor @p i.
- **/
+ */
const std::set<unsigned int> &level_ghost_owners () const;
protected:
/**
* MPI communicator to be used for the triangulation. We create a unique
- * communicator for this class, which is a duplicate of the one passed
- * to the constructor.
+ * communicator for this class, which is a duplicate of the one passed to
+ * the constructor.
*/
MPI_Comm mpi_communicator;
struct NumberCache
{
/**
- * This vector stores the number of locally owned active cells per MPI
- * rank.
+ * This vector stores the number of locally owned active cells per MPI
+ * rank.
*/
std::vector<unsigned int> n_locally_owned_active_cells;
/**
- * The total number of active cells (sum of
- * @p n_locally_owned_active_cells).
+ * The total number of active cells (sum of @p
+ * n_locally_owned_active_cells).
*/
types::global_dof_index n_global_active_cells;
/**
* }
* @endcode
*
- * In this
- * example, <tt>solution</tt> obtains the block structure needed to represent
- * a finite element function on the DoFHandler. Similarly, all levels of
- * <tt>mg_vector</tt> will have the block structure needed on that level.
+ * In this example, <tt>solution</tt> obtains the block structure needed to
+ * represent a finite element function on the DoFHandler. Similarly, all
+ * levels of <tt>mg_vector</tt> will have the block structure needed on that
+ * level.
*
* @todo Extend the functions local() and renumber() to the concept to
* hpDoFHandler.
virtual ~PolicyBase ();
/**
- * Distribute degrees of freedom on
- * the object given as first argument.
- * The reference to the NumberCache of the
- * DoFHandler object has to be passed in a
- * second argument. It could then be modified to
- * make DoFHandler related functions work properly
- * when called within the policies classes.
- * The updated NumberCache is written to that argument.
+ * Distribute degrees of freedom on the object given as first
+ * argument. The reference to the NumberCache of the DoFHandler object
+ * has to be passed in a second argument. It could then be modified to
+ * make DoFHandler related functions work properly when called within
+ * the policies classes. The updated NumberCache is written to that
+ * argument.
*/
virtual
void
std::vector<NumberCache> &number_caches) const = 0;
/**
- * Renumber degrees of freedom as
- * specified by the first argument.
- * The reference to the NumberCache of the
- * DoFHandler object has to be passed in a
- * second argument. It could then be modified to
- * make DoFHandler related functions work properly
- * when called within the policies classes.
- * The updated NumberCache is written to that argument.
+ * Renumber degrees of freedom as specified by the first argument. The
+ * reference to the NumberCache of the DoFHandler object has to be
+ * passed in a second argument. It could then be modified to make
+ * DoFHandler related functions work properly when called within the
+ * policies classes. The updated NumberCache is written to that
+ * argument.
*/
virtual
void
};
/**
- * This class implements the
- * policy for operations when
- * we use a
- * parallel::shared::Triangulation
- * object.
- */
+ * This class implements the policy for operations when we use a
+ * parallel::shared::Triangulation object.
+ */
template <int dim, int spacedim>
class ParallelShared : public Sequential<dim,spacedim>
{
public:
/**
- * Distribute degrees of freedom on
- * the object given as first argument.
- *
- * On distribution, DoFs are renumbered subdomain-wise and
- * number_cache.n_locally_owned_dofs_per_processor[i] and
- * number_cache.locally_owned_dofs are updated consistently.
- */
+ * Distribute degrees of freedom on the object given as first
+ * argument.
+ *
+ * On distribution, DoFs are renumbered subdomain-wise and
+ * number_cache.n_locally_owned_dofs_per_processor[i] and
+ * number_cache.locally_owned_dofs are updated consistently.
+ */
virtual
void
distribute_dofs (dealii::DoFHandler<dim,spacedim> &dof_handler,
std::vector<NumberCache> &number_caches) const;
/**
- * Renumber degrees of freedom as
- * specified by the first argument.
- *
- * The input argument @p new_numbers may either have as many entries
- * as there are global degrees of freedom (i.e. dof_handler.n_dofs() )
- * or dof_handler.locally_owned_dofs().n_elements().
- * Therefore it can be utilised with renumbering functions
- * implemented for the parallel::distributed case.
- */
+ * Renumber degrees of freedom as specified by the first argument.
+ *
+ * The input argument @p new_numbers may either have as many entries
+ * as there are global degrees of freedom (i.e. dof_handler.n_dofs() )
+ * or dof_handler.locally_owned_dofs().n_elements(). Therefore it can
+ * be utilised with renumbering functions implemented for the
+ * parallel::distributed case.
+ */
virtual
void
renumber_dofs (const std::vector<types::global_dof_index> &new_numbers,
hierarchical (DoFHandler<dim> &dof_handler);
/**
- * Renumber degrees of freedom by cell. The function takes a vector of
- * cell iterators (which needs to list <i>all</i> active cells of the DoF
- * handler objects) and will give degrees of freedom new indices based
- * on where in the given list of cells the cell is on which the degree
- * of freedom is located. Degrees of freedom that exist at the interface
- * between two or more cells will be numbered when they are encountered
- * first.
+ * Renumber degrees of freedom by cell. The function takes a vector of cell
+ * iterators (which needs to list <i>all</i> active cells of the DoF handler
+ * objects) and will give degrees of freedom new indices based on where in
+ * the given list of cells the cell is on which the degree of freedom is
+ * located. Degrees of freedom that exist at the interface between two or
+ * more cells will be numbered when they are encountered first.
*
- * Degrees of freedom that are encountered first on the same cell
- * retain their original ordering before the renumbering step.
+ * Degrees of freedom that are encountered first on the same cell retain
+ * their original ordering before the renumbering step.
*
- * @param[in,out] dof_handler The DoFHandler whose degrees of freedom are
- * to be renumbered.
- * @param[in] cell_order A vector that contains the order of the cells
- * that defines the order in which degrees of freedom should be
- * renumbered.
+ * @param[in,out] dof_handler The DoFHandler whose degrees of freedom are to
+ * be renumbered.
+ * @param[in] cell_order A vector that contains the order of the cells that
+ * defines the order in which degrees of freedom should be renumbered.
*
* @pre @p cell_order must have size
- * <code>dof_handler.get_triangulation().n_active_cells()</code>. Every active
- * cell iterator of that triangulation needs to be present in @p cell_order
- * exactly once.
+ * <code>dof_handler.get_triangulation().n_active_cells()</code>. Every
+ * active cell iterator of that triangulation needs to be present in @p
+ * cell_order exactly once.
*/
template <typename DoFHandlerType>
void
* between two or more cells will be numbered when they are encountered
* first.
*
- * Degrees of freedom that are encountered first on the same cell
- * retain their original ordering before the renumbering step.
+ * Degrees of freedom that are encountered first on the same cell retain
+ * their original ordering before the renumbering step.
*
- * @param[out] renumbering A vector of length <code>dof_handler.n_dofs()</code>
- * that contains for each degree of freedom (in their current numbering)
- * their future DoF index. This vector therefore presents a
- * (very particular) <i>permutation</i> of the current DoF indices.
+ * @param[out] renumbering A vector of length
+ * <code>dof_handler.n_dofs()</code> that contains for each degree of
+ * freedom (in their current numbering) their future DoF index. This vector
+ * therefore presents a (very particular) <i>permutation</i> of the current
+ * DoF indices.
* @param[out] inverse_renumbering The reverse of the permutation returned
- * in the previous argument.
- * @param[in] dof_handler The DoFHandler whose degrees of freedom are
- * to be renumbered.
- * @param[in] cell_order A vector that contains the order of the cells
- * that defines the order in which degrees of freedom should be
- * renumbered.
+ * in the previous argument.
+ * @param[in] dof_handler The DoFHandler whose degrees of freedom are to be
+ * renumbered.
+ * @param[in] cell_order A vector that contains the order of the cells that
+ * defines the order in which degrees of freedom should be renumbered.
*
* @pre @p cell_order must have size
- * <code>dof_handler.get_triangulation().n_active_cells()</code>. Every active
- * cell iterator of that triangulation needs to be present in @p cell_order
- * exactly once.
- * @post For each @p i between zero and <code>dof_handler.n_dofs()</code>,
- * the condition <code>renumbering[inverse_renumbering[i]] == i</code>
- * will hold.
+ * <code>dof_handler.get_triangulation().n_active_cells()</code>. Every
+ * active cell iterator of that triangulation needs to be present in @p
+ * cell_order exactly once. @post For each @p i between zero and
+ * <code>dof_handler.n_dofs()</code>, the condition
+ * <code>renumbering[inverse_renumbering[i]] == i</code> will hold.
*/
template <typename DoFHandlerType>
void
const std::vector<typename DoFHandlerType::active_cell_iterator> &cell_order);
/**
- * Like the other cell_wise() function, but for one level
- * of a multilevel enumeration of degrees of freedom.
+ * Like the other cell_wise() function, but for one level of a multilevel
+ * enumeration of degrees of freedom.
*/
template <typename DoFHandlerType>
void
const std::vector<typename DoFHandlerType::level_cell_iterator> &cell_order);
/**
- * Like the other compute_cell_wise() function, but for one level
- * of a multilevel enumeration of degrees of freedom.
+ * Like the other compute_cell_wise() function, but for one level of a
+ * multilevel enumeration of degrees of freedom.
*/
template <typename DoFHandlerType>
void
/**
* Renumber the degrees of freedom in a random way. The result of this
- * function is repeatable in that two runs of the same program will
- * yield the same result. This is achieved by creating a new random
- * number generator with a fixed seed every time this function is
- * entered. In particular, the function therefore does not rely on an
- * external random number generator for which it would matter how often
- * it has been called before this function (or, for that matter, whether
- * other threads running concurrently to this function also draw
- * random numbers).
+ * function is repeatable in that two runs of the same program will yield
+ * the same result. This is achieved by creating a new random number
+ * generator with a fixed seed every time this function is entered. In
+ * particular, the function therefore does not rely on an external random
+ * number generator for which it would matter how often it has been called
+ * before this function (or, for that matter, whether other threads running
+ * concurrently to this function also draw random numbers).
*/
template <typename DoFHandlerType>
void
* Computes the renumbering vector needed by the random() function. See
* there for more information on the computed random renumbering.
*
- * This function does not
- * perform the renumbering on the DoFHandler dofs but returns the
- * renumbering vector.
+ * This function does not perform the renumbering on the DoFHandler dofs but
+ * returns the renumbering vector.
*/
template <typename DoFHandlerType>
void
};
/**
- * @name Functions to support code that generically uses both DoFHandler and hp::DoFHandler
+ * @name Functions to support code that generically uses both DoFHandler and
+ * hp::DoFHandler
* @{
*/
/**
*/
/**
- * Compute which entries of a matrix built on the given
- * @p dof_handler may possibly be nonzero, and create a sparsity
- * pattern object that represents these nonzero locations.
- *
- * This function computes the possible positions of non-zero entries
- * in the global system matrix by <i>simulating</i> which entries
- * one would write to during the actual assembly of a matrix. For
- * this, the function assumes that each finite element basis
- * function is non-zero on a cell only if its degree of freedom is
- * associated with the interior, a face, an edge or a vertex of this
- * cell. As a result, a matrix entry $A_{ij}$ that is computed from
- * two basis functions $\varphi_i$ and $\varphi_j$ with (global)
- * indices $i$ and $j$ (for example, using a bilinear form
- * $A_{ij}=a(\varphi_i,\varphi_j)$) can be non-zero only if these
- * shape functions correspond to degrees of freedom that are defined
- * on at least one common cell. Therefore, this function just loops
- * over all cells, figures out the global indices of all degrees of
- * freedom, and presumes that all matrix entries that couple any of
- * these indices will result in a nonzero matrix entry. These will
- * then be added to the sparsity pattern. As this process of
- * generating the sparsity pattern does not take into account the
- * equation to be solved later on, the resulting sparsity pattern is
- * symmetric.
- *
- * This algorithm makes no distinction between shape functions on
- * each cell, i.e., it simply couples all degrees of freedom on a
- * cell with all other degrees of freedom on a cell. This is often
- * the case, and always a safe assumption. However, if you know
- * something about the structure of your operator and that it does
- * not couple certain shape functions with certain test functions,
- * then you can get a sparser sparsity pattern by calling a variant
- * of the current function described below that allows to specify
- * which vector components couple with which other vector
- * components.
- *
- * The method described above lives on the assumption that coupling
- * between degrees of freedom only happens if shape functions
- * overlap on at least one cell. This is the case with most usual
- * finite element formulations involving conforming
- * elements. However, for formulations such as the Discontinuous
- * Galerkin finite element method, the bilinear form contains terms
- * on interfaces between cells that couple shape functions that live
- * on one cell with shape functions that live on a neighboring
- * cell. The current function would not see these couplings, and
- * would consequently not allocate entries in the sparsity
- * pattern. You would then get into trouble during matrix assembly
- * because you try to write into matrix entries for which no space
- * has been allocated in the sparsity pattern. This can be avoided
- * by calling the DoFTools::make_flux_sparsity_pattern() function
- * instead, which takes into account coupling between degrees of
+ * Compute which entries of a matrix built on the given @p dof_handler may
+ * possibly be nonzero, and create a sparsity pattern object that represents
+ * these nonzero locations.
+ *
+ * This function computes the possible positions of non-zero entries in the
+ * global system matrix by <i>simulating</i> which entries one would write
+ * to during the actual assembly of a matrix. For this, the function assumes
+ * that each finite element basis function is non-zero on a cell only if its
+ * degree of freedom is associated with the interior, a face, an edge or a
+ * vertex of this cell. As a result, a matrix entry $A_{ij}$ that is
+ * computed from two basis functions $\varphi_i$ and $\varphi_j$ with
+ * (global) indices $i$ and $j$ (for example, using a bilinear form
+ * $A_{ij}=a(\varphi_i,\varphi_j)$) can be non-zero only if these shape
+ * functions correspond to degrees of freedom that are defined on at least
+ * one common cell. Therefore, this function just loops over all cells,
+ * figures out the global indices of all degrees of freedom, and presumes
+ * that all matrix entries that couple any of these indices will result in a
+ * nonzero matrix entry. These will then be added to the sparsity pattern.
+ * As this process of generating the sparsity pattern does not take into
+ * account the equation to be solved later on, the resulting sparsity
+ * pattern is symmetric.
+ *
+ * This algorithm makes no distinction between shape functions on each cell,
+ * i.e., it simply couples all degrees of freedom on a cell with all other
+ * degrees of freedom on a cell. This is often the case, and always a safe
+ * assumption. However, if you know something about the structure of your
+ * operator and that it does not couple certain shape functions with certain
+ * test functions, then you can get a sparser sparsity pattern by calling a
+ * variant of the current function described below that allows to specify
+ * which vector components couple with which other vector components.
+ *
+ * The method described above lives on the assumption that coupling between
+ * degrees of freedom only happens if shape functions overlap on at least
+ * one cell. This is the case with most usual finite element formulations
+ * involving conforming elements. However, for formulations such as the
+ * Discontinuous Galerkin finite element method, the bilinear form contains
+ * terms on interfaces between cells that couple shape functions that live
+ * on one cell with shape functions that live on a neighboring cell. The
+ * current function would not see these couplings, and would consequently
+ * not allocate entries in the sparsity pattern. You would then get into
+ * trouble during matrix assembly because you try to write into matrix
+ * entries for which no space has been allocated in the sparsity pattern.
+ * This can be avoided by calling the DoFTools::make_flux_sparsity_pattern()
+ * function instead, which takes into account coupling between degrees of
* freedom on neighboring cells.
*
- * There are other situations where bilinear forms contain non-local
- * terms, for example in treating integral equations. These require
- * different methods for building the sparsity patterns that depend
- * on the exact formulation of the problem. You will have to do this
- * yourself then.
+ * There are other situations where bilinear forms contain non-local terms,
+ * for example in treating integral equations. These require different
+ * methods for building the sparsity patterns that depend on the exact
+ * formulation of the problem. You will have to do this yourself then.
*
- * @param[in] dof_handler The DoFHandler or hp::DoFHandler object
- * that describes which degrees of freedom live on which cells.
+ * @param[in] dof_handler The DoFHandler or hp::DoFHandler object that
+ * describes which degrees of freedom live on which cells.
*
* @param[out] sparsity_pattern The sparsity pattern to be filled with
- * entries.
- *
- * @param[in] constraints The process for generating entries
- * described above is purely local to each cell. Consequently, the
- * sparsity pattern does not provide for matrix entries that will
- * only be written into during the elimination of hanging nodes or
- * other constraints. They have to be taken care of by a
- * subsequent call to ConstraintMatrix::condense().
- * Alternatively, the constraints on degrees of freedom can
- * already be taken into account at the time of creating the
- * sparsity pattern. For this, pass the ConstraintMatrix object as
- * the third argument to the current function. No call to
- * ConstraintMatrix::condense() is then necessary. This process is
- * explained in step-6, step-27, and other tutorial programs.
- *
- * @param[in] keep_constrained_dofs In case the constraints are
- * already taken care of in this function by passing in a
- * ConstraintMatrix object, it is possible to abandon some
- * off-diagonal entries in the sparsity pattern if these entries
- * will also not be written into during the actual assembly of the
- * matrix this sparsity pattern later serves. Specifically, when
- * using an assembly method that uses
- * ConstraintMatrix::distribute_local_to_global(), no entries will
- * ever be written into those matrix rows or columns that
- * correspond to constrained degrees of freedom. In such cases,
- * you can set the argument @p keep_constrained_dofs to @p false
- * to avoid allocating these entries in the sparsity pattern.
- *
- * @param[in] subdomain_id If specified, the sparsity pattern is
- * built only on cells that have a subdomain_id equal to the given
- * argument. This is useful in parallel contexts where the matrix
- * and sparsity pattern (for example a
- * TrilinosWrappers::SparsityPattern) may be distributed and not
- * every MPI process needs to build the entire sparsity pattern;
- * in that case, it is sufficient if every process only builds
- * that part of the sparsity pattern that corresponds to the
- * subdomain_id for which it is responsible. This feature is used
- * in step-32. (This argument is not usually needed for objects of
- * type parallel::distributed::Triangulation because the current
- * function only loops over locally owned cells anyway; thus, this
- * argument typically only makes sense if you want to use the
- * subdomain_id for anything other than indicating which processor
- * owns a cell, for example which geometric component of the
- * domain a cell belongs to.)
- *
- * @note The actual type of the sparsity pattern may be
- * SparsityPattern, DynamicSparsityPattern, BlockSparsityPattern,
- * BlockDynamicSparsityPattern, or any other class that satisfies
- * similar requirements. It is assumed that the size of the
- * sparsity pattern matches the number of degrees of freedom and
- * that enough unused nonzero entries are left to fill the
- * sparsity pattern if the sparsity pattern is of "static" kind
- * (see
- * @ref Sparsity
- * for more information on what this
- * means). The nonzero entries generated by this function are
- * added to possible previous content of the object, i.e.,
- * previously added entries are not removed.
+ * entries.
+ *
+ * @param[in] constraints The process for generating entries described above
+ * is purely local to each cell. Consequently, the sparsity pattern does not
+ * provide for matrix entries that will only be written into during the
+ * elimination of hanging nodes or other constraints. They have to be taken
+ * care of by a subsequent call to ConstraintMatrix::condense().
+ * Alternatively, the constraints on degrees of freedom can already be taken
+ * into account at the time of creating the sparsity pattern. For this, pass
+ * the ConstraintMatrix object as the third argument to the current
+ * function. No call to ConstraintMatrix::condense() is then necessary. This
+ * process is explained in step-6, step-27, and other tutorial programs.
+ *
+ * @param[in] keep_constrained_dofs In case the constraints are already
+ * taken care of in this function by passing in a ConstraintMatrix object,
+ * it is possible to abandon some off-diagonal entries in the sparsity
+ * pattern if these entries will also not be written into during the actual
+ * assembly of the matrix this sparsity pattern later serves. Specifically,
+ * when using an assembly method that uses
+ * ConstraintMatrix::distribute_local_to_global(), no entries will ever be
+ * written into those matrix rows or columns that correspond to constrained
+ * degrees of freedom. In such cases, you can set the argument @p
+ * keep_constrained_dofs to @p false to avoid allocating these entries in
+ * the sparsity pattern.
+ *
+ * @param[in] subdomain_id If specified, the sparsity pattern is built only
+ * on cells that have a subdomain_id equal to the given argument. This is
+ * useful in parallel contexts where the matrix and sparsity pattern (for
+ * example a TrilinosWrappers::SparsityPattern) may be distributed and not
+ * every MPI process needs to build the entire sparsity pattern; in that
+ * case, it is sufficient if every process only builds that part of the
+ * sparsity pattern that corresponds to the subdomain_id for which it is
+ * responsible. This feature is used in step-32. (This argument is not
+ * usually needed for objects of type parallel::distributed::Triangulation
+ * because the current function only loops over locally owned cells anyway;
+ * thus, this argument typically only makes sense if you want to use the
+ * subdomain_id for anything other than indicating which processor owns a
+ * cell, for example which geometric component of the domain a cell belongs
+ * to.)
+ *
+ * @note The actual type of the sparsity pattern may be SparsityPattern,
+ * DynamicSparsityPattern, BlockSparsityPattern,
+ * BlockDynamicSparsityPattern, or any other class that satisfies similar
+ * requirements. It is assumed that the size of the sparsity pattern matches
+ * the number of degrees of freedom and that enough unused nonzero entries
+ * are left to fill the sparsity pattern if the sparsity pattern is of
+ * "static" kind (see
+ * @ref Sparsity
+ * for more information on what this means). The nonzero entries generated
+ * by this function are added to possible previous content of the object,
+ * i.e., previously added entries are not removed.
*
* @note If the sparsity pattern is represented by an object of type
- * SparsityPattern (as opposed to, for example,
- * DynamicSparsityPattern), you need to remember using
- * SparsityPattern::compress() after generating the pattern.
+ * SparsityPattern (as opposed to, for example, DynamicSparsityPattern), you
+ * need to remember using SparsityPattern::compress() after generating the
+ * pattern.
*
* @ingroup constraints
*/
const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
/**
- * Compute which entries of a matrix built on the given
- * @p dof_handler may possibly be nonzero, and create a sparsity
- * pattern object that represents these nonzero locations.
+ * Compute which entries of a matrix built on the given @p dof_handler may
+ * possibly be nonzero, and create a sparsity pattern object that represents
+ * these nonzero locations.
*
* This function is a simple variation on the previous
- * make_sparsity_pattern() function (see there for a description of
- * all of the common arguments), but it provides functionality for
- * vector finite elements that allows to be more specific about
- * which variables couple in which equation.
+ * make_sparsity_pattern() function (see there for a description of all of
+ * the common arguments), but it provides functionality for vector finite
+ * elements that allows to be more specific about which variables couple in
+ * which equation.
*
* For example, if you wanted to solve the Stokes equations,
*
* -\Delta \mathbf u + \nabla p &= 0,\\ \text{div}\ u &= 0
* @f}
*
- * in two space dimensions, using stable Q2/Q1 mixed elements (using
- * the FESystem class), then you don't want all degrees of freedom
- * to couple in each equation. More specifically, in the first
- * equation, only $u_x$ and $p$ appear; in the second equation, only
- * $u_y$ and $p$ appear; and in the third equation, only $u_x$ and
- * $u_y$ appear. (Note that this discussion only talks about vector
- * components of the solution variable and the different equation,
- * and has nothing to do with degrees of freedom, or in fact with
- * any kind of discretization.) We can describe this by the
+ * in two space dimensions, using stable Q2/Q1 mixed elements (using the
+ * FESystem class), then you don't want all degrees of freedom to couple in
+ * each equation. More specifically, in the first equation, only $u_x$ and
+ * $p$ appear; in the second equation, only $u_y$ and $p$ appear; and in the
+ * third equation, only $u_x$ and $u_y$ appear. (Note that this discussion
+ * only talks about vector components of the solution variable and the
+ * different equation, and has nothing to do with degrees of freedom, or in
+ * fact with any kind of discretization.) We can describe this by the
* following pattern of "couplings":
*
* @f[
* \right]
* @f]
*
- * where "1" indicates that two variables (i.e., vector components
- * of the FESystem) couple in the respective equation, and a "0"
- * means no coupling. These zeros imply that upon discretization via
- * a standard finite element formulation, we will not write entries
- * into the matrix that, for example, couple pressure test functions
- * with pressure shape functions (and similar for the other zeros
- * above). It is then a waste to allocate memory for these entries
- * in the matrix and the sparsity pattern, and you can avoid this by
- * creating a mask such as the one above that describes this to the
- * (current) function that computes the sparsity pattern. As stated
- * above, the mask shown above refers to components of the composed
- * FESystem, rather than to degrees of freedom or shape functions.
+ * where "1" indicates that two variables (i.e., vector components of the
+ * FESystem) couple in the respective equation, and a "0" means no coupling.
+ * These zeros imply that upon discretization via a standard finite element
+ * formulation, we will not write entries into the matrix that, for example,
+ * couple pressure test functions with pressure shape functions (and similar
+ * for the other zeros above). It is then a waste to allocate memory for
+ * these entries in the matrix and the sparsity pattern, and you can avoid
+ * this by creating a mask such as the one above that describes this to the
+ * (current) function that computes the sparsity pattern. As stated above,
+ * the mask shown above refers to components of the composed FESystem,
+ * rather than to degrees of freedom or shape functions.
*
* This function is designed to accept a coupling pattern, like the one
* shown above, through the @p couplings parameter, which contains values of
* finite element in use are non-zero in more than one component (in deal.II
* speak: they are
* @ref GlossPrimitive "non-primitive finite elements").
- * In
- * this case, the coupling element
- * corresponding to the first non-zero component is taken and additional
- * ones for this component are ignored.
+ * In this case, the coupling element corresponding to the first non-zero
+ * component is taken and additional ones for this component are ignored.
*
* @ingroup constraints
*/
SparsityPatternType &sparsity);
/**
- * Compute which entries of a matrix built on the given @p
- * dof_handler may possibly be nonzero, and create a sparsity
- * pattern object that represents these nonzero locations. This
- * function is a variation of the make_sparsity_pattern() functions
- * above in that it assumes that the bilinear form you want to use
- * to generate the matrix also contains terms that integrate over
- * the <i>faces</i> between cells (i.e., it contains "fluxes"
- * between cells, explaining the name of the function).
- *
- * This function is useful for Discontinuous Galerkin methods where
- * the standard make_sparsity_pattern() function would only create
- * nonzero entries for all degrees of freedom on one cell coupling
- * to all other degrees of freedom on the same cell; however, in DG
- * methods, all or some degrees of freedom on each cell also couple
- * to the degrees of freedom on other cells connected to the current
- * one by a common face. The current function also creates the
- * nonzero entries in the matrix resulting from these additional
- * couplings. In other words, this function computes a strict
- * super-set of nonzero entries compared to the work done by
+ * Compute which entries of a matrix built on the given @p dof_handler may
+ * possibly be nonzero, and create a sparsity pattern object that represents
+ * these nonzero locations. This function is a variation of the
+ * make_sparsity_pattern() functions above in that it assumes that the
+ * bilinear form you want to use to generate the matrix also contains terms
+ * that integrate over the <i>faces</i> between cells (i.e., it contains
+ * "fluxes" between cells, explaining the name of the function).
+ *
+ * This function is useful for Discontinuous Galerkin methods where the
+ * standard make_sparsity_pattern() function would only create nonzero
+ * entries for all degrees of freedom on one cell coupling to all other
+ * degrees of freedom on the same cell; however, in DG methods, all or some
+ * degrees of freedom on each cell also couple to the degrees of freedom on
+ * other cells connected to the current one by a common face. The current
+ * function also creates the nonzero entries in the matrix resulting from
+ * these additional couplings. In other words, this function computes a
+ * strict super-set of nonzero entries compared to the work done by
* make_sparsity_pattern().
*
- * @param[in] dof_handler The DoFHandler or hp::DoFHandler object
- * that describes which degrees of freedom live on which cells.
+ * @param[in] dof_handler The DoFHandler or hp::DoFHandler object that
+ * describes which degrees of freedom live on which cells.
*
* @param[out] sparsity_pattern The sparsity pattern to be filled with
- * entries.
- *
- * @note The actual type of the sparsity pattern may be
- * SparsityPattern, DynamicSparsityPattern, BlockSparsityPattern,
- * BlockDynamicSparsityPattern, or any other class that satisfies
- * similar requirements. It is assumed that the size of the
- * sparsity pattern matches the number of degrees of freedom and
- * that enough unused nonzero entries are left to fill the
- * sparsity pattern if the sparsity pattern is of "static" kind
- * (see
- * @ref Sparsity
- * for more information on what this
- * means). The nonzero entries generated by this function are
- * added to possible previous content of the object, i.e.,
- * previously added entries are not removed.
+ * entries.
+ *
+ * @note The actual type of the sparsity pattern may be SparsityPattern,
+ * DynamicSparsityPattern, BlockSparsityPattern,
+ * BlockDynamicSparsityPattern, or any other class that satisfies similar
+ * requirements. It is assumed that the size of the sparsity pattern matches
+ * the number of degrees of freedom and that enough unused nonzero entries
+ * are left to fill the sparsity pattern if the sparsity pattern is of
+ * "static" kind (see
+ * @ref Sparsity
+ * for more information on what this means). The nonzero entries generated
+ * by this function are added to possible previous content of the object,
+ * i.e., previously added entries are not removed.
*
* @note If the sparsity pattern is represented by an object of type
- * SparsityPattern (as opposed to, for example,
- * DynamicSparsityPattern), you need to remember using
- * SparsityPattern::compress() after generating the pattern.
+ * SparsityPattern (as opposed to, for example, DynamicSparsityPattern), you
+ * need to remember using SparsityPattern::compress() after generating the
+ * pattern.
*
* @ingroup constraints
*/
/**
* This function does essentially the same as the other
- * make_flux_sparsity_pattern() function but allows the
- * specification of a number of additional arguments. These carry
- * the same meaning as discussed in the first
- * make_sparsity_pattern() function above.
+ * make_flux_sparsity_pattern() function but allows the specification of a
+ * number of additional arguments. These carry the same meaning as discussed
+ * in the first make_sparsity_pattern() function above.
*
* @ingroup constraints
*/
/**
* This function does essentially the same as the other
- * make_flux_sparsity_pattern() function but allows the
- * specification of coupling matrices that state which components of
- * the solution variable couple in each of the equations you are
- * discretizing. This works in complete analogy as discussed in the
- * second make_sparsity_pattern() function above.
+ * make_flux_sparsity_pattern() function but allows the specification of
+ * coupling matrices that state which components of the solution variable
+ * couple in each of the equations you are discretizing. This works in
+ * complete analogy as discussed in the second make_sparsity_pattern()
+ * function above.
*
* In fact, this function takes two such masks, one describing which
- * variables couple with each other in the cell integrals that make
- * up your bilinear form, and which variables coupld with each other
- * in the face integrals. If you passed masks consisting of only 1s
- * to both of these, then you would get the same sparsity pattern as
- * if you had called the first of the make_sparsity_pattern()
- * functions above. By setting some of the entries of these masks to
- * zeros, you can get a sparser sparsity pattern.
+ * variables couple with each other in the cell integrals that make up your
+ * bilinear form, and which variables coupld with each other in the face
+ * integrals. If you passed masks consisting of only 1s to both of these,
+ * then you would get the same sparsity pattern as if you had called the
+ * first of the make_sparsity_pattern() functions above. By setting some of
+ * the entries of these masks to zeros, you can get a sparser sparsity
+ * pattern.
*
* @ingroup constraints
*/
* Create the sparsity pattern for boundary matrices. See the general
* documentation of this class for more information.
*
- * The function does essentially what the other
- * make_sparsity_pattern() functions do, but assumes that the
- * bilinear form that is used to build the matrix does not consist
- * of domain integrals, but only of integrals over the boundary of
- * the domain.
+ * The function does essentially what the other make_sparsity_pattern()
+ * functions do, but assumes that the bilinear form that is used to build
+ * the matrix does not consist of domain integrals, but only of integrals
+ * over the boundary of the domain.
*/
template <typename DoFHandlerType, typename SparsityPatternType>
void
/**
* This function is a variation of the previous
- * make_boundary_sparsity_pattern() function in which we assume that
- * the boundary integrals that will give rise to the matrix extends
- * only over those parts of the boundary whose boundary indicators
- * are listed in the @p boundary_ids argument to this function.
- *
- * This function could have been written by passing a @p set of
- * boundary_id numbers. However, most of the functions throughout
- * deal.II dealing with boundary indicators take a mapping of
- * boundary indicators and the corresponding boundary function,
- * i.e., a FunctionMap argument. Correspondingly, this function does
- * the same, though the actual boundary function is ignored here.
- * (Consequently, if you don't have any such boundary functions,
- * just create a map with the boundary indicators you want and set
- * the function pointers to null pointers).
+ * make_boundary_sparsity_pattern() function in which we assume that the
+ * boundary integrals that will give rise to the matrix extends only over
+ * those parts of the boundary whose boundary indicators are listed in the
+ * @p boundary_ids argument to this function.
+ *
+ * This function could have been written by passing a @p set of boundary_id
+ * numbers. However, most of the functions throughout deal.II dealing with
+ * boundary indicators take a mapping of boundary indicators and the
+ * corresponding boundary function, i.e., a FunctionMap argument.
+ * Correspondingly, this function does the same, though the actual boundary
+ * function is ignored here. (Consequently, if you don't have any such
+ * boundary functions, just create a map with the boundary indicators you
+ * want and set the function pointers to null pointers).
*/
template <typename DoFHandlerType, typename SparsityPatternType>
void
* elements of the other vector components of the finite element fields on
* the fine grid are not touched.
*
- * Triangulation of the fine grid can be distributed. When called in parallel,
- * each process has to have a copy of the coarse grid. In this case, function
- * returns transfer representation for a set of locally owned cells.
+ * Triangulation of the fine grid can be distributed. When called in
+ * parallel, each process has to have a copy of the coarse grid. In this
+ * case, function returns transfer representation for a set of locally owned
+ * cells.
*
* The output of this function is a compressed format that can be used to
* construct corresponding sparse transfer matrix.
* and any combination of that...
* @endcode
*
- * Optionally a matrix @p matrix along with an std::vector
- * @p first_vector_components can be specified that describes how DoFs on
- * @p face_1 should be modified prior to constraining to the DoFs of
- * @p face_2. Here, two declarations are possible: If the std::vector
- * @p first_vector_components is non empty the matrix is interpreted as a
- * @p dim $\times$ @p dim rotation matrix that is applied to all vector
- * valued blocks listed in @p first_vector_components of the FESystem. If
- * @p first_vector_components is empty the matrix is interpreted as an
+ * Optionally a matrix @p matrix along with an std::vector @p
+ * first_vector_components can be specified that describes how DoFs on @p
+ * face_1 should be modified prior to constraining to the DoFs of @p face_2.
+ * Here, two declarations are possible: If the std::vector @p
+ * first_vector_components is non empty the matrix is interpreted as a @p
+ * dim $\times$ @p dim rotation matrix that is applied to all vector valued
+ * blocks listed in @p first_vector_components of the FESystem. If @p
+ * first_vector_components is empty the matrix is interpreted as an
* interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
*
* Detailed information can be found in the see
*/
/**
- * @name Identifying subsets of degrees of freedom with particular properties
+ * @name Identifying subsets of degrees of freedom with particular
+ * properties
* @{
*/
/**
*
- * For each processor, determine the set of locally owned degrees of freedom as an IndexSet.
- * This function then returns a vector of index sets, where the vector has size equal to the
- * number of MPI processes that participate in the DoF handler object.
+ * For each processor, determine the set of locally owned degrees of freedom
+ * as an IndexSet. This function then returns a vector of index sets, where
+ * the vector has size equal to the number of MPI processes that participate
+ * in the DoF handler object.
*
- * The function can be used for objects of type dealii::Triangulation or parallel::shared::Triangulation.
- * It will not work for objects of type parallel::distributed::Triangulation since for such triangulations
- * we do not have information about all cells of the triangulation available locally,
- * and consequently can not say anything definitive about the degrees of freedom active on other
- * processors' locally owned cells.
+ * The function can be used for objects of type dealii::Triangulation or
+ * parallel::shared::Triangulation. It will not work for objects of type
+ * parallel::distributed::Triangulation since for such triangulations we do
+ * not have information about all cells of the triangulation available
+ * locally, and consequently can not say anything definitive about the
+ * degrees of freedom active on other processors' locally owned cells.
*
* @author Denis Davydov, 2015
*/
/**
*
- * For each processor, determine the set of locally relevant degrees of freedom as an IndexSet.
- * This function then returns a vector of index sets, where the vector has size equal to the
- * number of MPI processes that participate in the DoF handler object.
+ * For each processor, determine the set of locally relevant degrees of
+ * freedom as an IndexSet. This function then returns a vector of index
+ * sets, where the vector has size equal to the number of MPI processes that
+ * participate in the DoF handler object.
*
- * The function can be used for objects of type dealii::Triangulation or parallel::shared::Triangulation.
- * It will not work for objects of type parallel::distributed::Triangulation since for such triangulations
- * we do not have information about all cells of the triangulation available locally,
- * and consequently can not say anything definitive about the degrees of freedom active on other
- * processors' locally owned cells.
+ * The function can be used for objects of type dealii::Triangulation or
+ * parallel::shared::Triangulation. It will not work for objects of type
+ * parallel::distributed::Triangulation since for such triangulations we do
+ * not have information about all cells of the triangulation available
+ * locally, and consequently can not say anything definitive about the
+ * degrees of freedom active on other processors' locally owned cells.
*
* @author Jean-Paul Pelteret, 2015
*/
/**
- * Same as extract_locally_relevant_dofs() but for multigrid DoFs
- * for the given @p level.
+ * Same as extract_locally_relevant_dofs() but for multigrid DoFs for the
+ * given @p level.
*/
template <typename DoFHandlerType>
void
/**
- * For each degree of freedom, return in the output array to which
- * subdomain (as given by the <tt>cell->subdomain_id()</tt>
- * function) it belongs. The output array is supposed to have the
- * right size already when calling this function.
+ * For each degree of freedom, return in the output array to which subdomain
+ * (as given by the <tt>cell->subdomain_id()</tt> function) it belongs. The
+ * output array is supposed to have the right size already when calling this
+ * function.
*
* Note that degrees of freedom associated with faces, edges, and vertices
* may be associated with multiple subdomains if they are sitting on
* processor. Note that this includes the ones that this subdomain "owns"
* (i.e. the ones for which get_subdomain_association() returns a value
* equal to the subdomain given here and that are selected by the
- * extract_locally_owned_dofs() function) but also all of those that sit on the
- * boundary between the given subdomain and other subdomain. In essence,
+ * extract_locally_owned_dofs() function) but also all of those that sit on
+ * the boundary between the given subdomain and other subdomain. In essence,
* degrees of freedom that sit on boundaries between subdomain will be in
* the index sets returned by this function for more than one subdomain.
*
*
* @tparam DoFHandlerType A type that is either DoFHandler or
* hp::DoFHandler. In C++, the compiler can not determine the type of
- * <code>DoFHandlerType</code> from the function call. You need to specify it
- * as an explicit template argument following the function name.
+ * <code>DoFHandlerType</code> from the function call. You need to specify
+ * it as an explicit template argument following the function name.
*
- * @param patch A collection of cells within an object of type DoFHandlerType
+ * @param patch A collection of cells within an object of type
+ * DoFHandlerType
*
* @return The number of degrees of freedom associated with the cells of
* this patch.
*
* @tparam DoFHandlerType A type that is either DoFHandler or
* hp::DoFHandler. In C++, the compiler can not determine the type of
- * <code>DoFHandlerType</code> from the function call. You need to specify it
- * as an explicit template argument following the function name.
+ * <code>DoFHandlerType</code> from the function call. You need to specify
+ * it as an explicit template argument following the function name.
*
- * @param patch A collection of cells within an object of type DoFHandlerType
+ * @param patch A collection of cells within an object of type
+ * DoFHandlerType
*
* @return A list of those global degrees of freedom located on the patch,
* as defined above.
* \mathbf n \cdot \nabla u = h_i \qquad \qquad
* \text{on}\ \Gamma_i\subset\partial\Omega.
* @f}
- * An example is the function
- * KellyErrorEstimator::estimate() that allows us to provide a set of
- * functions $h_i$ for all those boundary indicators $i$ for which the
- * boundary condition is supposed to be of Neumann type. Of course, the same
- * kind of principle can be applied to cases where we care about Dirichlet
- * values, where one needs to provide a map from boundary indicator $i$ to
- * Dirichlet function $h_i$ if the boundary conditions are given as
+ * An example is the function KellyErrorEstimator::estimate() that allows us
+ * to provide a set of functions $h_i$ for all those boundary indicators $i$
+ * for which the boundary condition is supposed to be of Neumann type. Of
+ * course, the same kind of principle can be applied to cases where we care
+ * about Dirichlet values, where one needs to provide a map from boundary
+ * indicator $i$ to Dirichlet function $h_i$ if the boundary conditions are
+ * given as
* @f{align*}{
* u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega.
* @f}
- * This
- * is, for example, the case for the VectorTools::interpolate() functions.
+ * This is, for example, the case for the VectorTools::interpolate()
+ * functions.
*
* Tutorial programs step-6, step-7 and step-8 show examples of how to use
* function arguments of this type in situations where we actually have an
/**
* This is the base class for finite elements in arbitrary dimensions. It
- * declares the interface both in terms of member variables and public
- * member functions through which properties of a concrete implementation
- * of a finite element can be accessed. This interface generally consists
- * of a number of groups of variables and functions that can roughly be
- * delineated as follows:
+ * declares the interface both in terms of member variables and public member
+ * functions through which properties of a concrete implementation of a finite
+ * element can be accessed. This interface generally consists of a number of
+ * groups of variables and functions that can roughly be delineated as
+ * follows:
* - Basic information about the finite element, such as the number of
- * degrees of freedom per vertex, edge, or cell. This kind of data
- * is stored in the FiniteElementData base class. (Though the
- * FiniteElement::get_name() member function also falls into this category.)
+ * degrees of freedom per vertex, edge, or cell. This kind of data is stored
+ * in the FiniteElementData base class. (Though the FiniteElement::get_name()
+ * member function also falls into this category.)
* - A description of the shape functions and their derivatives on the
- * reference cell $[0,1]^d$, if an element is indeed defined by mapping
- * shape functions from the reference cell to an actual cell.
+ * reference cell $[0,1]^d$, if an element is indeed defined by mapping shape
+ * functions from the reference cell to an actual cell.
* - Matrices (and functions that access them) that describe how an
- * element's shape functions related to those on parent or child cells
- * (restriction or prolongation) or neighboring cells (for hanging
- * node constraints), as well as to other finite element spaces
- * defined on the same cell (e.g., when doing $p$ refinement).
+ * element's shape functions related to those on parent or child cells
+ * (restriction or prolongation) or neighboring cells (for hanging node
+ * constraints), as well as to other finite element spaces defined on the same
+ * cell (e.g., when doing $p$ refinement).
* - %Functions that describe the properties of individual shape functions,
- * for example which
- * @ref GlossComponent "vector components"
- * of a
- * @ref vector_valued "vector-valued finite element's"
- * shape function
- * is nonzero, or whether an element is
- * @ref GlossPrimitive "primitive".
+ * for example which
+ * @ref GlossComponent "vector components"
+ * of a
+ * @ref vector_valued "vector-valued finite element's"
+ * shape function is nonzero, or whether an element is
+ * @ref GlossPrimitive "primitive".
* - For elements that are interpolatory, such as the common $Q_p$
- * Lagrange elements, data that describes where their
- * @ref GlossSupport "support points"
- * are located.
+ * Lagrange elements, data that describes where their
+ * @ref GlossSupport "support points"
+ * are located.
* - %Functions that define the interface to the FEValues class that is
- * almost always used to access finite element shape functions from
- * user code.
+ * almost always used to access finite element shape functions from user code.
*
- * The following sections discuss many of these concepts in more detail,
- * and outline strategies by which concrete implementations of a finite
- * element can provide the details necessary for a complete description
- * of a finite element space.
+ * The following sections discuss many of these concepts in more detail, and
+ * outline strategies by which concrete implementations of a finite element
+ * can provide the details necessary for a complete description of a finite
+ * element space.
*
- * As a general rule, there are three ways by which derived classes
- * provide this information:
+ * As a general rule, there are three ways by which derived classes provide
+ * this information:
* - A number of fields that are generally easy to compute and that
- * are initialized by the constructor of this class (or the constructor
- * of the FiniteElementData base class) and derived classes therefore
- * have to compute in the process of calling this class's constructor.
- * This is, specifically, the case for the basic information and parts
- * of the descriptive information about shape functions mentioned above.
+ * are initialized by the constructor of this class (or the constructor of the
+ * FiniteElementData base class) and derived classes therefore have to compute
+ * in the process of calling this class's constructor. This is, specifically,
+ * the case for the basic information and parts of the descriptive information
+ * about shape functions mentioned above.
* - Some common matrices that are widely used in the library and for
- * which this class provides protected member variables that the
- * constructors of derived classes need to fill. The purpose of providing
- * these matrices in this class is that (i) they are frequently used,
- * and (ii) they are expensive to compute. Consequently, it makes sense
- * to only compute them once, rather than every time they are used. In most
- * cases, the constructor of the current class already sets them to their
- * correct size, and derived classes therefore only have to fill them.
- * Examples of this include the matrices that relate the shape functions on
- * one cell to the shape functions on neighbors, children, and parents.
+ * which this class provides protected member variables that the constructors
+ * of derived classes need to fill. The purpose of providing these matrices in
+ * this class is that (i) they are frequently used, and (ii) they are
+ * expensive to compute. Consequently, it makes sense to only compute them
+ * once, rather than every time they are used. In most cases, the constructor
+ * of the current class already sets them to their correct size, and derived
+ * classes therefore only have to fill them. Examples of this include the
+ * matrices that relate the shape functions on one cell to the shape functions
+ * on neighbors, children, and parents.
* - Uncommon information, or information that depends on specific input
- * arguments, and that needs to be implemented by derived classes. For
- * these, this base class only declares abstract virtual member functions
- * and derived classes then have to implement them. Examples of this
- * category would include the functions that compute values and
- * derivatives of shape functions on the reference cell for which it
- * is not possible to tabulate values because there are infinitely
- * many points at which one may want to evaluate them. In some cases,
- * derived classes may choose to simply not implement <i>all</i> possible
- * interfaces (or may not <i>yet</i> have a complete implementation);
- * for uncommon functions, there is then often a member function
- * derived classes can overload that describes whether a particular
- * feature is implemented. An example is whether an element implements
- * the information necessary to use it in the $hp$ finite element
- * context (see
- * @ref hp "hp finite element support").
+ * arguments, and that needs to be implemented by derived classes. For these,
+ * this base class only declares abstract virtual member functions and derived
+ * classes then have to implement them. Examples of this category would
+ * include the functions that compute values and derivatives of shape
+ * functions on the reference cell for which it is not possible to tabulate
+ * values because there are infinitely many points at which one may want to
+ * evaluate them. In some cases, derived classes may choose to simply not
+ * implement <i>all</i> possible interfaces (or may not <i>yet</i> have a
+ * complete implementation); for uncommon functions, there is then often a
+ * member function derived classes can overload that describes whether a
+ * particular feature is implemented. An example is whether an element
+ * implements the information necessary to use it in the $hp$ finite element
+ * context (see
+ * @ref hp "hp finite element support").
*
*
* <h3>Nomenclature</h3>
*
- * Finite element classes have to define a large number of different properties
- * describing a finite element space. The following subsections describe some
- * nomenclature that will be used in the documentation below.
+ * Finite element classes have to define a large number of different
+ * properties describing a finite element space. The following subsections
+ * describe some nomenclature that will be used in the documentation below.
*
* <h4>Components and blocks</h4>
*
* @ref vector_valued "Vector-valued finite element"
- * are elements used for
- * systems of partial differential equations. Oftentimes, they are composed
- * via the FESystem class (which is itself derived from the current class),
- * but there are also non-composed elements that have multiple components
- * (for example the FE_Nedelec and FE_RaviartThomas classes, among others).
- * For any of these vector valued elements, individual shape functions may
- * be nonzero in one or several
+ * are elements used for systems of partial differential equations.
+ * Oftentimes, they are composed via the FESystem class (which is itself
+ * derived from the current class), but there are also non-composed elements
+ * that have multiple components (for example the FE_Nedelec and
+ * FE_RaviartThomas classes, among others). For any of these vector valued
+ * elements, individual shape functions may be nonzero in one or several
* @ref GlossComponent "components"
* of the vector valued function. If the element is
* @ref GlossPrimitive "primitive",
* function. This component can be determined using the
* FiniteElement::system_to_component_index() function.
*
- * On the other hand, if there is at least one shape function that
- * is nonzero in more than one vector component, then we call the entire
- * element "non-primitive". The FiniteElement::get_nonzero_components()
- * can then be used to determine which vector components of a shape
- * function are nonzero. The number of nonzero components of a shape function
- * is returned by FiniteElement::n_components(). Whether a shape
- * function is non-primitive can be queried by
- * FiniteElement::is_primitive().
+ * On the other hand, if there is at least one shape function that is nonzero
+ * in more than one vector component, then we call the entire element "non-
+ * primitive". The FiniteElement::get_nonzero_components() can then be used to
+ * determine which vector components of a shape function are nonzero. The
+ * number of nonzero components of a shape function is returned by
+ * FiniteElement::n_components(). Whether a shape function is non-primitive
+ * can be queried by FiniteElement::is_primitive().
*
* Oftentimes, one may want to split linear system into blocks so that they
* reflect the structure of the underlying operator. This is typically not
* done based on vector components, but based on the use of
* @ref GlossBlock "blocks",
- * and the result is then used to substructure
- * objects of type BlockVector, BlockSparseMatrix, BlockMatrixArray, and so on.
- * If you use non-primitive elements, you cannot determine the block number by
+ * and the result is then used to substructure objects of type BlockVector,
+ * BlockSparseMatrix, BlockMatrixArray, and so on. If you use non-primitive
+ * elements, you cannot determine the block number by
* FiniteElement::system_to_component_index(). Instead, you can use
* FiniteElement::system_to_block_index(). The number of blocks of a finite
* element can be determined by FiniteElement::n_blocks().
*
* <h4>Support points</h4>
*
- * Finite elements are frequently defined by defining a polynomial space and
- * a set of dual functionals. If these functionals involve point evaluations,
- * then the element is "interpolatory" and it is possible to interpolate
- * an arbitrary (but sufficiently smooth) function onto the finite element
- * space by evaluating it at these points. We call these points "support
- * points".
+ * Finite elements are frequently defined by defining a polynomial space and a
+ * set of dual functionals. If these functionals involve point evaluations,
+ * then the element is "interpolatory" and it is possible to interpolate an
+ * arbitrary (but sufficiently smooth) function onto the finite element space
+ * by evaluating it at these points. We call these points "support points".
*
- * Most finite elements are defined by mapping from the reference cell to
- * a concrete cell. Consequently, the support points are then defined on
- * the reference ("unit") cell, see
+ * Most finite elements are defined by mapping from the reference cell to a
+ * concrete cell. Consequently, the support points are then defined on the
+ * reference ("unit") cell, see
* @ref GlossSupport "this glossary entry".
- * The support points on a concrete
- * cell can then be computed by mapping the unit support points, using the
- * Mapping class interface and derived classes, typically via the FEValues
- * class.
+ * The support points on a concrete cell can then be computed by mapping the
+ * unit support points, using the Mapping class interface and derived classes,
+ * typically via the FEValues class.
*
* A typical code snippet to do so would look as follows:
* @code
* @endcode
*
* @note Finite elements' implementation of the get_unit_support_points()
- * function returns these points in the same order as shape functions. As a
- * consequence, the quadrature points accessed above are also ordered in this
- * way. The order of shape functions is typically documented in the class
- * documentation of the various finite element classes.
+ * function returns these points in the same order as shape functions. As a
+ * consequence, the quadrature points accessed above are also ordered in this
+ * way. The order of shape functions is typically documented in the class
+ * documentation of the various finite element classes.
*
*
* <h3>Implementing finite element spaces in derived classes</h3>
*
- * The following sections provide some more guidance for implementing
- * concrete finite element spaces in derived classes. This includes information
- * that depends on the dimension for which you want to provide something,
- * followed by a list of tools helping to generate information in concrete
- * cases.
+ * The following sections provide some more guidance for implementing concrete
+ * finite element spaces in derived classes. This includes information that
+ * depends on the dimension for which you want to provide something, followed
+ * by a list of tools helping to generate information in concrete cases.
*
- * It is important to note that there is a number of intermediate classes
- * that can do a lot of what is necessary for a complete description of
- * finite element spaces. For example, the FE_Poly, FE_PolyTensor, and
- * FE_PolyFace classes in essence build a complete finite element space
- * if you only provide them with an abstract description of the
- * polynomial space upon which you want to build an element. Using these
- * intermediate classes typically makes implementing finite element
- * descriptions vastly simpler.
+ * It is important to note that there is a number of intermediate classes that
+ * can do a lot of what is necessary for a complete description of finite
+ * element spaces. For example, the FE_Poly, FE_PolyTensor, and FE_PolyFace
+ * classes in essence build a complete finite element space if you only
+ * provide them with an abstract description of the polynomial space upon
+ * which you want to build an element. Using these intermediate classes
+ * typically makes implementing finite element descriptions vastly simpler.
*
- * As a general rule, if you want to
- * implement an element, you will likely want to look at the implementation
- * of other, similar elements first. Since many of the more complicated
- * pieces of a finite element interface have to do with how they interact
- * with mappings, quadrature, and the FEValues class, you will also want
- * to read through the
+ * As a general rule, if you want to implement an element, you will likely
+ * want to look at the implementation of other, similar elements first. Since
+ * many of the more complicated pieces of a finite element interface have to
+ * do with how they interact with mappings, quadrature, and the FEValues
+ * class, you will also want to read through the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module.
+ * documentation module.
*
*
* <h4>Interpolation matrices in one dimension</h4>
*
- * In one space dimension (i.e., for <code>dim==1</code> and any
- * value of <code>spacedim</code>),
- * finite element classes implementing the interface of the current
- * base class need only set the #restriction and
- * #prolongation matrices that describe the interpolation of the finite
- * element space on one cell to that of its parent cell, and to that
- * on its children, respectively. The constructor of the current class
- * in one dimension presets the #interface_constraints matrix (used to
- * describe hanging node constraints at the interface between cells of
- * different refinement levels) to have size zero because there are no
- * hanging nodes in 1d.
+ * In one space dimension (i.e., for <code>dim==1</code> and any value of
+ * <code>spacedim</code>), finite element classes implementing the interface
+ * of the current base class need only set the #restriction and #prolongation
+ * matrices that describe the interpolation of the finite element space on one
+ * cell to that of its parent cell, and to that on its children, respectively.
+ * The constructor of the current class in one dimension presets the
+ * #interface_constraints matrix (used to describe hanging node constraints at
+ * the interface between cells of different refinement levels) to have size
+ * zero because there are no hanging nodes in 1d.
*
* <h4>Interpolation matrices in two dimensions</h4>
*
* In addition to the fields discussed above for 1D, a constraint matrix is
* needed to describe hanging node constraints if the finite element has
- * degrees of freedom located on edges or vertices.
- * These constraints are represented by an $m\times n$-matrix
- * #interface_constraints, where <i>m</i> is the number of degrees of freedom
- * on the refined side without the corner vertices (those dofs on the middle
- * vertex plus those on the two lines), and <i>n</i> is that of the unrefined
- * side (those dofs on the two vertices plus those on the line). The matrix is
- * thus a rectangular one. The $m\times n$ size of the #interface_constraints
- * matrix can also be accessed through the interface_constraints_size()
- * function.
+ * degrees of freedom located on edges or vertices. These constraints are
+ * represented by an $m\times n$-matrix #interface_constraints, where <i>m</i>
+ * is the number of degrees of freedom on the refined side without the corner
+ * vertices (those dofs on the middle vertex plus those on the two lines), and
+ * <i>n</i> is that of the unrefined side (those dofs on the two vertices plus
+ * those on the line). The matrix is thus a rectangular one. The $m\times n$
+ * size of the #interface_constraints matrix can also be accessed through the
+ * interface_constraints_size() function.
*
* The mapping of the dofs onto the indices of the matrix on the unrefined
* side is as follows: let $d_v$ be the number of dofs on a vertex, $d_l$ that
* DoFTools::make_hanging_node_constraints() function.
*
* @note The hanging node constraints described by these matrices are only
- * relevant to the case where the same finite element space is used on
- * neighboring (but differently refined) cells. The case that the finite
- * element spaces on different sides of a face are different, i.e.,
- * the $hp$ case (see
- * @ref hp "hp finite element support")
- * is handled
- * by separate functions. See the FiniteElement::get_face_interpolation_matrix()
- * and FiniteElement::get_subface_interpolation_matrix() functions.
+ * relevant to the case where the same finite element space is used on
+ * neighboring (but differently refined) cells. The case that the finite
+ * element spaces on different sides of a face are different, i.e., the $hp$
+ * case (see
+ * @ref hp "hp finite element support")
+ * is handled by separate functions. See the
+ * FiniteElement::get_face_interpolation_matrix() and
+ * FiniteElement::get_subface_interpolation_matrix() functions.
*
*
* <h4>Interpolation matrices in three dimensions</h4>
*
- * For the interface constraints, the 3d case is similar to the 2d case.
- * The numbering for the indices $n$ on the mother face is obvious and keeps
- * to the usual numbering of degrees of freedom on quadrilaterals.
+ * For the interface constraints, the 3d case is similar to the 2d case. The
+ * numbering for the indices $n$ on the mother face is obvious and keeps to
+ * the usual numbering of degrees of freedom on quadrilaterals.
*
* The numbering of the degrees of freedom on the interior of the refined
* faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above, and
* above), it insists that the weights are exactly the same.
*
* Using this scheme, child face degrees of freedom are constrained against
- * parent face degrees of freedom that contain those on the edges of the parent
- * face; it is possible that some of them are in turn constrained themselves,
- * leading to longer chains of constraints that the ConstraintMatrix class will
- * eventually have to sort out. (The constraints described above are used by
- * the DoFTools::make_hanging_node_constraints() function that constructs a
- * ConstraintMatrix object.) However, this is of no concern for the
- * FiniteElement and derived classes since they only act locally on one cell
- * and its immediate neighbor, and do not see the bigger picture. The
+ * parent face degrees of freedom that contain those on the edges of the
+ * parent face; it is possible that some of them are in turn constrained
+ * themselves, leading to longer chains of constraints that the
+ * ConstraintMatrix class will eventually have to sort out. (The constraints
+ * described above are used by the DoFTools::make_hanging_node_constraints()
+ * function that constructs a ConstraintMatrix object.) However, this is of no
+ * concern for the FiniteElement and derived classes since they only act
+ * locally on one cell and its immediate neighbor, and do not see the bigger
+ * picture. The
* @ref hp_paper
* details how such chains are handled in practice.
*
* etc). Other tasks can be automated by some of the functions in namespace
* FETools.
*
- * <h5>Computing the correct basis from a set of linearly independent functions</h5>
+ * <h5>Computing the correct basis from a set of linearly independent
+ * functions</h5>
*
* First, it may already be difficult to compute the basis of shape functions
* for arbitrary order and dimension. On the other hand, if the
* <i>w<sub>j</sub></i>.
* </ol>
*
- * The matrix <i>M</i> may be computed using
- * FETools::compute_node_matrix(). This function relies on the existence of
- * #generalized_support_points and an implementation of the
- * FiniteElement::interpolate() function with
+ * The matrix <i>M</i> may be computed using FETools::compute_node_matrix().
+ * This function relies on the existence of #generalized_support_points and an
+ * implementation of the FiniteElement::interpolate() function with
* VectorSlice argument. (See the
* @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.) With this, one can then use the following
- * piece of code in the constructor of a class derived from FinitElement to
- * compute the $M$ matrix:
+ * for more information.) With this, one can then use the following piece of
+ * code in the constructor of a class derived from FinitElement to compute the
+ * $M$ matrix:
* @code
* FullMatrix<double> M(this->dofs_per_cell, this->dofs_per_cell);
* FETools::compute_node_matrix(M, *this);
*
* <h5>Computing prolongation matrices</h5>
*
- * Once you have shape functions, you can define matrices that transfer
- * data from one cell to its children or the other way around. This is
- * a common operation in multigrid, of course, but is also used when
- * interpolating the solution from one mesh to another after mesh refinement,
- * as well as in the definition of some error estimators.
+ * Once you have shape functions, you can define matrices that transfer data
+ * from one cell to its children or the other way around. This is a common
+ * operation in multigrid, of course, but is also used when interpolating the
+ * solution from one mesh to another after mesh refinement, as well as in the
+ * definition of some error estimators.
*
- * To define the prolongation matrices, i.e., those matrices that
- * describe the transfer of a finite element field from one cell to
- * its children, implementations of finite elements can either
- * fill the #prolongation array by hand, or can call
- * FETools::compute_embedding_matrices().
+ * To define the prolongation matrices, i.e., those matrices that describe the
+ * transfer of a finite element field from one cell to its children,
+ * implementations of finite elements can either fill the #prolongation array
+ * by hand, or can call FETools::compute_embedding_matrices().
*
* In the latter case, all that is required is the following piece of code:
* @code
* FETools::compute_embedding_matrices (*this, this->prolongation);
* @endcode
* As in this example, prolongation is almost always implemented via
- * embedding, i.e., the nodal values of the function on the children
- * may be different from the nodal values of the function on the parent
- * cell, but as a function of $\mathbf x\in{\mathbb R}^\text{spacedim}$,
- * the finite element field on the child is the same as on the parent.
+ * embedding, i.e., the nodal values of the function on the children may be
+ * different from the nodal values of the function on the parent cell, but as
+ * a function of $\mathbf x\in{\mathbb R}^\text{spacedim}$, the finite element
+ * field on the child is the same as on the parent.
*
*
* <h5>Computing restriction matrices</h5>
*
- * The opposite operation, restricting a finite element function defined
- * on the children to the parent cell is typically implemented by
- * interpolating the finite element function on the children to the
- * nodal values of the parent cell. In deal.II, the restriction operation
- * is implemented as a loop over the children of a cell that each
- * apply a matrix to the vector of unknowns on that child cell
- * (these matrices are stored in #restriction and are accessed by
- * get_restriction_matrix()). The operation that then needs to be
- * implemented turns out to be surprisingly difficult to describe,
- * but is instructive to describe because it also defines the
- * meaning of the #restriction_is_additive_flags array
- * (accessed via the restriction_is_additive() function).
+ * The opposite operation, restricting a finite element function defined on
+ * the children to the parent cell is typically implemented by interpolating
+ * the finite element function on the children to the nodal values of the
+ * parent cell. In deal.II, the restriction operation is implemented as a loop
+ * over the children of a cell that each apply a matrix to the vector of
+ * unknowns on that child cell (these matrices are stored in #restriction and
+ * are accessed by get_restriction_matrix()). The operation that then needs to
+ * be implemented turns out to be surprisingly difficult to describe, but is
+ * instructive to describe because it also defines the meaning of the
+ * #restriction_is_additive_flags array (accessed via the
+ * restriction_is_additive() function).
*
- * To give a concrete example, assume we use a $Q_1$ element in 1d,
- * and that on each of the parent and child cells degrees of freedom
- * are (locally and globally) numbered as follows:
+ * To give a concrete example, assume we use a $Q_1$ element in 1d, and that
+ * on each of the parent and child cells degrees of freedom are (locally and
+ * globally) numbered as follows:
* @code
* meshes: *-------* *---*---*
* local DoF numbers: 0 1 0 1|0 1
* global DoF numbers: 0 1 0 1 2
* @endcode
- * Then we want the restriction operation to take the value of the
- * zeroth DoF on child 0 as the value of the zeroth DoF on the
- * parent, and take the value of the first DoF on child 1 as the
- * value of the first DoF on the parent. Ideally, we would like
- * to write this follows
+ * Then we want the restriction operation to take the value of the zeroth DoF
+ * on child 0 as the value of the zeroth DoF on the parent, and take the value
+ * of the first DoF on child 1 as the value of the first DoF on the parent.
+ * Ideally, we would like to write this follows
* @f[
* U^\text{coarse}|_\text{parent}
* = \sum_{\text{child}=0}^1 R_\text{child} U^\text{fine}|_\text{child}
* \qquad\qquad
* R_1 = \left(\begin{matrix}0 & 0 \\ 0 & 1\end{matrix}\right).
* @f]
- * However, this approach already fails if we go to a $Q_2$ element
- * with the following degrees of freedom:
+ * However, this approach already fails if we go to a $Q_2$ element with the
+ * following degrees of freedom:
* @code
* meshes: *-------* *----*----*
* local DoF numbers: 0 2 1 0 2 1|0 2 1
* global DoF numbers: 0 2 1 0 2 1 4 3
* @endcode
- * Writing things as the sum over matrix operations as above would not
- * easily work because we have to add nonzero values to $U^\text{coarse}_2$
- * twice, once for each child.
+ * Writing things as the sum over matrix operations as above would not easily
+ * work because we have to add nonzero values to $U^\text{coarse}_2$ twice,
+ * once for each child.
*
- * Consequently, restriction is typically implemented as a <i>concatenation</i>
- * operation. I.e., we first compute the individual restrictions from each
- * child,
+ * Consequently, restriction is typically implemented as a
+ * <i>concatenation</i> operation. I.e., we first compute the individual
+ * restrictions from each child,
* @f[
* \tilde U^\text{coarse}_\text{child}
* = R_\text{child} U^\text{fine}|_\text{child},
* @f]
- * and then compute the values of $U^\text{coarse}|_\text{parent}$ with
- * the following code:
+ * and then compute the values of $U^\text{coarse}|_\text{parent}$ with the
+ * following code:
* @code
* for (unsigned int child=0; child<cell->n_children(); ++child)
* for (unsigned int i=0; i<dofs_per_cell; ++i)
* if (U_tilde_coarse[child][i] != 0)
* U_coarse_on_parent[i] = U_tilde_coarse[child][i];
* @endcode
- * In other words, each nonzero element of $\tilde U^\text{coarse}_\text{child}$
- * <i>overwrites</i>, rather than adds to the corresponding element of
- * $U^\text{coarse}|_\text{parent}$. This typically also implies that
- * the restriction matrices from two different cells should agree on
- * a value for coarse degrees of freedom that they both want to touch (otherwise
- * the result would depend on the order in which we loop over children, which
- * would be unreasonable because the order of children is an otherwise
- * arbitrary convention). For example, in the example above, the
+ * In other words, each nonzero element of $\tilde
+ * U^\text{coarse}_\text{child}$ <i>overwrites</i>, rather than adds to the
+ * corresponding element of $U^\text{coarse}|_\text{parent}$. This typically
+ * also implies that the restriction matrices from two different cells should
+ * agree on a value for coarse degrees of freedom that they both want to touch
+ * (otherwise the result would depend on the order in which we loop over
+ * children, which would be unreasonable because the order of children is an
+ * otherwise arbitrary convention). For example, in the example above, the
* restriction matrices will be
* @f[
* R_0 = \left(\begin{matrix}1 & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 1 & 0 \end{matrix}\right),
* \qquad\qquad
* R_1 = \left(\begin{matrix}0 & 0 & 0 \\ 0 & 1 & 0 \\ 1 & 0 & 0 \end{matrix}\right),
* @f]
- * and the compatibility condition is the $R_{0,21}=R_{1,20}$ because they both
- * indicate that $U^\text{coarse}|_\text{parent,2}$ should be set to one times
- * $U^\text{fine}|_\text{child=0,1}$ and $U^\text{fine}|_\text{child=1,0}$.
+ * and the compatibility condition is the $R_{0,21}=R_{1,20}$ because they
+ * both indicate that $U^\text{coarse}|_\text{parent,2}$ should be set to one
+ * times $U^\text{fine}|_\text{child=0,1}$ and
+ * $U^\text{fine}|_\text{child=1,0}$.
*
- * Unfortunately, not all finite elements allow to write the restriction operation
- * in this way. For example, for the piecewise constant FE_DGQ(0) element, the
- * value of the finite element field on the parent cell can not be determined
- * by interpolation from the children. Rather, the only reasonable choice is to
- * take it as the <i>average</i> value between the children -- so we are back
- * to the sum operation, rather than the concatenation. Further thought shows that
- * whether restriction should be additive or not is a property of the individual
- * shape function, not of the finite element as a whole. Consequently, the
+ * Unfortunately, not all finite elements allow to write the restriction
+ * operation in this way. For example, for the piecewise constant FE_DGQ(0)
+ * element, the value of the finite element field on the parent cell can not
+ * be determined by interpolation from the children. Rather, the only
+ * reasonable choice is to take it as the <i>average</i> value between the
+ * children -- so we are back to the sum operation, rather than the
+ * concatenation. Further thought shows that whether restriction should be
+ * additive or not is a property of the individual shape function, not of the
+ * finite element as a whole. Consequently, the
* FiniteElement::restriction_is_additive() function returns whether a
- * particular shape function should act via concatenation (a return value
- * of @p false) or via addition (return value of @p true), and the correct
- * code for the overall operation is then as follows (and as, in fact,
- * implemented in DoFAccessor::get_interpolated_dof_values()):
+ * particular shape function should act via concatenation (a return value of
+ * @p false) or via addition (return value of @p true), and the correct code
+ * for the overall operation is then as follows (and as, in fact, implemented
+ * in DoFAccessor::get_interpolated_dof_values()):
* @code
* for (unsigned int child=0; child<cell->n_children(); ++child)
* for (unsigned int i=0; i<dofs_per_cell; ++i)
* FiniteElement::get_data() function. This object is then passed to the
* FiniteElement::fill_fe_values(), FiniteElement::fill_fe_face_values(),
* and FiniteElement::fill_fe_subface_values() functions as a constant
- * object. The intent of these objects is so that finite element classes
- * can pre-compute information once at the beginning (in the call to
- * FiniteElement::get_data() call) that can then be used on each cell
- * that is subsequently visited. An example for this is the values of
- * shape functions at the quadrature point of the reference cell,
- * which remain the same no matter the cell visited, and that can
- * therefore be computed once at the beginning and reused later on.
- *
- * Because only derived classes can know what they can pre-compute,
- * each derived class that wants to store information computed once
- * at the beginning, needs to derive its own InternalData class from
- * this class, and return an object of the derived type through its
- * get_data() function.
+ * object. The intent of these objects is so that finite element classes can
+ * pre-compute information once at the beginning (in the call to
+ * FiniteElement::get_data() call) that can then be used on each cell that
+ * is subsequently visited. An example for this is the values of shape
+ * functions at the quadrature point of the reference cell, which remain the
+ * same no matter the cell visited, and that can therefore be computed once
+ * at the beginning and reused later on.
+ *
+ * Because only derived classes can know what they can pre-compute, each
+ * derived class that wants to store information computed once at the
+ * beginning, needs to derive its own InternalData class from this class,
+ * and return an object of the derived type through its get_data() function.
*
* @author Guido Kanschat, 2001; Wolfgang Bangerth, 2015.
*/
virtual ~InternalDataBase ();
/**
- * A set of update flags specifying the kind of information that
- * an implementation of the FiniteElement interface needs to compute on
- * each cell or face, i.e., in FiniteElement::fill_fe_values() and
- * friends.
+ * A set of update flags specifying the kind of information that an
+ * implementation of the FiniteElement interface needs to compute on each
+ * cell or face, i.e., in FiniteElement::fill_fe_values() and friends.
*
* This set of flags is stored here by implementations of
* FiniteElement::get_data(), FiniteElement::get_face_data(), or
* FiniteElement::get_subface_data(), and is that subset of the update
- * flags passed to those functions that require re-computation on
- * every cell. (The subset of the flags corresponding to
- * information that can be computed once and for all already at
- * the time of the call to FiniteElement::get_data() -- or an
- * implementation of that interface -- need not be stored here
- * because it has already been taken care of.)
+ * flags passed to those functions that require re-computation on every
+ * cell. (The subset of the flags corresponding to information that can be
+ * computed once and for all already at the time of the call to
+ * FiniteElement::get_data() -- or an implementation of that interface --
+ * need not be stored here because it has already been taken care of.)
*/
UpdateFlags update_each;
* elements.
*
* @param[in] fe_data An object that stores identifying (typically integral)
- * information about the element to be constructed. In particular, this
- * object will contain data such as the number of degrees of freedom
- * per cell (and per vertex, line, etc), the number of vector components,
- * etc. This argument is used to initialize the base class of the current
- * object under construction.
+ * information about the element to be constructed. In particular, this
+ * object will contain data such as the number of degrees of freedom per
+ * cell (and per vertex, line, etc), the number of vector components, etc.
+ * This argument is used to initialize the base class of the current object
+ * under construction.
* @param[in] restriction_is_additive_flags A vector of size
- * <code>dofs_per_cell</code> (or of size one, see below) that for each
- * shape function states whether the shape function is additive or not. The
- * meaning of these flags is described in the section on restriction matrices
- * in the general documentation of this class.
- * @param[in] nonzero_components A vector of size
- * <code>dofs_per_cell</code> (or of size one, see below) that for each
- * shape function provides a ComponentMask (of size
- * <code>fe_data.n_components()</code>) that indicates in which vector
- * components this shape function is nonzero (after mapping the shape
- * function to the real cell). For "primitive" shape
- * functions, this component mask will have a single entry (see
- * @ref GlossPrimitive
- * for more information about primitive elements).
- * On the other hand, for elements such as the Raviart-Thomas or Nedelec
- * elements, shape functions are nonzero in more than one vector component
- * (after mapping to the real cell) and the given component mask will
- * contain more than one entry. (For these two elements, all entries
- * will in fact be set, but this would not be the case if you couple
- * a FE_RaviartThomas and a FE_Nedelec together into a FESystem.)
+ * <code>dofs_per_cell</code> (or of size one, see below) that for each
+ * shape function states whether the shape function is additive or not. The
+ * meaning of these flags is described in the section on restriction
+ * matrices in the general documentation of this class.
+ * @param[in] nonzero_components A vector of size <code>dofs_per_cell</code>
+ * (or of size one, see below) that for each shape function provides a
+ * ComponentMask (of size <code>fe_data.n_components()</code>) that
+ * indicates in which vector components this shape function is nonzero
+ * (after mapping the shape function to the real cell). For "primitive"
+ * shape functions, this component mask will have a single entry (see
+ * @ref GlossPrimitive
+ * for more information about primitive elements). On the other hand, for
+ * elements such as the Raviart-Thomas or Nedelec elements, shape functions
+ * are nonzero in more than one vector component (after mapping to the real
+ * cell) and the given component mask will contain more than one entry. (For
+ * these two elements, all entries will in fact be set, but this would not
+ * be the case if you couple a FE_RaviartThomas and a FE_Nedelec together
+ * into a FESystem.)
*
* @pre <code>restriction_is_additive_flags.size() == dofs_per_cell</code>,
- * or <code>restriction_is_additive_flags.size() == 1</code>. In the latter
- * case, the array is simply interpreted as having size
- * <code>dofs_per_cell</code> where each element has the same value as the
- * single element given.
+ * or <code>restriction_is_additive_flags.size() == 1</code>. In the latter
+ * case, the array is simply interpreted as having size
+ * <code>dofs_per_cell</code> where each element has the same value as the
+ * single element given.
*
- * @pre <code>nonzero_components.size() == dofs_per_cell</code>,
- * or <code>nonzero_components.size() == 1</code>. In the latter
- * case, the array is simply interpreted as having size
- * <code>dofs_per_cell</code> where each element equals the component
- * mask provided in the single element given.
+ * @pre <code>nonzero_components.size() == dofs_per_cell</code>, or
+ * <code>nonzero_components.size() == 1</code>. In the latter case, the
+ * array is simply interpreted as having size <code>dofs_per_cell</code>
+ * where each element equals the component mask provided in the single
+ * element given.
*/
FiniteElement (const FiniteElementData<dim> &fe_data,
const std::vector<bool> &restriction_is_additive_flags,
* shape_value_component() function.
*
* Implementations of this function should throw an exception of type
- * ExcUnitShapeValuesDoNotExist if the shape functions of the
- * FiniteElement under consideration depend on the shape of the cell in
- * real space, i.e., if the shape functions are not defined by
- * mapping from the reference cell. Some non-conforming elements are
- * defined this way, as is the FE_DGPNonparametric class, to name just
- * one example.
+ * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
+ * under consideration depend on the shape of the cell in real space, i.e.,
+ * if the shape functions are not defined by mapping from the reference
+ * cell. Some non-conforming elements are defined this way, as is the
+ * FE_DGPNonparametric class, to name just one example.
*
- * The default implementation of this virtual function does exactly
- * this, i.e., it simply throws an exception of type
- * ExcUnitShapeValuesDoNotExist.
+ * The default implementation of this virtual function does exactly this,
+ * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
*/
virtual double shape_value (const unsigned int i,
const Point<dim> &p) const;
* case, use the shape_grad_component() function.
*
* Implementations of this function should throw an exception of type
- * ExcUnitShapeValuesDoNotExist if the shape functions of the
- * FiniteElement under consideration depend on the shape of the cell in
- * real space, i.e., if the shape functions are not defined by
- * mapping from the reference cell. Some non-conforming elements are
- * defined this way, as is the FE_DGPNonparametric class, to name just
- * one example.
+ * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
+ * under consideration depend on the shape of the cell in real space, i.e.,
+ * if the shape functions are not defined by mapping from the reference
+ * cell. Some non-conforming elements are defined this way, as is the
+ * FE_DGPNonparametric class, to name just one example.
*
- * The default implementation of this virtual function does exactly
- * this, i.e., it simply throws an exception of type
- * ExcUnitShapeValuesDoNotExist.
+ * The default implementation of this virtual function does exactly this,
+ * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<1,dim> shape_grad (const unsigned int i,
const Point<dim> &p) const;
* shape_grad_grad_component() function.
*
* Implementations of this function should throw an exception of type
- * ExcUnitShapeValuesDoNotExist if the shape functions of the
- * FiniteElement under consideration depend on the shape of the cell in
- * real space, i.e., if the shape functions are not defined by
- * mapping from the reference cell. Some non-conforming elements are
- * defined this way, as is the FE_DGPNonparametric class, to name just
- * one example.
+ * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
+ * under consideration depend on the shape of the cell in real space, i.e.,
+ * if the shape functions are not defined by mapping from the reference
+ * cell. Some non-conforming elements are defined this way, as is the
+ * FE_DGPNonparametric class, to name just one example.
*
- * The default implementation of this virtual function does exactly
- * this, i.e., it simply throws an exception of type
- * ExcUnitShapeValuesDoNotExist.
+ * The default implementation of this virtual function does exactly this,
+ * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
const Point<dim> &p) const;
* shape_3rd_derivative_component() function.
*
* Implementations of this function should throw an exception of type
- * ExcUnitShapeValuesDoNotExist if the shape functions of the
- * FiniteElement under consideration depend on the shape of the cell in
- * real space, i.e., if the shape functions are not defined by
- * mapping from the reference cell. Some non-conforming elements are
- * defined this way, as is the FE_DGPNonparametric class, to name just
- * one example.
+ * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
+ * under consideration depend on the shape of the cell in real space, i.e.,
+ * if the shape functions are not defined by mapping from the reference
+ * cell. Some non-conforming elements are defined this way, as is the
+ * FE_DGPNonparametric class, to name just one example.
*
- * The default implementation of this virtual function does exactly
- * this, i.e., it simply throws an exception of type
- * ExcUnitShapeValuesDoNotExist.
+ * The default implementation of this virtual function does exactly this,
+ * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<3,dim> shape_3rd_derivative (const unsigned int i,
const Point<dim> &p) const;
/**
- * Just like for shape_3rd_derivative(), but this function will be called when
- * the shape function has more than one non-zero vector component. In that
- * case, this function should return the gradient of the @p component-th
- * vector component of the @p ith shape function at point @p p.
+ * Just like for shape_3rd_derivative(), but this function will be called
+ * when the shape function has more than one non-zero vector component. In
+ * that case, this function should return the gradient of the @p component-
+ * th vector component of the @p ith shape function at point @p p.
*/
virtual Tensor<3,dim> shape_3rd_derivative_component (const unsigned int i,
const Point<dim> &p,
* shape_4th_derivative_component() function.
*
* Implementations of this function should throw an exception of type
- * ExcUnitShapeValuesDoNotExist if the shape functions of the
- * FiniteElement under consideration depend on the shape of the cell in
- * real space, i.e., if the shape functions are not defined by
- * mapping from the reference cell. Some non-conforming elements are
- * defined this way, as is the FE_DGPNonparametric class, to name just
- * one example.
+ * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
+ * under consideration depend on the shape of the cell in real space, i.e.,
+ * if the shape functions are not defined by mapping from the reference
+ * cell. Some non-conforming elements are defined this way, as is the
+ * FE_DGPNonparametric class, to name just one example.
*
- * The default implementation of this virtual function does exactly
- * this, i.e., it simply throws an exception of type
- * ExcUnitShapeValuesDoNotExist.
+ * The default implementation of this virtual function does exactly this,
+ * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<4,dim> shape_4th_derivative (const unsigned int i,
const Point<dim> &p) const;
/**
- * Just like for shape_4th_derivative(), but this function will be called when
- * the shape function has more than one non-zero vector component. In that
- * case, this function should return the gradient of the @p component-th
- * vector component of the @p ith shape function at point @p p.
+ * Just like for shape_4th_derivative(), but this function will be called
+ * when the shape function has more than one non-zero vector component. In
+ * that case, this function should return the gradient of the @p component-
+ * th vector component of the @p ith shape function at point @p p.
*/
virtual Tensor<4,dim> shape_4th_derivative_component (const unsigned int i,
const Point<dim> &p,
*/
/**
- * Return the matrix that describes restricting a finite element
- * field from the given @p child (as obtained by the given
- * @p refinement_case) to the parent cell. The interpretation of
- * the returned matrix depends on what
+ * Return the matrix that describes restricting a finite element field from
+ * the given @p child (as obtained by the given @p refinement_case) to the
+ * parent cell. The interpretation of the returned matrix depends on what
* restriction_is_additive() returns for each shape function.
*
* Row and column indices are related to coarse grid and fine grid spaces,
*
* If projection matrices are not implemented in the derived finite element
* class, this function aborts with an exception of type
- * FiniteElement::ExcProjectionVoid. You can check whether
- * this would happen by first calling the restriction_is_implemented() or the
+ * FiniteElement::ExcProjectionVoid. You can check whether this would happen
+ * by first calling the restriction_is_implemented() or the
* isotropic_restriction_is_implemented() function.
*/
virtual const FullMatrix<double> &
/**
* Prolongation/embedding matrix between grids.
*
- * The identity operator from a coarse grid space into a fine grid space (where
- * both spaces are identified as functions defined on the parent and child cells) is
- * associated with a matrix @p P that maps the corresponding representations
- * of these functions in terms of their nodal values. The restriction of this matrix
- * @p P_i to a single child cell is returned here.
+ * The identity operator from a coarse grid space into a fine grid space
+ * (where both spaces are identified as functions defined on the parent and
+ * child cells) is associated with a matrix @p P that maps the corresponding
+ * representations of these functions in terms of their nodal values. The
+ * restriction of this matrix @p P_i to a single child cell is returned
+ * here.
*
* The matrix @p P is the concatenation, not the sum of the cell matrices @p
* P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in in two
* cells using this matrix array, zero elements in the prolongation matrix
* are discarded and will not fill up the transfer matrix.
*
- * If prolongation matrices are not implemented in the derived finite element
- * class, this function aborts with an exception of type
- * FiniteElement::ExcEmbeddingVoid. You can check whether
- * this would happen by first calling the prolongation_is_implemented() or the
+ * If prolongation matrices are not implemented in the derived finite
+ * element class, this function aborts with an exception of type
+ * FiniteElement::ExcEmbeddingVoid. You can check whether this would happen
+ * by first calling the prolongation_is_implemented() or the
* isotropic_prolongation_is_implemented() function.
*/
virtual const FullMatrix<double> &
/**
- * Access the #restriction_is_additive_flags field. See the discussion
- * about restriction matrices in the general class documentation for
- * more information.
+ * Access the #restriction_is_additive_flags field. See the discussion about
+ * restriction matrices in the general class documentation for more
+ * information.
*
* The index must be between zero and the number of shape functions of this
* element.
*
* @note This function is implemented in FiniteElement for the case that the
* element has support points. In this case, the resulting coefficients are
- * just the values in the support points. All other elements must reimplement
- * it.
+ * just the values in the support points. All other elements must
+ * reimplement it.
*/
virtual
void
* can be in (all combinations of the three bool flags face_orientation,
* face_flip and face_rotation).
*
- * The standard implementation fills this with zeros, i.e. no permutation
- * at all. Derived finite element classes have to fill this Table with the
+ * The standard implementation fills this with zeros, i.e. no permutation at
+ * all. Derived finite element classes have to fill this Table with the
* correct values.
*/
Table<2,int> adjust_quad_dof_index_for_face_orientation_table;
component_to_base_table;
/**
- * A flag determining whether restriction matrices are to be concatenated
- * or summed up. See the discussion about restriction matrices in the
- * general class documentation for more information.
+ * A flag determining whether restriction matrices are to be concatenated or
+ * summed up. See the discussion about restriction matrices in the general
+ * class documentation for more information.
*/
const std::vector<bool> restriction_is_additive_flags;
/**
* Given a set of update flags, compute which other quantities <i>also</i>
* need to be computed in order to satisfy the request by the given flags.
- * Then return the combination of the original set of flags and those
- * just computed.
- *
- * As an example, if @p update_flags contains update_gradients
- * a finite element class will typically
- * require the computation of the inverse of the Jacobian matrix in order to
- * rotate the gradient of shape functions on the reference cell to the
- * real cell. It would then return not just
+ * Then return the combination of the original set of flags and those just
+ * computed.
+ *
+ * As an example, if @p update_flags contains update_gradients a finite
+ * element class will typically require the computation of the inverse of
+ * the Jacobian matrix in order to rotate the gradient of shape functions on
+ * the reference cell to the real cell. It would then return not just
* update_gradients, but also update_covariant_transformation, the flag that
* makes the mapping class produce the inverse of the Jacobian matrix.
*
* An extensive discussion of the interaction between this function and
* FEValues can be found in the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module.
+ * documentation module.
*
* @see UpdateFlags
*/
/**
* Create an internal data object and return a pointer to it of which the
- * caller of this function then assumes ownership. This object will
- * then be passed to the FiniteElement::fill_fe_values() every time
- * the finite element shape functions and their derivatives are evaluated
- * on a concrete cell. The object created here is therefore used by
- * derived classes as a place for scratch objects that are used in
- * evaluating shape functions, as well as to store information that
- * can be pre-computed once and re-used on every cell (e.g., for
- * evaluating the values and gradients of shape functions on the
- * reference cell, for later re-use when transforming these values to
- * a concrete cell).
- *
- * This function is the first one called in the process of initializing
- * a FEValues object for a given mapping and finite element object. The
+ * caller of this function then assumes ownership. This object will then be
+ * passed to the FiniteElement::fill_fe_values() every time the finite
+ * element shape functions and their derivatives are evaluated on a concrete
+ * cell. The object created here is therefore used by derived classes as a
+ * place for scratch objects that are used in evaluating shape functions, as
+ * well as to store information that can be pre-computed once and re-used on
+ * every cell (e.g., for evaluating the values and gradients of shape
+ * functions on the reference cell, for later re-use when transforming these
+ * values to a concrete cell).
+ *
+ * This function is the first one called in the process of initializing a
+ * FEValues object for a given mapping and finite element object. The
* returned object will later be passed to FiniteElement::fill_fe_values()
- * for a concrete cell, which will itself place its output into an object
- * of type internal::FEValues::FiniteElementRelatedData. Since there may
- * be data that can already be computed in its <i>final</i> form on the
+ * for a concrete cell, which will itself place its output into an object of
+ * type internal::FEValues::FiniteElementRelatedData. Since there may be
+ * data that can already be computed in its <i>final</i> form on the
* reference cell, this function also receives a reference to the
* internal::FEValues::FiniteElementRelatedData object as its last argument.
* This output argument is guaranteed to always be the same one when used
* with the InternalDataBase object returned by this function. In other
* words, the subdivision of scratch data and final data in the returned
- * object and the @p output_data object is as follows: If data can be
- * pre-computed on the reference cell in the exact form in which it
- * will later be needed on a concrete cell, then this function should
- * already emplace it in the @p output_data object. An example are the
- * values of shape functions at quadrature points for the usual
- * Lagrange elements which on a concrete cell are identical to the
- * ones on the reference cell. On the other hand, if some data can
- * be pre-computed to make computations on a concrete cell <i>cheaper</i>,
- * then it should be put into the returned object for later re-use
- * in a derive class's implementation of FiniteElement::fill_fe_values().
- * An example are the gradients of shape functions on the reference
- * cell for Lagrange elements: to compute the gradients of the shape
- * functions on a concrete cell, one has to multiply the gradients on
- * the reference cell by the inverse of the Jacobian of the mapping;
- * consequently, we cannot already compute the gradients on a concrete
- * cell at the time the current function is called, but we can at least
- * pre-compute the gradients on the reference cell, and store it
- * in the object returned.
+ * object and the @p output_data object is as follows: If data can be pre-
+ * computed on the reference cell in the exact form in which it will later
+ * be needed on a concrete cell, then this function should already emplace
+ * it in the @p output_data object. An example are the values of shape
+ * functions at quadrature points for the usual Lagrange elements which on a
+ * concrete cell are identical to the ones on the reference cell. On the
+ * other hand, if some data can be pre-computed to make computations on a
+ * concrete cell <i>cheaper</i>, then it should be put into the returned
+ * object for later re-use in a derive class's implementation of
+ * FiniteElement::fill_fe_values(). An example are the gradients of shape
+ * functions on the reference cell for Lagrange elements: to compute the
+ * gradients of the shape functions on a concrete cell, one has to multiply
+ * the gradients on the reference cell by the inverse of the Jacobian of the
+ * mapping; consequently, we cannot already compute the gradients on a
+ * concrete cell at the time the current function is called, but we can at
+ * least pre-compute the gradients on the reference cell, and store it in
+ * the object returned.
*
* An extensive discussion of the interaction between this function and
* FEValues can be found in the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module. See also the documentation of the InternalDataBase class.
- *
- * @param[in] update_flags A set of UpdateFlags values that describe
- * what kind of information the FEValues object requests the finite
- * element to compute. This set of flags may also include information
- * that the finite element can not compute, e.g., flags that pertain
- * to data produced by the mapping. An implementation of this function
- * needs to set up all data fields in the returned object that are
- * necessary to produce the finite-element related data specified by
- * these flags, and may already pre-compute part of this information
- * as discussed above. Elements may want to store these update flags
- * (or a subset of these flags) in InternalDataBase::update_each so
- * they know at the time when FinitElement::fill_fe_values() is called
- * what they are supposed to compute
- * @param[in] mapping A reference to the mapping used for computing
- * values and derivatives of shape functions.
- * @param[in] quadrature A reference to the object that describes where
- * the shape functions should be evaluated.
- * @param[out] output_data A reference to the object that FEValues
- * will use in conjunction with the object returned here and where
- * an implementation of FiniteElement::fill_fe_values() will place
- * the requested information. This allows the current function
- * to already pre-compute pieces of information that can be computed
- * on the reference cell, as discussed above. FEValues guarantees
- * that this output object and the object returned by the current
- * function will always be used together.
+ * documentation module. See also the documentation of the InternalDataBase
+ * class.
+ *
+ * @param[in] update_flags A set of UpdateFlags values that describe what
+ * kind of information the FEValues object requests the finite element to
+ * compute. This set of flags may also include information that the finite
+ * element can not compute, e.g., flags that pertain to data produced by the
+ * mapping. An implementation of this function needs to set up all data
+ * fields in the returned object that are necessary to produce the finite-
+ * element related data specified by these flags, and may already pre-
+ * compute part of this information as discussed above. Elements may want to
+ * store these update flags (or a subset of these flags) in
+ * InternalDataBase::update_each so they know at the time when
+ * FinitElement::fill_fe_values() is called what they are supposed to
+ * compute
+ * @param[in] mapping A reference to the mapping used for computing values
+ * and derivatives of shape functions.
+ * @param[in] quadrature A reference to the object that describes where the
+ * shape functions should be evaluated.
+ * @param[out] output_data A reference to the object that FEValues will use
+ * in conjunction with the object returned here and where an implementation
+ * of FiniteElement::fill_fe_values() will place the requested information.
+ * This allows the current function to already pre-compute pieces of
+ * information that can be computed on the reference cell, as discussed
+ * above. FEValues guarantees that this output object and the object
+ * returned by the current function will always be used together.
* @return A pointer to an object of a type derived from InternalDataBase
- * and that derived classes can use to store scratch data that can
- * be pre-computed, or for scratch arrays that then only need to
- * be allocated once. The calling site assumes ownership of this
- * object and will delete it when it is no longer necessary.
+ * and that derived classes can use to store scratch data that can be pre-
+ * computed, or for scratch arrays that then only need to be allocated once.
+ * The calling site assumes ownership of this object and will delete it when
+ * it is no longer necessary.
*/
virtual
InternalDataBase *
/**
* Like get_data(), but return an object that will later be used for
- * evaluating shape function information at quadrature points on faces
- * of cells. The object will then be used in calls to implementations of
+ * evaluating shape function information at quadrature points on faces of
+ * cells. The object will then be used in calls to implementations of
* FiniteElement::fill_fe_face_values(). See the documentation of get_data()
* for more information.
*
* The default implementation of this function converts the face quadrature
- * into a cell quadrature with appropriate quadrature point locations,
- * and with that calls the get_data() function above that has to be
- * implemented in derived classes.
- *
- * @param[in] update_flags A set of UpdateFlags values that describe
- * what kind of information the FEValues object requests the finite
- * element to compute. This set of flags may also include information
- * that the finite element can not compute, e.g., flags that pertain
- * to data produced by the mapping. An implementation of this function
- * needs to set up all data fields in the returned object that are
- * necessary to produce the finite-element related data specified by
- * these flags, and may already pre-compute part of this information
- * as discussed above. Elements may want to store these update flags
- * (or a subset of these flags) in InternalDataBase::update_each so
- * they know at the time when FinitElement::fill_fe_face_values() is called
- * what they are supposed to compute
- * @param[in] mapping A reference to the mapping used for computing
- * values and derivatives of shape functions.
- * @param[in] quadrature A reference to the object that describes where
- * the shape functions should be evaluated.
- * @param[out] output_data A reference to the object that FEValues
- * will use in conjunction with the object returned here and where
- * an implementation of FiniteElement::fill_fe_face_values() will place
- * the requested information. This allows the current function
- * to already pre-compute pieces of information that can be computed
- * on the reference cell, as discussed above. FEValues guarantees
- * that this output object and the object returned by the current
- * function will always be used together.
+ * into a cell quadrature with appropriate quadrature point locations, and
+ * with that calls the get_data() function above that has to be implemented
+ * in derived classes.
+ *
+ * @param[in] update_flags A set of UpdateFlags values that describe what
+ * kind of information the FEValues object requests the finite element to
+ * compute. This set of flags may also include information that the finite
+ * element can not compute, e.g., flags that pertain to data produced by the
+ * mapping. An implementation of this function needs to set up all data
+ * fields in the returned object that are necessary to produce the finite-
+ * element related data specified by these flags, and may already pre-
+ * compute part of this information as discussed above. Elements may want to
+ * store these update flags (or a subset of these flags) in
+ * InternalDataBase::update_each so they know at the time when
+ * FinitElement::fill_fe_face_values() is called what they are supposed to
+ * compute
+ * @param[in] mapping A reference to the mapping used for computing values
+ * and derivatives of shape functions.
+ * @param[in] quadrature A reference to the object that describes where the
+ * shape functions should be evaluated.
+ * @param[out] output_data A reference to the object that FEValues will use
+ * in conjunction with the object returned here and where an implementation
+ * of FiniteElement::fill_fe_face_values() will place the requested
+ * information. This allows the current function to already pre-compute
+ * pieces of information that can be computed on the reference cell, as
+ * discussed above. FEValues guarantees that this output object and the
+ * object returned by the current function will always be used together.
* @return A pointer to an object of a type derived from InternalDataBase
- * and that derived classes can use to store scratch data that can
- * be pre-computed, or for scratch arrays that then only need to
- * be allocated once. The calling site assumes ownership of this
- * object and will delete it when it is no longer necessary.
+ * and that derived classes can use to store scratch data that can be pre-
+ * computed, or for scratch arrays that then only need to be allocated once.
+ * The calling site assumes ownership of this object and will delete it when
+ * it is no longer necessary.
*/
virtual
InternalDataBase *
/**
* Like get_data(), but return an object that will later be used for
- * evaluating shape function information at quadrature points on children
- * of faces of cells. The object will then be used in calls to
- * implementations of FiniteElement::fill_fe_subface_values(). See the
- * documentation of get_data() for more information.
+ * evaluating shape function information at quadrature points on children of
+ * faces of cells. The object will then be used in calls to implementations
+ * of FiniteElement::fill_fe_subface_values(). See the documentation of
+ * get_data() for more information.
*
* The default implementation of this function converts the face quadrature
- * into a cell quadrature with appropriate quadrature point locations,
- * and with that calls the get_data() function above that has to be
- * implemented in derived classes.
- *
- * @param[in] update_flags A set of UpdateFlags values that describe
- * what kind of information the FEValues object requests the finite
- * element to compute. This set of flags may also include information
- * that the finite element can not compute, e.g., flags that pertain
- * to data produced by the mapping. An implementation of this function
- * needs to set up all data fields in the returned object that are
- * necessary to produce the finite-element related data specified by
- * these flags, and may already pre-compute part of this information
- * as discussed above. Elements may want to store these update flags
- * (or a subset of these flags) in InternalDataBase::update_each so
- * they know at the time when FinitElement::fill_fe_subface_values()
- * is called what they are supposed to compute
- * @param[in] mapping A reference to the mapping used for computing
- * values and derivatives of shape functions.
- * @param[in] quadrature A reference to the object that describes where
- * the shape functions should be evaluated.
- * @param[out] output_data A reference to the object that FEValues
- * will use in conjunction with the object returned here and where
- * an implementation of FiniteElement::fill_fe_subface_values() will place
- * the requested information. This allows the current function
- * to already pre-compute pieces of information that can be computed
- * on the reference cell, as discussed above. FEValues guarantees
- * that this output object and the object returned by the current
- * function will always be used together.
+ * into a cell quadrature with appropriate quadrature point locations, and
+ * with that calls the get_data() function above that has to be implemented
+ * in derived classes.
+ *
+ * @param[in] update_flags A set of UpdateFlags values that describe what
+ * kind of information the FEValues object requests the finite element to
+ * compute. This set of flags may also include information that the finite
+ * element can not compute, e.g., flags that pertain to data produced by the
+ * mapping. An implementation of this function needs to set up all data
+ * fields in the returned object that are necessary to produce the finite-
+ * element related data specified by these flags, and may already pre-
+ * compute part of this information as discussed above. Elements may want to
+ * store these update flags (or a subset of these flags) in
+ * InternalDataBase::update_each so they know at the time when
+ * FinitElement::fill_fe_subface_values() is called what they are supposed
+ * to compute
+ * @param[in] mapping A reference to the mapping used for computing values
+ * and derivatives of shape functions.
+ * @param[in] quadrature A reference to the object that describes where the
+ * shape functions should be evaluated.
+ * @param[out] output_data A reference to the object that FEValues will use
+ * in conjunction with the object returned here and where an implementation
+ * of FiniteElement::fill_fe_subface_values() will place the requested
+ * information. This allows the current function to already pre-compute
+ * pieces of information that can be computed on the reference cell, as
+ * discussed above. FEValues guarantees that this output object and the
+ * object returned by the current function will always be used together.
* @return A pointer to an object of a type derived from InternalDataBase
- * and that derived classes can use to store scratch data that can
- * be pre-computed, or for scratch arrays that then only need to
- * be allocated once. The calling site assumes ownership of this
- * object and will delete it when it is no longer necessary.
+ * and that derived classes can use to store scratch data that can be pre-
+ * computed, or for scratch arrays that then only need to be allocated once.
+ * The calling site assumes ownership of this object and will delete it when
+ * it is no longer necessary.
*/
virtual
InternalDataBase *
dealii::internal::FEValues::FiniteElementRelatedData<dim, spacedim> &output_data) const;
/**
- * Compute information about the shape functions on the cell denoted
- * by the first argument. Derived classes will have to implement this
- * function based on the kind of element they represent. It is called
- * by FEValues::reinit().
+ * Compute information about the shape functions on the cell denoted by the
+ * first argument. Derived classes will have to implement this function
+ * based on the kind of element they represent. It is called by
+ * FEValues::reinit().
*
* Conceptually, this function evaluates shape functions and their
- * derivatives at the quadrature points represented by the mapped
- * locations of those described by the quadrature argument to this
- * function. In many cases, computing derivatives of shape functions
- * (and in some cases also computing values of shape functions)
- * requires making use of the mapping from the reference to the real
- * cell; this information can either be taken from the @p mapping_data
- * object that has been filled for the current cell before this
- * function is called, or by calling the member functions of a
- * Mapping object with the @p mapping_internal object that also
- * corresponds to the current cell.
+ * derivatives at the quadrature points represented by the mapped locations
+ * of those described by the quadrature argument to this function. In many
+ * cases, computing derivatives of shape functions (and in some cases also
+ * computing values of shape functions) requires making use of the mapping
+ * from the reference to the real cell; this information can either be taken
+ * from the @p mapping_data object that has been filled for the current cell
+ * before this function is called, or by calling the member functions of a
+ * Mapping object with the @p mapping_internal object that also corresponds
+ * to the current cell.
*
* The information computed by this function is used to fill the various
- * member variables of the output argument of this function. Which of
- * the member variables of that structure should be filled is determined
- * by the update flags stored in the
- * FiniteElement::InternalDataBase::update_each field of the object
- * passed to this function. These flags are typically set by
- * FiniteElement::get_data(), FiniteElement::get_face_date() and
+ * member variables of the output argument of this function. Which of the
+ * member variables of that structure should be filled is determined by the
+ * update flags stored in the FiniteElement::InternalDataBase::update_each
+ * field of the object passed to this function. These flags are typically
+ * set by FiniteElement::get_data(), FiniteElement::get_face_date() and
* FiniteElement::get_subface_data() (or, more specifically, implementations
* of these functions in derived classes).
*
* @ref FE_vs_Mapping_vs_FEValues
* documentation module.
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] cell_similarity Whether or not the cell given as first
- * argument is simply a translation, rotation, etc of the cell for
- * which this function was called the most recent time. This
- * information is computed simply by matching the vertices (as stored
- * by the Triangulation) between the previous and the current cell.
- * The value passed here may be modified by implementations of
- * this function and should then be returned (see the discussion of the
- * return value of this function).
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * current object is then responsible for evaluating shape functions
- * at the mapped locations of the quadrature points represented by
- * this object.
- * @param[in] mapping A reference to the mapping object used to map
- * from the reference cell to the current cell. This object was used
- * to compute the information in the @p mapping_data object before the
- * current function was called. It is also the mapping object that
- * created the @p mapping_internal object via Mapping::get_data().
- * You will need the reference to this mapping object most often
- * to call Mapping::transform() to transform gradients and
- * higher derivatives from the reference to the current cell.
- * @param[in] mapping_internal An object specific to the mapping
- * object. What the mapping chooses to store in there is of no
- * relevance to the current function, but you may have to pass
- * a reference to this object to certain functions of the
- * Mapping class (e.g., Mapping::transform()) if you need to
- * call them from the current function.
+ * argument is simply a translation, rotation, etc of the cell for which
+ * this function was called the most recent time. This information is
+ * computed simply by matching the vertices (as stored by the Triangulation)
+ * between the previous and the current cell. The value passed here may be
+ * modified by implementations of this function and should then be returned
+ * (see the discussion of the return value of this function).
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The current object is
+ * then responsible for evaluating shape functions at the mapped locations
+ * of the quadrature points represented by this object.
+ * @param[in] mapping A reference to the mapping object used to map from the
+ * reference cell to the current cell. This object was used to compute the
+ * information in the @p mapping_data object before the current function was
+ * called. It is also the mapping object that created the @p
+ * mapping_internal object via Mapping::get_data(). You will need the
+ * reference to this mapping object most often to call Mapping::transform()
+ * to transform gradients and higher derivatives from the reference to the
+ * current cell.
+ * @param[in] mapping_internal An object specific to the mapping object.
+ * What the mapping chooses to store in there is of no relevance to the
+ * current function, but you may have to pass a reference to this object to
+ * certain functions of the Mapping class (e.g., Mapping::transform()) if
+ * you need to call them from the current function.
* @param[in] mapping_data The output object into which the
- * Mapping::fill_fe_values() function wrote the mapping information
- * corresponding to the current cell. This includes, for example,
- * Jacobians of the mapping that may be of relevance to the
- * current function, as well as other information that FEValues::reinit()
- * requested from the mapping.
- * @param[in] fe_internal A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the FiniteElement::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p fe_internal object.
- *
- * @note FEValues ensures that this function is always called with
- * the same pair of @p fe_internal and @p output_data objects. In
- * other words, if an implementation of this function knows that it
- * has written a piece of data into the output argument in a previous
- * call, then there is no need to copy it there again in a later
- * call if the implementation knows that this is the same value.
+ * Mapping::fill_fe_values() function wrote the mapping information
+ * corresponding to the current cell. This includes, for example, Jacobians
+ * of the mapping that may be of relevance to the current function, as well
+ * as other information that FEValues::reinit() requested from the mapping.
+ * @param[in] fe_internal A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * FiniteElement::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p fe_internal object.
+ *
+ * @note FEValues ensures that this function is always called with the same
+ * pair of @p fe_internal and @p output_data objects. In other words, if an
+ * implementation of this function knows that it has written a piece of data
+ * into the output argument in a previous call, then there is no need to
+ * copy it there again in a later call if the implementation knows that this
+ * is the same value.
*/
virtual
void
dealii::internal::FEValues::FiniteElementRelatedData<dim, spacedim> &output_data) const = 0;
/**
- * This function is the equivalent to FiniteElement::fill_fe_values(),
- * but for faces of cells. See there for an extensive discussion
- * of its purpose. It is called by FEFaceValues::reinit().
+ * This function is the equivalent to FiniteElement::fill_fe_values(), but
+ * for faces of cells. See there for an extensive discussion of its purpose.
+ * It is called by FEFaceValues::reinit().
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] face_no The number of the face we are currently considering,
- * indexed among the faces of the cell specified by the previous argument.
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * current object is then responsible for evaluating shape functions
- * at the mapped locations of the quadrature points represented by
- * this object.
- * @param[in] mapping A reference to the mapping object used to map
- * from the reference cell to the current cell. This object was used
- * to compute the information in the @p mapping_data object before the
- * current function was called. It is also the mapping object that
- * created the @p mapping_internal object via Mapping::get_data().
- * You will need the reference to this mapping object most often
- * to call Mapping::transform() to transform gradients and
- * higher derivatives from the reference to the current cell.
- * @param[in] mapping_internal An object specific to the mapping
- * object. What the mapping chooses to store in there is of no
- * relevance to the current function, but you may have to pass
- * a reference to this object to certain functions of the
- * Mapping class (e.g., Mapping::transform()) if you need to
- * call them from the current function.
+ * indexed among the faces of the cell specified by the previous argument.
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The current object is
+ * then responsible for evaluating shape functions at the mapped locations
+ * of the quadrature points represented by this object.
+ * @param[in] mapping A reference to the mapping object used to map from the
+ * reference cell to the current cell. This object was used to compute the
+ * information in the @p mapping_data object before the current function was
+ * called. It is also the mapping object that created the @p
+ * mapping_internal object via Mapping::get_data(). You will need the
+ * reference to this mapping object most often to call Mapping::transform()
+ * to transform gradients and higher derivatives from the reference to the
+ * current cell.
+ * @param[in] mapping_internal An object specific to the mapping object.
+ * What the mapping chooses to store in there is of no relevance to the
+ * current function, but you may have to pass a reference to this object to
+ * certain functions of the Mapping class (e.g., Mapping::transform()) if
+ * you need to call them from the current function.
* @param[in] mapping_data The output object into which the
- * Mapping::fill_fe_values() function wrote the mapping information
- * corresponding to the current cell. This includes, for example,
- * Jacobians of the mapping that may be of relevance to the
- * current function, as well as other information that FEValues::reinit()
- * requested from the mapping.
- * @param[in] fe_internal A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the FiniteElement::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p fe_internal object.
+ * Mapping::fill_fe_values() function wrote the mapping information
+ * corresponding to the current cell. This includes, for example, Jacobians
+ * of the mapping that may be of relevance to the current function, as well
+ * as other information that FEValues::reinit() requested from the mapping.
+ * @param[in] fe_internal A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * FiniteElement::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p fe_internal object.
*/
virtual
void
dealii::internal::FEValues::FiniteElementRelatedData<dim, spacedim> &output_data) const = 0;
/**
- * This function is the equivalent to FiniteElement::fill_fe_values(),
- * but for the children of faces of cells. See there for an extensive
- * discussion of its purpose. It is called by FESubfaceValues::reinit().
+ * This function is the equivalent to FiniteElement::fill_fe_values(), but
+ * for the children of faces of cells. See there for an extensive discussion
+ * of its purpose. It is called by FESubfaceValues::reinit().
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] face_no The number of the face we are currently considering,
- * indexed among the faces of the cell specified by the previous argument.
- * @param[in] sub_no The number of the subface, i.e., the number of the child
- * of a face, that we are currently considering,
- * indexed among the children of the face specified by the previous
- * argument.
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * current object is then responsible for evaluating shape functions
- * at the mapped locations of the quadrature points represented by
- * this object.
- * @param[in] mapping A reference to the mapping object used to map
- * from the reference cell to the current cell. This object was used
- * to compute the information in the @p mapping_data object before the
- * current function was called. It is also the mapping object that
- * created the @p mapping_internal object via Mapping::get_data().
- * You will need the reference to this mapping object most often
- * to call Mapping::transform() to transform gradients and
- * higher derivatives from the reference to the current cell.
- * @param[in] mapping_internal An object specific to the mapping
- * object. What the mapping chooses to store in there is of no
- * relevance to the current function, but you may have to pass
- * a reference to this object to certain functions of the
- * Mapping class (e.g., Mapping::transform()) if you need to
- * call them from the current function.
+ * indexed among the faces of the cell specified by the previous argument.
+ * @param[in] sub_no The number of the subface, i.e., the number of the
+ * child of a face, that we are currently considering, indexed among the
+ * children of the face specified by the previous argument.
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The current object is
+ * then responsible for evaluating shape functions at the mapped locations
+ * of the quadrature points represented by this object.
+ * @param[in] mapping A reference to the mapping object used to map from the
+ * reference cell to the current cell. This object was used to compute the
+ * information in the @p mapping_data object before the current function was
+ * called. It is also the mapping object that created the @p
+ * mapping_internal object via Mapping::get_data(). You will need the
+ * reference to this mapping object most often to call Mapping::transform()
+ * to transform gradients and higher derivatives from the reference to the
+ * current cell.
+ * @param[in] mapping_internal An object specific to the mapping object.
+ * What the mapping chooses to store in there is of no relevance to the
+ * current function, but you may have to pass a reference to this object to
+ * certain functions of the Mapping class (e.g., Mapping::transform()) if
+ * you need to call them from the current function.
* @param[in] mapping_data The output object into which the
- * Mapping::fill_fe_values() function wrote the mapping information
- * corresponding to the current cell. This includes, for example,
- * Jacobians of the mapping that may be of relevance to the
- * current function, as well as other information that FEValues::reinit()
- * requested from the mapping.
- * @param[in] fe_internal A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the FiniteElement::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p fe_internal object.
+ * Mapping::fill_fe_values() function wrote the mapping information
+ * corresponding to the current cell. This includes, for example, Jacobians
+ * of the mapping that may be of relevance to the current function, as well
+ * as other information that FEValues::reinit() requested from the mapping.
+ * @param[in] fe_internal A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * FiniteElement::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p fe_internal object.
*/
virtual
void
/**
* A class that declares a number of scalar constant variables that describe
* basic properties of a finite element implementation. This includes, for
- * example, the number of degrees of freedom per vertex, line, or cell;
- * the number of vector components; etc.
+ * example, the number of degrees of freedom per vertex, line, or cell; the
+ * number of vector components; etc.
*
- * The kind of information stored here is computed during initialization
- * of a finite element object and is passed down to this class via its
- * constructor. The data stored by this class is part of the public
- * interface of the FiniteElement class (which derives from the current
- * class). See there for more information.
+ * The kind of information stored here is computed during initialization of a
+ * finite element object and is passed down to this class via its constructor.
+ * The data stored by this class is part of the public interface of the
+ * FiniteElement class (which derives from the current class). See there for
+ * more information.
*
* @ingroup febase
* @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2001, 2003,
* Constructor, computing all necessary values from the distribution of dofs
* to geometrical objects.
*
- * @param[in] dofs_per_object A vector that describes the number of degrees of
- * freedom on geometrical objects for each dimension. This vector must
- * have size dim+1, and entry 0 describes the number of degrees of freedom
- * per vertex, entry 1 the number of degrees of freedom per line, etc.
- * As an example, for the common $Q_1$ Lagrange element in 2d, this
- * vector would have elements <code>(1,0,0)</code>. On the other hand,
- * for a $Q_3$ element in 3d, it would have entries <code>(1,2,4,8)</code>.
+ * @param[in] dofs_per_object A vector that describes the number of degrees
+ * of freedom on geometrical objects for each dimension. This vector must
+ * have size dim+1, and entry 0 describes the number of degrees of freedom
+ * per vertex, entry 1 the number of degrees of freedom per line, etc. As an
+ * example, for the common $Q_1$ Lagrange element in 2d, this vector would
+ * have elements <code>(1,0,0)</code>. On the other hand, for a $Q_3$
+ * element in 3d, it would have entries <code>(1,2,4,8)</code>.
*
* @param[in] n_components Number of vector components of the element.
*
- * @param[in] degree The maximal polynomial degree of any of the shape functions
- * of this element in any variable on the reference element. For example,
- * for the $Q_1$ element (in any space dimension), this would be one; this
- * is so despite the fact that the element has a shape function of the form
- * $\hat x\hat y$ (in 2d) and $\hat x\hat y\hat z$ (in 3d), which, although
- * quadratic and cubic polynomials, are still only linear in each reference
- * variable separately. The information provided by this variable is
- * typically used in determining what an appropriate quadrature formula is.
+ * @param[in] degree The maximal polynomial degree of any of the shape
+ * functions of this element in any variable on the reference element. For
+ * example, for the $Q_1$ element (in any space dimension), this would be
+ * one; this is so despite the fact that the element has a shape function of
+ * the form $\hat x\hat y$ (in 2d) and $\hat x\hat y\hat z$ (in 3d), which,
+ * although quadratic and cubic polynomials, are still only linear in each
+ * reference variable separately. The information provided by this variable
+ * is typically used in determining what an appropriate quadrature formula
+ * is.
*
* @param[in] conformity A variable describing which Sobolev space this
- * element conforms to. For example, the $Q_p$ Lagrange elements
- * (implemented by the FE_Q class) are $H^1$ conforming, whereas the
- * Raviart-Thomas element (implemented by the FE_RaviartThomas class) is
- * $H_\text{div}$ conforming; finally, completely discontinuous
- * elements (implemented by the FE_DGQ class) are only $L_2$
- * conforming.
+ * element conforms to. For example, the $Q_p$ Lagrange elements
+ * (implemented by the FE_Q class) are $H^1$ conforming, whereas the
+ * Raviart-Thomas element (implemented by the FE_RaviartThomas class) is
+ * $H_\text{div}$ conforming; finally, completely discontinuous elements
+ * (implemented by the FE_DGQ class) are only $L_2$ conforming.
*
* @param[in] block_indices An argument that describes how the base elements
- * of a finite element are grouped. The default value constructs a single
- * block that consists of all @p dofs_per_cell degrees of freedom. This
- * is appropriate for all "atomic" elements (including non-primitive ones)
- * and these can therefore omit this argument. On the other hand, composed
- * elements such as FESystem will want to pass a different value here.
+ * of a finite element are grouped. The default value constructs a single
+ * block that consists of all @p dofs_per_cell degrees of freedom. This is
+ * appropriate for all "atomic" elements (including non-primitive ones) and
+ * these can therefore omit this argument. On the other hand, composed
+ * elements such as FESystem will want to pass a different value here.
*/
FiniteElementData (const std::vector<unsigned int> &dofs_per_object,
const unsigned int n_components,
*
* <h3>Degrees of freedom</h3>
*
- * @todo The 3D version exhibits some numerical instabilities, in
- * particular for higher order
+ * @todo The 3D version exhibits some numerical instabilities, in particular
+ * for higher order
*
* @todo Restriction matrices are missing.
*
*/
void initialize_support_points (const unsigned int bdm_degree);
/**
- * The values in the face support points of the polynomials needed as
- * test functions. The outer vector is indexed by quadrature points, the
- * inner by the test function. The test function space is PolynomialsP<dim-1>.
+ * The values in the face support points of the polynomials needed as test
+ * functions. The outer vector is indexed by quadrature points, the inner by
+ * the test function. The test function space is PolynomialsP<dim-1>.
*/
std::vector<std::vector<double> > test_values_face;
/**
* are suitable for DG and hybrid formulations involving these function
* spaces.
*
- * The template argument <tt>PolynomialType</tt> refers to a vector valued polynomial
- * space like PolynomialsRaviartThomas or PolynomialsNedelec. Note that the
- * dimension of the polynomial space and the argument <tt>dim</tt> must
- * coincide.
+ * The template argument <tt>PolynomialType</tt> refers to a vector valued
+ * polynomial space like PolynomialsRaviartThomas or PolynomialsNedelec. Note
+ * that the dimension of the polynomial space and the argument <tt>dim</tt>
+ * must coincide.
*
* @ingroup febase
* @author Guido Kanschat
*
* <h3> Implementation details </h3>
*
- * This element does not have an InternalData class, unlike all other elements,
- * because the InternalData classes are used to store things that can be computed once
- * and reused multiple times (such as the values of shape functions
- * at quadrature points on the reference cell). However, because the
- * element is not mapped, this element has nothing that could be computed on the
- * reference cell -- everything needs to be computed on the real cell -- and
- * consequently there is nothing we'd like to store in such an object. We can thus
- * simply use the members already provided by FiniteElement::InternalDataBase without
- * adding anything in a derived class in this class.
+ * This element does not have an InternalData class, unlike all other
+ * elements, because the InternalData classes are used to store things that
+ * can be computed once and reused multiple times (such as the values of shape
+ * functions at quadrature points on the reference cell). However, because the
+ * element is not mapped, this element has nothing that could be computed on
+ * the reference cell -- everything needs to be computed on the real cell --
+ * and consequently there is nothing we'd like to store in such an object. We
+ * can thus simply use the members already provided by
+ * FiniteElement::InternalDataBase without adding anything in a derived class
+ * in this class.
*
* @author Guido Kanschat, 2002
*/
requires_update_flags (const UpdateFlags update_flags) const;
/**
- * This function is intended to return the value of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the value of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_value(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_value(), this function throws an exception of
+ * type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual double shape_value (const unsigned int i,
const Point<dim> &p) const;
/**
- * This function is intended to return the value of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the value of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_value_component(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_value_component(), this function throws an
+ * exception of type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual double shape_value_component (const unsigned int i,
const Point<dim> &p,
const unsigned int component) const;
/**
- * This function is intended to return the gradient of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the gradient of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_grad(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_grad(), this function throws an exception of
+ * type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<1,dim> shape_grad (const unsigned int i,
const Point<dim> &p) const;
/**
- * This function is intended to return the gradient of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the gradient of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_grad_component(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_grad_component(), this function throws an
+ * exception of type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<1,dim> shape_grad_component (const unsigned int i,
const Point<dim> &p,
const unsigned int component) const;
/**
- * This function is intended to return the Hessian of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the Hessian of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_grad_grad(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_grad_grad(), this function throws an
+ * exception of type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
const Point<dim> &p) const;
/**
- * This function is intended to return the Hessian of a shape function
- * at a point on the reference cell. However, since the current element
- * does not implement shape functions by mapping from a reference cell,
- * no shape functions exist on the reference cell.
+ * This function is intended to return the Hessian of a shape function at a
+ * point on the reference cell. However, since the current element does not
+ * implement shape functions by mapping from a reference cell, no shape
+ * functions exist on the reference cell.
*
* Consequently, as discussed in the corresponding function in the base
- * class, FiniteElement::shape_grad_grad_component(), this function throws an exception
- * of type FiniteElement::ExcUnitShapeValuesDoNotExist.
+ * class, FiniteElement::shape_grad_grad_component(), this function throws
+ * an exception of type FiniteElement::ExcUnitShapeValuesDoNotExist.
*/
virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
const Point<dim> &p,
* Constructor. First argument denotes the number of components to give this
* finite element (default = 1).
*
- * Second argument decides whether FE_Nothing
- * will dominate any other FE in compare_for_face_domination() (default = false).
- * Therefore at interfaces where, for example, a Q1 meets an FE_Nothing,
- * we will force the traces of the two functions to be the same. Because the
- * FE_Nothing encodes a space that is zero everywhere, this means that the Q1
- * field will be forced to become zero at this interface.
+ * Second argument decides whether FE_Nothing will dominate any other FE in
+ * compare_for_face_domination() (default = false). Therefore at interfaces
+ * where, for example, a Q1 meets an FE_Nothing, we will force the traces of
+ * the two functions to be the same. Because the FE_Nothing encodes a space
+ * that is zero everywhere, this means that the Q1 field will be forced to
+ * become zero at this interface.
*/
FE_Nothing (const unsigned int n_components = 1,
const bool dominate = false);
* @ref hp_paper "hp paper".
*
* In the current case, this element is assumed to dominate if the second
- * argument in the constructor @p dominate is true. When this argument is false
- * and @p fe_other is also of type FE_Nothing(), either element can dominate.
- * Otherwise there are no_requirements.
+ * argument in the constructor @p dominate is true. When this argument is
+ * false and @p fe_other is also of type FE_Nothing(), either element can
+ * dominate. Otherwise there are no_requirements.
*/
virtual
FiniteElementDomination::Domination
private:
/**
- * If true, this element will dominate any other apart from itself in compare_for_face_domination();
+ * If true, this element will dominate any other apart from itself in
+ * compare_for_face_domination();
*/
const bool dominate;
};
*
* This class is not a fully implemented FiniteElement class. Instead there
* are several pure virtual functions declared in the FiniteElement and
- * FiniteElement classes which cannot be implemented by this class but are left
- * for implementation in derived classes.
+ * FiniteElement classes which cannot be implemented by this class but are
+ * left for implementation in derived classes.
*
* @todo Since nearly all functions for spacedim != dim are specialized, this
* class needs cleaning up.
const unsigned int component) const;
/**
- * Return the tensor of third derivatives of the <tt>i</tt>th shape
- * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
- * class for more information about the semantics of this function.
+ * Return the tensor of third derivatives of the <tt>i</tt>th shape function
+ * at point <tt>p</tt> on the unit cell. See the FiniteElement base class
+ * for more information about the semantics of this function.
*/
virtual Tensor<3,dim> shape_3rd_derivative (const unsigned int i,
const Point<dim> &p) const;
* point.
*
* We store the hessians in the quadrature points on the unit cell. We
- * then only have to apply the transformation when visiting an actual cell.
+ * then only have to apply the transformation when visiting an actual
+ * cell.
*/
Table<2,Tensor<2,dim> > shape_hessians;
};
/**
- * Correct the shape third derivatives by subtracting the terms corresponding
- * to the Jacobian pushed forward gradient and second derivative.
+ * Correct the shape third derivatives by subtracting the terms
+ * corresponding to the Jacobian pushed forward gradient and second
+ * derivative.
*
* Before the correction, the third derivatives would be given by
* @f[
* D_{ijkl} = \frac{d^3\phi_i}{d \hat x_J d \hat x_K d \hat x_L} (J_{jJ})^{-1} (J_{kK})^{-1} (J_{lL})^{-1},
* @f]
- * where $J_{iI}=\frac{d x_i}{d \hat x_I}$. After the correction, the correct
- * third derivative would be given by
+ * where $J_{iI}=\frac{d x_i}{d \hat x_I}$. After the correction, the
+ * correct third derivative would be given by
* @f[
* \frac{d^3\phi_i}{d x_j d x_k d x_l} = D_{ijkl} - H_{mjl} \frac{d^2 \phi_i}{d x_k d x_m}
* - H_{mkl} \frac{d^2 \phi_i}{d x_j d x_m} - H_{mjk} \frac{d^2 \phi_i}{d x_l d x_m}
* - K_{mjkl} \frac{d \phi_i}{d x_m},
* @f]
- * where $H_{ijk}$ is the Jacobian pushed-forward derivative and $K_{ijkl}$ is
- * the Jacobian pushed-forward second derivative.
+ * where $H_{ijk}$ is the Jacobian pushed-forward derivative and $K_{ijkl}$
+ * is the Jacobian pushed-forward second derivative.
*/
void
correct_third_derivatives (internal::FEValues::FiniteElementRelatedData<dim,spacedim> &output_data,
const unsigned int dof) const;
/**
- * The polynomial space. Its type is given by the template parameter PolynomialType.
+ * The polynomial space. Its type is given by the template parameter
+ * PolynomialType.
*/
PolynomialType poly_space;
};
};
/**
- * The polynomial space. Its type is given by the template parameter PolynomialType.
+ * The polynomial space. Its type is given by the template parameter
+ * PolynomialType.
*/
PolynomialType poly_space;
};
*
* @note The matrix #inverse_node_matrix should have dimensions zero before
* this piece of code is executed. Only then, shape_value_component() will
- * return the raw polynomial <i>j</i> as defined in the polynomial space PolynomialType.
+ * return the raw polynomial <i>j</i> as defined in the polynomial space
+ * PolynomialType.
*
* <h4>Setting the transformation</h4>
*
requires_update_flags (const UpdateFlags update_flags) const;
/**
- * Compute the (scalar) value of shape function @p i at
- * the given quadrature point @p p.
- * Since the elements represented by this class are vector
- * valued, there is no such scalar value and the function therefore
- * throws an exception.
+ * Compute the (scalar) value of shape function @p i at the given quadrature
+ * point @p p. Since the elements represented by this class are vector
+ * valued, there is no such scalar value and the function therefore throws
+ * an exception.
*/
virtual double shape_value (const unsigned int i,
const Point<dim> &p) const;
const unsigned int component) const;
/**
- * Compute the gradient of (scalar) shape function @p i at
- * the given quadrature point @p p.
- * Since the elements represented by this class are vector
- * valued, there is no such scalar value and the function therefore
+ * Compute the gradient of (scalar) shape function @p i at the given
+ * quadrature point @p p. Since the elements represented by this class are
+ * vector valued, there is no such scalar value and the function therefore
* throws an exception.
*/
virtual Tensor<1,dim> shape_grad (const unsigned int i,
const unsigned int component) const;
/**
- * Compute the Hessian of (scalar) shape function @p i at
- * the given quadrature point @p p.
- * Since the elements represented by this class are vector
- * valued, there is no such scalar value and the function therefore
+ * Compute the Hessian of (scalar) shape function @p i at the given
+ * quadrature point @p p. Since the elements represented by this class are
+ * vector valued, there is no such scalar value and the function therefore
* throws an exception.
*/
virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
Table<2,DerivativeForm<1, dim, spacedim> > shape_grads;
/**
- * Array with shape function hessians in quadrature points. There is one
- * row for each shape function, containing values for each quadrature
- * point.
- */
+ * Array with shape function hessians in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
+ * point.
+ */
Table<2,DerivativeForm<2, dim, spacedim> > shape_grad_grads;
/**
/**
- * The polynomial space. Its type is given by the template parameter PolynomialType.
+ * The polynomial space. Its type is given by the template parameter
+ * PolynomialType.
*/
PolynomialType poly_space;
/*@{*/
/**
- * This class collects the basic methods used in FE_Q, FE_Q_DG0 and FE_Q_Bubbles.
- * There is no public constructor for this class as it is not functional as a stand-
- * alone. The completion of definitions is left to the derived classes.
+ * This class collects the basic methods used in FE_Q, FE_Q_DG0 and
+ * FE_Q_Bubbles. There is no public constructor for this class as it is not
+ * functional as a stand- alone. The completion of definitions is left to the
+ * derived classes.
*
* @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann,
* 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008;
* Implementation of a scalar Lagrange finite element @p Q_p^+ that yields the
* finite element space of continuous, piecewise polynomials of degree @p p in
* each coordinate direction plus some bubble enrichment space spanned by
- * $(2x_j-1)^{p-1}\prod_{i=0}^{dim-1}(x_i(1-x_i))$. Therefore the highest polynomial
- * degree is $p+1$.
- * This class is realized using tensor product polynomials based on equidistant
- * or given support points.
+ * $(2x_j-1)^{p-1}\prod_{i=0}^{dim-1}(x_i(1-x_i))$. Therefore the highest
+ * polynomial degree is $p+1$. This class is realized using tensor product
+ * polynomials based on equidistant or given support points.
*
* The standard constructor of this class takes the degree @p p of this finite
* element. Alternatively, it can take a quadrature formula @p points defining
- * the support points of the Lagrange interpolation in one coordinate direction.
+ * the support points of the Lagrange interpolation in one coordinate
+ * direction.
*
* For more information about the <tt>spacedim</tt> template parameter check
* the documentation of FiniteElement or the one of Triangulation.
*
- * Due to the fact that the enrichments are small almost everywhere
- * for large p, the condition number for the mass and stiffness matrix fastly
- * increaseses with increasing p.
- * Below you see a comparison with FE_Q(QGaussLobatto(p+1)) for dim=1.
+ * Due to the fact that the enrichments are small almost everywhere for large
+ * p, the condition number for the mass and stiffness matrix fastly
+ * increaseses with increasing p. Below you see a comparison with
+ * FE_Q(QGaussLobatto(p+1)) for dim=1.
*
* <p ALIGN="center">
* @image html fe_q_bubbles_conditioning.png
* <h3>Implementation</h3>
*
* The constructor creates a TensorProductPolynomials object that includes the
- * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus the
- * bubble enrichments. This @p TensorProductPolynomialsBubbles object
+ * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus
+ * the bubble enrichments. This @p TensorProductPolynomialsBubbles object
* provides all values and derivatives of the shape functions. In case a
* quadrature rule is given, the constructor creates a
- * TensorProductPolynomialsBubbles object that includes the tensor product of @p
- * Lagrange polynomials with the support points from @p points and the bubble enrichments
- * as defined above.
+ * TensorProductPolynomialsBubbles object that includes the tensor product of
+ * @p Lagrange polynomials with the support points from @p points and the
+ * bubble enrichments as defined above.
*
* Furthermore the constructor fills the @p interface_constrains, the @p
* prolongation (embedding) and the @p restriction matrices.
* <h3>Numbering of the degrees of freedom (DoFs)</h3>
*
* The original ordering of the shape functions represented by the
- * TensorProductPolynomialsBubbles is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. Finally, there are support points for the bubble enrichments
- * in the middle of the cell.
+ * TensorProductPolynomialsBubbles is a tensor product numbering. However, the
+ * shape functions on a cell are renumbered beginning with the shape functions
+ * whose support points are at the vertices, then on the line, on the quads,
+ * and finally (for 3d) on the hexes. Finally, there are support points for
+ * the bubble enrichments in the middle of the cell.
*
*/
template <int dim, int spacedim=dim>
{
public:
/**
- * Constructor for tensor product polynomials of degree @p p plus bubble enrichments
+ * Constructor for tensor product polynomials of degree @p p plus bubble
+ * enrichments
*
*/
FE_Q_Bubbles (const unsigned int p);
/**
* Constructor for tensor product polynomials with support points @p points
- * plus bubble enrichments based on a one-dimensional quadrature
- * formula. The degree of the finite element is <tt>points.size()</tt>.
- * Note that the first point has to be 0 and the last one 1.
+ * plus bubble enrichments based on a one-dimensional quadrature formula.
+ * The degree of the finite element is <tt>points.size()</tt>. Note that the
+ * first point has to be 0 and the last one 1.
*/
FE_Q_Bubbles (const Quadrature<1> &points);
private:
/**
- * Returns the restriction_is_additive flags.
- * Only the last components for the bubble enrichments are true.
+ * Returns the restriction_is_additive flags. Only the last components for
+ * the bubble enrichments are true.
*/
static std::vector<bool> get_riaf_vector(const unsigned int degree);
*
* <h3>Interpolation</h3>
*
- * <h4>Node values</h4>
- * The
+ * <h4>Node values</h4> The
* @ref GlossNodes "node values"
* are moments on faces.
*
- * <h4>Generalized support points</h4>
- * To calculate the node values, we are using a QGauss rule on each face.
- * By default, we are using a two point rule to integrate Rannacher-Turek
- * functions exactly. But in order to be able to interpolate other
- * functions with sufficient accuracy, the number of quadrature points
- * used on a face can be adjusted in the constructor.
+ * <h4>Generalized support points</h4> To calculate the node values, we are
+ * using a QGauss rule on each face. By default, we are using a two point rule
+ * to integrate Rannacher-Turek functions exactly. But in order to be able to
+ * interpolate other functions with sufficient accuracy, the number of
+ * quadrature points used on a face can be adjusted in the constructor.
*
* @ingroup fe
* @author Patrick Esser
{
public:
/**
- * Constructor for Rannacher-Turek element of degree @p degree, using
- * @p n_face_support_points quadrature points on each face for
- * interpolation. Notice that the element of degree 0 contains
- * polynomials of degree 2.
+ * Constructor for Rannacher-Turek element of degree @p degree, using @p
+ * n_face_support_points quadrature points on each face for interpolation.
+ * Notice that the element of degree 0 contains polynomials of degree 2.
*
* Only implemented for degree 0 in 2D.
*/
*/
void initialize_support_points();
/**
- * Return information about degrees of freedom per object as needed
- * during construction.
+ * Return information about degrees of freedom per object as needed during
+ * construction.
*/
std::vector<unsigned int> get_dpo_vector();
};
*
* If projection matrices are not implemented in the derived finite element
* class, this function aborts with an exception of type
- * FiniteElement::ExcProjectionVoid. You can check whether
- * this would happen by first calling the restriction_is_implemented() or the
+ * FiniteElement::ExcProjectionVoid. You can check whether this would happen
+ * by first calling the restriction_is_implemented() or the
* isotropic_restriction_is_implemented() function.
*/
virtual const FullMatrix<double> &
* cells using this matrix array, zero elements in the prolongation matrix
* are discarded and will not fill up the transfer matrix.
*
- * If prolongation matrices are not implemented in one of the base finite element
- * classes, this function aborts with an exception of type
- * FiniteElement::ExcEmbeddingVoid. You can check whether
- * this would happen by first calling the prolongation_is_implemented() or the
+ * If prolongation matrices are not implemented in one of the base finite
+ * element classes, this function aborts with an exception of type
+ * FiniteElement::ExcEmbeddingVoid. You can check whether this would happen
+ * by first calling the prolongation_is_implemented() or the
* isotropic_prolongation_is_implemented() function.
*/
virtual const FullMatrix<double> &
typename std::vector<typename FiniteElement<dim,spacedim>::InternalDataBase *> base_fe_datas;
/**
- * A collection of objects to which the base elements will write their output
- * when we call
- * FiniteElement::fill_fe_values() and related functions on them.
+ * A collection of objects to which the base elements will write their
+ * output when we call FiniteElement::fill_fe_values() and related
+ * functions on them.
*
* The size of this vector is set to @p n_base_elements by the
* InternalData constructor.
* @param isotropic_only Set to <code>true</code> if you only want to
* compute matrices for isotropic refinement.
*
- * @param threshold is the gap allowed in the least squares
- * algorithm computing the embedding.
+ * @param threshold is the gap allowed in the least squares algorithm
+ * computing the embedding.
*/
template <int dim, typename number, int spacedim>
void compute_embedding_matrices(const FiniteElement<dim,spacedim> &fe,
* @param face_fine The number of the face on the refined side of the face
* for which this is computed.
*
- * @param threshold is the gap allowed in the least squares
- * algorithm computing the embedding.
+ * @param threshold is the gap allowed in the least squares algorithm
+ * computing the embedding.
*
* @warning This function will be used in computing constraint matrices. It
* is not sufficiently tested yet.
*
* <h3>Use of these flags flags</h3>
*
- * More information on the use of this type both in user code as
- * well as internally can be found in the documentation modules on
+ * More information on the use of this type both in user code as well as
+ * internally can be found in the documentation modules on
* @ref UpdateFlags "The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues"
* and
* @ref FE_vs_Mapping_vs_FEValues "How Mapping, FiniteElement, and FEValues work together".
* when calling the method FEValues::reinit() (like derivatives, which do not
* change if one cell is just a translation of the previous). Currently, this
* variable does only recognize a translation and an inverted translation (if
- * dim<spacedim). However, this concept makes it easy to add additional
- * states to be detected in FEValues/FEFaceValues for making use of these
+ * dim<spacedim). However, this concept makes it easy to add additional states
+ * to be detected in FEValues/FEFaceValues for making use of these
* similarities as well.
*/
namespace CellSimilarity
/**
* A class that stores all of the mapping related data used in
* dealii::FEValues, dealii::FEFaceValues, and dealii::FESubfaceValues
- * objects. Objects of this kind will be given
- * as <i>output</i> argument when dealii::FEValues::reinit()
- * calls Mapping::fill_fe_values() for a given cell, face, or subface.
+ * objects. Objects of this kind will be given as <i>output</i> argument
+ * when dealii::FEValues::reinit() calls Mapping::fill_fe_values() for a
+ * given cell, face, or subface.
*
- * The data herein will then be provided as <i>input</i> argument in
- * the following call to FiniteElement::fill_fe_values().
+ * The data herein will then be provided as <i>input</i> argument in the
+ * following call to FiniteElement::fill_fe_values().
*
* @ingroup feaccess
*/
const UpdateFlags flags);
/**
- * Compute and return an estimate for the memory consumption (in
- * bytes) of this object.
+ * Compute and return an estimate for the memory consumption (in bytes)
+ * of this object.
*/
std::size_t memory_consumption () const;
/**
- * Store an array of weights times the Jacobi determinant at the quadrature
- * points. This function is reset each time reinit() is called. The Jacobi
- * determinant is actually the reciprocal value of the Jacobi matrices
- * stored in this class, see the general documentation of this class for
- * more information.
+ * Store an array of weights times the Jacobi determinant at the
+ * quadrature points. This function is reset each time reinit() is
+ * called. The Jacobi determinant is actually the reciprocal value of
+ * the Jacobi matrices stored in this class, see the general
+ * documentation of this class for more information.
*
* However, if this object refers to an FEFaceValues or FESubfaceValues
* object, then the JxW_values correspond to the Jacobian of the
- * transformation of the face, not the cell, i.e. the dimensionality is that
- * of a surface measure, not of a volume measure. In this case, it is
- * computed from the boundary forms, rather than the Jacobian matrix.
+ * transformation of the face, not the cell, i.e. the dimensionality is
+ * that of a surface measure, not of a volume measure. In this case, it
+ * is computed from the boundary forms, rather than the Jacobian matrix.
*/
std::vector<double> JxW_values;
std::vector<DerivativeForm<1,spacedim,dim> > inverse_jacobians;
/**
- * Array of the derivatives of the Jacobian matrices at the
- * quadrature points, pushed forward to the real cell coordinates.
+ * Array of the derivatives of the Jacobian matrices at the quadrature
+ * points, pushed forward to the real cell coordinates.
*/
std::vector<Tensor<3,spacedim> > jacobian_pushed_forward_grads;
/**
* Array of the third derivatives of the Jacobian matrices at the
* quadrature points, pushed forward to the real cell coordinates.
-
*/
std::vector<Tensor<5,spacedim> > jacobian_pushed_forward_3rd_derivatives;
/**
- * Array of quadrature points. This array is set up upon calling reinit()
- * and contains the quadrature points on the real element, rather than on
- * the reference element.
+ * Array of quadrature points. This array is set up upon calling
+ * reinit() and contains the quadrature points on the real element,
+ * rather than on the reference element.
*/
std::vector<Point<spacedim> > quadrature_points;
/**
* A class that stores all of the shape function related data used in
* dealii::FEValues, dealii::FEFaceValues, and dealii::FESubfaceValues
- * objects. Objects of this kind will be given
- * as <i>output</i> argument when dealii::FEValues::reinit()
- * calls FiniteElement::fill_fe_values().
+ * objects. Objects of this kind will be given as <i>output</i> argument
+ * when dealii::FEValues::reinit() calls FiniteElement::fill_fe_values().
*
* @ingroup feaccess
*/
const UpdateFlags flags);
/**
- * Compute and return an estimate for the memory consumption (in
- * bytes) of this object.
+ * Compute and return an estimate for the memory consumption (in bytes)
+ * of this object.
*/
std::size_t memory_consumption () const;
/**
- * Storage type for shape values. Each row in the matrix denotes the values
- * of a single shape function at the different points, columns are for a
- * single point with the different shape functions.
+ * Storage type for shape values. Each row in the matrix denotes the
+ * values of a single shape function at the different points, columns
+ * are for a single point with the different shape functions.
*
* If a shape function has more than one non-zero component (in deal.II
* diction: it is non-primitive), then we allocate one row per non-zero
- * component, and shift subsequent rows backward. Lookup of the correct row
- * for a shape function is thus simple in case the entire finite element is
- * primitive (i.e. all shape functions are primitive), since then the shape
- * function number equals the row number. Otherwise, use the
- * #shape_function_to_row_table array to get at the first row that belongs
- * to this particular shape function, and navigate among all the rows for
- * this shape function using the FiniteElement::get_nonzero_components()
- * function which tells us which components are non-zero and thus have a row
- * in the array presently under discussion.
+ * component, and shift subsequent rows backward. Lookup of the correct
+ * row for a shape function is thus simple in case the entire finite
+ * element is primitive (i.e. all shape functions are primitive), since
+ * then the shape function number equals the row number. Otherwise, use
+ * the #shape_function_to_row_table array to get at the first row that
+ * belongs to this particular shape function, and navigate among all the
+ * rows for this shape function using the
+ * FiniteElement::get_nonzero_components() function which tells us which
+ * components are non-zero and thus have a row in the array presently
+ * under discussion.
*/
typedef dealii::Table<2,double> ShapeVector;
typedef dealii::Table<2,Tensor<3,spacedim> > ThirdDerivativeVector;
/**
- * Store the values of the shape functions at the quadrature points. See the
- * description of the data type for the layout of the data in this field.
+ * Store the values of the shape functions at the quadrature points. See
+ * the description of the data type for the layout of the data in this
+ * field.
*/
ShapeVector shape_values;
/**
- * Store the gradients of the shape functions at the quadrature points. See
- * the description of the data type for the layout of the data in this
- * field.
+ * Store the gradients of the shape functions at the quadrature points.
+ * See the description of the data type for the layout of the data in
+ * this field.
*/
GradientVector shape_gradients;
/**
* Store the 2nd derivatives of the shape functions at the quadrature
- * points. See the description of the data type for the layout of the data
- * in this field.
+ * points. See the description of the data type for the layout of the
+ * data in this field.
*/
HessianVector shape_hessians;
/**
* Store the 3nd derivatives of the shape functions at the quadrature
- * points. See the description of the data type for the layout of the data
- * in this field.
+ * points. See the description of the data type for the layout of the
+ * data in this field.
*/
ThirdDerivativeVector shape_3rd_derivatives;
/**
- * When asked for the value (or gradient, or Hessian) of shape function i's
- * c-th vector component, we need to look it up in the #shape_values,
- * #shape_gradients and #shape_hessians arrays. The question is where in
- * this array does the data for shape function i, component c reside. This
- * is what this table answers.
+ * When asked for the value (or gradient, or Hessian) of shape function
+ * i's c-th vector component, we need to look it up in the
+ * #shape_values, #shape_gradients and #shape_hessians arrays. The
+ * question is where in this array does the data for shape function i,
+ * component c reside. This is what this table answers.
*
* The format of the table is as follows: - It has dofs_per_cell times
- * n_components entries. - The entry that corresponds to shape function i,
- * component c is <code>i * n_components + c</code>. - The value stored at
- * this position indicates the row in #shape_values and the other tables
- * where the corresponding datum is stored for all the quadrature points.
+ * n_components entries. - The entry that corresponds to shape function
+ * i, component c is <code>i * n_components + c</code>. - The value
+ * stored at this position indicates the row in #shape_values and the
+ * other tables where the corresponding datum is stored for all the
+ * quadrature points.
*
- * In the general, vector-valued context, the number of components is larger
- * than one, but for a given shape function, not all vector components may
- * be nonzero (e.g., if a shape function is primitive, then exactly one
- * vector component is non-zero, while the others are all zero). For such
- * zero components, #shape_values and friends do not have a row.
- * Consequently, for vector components for which shape function i is zero,
- * the entry in the current table is numbers::invalid_unsigned_int.
+ * In the general, vector-valued context, the number of components is
+ * larger than one, but for a given shape function, not all vector
+ * components may be nonzero (e.g., if a shape function is primitive,
+ * then exactly one vector component is non-zero, while the others are
+ * all zero). For such zero components, #shape_values and friends do not
+ * have a row. Consequently, for vector components for which shape
+ * function i is zero, the entry in the current table is
+ * numbers::invalid_unsigned_int.
*
* On the other hand, the table is guaranteed to have at least one valid
* index for each shape function. In particular, for a primitive finite
- * element, each shape function has exactly one nonzero component and so for
- * each i, there is exactly one valid index within the range
+ * element, each shape function has exactly one nonzero component and so
+ * for each i, there is exactly one valid index within the range
* <code>[i*n_components, (i+1)*n_components)</code>.
*/
std::vector<unsigned int> shape_function_to_row_table;
* on the selected scalar component.
*
* The data type stored by the output vector must be what you get when you
- * multiply the third derivatives of shape functions
- * (i.e., @p third_derivative_type) times the type used to store the values
- * of the unknowns $U_j$ of your finite element vector $U$ (represented by
- * the @p fe_function argument).
+ * multiply the third derivatives of shape functions (i.e., @p
+ * third_derivative_type) times the type used to store the values of the
+ * unknowns $U_j$ of your finite element vector $U$ (represented by the @p
+ * fe_function argument).
*
* @dealiiRequiresUpdateFlags{update_third_derivatives}
*/
const unsigned int q_point) const;
/**
- * Return the tensor of rank 3 of all third derivatives of
- * the vector components selected by this view, for the shape function and
- * quadrature point selected by the arguments.
+ * Return the tensor of rank 3 of all third derivatives of the vector
+ * components selected by this view, for the shape function and quadrature
+ * point selected by the arguments.
*
* @note The meaning of the arguments is as documented for the value()
* function.
* on the selected scalar component.
*
* The data type stored by the output vector must be what you get when you
- * multiply the third derivatives of shape functions
- * (i.e., @p third_derivative_type) times the type used to store the values
- * of the unknowns $U_j$ of your finite element vector $U$ (represented by
- * the @p fe_function argument).
+ * multiply the third derivatives of shape functions (i.e., @p
+ * third_derivative_type) times the type used to store the values of the
+ * unknowns $U_j$ of your finite element vector $U$ (represented by the @p
+ * fe_function argument).
*
* @dealiiRequiresUpdateFlags{update_third_derivatives}
*/
* of finite element and mapping, some values can be computed once on the unit
* cell. Others must be computed on each cell, but maybe computation of
* several values at the same time offers ways for optimization. Since this
- * interplay may be complex and depends on the actual finite element, it cannot
- * be left to the applications programmer.
+ * interplay may be complex and depends on the actual finite element, it
+ * cannot be left to the applications programmer.
*
* FEValues, FEFaceValues and FESubfaceValues provide only data handling:
* computations are left to objects of type Mapping and FiniteElement. These
* <h3>Internals about the implementation</h3>
*
* The mechanisms by which this class work are discussed on the page on
- * @ref UpdateFlags "Update flags" and about the
+ * @ref UpdateFlags "Update flags"
+ * and about the
* @ref FE_vs_Mapping_vs_FEValues "How Mapping, FiniteElement, and FEValues work together".
*
*
*
* @param function_no Number of the shape function to be evaluated.
*
- * @param quadrature_point Number of the quadrature point at which function is to be
- * evaluated.
+ * @param quadrature_point Number of the quadrature point at which function
+ * is to be evaluated.
*
* @dealiiRequiresUpdateFlags{update_gradients}
*/
* <tt>point_no</tt>th quadrature point with respect to real cell
* coordinates. If you want to get the derivatives in one of the coordinate
* directions, use the appropriate function of the Tensor class to extract
- * one component. Since only a reference to the hessian values is
- * returned, there should be no major performance drawback.
+ * one component. Since only a reference to the hessian values is returned,
+ * there should be no major performance drawback.
*
* If the shape function is vector-valued, then this returns the only non-
* zero component. If the shape function has more than one non-zero
/**
* Third derivatives of the <tt>function_no</tt>th shape function at the
* <tt>point_no</tt>th quadrature point with respect to real cell
- * coordinates. If you want to get the 3rd derivatives in one of the coordinate
- * directions, use the appropriate function of the Tensor class to extract
- * one component. Since only a reference to the 3rd derivative values is
- * returned, there should be no major performance drawback.
+ * coordinates. If you want to get the 3rd derivatives in one of the
+ * coordinate directions, use the appropriate function of the Tensor class
+ * to extract one component. Since only a reference to the 3rd derivative
+ * values is returned, there should be no major performance drawback.
*
* If the shape function is vector-valued, then this returns the only non-
* zero component. If the shape function has more than one non-zero
const unsigned int point_no) const;
/**
- * Return one vector component of the third derivative of a shape function at a
- * quadrature point. If the finite element is scalar, then only component
- * zero is allowed and the return value equals that of the shape_3rdderivative()
- * function. If the finite element is vector valued but all shape functions
- * are primitive (i.e. they are non-zero in only one component), then the
- * value returned by shape_3rdderivative() equals that of this function for
- * exactly one component. This function is therefore only of greater
- * interest if the shape function is not primitive, but then it is necessary
- * since the other function cannot be used.
+ * Return one vector component of the third derivative of a shape function
+ * at a quadrature point. If the finite element is scalar, then only
+ * component zero is allowed and the return value equals that of the
+ * shape_3rdderivative() function. If the finite element is vector valued
+ * but all shape functions are primitive (i.e. they are non-zero in only one
+ * component), then the value returned by shape_3rdderivative() equals that
+ * of this function for exactly one component. This function is therefore
+ * only of greater interest if the shape function is not primitive, but then
+ * it is necessary since the other function cannot be used.
*
* The same holds for the arguments of this function as for the
* shape_value_component() function.
* store the values of the unknowns $U_j$ of your finite element vector $U$
* (represented by the @p fe_function argument).
*
- * @post <code>third_derivatives[q]</code> will contain the third derivatives
- * of the field described by fe_function at the $q$th quadrature point.
- * <code>third_derivatives[q][i][j][k]</code> represents the $(i,j,k)$th
- * component of the 3rd order tensor of third derivatives at quadrature
- * point $q$.
+ * @post <code>third_derivatives[q]</code> will contain the third
+ * derivatives of the field described by fe_function at the $q$th quadrature
+ * point. <code>third_derivatives[q][i][j][k]</code> represents the
+ * $(i,j,k)$th component of the 3rd order tensor of third derivatives at
+ * quadrature point $q$.
*
* @note The actual data type of the input vector may be either a
* Vector<T>, BlockVector<T>, or one of the sequential PETSc or
std::vector<Tensor<3,spacedim,typename InputVector::value_type> > &third_derivatives) const;
/**
- * This function does the same as the other get_function_third_derivatives(),
- * but applied to multi-component (vector-valued) elements. The meaning of
- * the arguments is as explained there.
+ * This function does the same as the other
+ * get_function_third_derivatives(), but applied to multi-component (vector-
+ * valued) elements. The meaning of the arguments is as explained there.
*
* @post <code>third_derivatives[q]</code> is a vector of third derivatives
* of the field described by fe_function at the $q$th quadrature point. The
* size of the vector accessed by <code>third_derivatives[q]</code> equals
* the number of components of the finite element, i.e.
* <code>third_derivatives[q][c]</code> returns the third derivative of the
- * $c$th vector component at the $q$th quadrature point.
- * Consequently, <code>third_derivatives[q][c][i][j][k]</code> is
- * the $(i,j,k)$th component of the tensor of third derivatives of the $c$th
- * vector component of the vector field at quadrature point $q$ of the
- * current cell.
+ * $c$th vector component at the $q$th quadrature point. Consequently,
+ * <code>third_derivatives[q][c][i][j][k]</code> is the $(i,j,k)$th
+ * component of the tensor of third derivatives of the $c$th vector
+ * component of the vector field at quadrature point $q$ of the current
+ * cell.
*
* @dealiiRequiresUpdateFlags{update_3rd_derivatives}
*/
const std::vector<Tensor<3,spacedim> > &get_jacobian_pushed_forward_grads () const;
/**
- * Return the third derivative of the transformation from unit to real
- * cell, i.e. the second derivative of the Jacobian, at the specified
- * quadrature point, i.e. $G_{ijkl}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l}$.
+ * Return the third derivative of the transformation from unit to real cell,
+ * i.e. the second derivative of the Jacobian, at the specified quadrature
+ * point, i.e. $G_{ijkl}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l}$.
*
* @dealiiRequiresUpdateFlags{update_jacobian_2nd_derivatives}
*/
const std::vector<DerivativeForm<3,dim,spacedim> > &get_jacobian_2nd_derivatives () const;
/**
- * Return the third derivative of the transformation from unit to real
- * cell, i.e. the second derivative of the Jacobian, at the specified
- * quadrature point, pushed forward to the real cell coordinates, i.e.
- * $G_{ijkl}=\frac{d^2J_{iJ}}{d\hat x_K d\hat x_L} (J_{jJ})^{-1} (J_{kK})^{-1}(J_{lL})^{-1}$.
+ * Return the third derivative of the transformation from unit to real cell,
+ * i.e. the second derivative of the Jacobian, at the specified quadrature
+ * point, pushed forward to the real cell coordinates, i.e.
+ * $G_{ijkl}=\frac{d^2J_{iJ}}{d\hat x_K d\hat x_L} (J_{jJ})^{-1}
+ * (J_{kK})^{-1}(J_{lL})^{-1}$.
*
* @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_2nd_derivatives}
*/
/**
* Return the fourth derivative of the transformation from unit to real
* cell, i.e. the third derivative of the Jacobian, at the specified
- * quadrature point, i.e. $G_{ijklm}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l d\hat x_m}$.
+ * quadrature point, i.e. $G_{ijklm}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l
+ * d\hat x_m}$.
*
* @dealiiRequiresUpdateFlags{update_jacobian_3rd_derivatives}
*/
* Return the fourth derivative of the transformation from unit to real
* cell, i.e. the third derivative of the Jacobian, at the specified
* quadrature point, pushed forward to the real cell coordinates, i.e.
- * $G_{ijklm}=\frac{d^3J_{iJ}}{d\hat x_K d\hat x_L d\hat x_M} (J_{jJ})^{-1} (J_{kK})^{-1} (J_{lL})^{-1} (J_{mM})^{-1}$.
+ * $G_{ijklm}=\frac{d^3J_{iJ}}{d\hat x_K d\hat x_L d\hat x_M} (J_{jJ})^{-1}
+ * (J_{kK})^{-1} (J_{lL})^{-1} (J_{mM})^{-1}$.
*
* @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_3rd_derivatives}
*/
* For a face, return the outward normal vector to the cell at the
* <tt>i</tt>th quadrature point.
*
- * For a cell of codimension one, return the normal vector. There
- * are of course two normal directions to a manifold in that case,
- * and this function returns the "up" direction as induced by the
- * numbering of the vertices.
+ * For a cell of codimension one, return the normal vector. There are of
+ * course two normal directions to a manifold in that case, and this
+ * function returns the "up" direction as induced by the numbering of the
+ * vertices.
*
* The length of the vector is normalized to one.
*
*
* @dealiiRequiresUpdateFlags{update_normal_vectors}
*
- * @note This function should really be named get_normal_vectors(),
- * but this function already exists with a different return type
- * that returns a vector of Point objects, rather than a vector of
- * Tensor objects. This is a historical accident, but can not
- * be fixed in a backward compatible style. That said, the
- * get_normal_vectors() function is now deprecated, will be removed
- * in the next version, and the current function will then be renamed.
+ * @note This function should really be named get_normal_vectors(), but this
+ * function already exists with a different return type that returns a
+ * vector of Point objects, rather than a vector of Tensor objects. This is
+ * a historical accident, but can not be fixed in a backward compatible
+ * style. That said, the get_normal_vectors() function is now deprecated,
+ * will be removed in the next version, and the current function will then
+ * be renamed.
*/
const std::vector<Tensor<1,spacedim> > &get_all_normal_vectors () const;
/**
- * Return the normal vectors at the quadrature points as a vector of
- * Point objects. This function is deprecated because normal vectors
- * are correctly represented by rank-1 Tensor objects, not Point objects.
- * Use get_all_normal_vectors() instead.
+ * Return the normal vectors at the quadrature points as a vector of Point
+ * objects. This function is deprecated because normal vectors are correctly
+ * represented by rank-1 Tensor objects, not Point objects. Use
+ * get_all_normal_vectors() instead.
*
* @dealiiRequiresUpdateFlags{update_normal_vectors}
*
std_cxx11::unique_ptr<typename Mapping<dim,spacedim>::InternalDataBase> mapping_data;
/**
- * An object into which the Mapping::fill_fe_values() and similar
- * functions place their output.
+ * An object into which the Mapping::fill_fe_values() and similar functions
+ * place their output.
*/
dealii::internal::FEValues::MappingRelatedData<dim, spacedim> mapping_output;
/**
- * A pointer to the finite element object associated with this FEValues object.
+ * A pointer to the finite element object associated with this FEValues
+ * object.
*/
const SmartPointer<const FiniteElement<dim,spacedim>,FEValuesBase<dim,spacedim> > fe;
const UpdateFlags update_flags);
/**
- * Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * Constructor. This constructor is equivalent to the other one except that
+ * it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*/
FEValues (const FiniteElement<dim,spacedim> &fe,
const Quadrature<dim> &quadrature,
* this class if they need information about degrees of freedom. These
* functions are, above all, the
* <tt>get_function_value/gradients/hessians/laplacians/third_derivatives</tt>
- * functions. If you want to call these functions, you have to call the
- * @p reinit variants that take iterators into DoFHandler or other DoF handler
+ * functions. If you want to call these functions, you have to call the @p
+ * reinit variants that take iterators into DoFHandler or other DoF handler
* type objects.
*/
void reinit (const typename Triangulation<dim,spacedim>::cell_iterator &cell);
const UpdateFlags update_flags);
/**
- * Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * Constructor. This constructor is equivalent to the other one except that
+ * it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*/
FEFaceValues (const FiniteElement<dim,spacedim> &fe,
const Quadrature<dim-1> &quadrature,
* some functions of this class if they need information about degrees of
* freedom. These functions are, above all, the
* <tt>get_function_value/gradients/hessians/third_derivatives</tt>
- * functions. If you want to call these functions, you have to call the
- * @p reinit variants that take iterators into DoFHandler or other
- * DoF handler type objects.
+ * functions. If you want to call these functions, you have to call the @p
+ * reinit variants that take iterators into DoFHandler or other DoF handler
+ * type objects.
*/
void reinit (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
const unsigned int face_no);
const UpdateFlags update_flags);
/**
- * Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * Constructor. This constructor is equivalent to the other one except that
+ * it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*/
FESubfaceValues (const FiniteElement<dim,spacedim> &fe,
const Quadrature<dim-1> &face_quadrature,
* some functions of this class if they need information about degrees of
* freedom. These functions are, above all, the
* <tt>get_function_value/gradients/hessians/third_derivatives</tt>
- * functions. If you want to call these functions, you have to call the
- * @p reinit variants that take iterators into DoFHandler or other
- * DoF handler type objects.
+ * functions. If you want to call these functions, you have to call the @p
+ * reinit variants that take iterators into DoFHandler or other DoF handler
+ * type objects.
*/
void reinit (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
const unsigned int face_no,
mapping_contravariant = 0x0002,
/**
- * Mapping of the gradient of a covariant vector field (see Mapping::transform() for details).
+ * Mapping of the gradient of a covariant vector field (see
+ * Mapping::transform() for details).
*/
mapping_covariant_gradient = 0x0003,
/**
- * Mapping of the gradient of a contravariant vector field (see Mapping::transform() for details).
+ * Mapping of the gradient of a contravariant vector field (see
+ * Mapping::transform() for details).
*/
mapping_contravariant_gradient = 0x0004,
* These are mappings typpically applied to hessians transformed to the
* reference cell.
*
- * Mapping of the hessian of a covariant vector field (see Mapping::transform() for details).
+ * Mapping of the hessian of a covariant vector field (see
+ * Mapping::transform() for details).
*/
mapping_covariant_hessian,
/**
- * Mapping of the hessian of a contravariant vector field (see Mapping::transform() for details).
- */
+ * Mapping of the hessian of a contravariant vector field (see
+ * Mapping::transform() for details).
+ */
mapping_contravariant_hessian,
/**
- * Mapping of the hessian of a piola vector field (see Mapping::transform() for details).
- */
+ * Mapping of the hessian of a piola vector field (see Mapping::transform()
+ * for details).
+ */
mapping_piola_hessian
};
/**
* @short Abstract base class for mapping classes.
*
- * This class declares the interface for the functionality to describe mappings
- * from the reference (unit) cell to a cell in real space, as well as for filling
- * the information necessary to use the FEValues, FEFaceValues, and FESubfaceValues
- * classes. Concrete implementations of these interfaces are provided in
- * derived classes.
+ * This class declares the interface for the functionality to describe
+ * mappings from the reference (unit) cell to a cell in real space, as well as
+ * for filling the information necessary to use the FEValues, FEFaceValues,
+ * and FESubfaceValues classes. Concrete implementations of these interfaces
+ * are provided in derived classes.
*
* <h3>Mathematics of the mapping</h3>
*
- * The mapping is a transformation $\mathbf x = \mathbf F_K(\hat{\mathbf x})$ which
- * maps points $\hat{\mathbf x}$ in the reference cell $[0,1]^\text{dim}$ to points
- * $\mathbf x$ in the actual grid cell
- * $K\subset{\mathbb R}^\text{spacedim}$. Many of the applications of such mappings
- * require the Jacobian of this mapping,
- * $J(\hat{\mathbf x}) = \hat\nabla {\mathbf F}_K(\hat{\mathbf x})$. For instance, if
+ * The mapping is a transformation $\mathbf x = \mathbf F_K(\hat{\mathbf x})$
+ * which maps points $\hat{\mathbf x}$ in the reference cell
+ * $[0,1]^\text{dim}$ to points $\mathbf x$ in the actual grid cell
+ * $K\subset{\mathbb R}^\text{spacedim}$. Many of the applications of such
+ * mappings require the Jacobian of this mapping, $J(\hat{\mathbf x}) =
+ * \hat\nabla {\mathbf F}_K(\hat{\mathbf x})$. For instance, if
* dim=spacedim=2, we have
* @f[
* J(\hat{\mathbf x}) = \left(\begin{matrix}
*
* <h4>%Mapping of scalar functions</h4>
*
- * The shape functions of scalar finite elements are typically defined on a reference
- * cell and are then simply mapped according to the rule
+ * The shape functions of scalar finite elements are typically defined on a
+ * reference cell and are then simply mapped according to the rule
* @f[
* \varphi(\mathbf x) = \varphi\bigl(\mathbf F_K(\hat{\mathbf x})\bigr)
* = \hat \varphi(\hat{\mathbf x}).
*
* <h4>%Mapping of integrals</h4>
*
- * Using simply a change of variables, integrals of scalar functions over a cell
- * $K$ can be expressed as an integral over the reference cell $\hat K$.
+ * Using simply a change of variables, integrals of scalar functions over a
+ * cell $K$ can be expressed as an integral over the reference cell $\hat K$.
* Specifically, The volume form $d\hat x$ is transformed so that
* @f[
* \int_K u(\mathbf x)\,dx = \int_{\hat K} \hat
* \,d\hat x.
* @f]
*
- * In expressions where such integrals are approximated by quadrature,
- * this then leads to terms of the form
+ * In expressions where such integrals are approximated by quadrature, this
+ * then leads to terms of the form
* @f[
* \int_K u(\mathbf x)\,dx
* \approx
* <h4>%Mapping of vector fields, differential forms and gradients of vector
* fields</h4>
*
- * The transformation of vector fields or differential forms
- * (gradients of scalar functions) $\mathbf v$, and gradients of vector fields $\mathbf T$
+ * The transformation of vector fields or differential forms (gradients of
+ * scalar functions) $\mathbf v$, and gradients of vector fields $\mathbf T$
* follows the general form
*
* @f[
* \mathbf T(\mathbf x) = \mathbf A(\hat{\mathbf x})
* \hat{\mathbf T}(\hat{\mathbf x}) \mathbf B(\hat{\mathbf x}).
* @f]
- * The differential forms <b>A</b> and <b>B</b> are
- * determined by the kind of object being transformed. These transformations are
- * performed through the transform() functions, and the type of object being
- * transformed is specified by their MappingType argument. See the documentation there
- * for possible choices.
+ * The differential forms <b>A</b> and <b>B</b> are determined by the kind of
+ * object being transformed. These transformations are performed through the
+ * transform() functions, and the type of object being transformed is
+ * specified by their MappingType argument. See the documentation there for
+ * possible choices.
*
* <h4>Derivatives of the mapping</h4>
*
- * Some applications require the derivatives of the mapping, of which the first order
- * derivative is the mapping Jacobian, $J_{iJ}(\hat{\mathbf x})=\frac{\partial x_i}{\partial \hat x_J}$,
- * described above. Higher order derivatives of the mapping are similarly
- * defined, for example the Jacobian derivative,
- * $\hat H_{iJK}(\hat{\mathbf x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial \hat x_K}$,
- * and the Jacobian second derivative,
- * $\hat K_{iJKL}(\hat{\mathbf x}) = \frac{\partial^3 x_i}{\partial \hat x_J \partial
- * \hat x_K \partial \hat x_L}$.
- * It is also useful to define the "pushed-forward" versions of the higher order derivatives:
- * the Jacobian pushed-forward
- * derivative, $H_{ijk}(\hat{\mathbf x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial
- * \hat x_K}(J_{jJ})^{-1}(J_{kK})^{-1}$,
- * and the Jacobian pushed-forward second derivative,
- * $K_{ijkl}(\hat{\mathbf x}) = \frac{\partial^3 x_i}{\partial \hat x_J \partial \hat x_K \partial
- * \hat x_L}(J_{jJ})^{-1}(J_{kK})^{-1}(J_{lL})^{-1}$.
- * These pushed-forward versions can be used to compute the higher order derivatives of functions
- * defined on the reference cell with respect to the
- * real cell coordinates. For instance, the Jacobian derivative with respect to the real cell coordinates is
- * given by:
+ * Some applications require the derivatives of the mapping, of which the
+ * first order derivative is the mapping Jacobian, $J_{iJ}(\hat{\mathbf
+ * x})=\frac{\partial x_i}{\partial \hat x_J}$, described above. Higher order
+ * derivatives of the mapping are similarly defined, for example the Jacobian
+ * derivative, $\hat H_{iJK}(\hat{\mathbf x}) = \frac{\partial^2
+ * x_i}{\partial \hat x_J \partial \hat x_K}$, and the Jacobian second
+ * derivative, $\hat K_{iJKL}(\hat{\mathbf x}) = \frac{\partial^3
+ * x_i}{\partial \hat x_J \partial \hat x_K \partial \hat x_L}$. It is also
+ * useful to define the "pushed-forward" versions of the higher order
+ * derivatives: the Jacobian pushed-forward derivative, $H_{ijk}(\hat{\mathbf
+ * x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial \hat
+ * x_K}(J_{jJ})^{-1}(J_{kK})^{-1}$, and the Jacobian pushed-forward second
+ * derivative, $K_{ijkl}(\hat{\mathbf x}) = \frac{\partial^3 x_i}{\partial
+ * \hat x_J \partial \hat x_K \partial \hat
+ * x_L}(J_{jJ})^{-1}(J_{kK})^{-1}(J_{lL})^{-1}$. These pushed-forward versions
+ * can be used to compute the higher order derivatives of functions defined on
+ * the reference cell with respect to the real cell coordinates. For instance,
+ * the Jacobian derivative with respect to the real cell coordinates is given
+ * by:
*
* @f[
* \frac{\partial}{\partial x_j}\left[J_{iJ}(\hat{\mathbf x})\right] =
* H_{ikn}(\hat{\mathbf x})J_{nJ}(\hat{\mathbf x}),
* @f]
- * and the derivative of the Jacobian inverse with respect to the real cell coordinates is similarly given by:
+ * and the derivative of the Jacobian inverse with respect to the real cell
+ * coordinates is similarly given by:
* @f[
* \frac{\partial}{\partial x_j}\left[\left(J_{iJ}(\hat{\mathbf x})\right)^{-1}\right]
* = -H_{nik}(\hat{\mathbf x})\left(J_{nJ}(\hat{\mathbf x})\right)^{-1}.
* @f]
*
- * In a similar fashion, higher order derivatives, with respect to the real cell coordinates, of functions
- * defined on the reference cell can
- * be defined using the Jacobian pushed-forward higher-order derivatives.
- * For example, the derivative, with respect to the real cell coordinates, of the Jacobian pushed-forward
- * derivative is given by:
+ * In a similar fashion, higher order derivatives, with respect to the real
+ * cell coordinates, of functions defined on the reference cell can be defined
+ * using the Jacobian pushed-forward higher-order derivatives. For example,
+ * the derivative, with respect to the real cell coordinates, of the Jacobian
+ * pushed-forward derivative is given by:
*
* @f[
* \frac{\partial}{\partial x_l}\left[H_{ijk}(\hat{\mathbf x})\right] = K_{ijkl}(\hat{\mathbf x})
get_vertices (const typename Triangulation<dim,spacedim>::cell_iterator &cell) const;
/**
- * Returns whether the mapping preserves vertex locations. In other
- * words, this function returns whether the
- * mapped location of the reference cell vertices (given by
- * GeometryInfo::unit_cell_vertex()) equals the result of
+ * Returns whether the mapping preserves vertex locations. In other words,
+ * this function returns whether the mapped location of the reference cell
+ * vertices (given by GeometryInfo::unit_cell_vertex()) equals the result of
* <code>cell-@>vertex()</code> (i.e., information stored by the
* triangulation).
*
* @param cell Iterator to the cell that will be used to define the mapping.
* @param p Location of a point on the reference cell.
* @return The location of the reference point mapped to real space using
- * the mapping defined by the class derived from the current one that
- * implements the mapping, and the coordinates of the cell identified by
- * the first argument.
+ * the mapping defined by the class derived from the current one that
+ * implements the mapping, and the coordinates of the cell identified by the
+ * first argument.
*/
virtual
Point<spacedim>
const Point<dim> &p) const = 0;
/**
- * Maps the point @p p on the real @p cell to the corresponding point
- * on the unit cell, and return its coordinates. This function provides
- * the inverse of the mapping provided by transform_unit_to_real_cell().
+ * Maps the point @p p on the real @p cell to the corresponding point on the
+ * unit cell, and return its coordinates. This function provides the inverse
+ * of the mapping provided by transform_unit_to_real_cell().
*
* In the codimension one case, this function returns the normal projection
* of the real point @p p on the curve or surface identified by the @p cell.
* @param cell Iterator to the cell that will be used to define the mapping.
* @param p Location of a point on the given cell.
* @return The reference cell location of the point that when mapped to real
- * space equals the coordinates given by the second argument. This mapping
- * uses the mapping defined by the class derived from the current one that
- * implements the mapping, and the coordinates of the cell identified by
- * the first argument.
+ * space equals the coordinates given by the second argument. This mapping
+ * uses the mapping defined by the class derived from the current one that
+ * implements the mapping, and the coordinates of the cell identified by the
+ * first argument.
*/
virtual
Point<dim>
* the given face number @p face_no. Ideally the point @p p is near the face
* @p face_no, but any point in the cell can technically be projected.
*
- * This function does not make physical sense when dim=1,
- * so it throws an exception in this case.
+ * This function does not make physical sense when dim=1, so it throws an
+ * exception in this case.
*/
Point<dim-1>
project_real_point_to_unit_point_on_face (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
public:
/**
- * Base class for internal data of mapping objects. The
- * internal mechanism is that upon construction of a FEValues object, it
- * asks the mapping and finite element classes that are to be used to
- * allocate memory for their own purpose in which they may store data that
- * only needs to be computed once. For example, most finite elements will
- * store the values of the shape functions at the quadrature points in this
- * object, since they do not change from cell to cell and only need to be
- * computed once. The same may be true for Mapping classes that want to
- * only evaluate the shape functions used for mapping once at the quadrature
- * points.
+ * Base class for internal data of mapping objects. The internal mechanism
+ * is that upon construction of a FEValues object, it asks the mapping and
+ * finite element classes that are to be used to allocate memory for their
+ * own purpose in which they may store data that only needs to be computed
+ * once. For example, most finite elements will store the values of the
+ * shape functions at the quadrature points in this object, since they do
+ * not change from cell to cell and only need to be computed once. The same
+ * may be true for Mapping classes that want to only evaluate the shape
+ * functions used for mapping once at the quadrature points.
*
- * Since different FEValues objects using different
- * quadrature rules might access the same mapping object at the same
- * time, it is necessary to create one such object per FEValues object.
- * FEValues does this by calling Mapping::get_data(), or in reality the
- * implementation of the corresponding function in derived classes.
- * Ownership of the object created by Mapping::get_data() is then transferred
- * to the FEValues object,
- * but a reference to this object is passed to the mapping object every
- * time it is asked to compute information on a concrete cell. This
+ * Since different FEValues objects using different quadrature rules might
+ * access the same mapping object at the same time, it is necessary to
+ * create one such object per FEValues object. FEValues does this by calling
+ * Mapping::get_data(), or in reality the implementation of the
+ * corresponding function in derived classes. Ownership of the object
+ * created by Mapping::get_data() is then transferred to the FEValues
+ * object, but a reference to this object is passed to the mapping object
+ * every time it is asked to compute information on a concrete cell. This
* happens when FEValues::reinit() (or the corresponding classes in
- * FEFaceValues and FESubfaceValues) call Mapping::fill_fe_values()
- * (and similarly via Mapping::fill_fe_face_values() and
+ * FEFaceValues and FESubfaceValues) call Mapping::fill_fe_values() (and
+ * similarly via Mapping::fill_fe_face_values() and
* Mapping::fill_fe_subface_values()).
*
* The purpose of this class is for mapping objects to store information
- * that can be computed once at the beginning, on the reference cell,
- * and to access it later when computing information on a concrete cell.
- * As such, the object handed to Mapping::fill_fe_values() is marked as
+ * that can be computed once at the beginning, on the reference cell, and to
+ * access it later when computing information on a concrete cell. As such,
+ * the object handed to Mapping::fill_fe_values() is marked as
* <code>const</code>, because the assumption is that at the time this
- * information is used, it will not need to modified again. However,
- * classes derived from Mapping can also use such objects for two other
- * purposes:
+ * information is used, it will not need to modified again. However, classes
+ * derived from Mapping can also use such objects for two other purposes:
*
* - To provide scratch space for computations that are done in
- * Mapping::fill_fe_values() and similar functions. Some of the
- * derived classes would like to use scratch arrays and it would
- * be a waste of time to allocate these arrays every time this
- * function is called, just to de-allocate it again at the end
- * of the function. Rather, one could allocate this memory once
- * as a member variable of the current class, and simply use
- * it in Mapping::fill_fe_values().
+ * Mapping::fill_fe_values() and similar functions. Some of the derived
+ * classes would like to use scratch arrays and it would be a waste of time
+ * to allocate these arrays every time this function is called, just to de-
+ * allocate it again at the end of the function. Rather, one could allocate
+ * this memory once as a member variable of the current class, and simply
+ * use it in Mapping::fill_fe_values().
* - After calling Mapping::fill_fe_values(), FEValues::reinit()
- * calls FiniteElement::fill_fe_values() where the finite element
- * computes values, gradients, etc of the shape functions using
- * both information computed once at the beginning using a mechanism
- * similar to the one described here (see FiniteElement::InternalDataBase)
- * as well as the data already computed by Mapping::fill_fe_values().
- * As part of its work, some implementations of
- * FiniteElement::fill_fe_values() need to transform shape function
- * data, and they do so by calling Mapping::transform(). The call
- * to the latter function also receives a reference to the
- * Mapping::InternalDataBase object. Since Mapping::transform()
- * may be called many times on each cell, it is sometimes worth
- * for derived classes to compute some information only once
- * in Mapping::fill_fe_values() and reuse it in
- * Mapping::transform(). This information can also be stored in
- * the classes that derived mapping classes derive from
- * InternalDataBase.
+ * calls FiniteElement::fill_fe_values() where the finite element computes
+ * values, gradients, etc of the shape functions using both information
+ * computed once at the beginning using a mechanism similar to the one
+ * described here (see FiniteElement::InternalDataBase) as well as the data
+ * already computed by Mapping::fill_fe_values(). As part of its work, some
+ * implementations of FiniteElement::fill_fe_values() need to transform
+ * shape function data, and they do so by calling Mapping::transform(). The
+ * call to the latter function also receives a reference to the
+ * Mapping::InternalDataBase object. Since Mapping::transform() may be
+ * called many times on each cell, it is sometimes worth for derived classes
+ * to compute some information only once in Mapping::fill_fe_values() and
+ * reuse it in Mapping::transform(). This information can also be stored in
+ * the classes that derived mapping classes derive from InternalDataBase.
*
- * In both of these cases, the InternalDataBase object being passed
- * around is "morally const", i.e., no external observer can tell
- * whether a scratch array or some intermediate data for
- * Mapping::transform() is being modified by Mapping::fill_fe_values()
- * or not. Consequently, the InternalDataBase objects are always
- * passed around as <code>const</code> objects. Derived classes
- * that would like to make use of the two additional uses outlined
- * above therefore need to mark the member variables they want to
- * use for these purposes as <code>mutable</code> to allow for their
- * modification despite the fact that the surrounding object is
- * marked as <code>const</code>.
+ * In both of these cases, the InternalDataBase object being passed around
+ * is "morally const", i.e., no external observer can tell whether a scratch
+ * array or some intermediate data for Mapping::transform() is being
+ * modified by Mapping::fill_fe_values() or not. Consequently, the
+ * InternalDataBase objects are always passed around as <code>const</code>
+ * objects. Derived classes that would like to make use of the two
+ * additional uses outlined above therefore need to mark the member
+ * variables they want to use for these purposes as <code>mutable</code> to
+ * allow for their modification despite the fact that the surrounding object
+ * is marked as <code>const</code>.
*/
class InternalDataBase
{
virtual ~InternalDataBase ();
/**
- * A set of update flags specifying the kind of information that
- * an implementation of the Mapping interface needs to compute on
- * each cell or face, i.e., in Mapping::fill_fe_values() and
- * friends.
+ * A set of update flags specifying the kind of information that an
+ * implementation of the Mapping interface needs to compute on each cell
+ * or face, i.e., in Mapping::fill_fe_values() and friends.
*
* This set of flags is stored here by implementations of
* Mapping::get_data(), Mapping::get_face_data(), or
- * Mapping::get_subface_data(), and is that subset of the update
- * flags passed to those functions that require re-computation on
- * every cell. (The subset of the flags corresponding to
- * information that can be computed once and for all already at
- * the time of the call to Mapping::get_data() -- or an
- * implementation of that interface -- need not be stored here
- * because it has already been taken care of.)
+ * Mapping::get_subface_data(), and is that subset of the update flags
+ * passed to those functions that require re-computation on every cell.
+ * (The subset of the flags corresponding to information that can be
+ * computed once and for all already at the time of the call to
+ * Mapping::get_data() -- or an implementation of that interface -- need
+ * not be stored here because it has already been taken care of.)
*/
UpdateFlags update_each;
/**
* Given a set of update flags, compute which other quantities <i>also</i>
* need to be computed in order to satisfy the request by the given flags.
- * Then return the combination of the original set of flags and those
- * just computed.
+ * Then return the combination of the original set of flags and those just
+ * computed.
*
- * As an example, if @p update_flags contains update_JxW_values
- * (i.e., the product of the determinant of the Jacobian and the
- * weights provided by the quadrature formula), a mapping may
- * require the computation of the full Jacobian matrix in order to
- * compute its determinant. They would then return not just
- * update_JxW_values, but also update_jacobians. (This is not how it
- * is actually done internally in the derived classes that compute
- * the JxW values -- they set update_contravariant_transformation
- * instead, from which the determinant can also be computed -- but
- * this does not take away from the instructiveness of the example.)
+ * As an example, if @p update_flags contains update_JxW_values (i.e., the
+ * product of the determinant of the Jacobian and the weights provided by
+ * the quadrature formula), a mapping may require the computation of the
+ * full Jacobian matrix in order to compute its determinant. They would then
+ * return not just update_JxW_values, but also update_jacobians. (This is
+ * not how it is actually done internally in the derived classes that
+ * compute the JxW values -- they set update_contravariant_transformation
+ * instead, from which the determinant can also be computed -- but this does
+ * not take away from the instructiveness of the example.)
*
* An extensive discussion of the interaction between this function and
* FEValues can be found in the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module.
+ * documentation module.
*
* @see UpdateFlags
*/
requires_update_flags (const UpdateFlags update_flags) const = 0;
/**
- * Create and return a pointer to an object into which mappings can
- * store data that only needs to be computed once but that can then
- * be used whenever the mapping is applied to a concrete cell (e.g.,
- * in the various transform() functions, as well as in the
- * fill_fe_values(), fill_fe_face_values() and fill_fe_subface_values()
- * that form the interface of mappings with the FEValues class).
+ * Create and return a pointer to an object into which mappings can store
+ * data that only needs to be computed once but that can then be used
+ * whenever the mapping is applied to a concrete cell (e.g., in the various
+ * transform() functions, as well as in the fill_fe_values(),
+ * fill_fe_face_values() and fill_fe_subface_values() that form the
+ * interface of mappings with the FEValues class).
*
- * Derived classes will return pointers to objects of a type
- * derived from Mapping::InternalDataBase (see there for more information)
- * and may pre-compute some information already (in accordance with what will
- * be asked of the mapping in the future, as specified by the update
- * flags) and for the given quadrature object. Subsequent calls to
- * transform() or fill_fe_values() and friends will then receive back the
- * object created here (with the same set of update flags and for the
- * same quadrature object). Derived classes can therefore pre-compute
- * some information in their get_data() function and store it in
- * the internal data object.
+ * Derived classes will return pointers to objects of a type derived from
+ * Mapping::InternalDataBase (see there for more information) and may pre-
+ * compute some information already (in accordance with what will be asked
+ * of the mapping in the future, as specified by the update flags) and for
+ * the given quadrature object. Subsequent calls to transform() or
+ * fill_fe_values() and friends will then receive back the object created
+ * here (with the same set of update flags and for the same quadrature
+ * object). Derived classes can therefore pre-compute some information in
+ * their get_data() function and store it in the internal data object.
*
- * The mapping classes do not keep track of the objects created by
- * this function. Ownership will therefore rest with the caller.
+ * The mapping classes do not keep track of the objects created by this
+ * function. Ownership will therefore rest with the caller.
*
* An extensive discussion of the interaction between this function and
* FEValues can be found in the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module.
+ * documentation module.
*
- * @param update_flags A set of flags that define what is expected of
- * the mapping class in future calls to transform() or the
- * fill_fe_values() group of functions. This set of flags may
- * contain flags that mappings do not know how to deal with
- * (e.g., for information that is in fact computed by the
- * finite element classes, such as UpdateFlags::update_values).
- * Derived classes will need to store these flags, or at least that
- * subset of flags that will require the mapping to perform any
- * actions in fill_fe_values(), in InternalDataBase::update_each.
- * @param quadrature The quadrature object for which mapping
- * information will have to be computed. This includes the
- * locations and weights of quadrature points.
- * @return A pointer to a newly created object of type
- * InternalDataBase (or a derived class). Ownership of this
- * object passes to the calling function.
+ * @param update_flags A set of flags that define what is expected of the
+ * mapping class in future calls to transform() or the fill_fe_values()
+ * group of functions. This set of flags may contain flags that mappings do
+ * not know how to deal with (e.g., for information that is in fact computed
+ * by the finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that subset
+ * of flags that will require the mapping to perform any actions in
+ * fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping information
+ * will have to be computed. This includes the locations and weights of
+ * quadrature points.
+ * @return A pointer to a newly created object of type InternalDataBase (or
+ * a derived class). Ownership of this object passes to the calling
+ * function.
*
- * @note C++ allows that virtual functions in derived classes
- * may return pointers to objects not of type InternalDataBase
- * but in fact pointers to objects of classes <i>derived</i>
- * from InternalDataBase. (This feature is called "covariant return
- * types".) This is useful in some contexts where the calling
- * is within the derived class and will immediately make use
- * of the returned object, knowing its real (derived) type.
+ * @note C++ allows that virtual functions in derived classes may return
+ * pointers to objects not of type InternalDataBase but in fact pointers to
+ * objects of classes <i>derived</i> from InternalDataBase. (This feature is
+ * called "covariant return types".) This is useful in some contexts where
+ * the calling is within the derived class and will immediately make use of
+ * the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
const Quadrature<dim> &quadrature) const = 0;
/**
- * Like get_data(), but in preparation for later calls to
- * transform() or fill_fe_face_values() that will need
- * information about mappings from the reference face to a
- * face of a concrete cell.
+ * Like get_data(), but in preparation for later calls to transform() or
+ * fill_fe_face_values() that will need information about mappings from the
+ * reference face to a face of a concrete cell.
*
- * @param update_flags A set of flags that define what is expected of
- * the mapping class in future calls to transform() or the
- * fill_fe_values() group of functions. This set of flags may
- * contain flags that mappings do not know how to deal with
- * (e.g., for information that is in fact computed by the
- * finite element classes, such as UpdateFlags::update_values).
- * Derived classes will need to store these flags, or at least that
- * subset of flags that will require the mapping to perform any
- * actions in fill_fe_values(), in InternalDataBase::update_each.
- * @param quadrature The quadrature object for which mapping
- * information will have to be computed. This includes the
- * locations and weights of quadrature points.
- * @return A pointer to a newly created object of type
- * InternalDataBase (or a derived class). Ownership of this
- * object passes to the calling function.
+ * @param update_flags A set of flags that define what is expected of the
+ * mapping class in future calls to transform() or the fill_fe_values()
+ * group of functions. This set of flags may contain flags that mappings do
+ * not know how to deal with (e.g., for information that is in fact computed
+ * by the finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that subset
+ * of flags that will require the mapping to perform any actions in
+ * fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping information
+ * will have to be computed. This includes the locations and weights of
+ * quadrature points.
+ * @return A pointer to a newly created object of type InternalDataBase (or
+ * a derived class). Ownership of this object passes to the calling
+ * function.
*
- * @note C++ allows that virtual functions in derived classes
- * may return pointers to objects not of type InternalDataBase
- * but in fact pointers to objects of classes <i>derived</i>
- * from InternalDataBase. (This feature is called "covariant return
- * types".) This is useful in some contexts where the calling
- * is within the derived class and will immediately make use
- * of the returned object, knowing its real (derived) type.
+ * @note C++ allows that virtual functions in derived classes may return
+ * pointers to objects not of type InternalDataBase but in fact pointers to
+ * objects of classes <i>derived</i> from InternalDataBase. (This feature is
+ * called "covariant return types".) This is useful in some contexts where
+ * the calling is within the derived class and will immediately make use of
+ * the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
const Quadrature<dim-1> &quadrature) const = 0;
/**
- * Like get_data() and get_face_data(), but in preparation for later calls to
- * transform() or fill_fe_subface_values() that will need
- * information about mappings from the reference face to a
- * child of a face (i.e., subface) of a concrete cell.
+ * Like get_data() and get_face_data(), but in preparation for later calls
+ * to transform() or fill_fe_subface_values() that will need information
+ * about mappings from the reference face to a child of a face (i.e.,
+ * subface) of a concrete cell.
*
- * @param update_flags A set of flags that define what is expected of
- * the mapping class in future calls to transform() or the
- * fill_fe_values() group of functions. This set of flags may
- * contain flags that mappings do not know how to deal with
- * (e.g., for information that is in fact computed by the
- * finite element classes, such as UpdateFlags::update_values).
- * Derived classes will need to store these flags, or at least that
- * subset of flags that will require the mapping to perform any
- * actions in fill_fe_values(), in InternalDataBase::update_each.
- * @param quadrature The quadrature object for which mapping
- * information will have to be computed. This includes the
- * locations and weights of quadrature points.
- * @return A pointer to a newly created object of type
- * InternalDataBase (or a derived class). Ownership of this
- * object passes to the calling function.
+ * @param update_flags A set of flags that define what is expected of the
+ * mapping class in future calls to transform() or the fill_fe_values()
+ * group of functions. This set of flags may contain flags that mappings do
+ * not know how to deal with (e.g., for information that is in fact computed
+ * by the finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that subset
+ * of flags that will require the mapping to perform any actions in
+ * fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping information
+ * will have to be computed. This includes the locations and weights of
+ * quadrature points.
+ * @return A pointer to a newly created object of type InternalDataBase (or
+ * a derived class). Ownership of this object passes to the calling
+ * function.
*
- * @note C++ allows that virtual functions in derived classes
- * may return pointers to objects not of type InternalDataBase
- * but in fact pointers to objects of classes <i>derived</i>
- * from InternalDataBase. (This feature is called "covariant return
- * types".) This is useful in some contexts where the calling
- * is within the derived class and will immediately make use
- * of the returned object, knowing its real (derived) type.
+ * @note C++ allows that virtual functions in derived classes may return
+ * pointers to objects not of type InternalDataBase but in fact pointers to
+ * objects of classes <i>derived</i> from InternalDataBase. (This feature is
+ * called "covariant return types".) This is useful in some contexts where
+ * the calling is within the derived class and will immediately make use of
+ * the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
const Quadrature<dim-1> &quadrature) const = 0;
/**
- * Compute information about the mapping from the reference cell
- * to the real cell indicated by the first argument to this function.
- * Derived classes will have to implement this function based on the
- * kind of mapping they represent. It is called by FEValues::reinit().
+ * Compute information about the mapping from the reference cell to the real
+ * cell indicated by the first argument to this function. Derived classes
+ * will have to implement this function based on the kind of mapping they
+ * represent. It is called by FEValues::reinit().
*
- * Conceptually, this function's represents the application of the
- * mapping $\mathbf x=\mathbf F_K(\hat {\mathbf x})$ from reference
- * coordinates $\mathbf\in [0,1]^d$ to real space coordinates
- * $\mathbf x$ for a given cell $K$. Its purpose is to compute the following
- * kinds of data:
+ * Conceptually, this function's represents the application of the mapping
+ * $\mathbf x=\mathbf F_K(\hat {\mathbf x})$ from reference coordinates
+ * $\mathbf\in [0,1]^d$ to real space coordinates $\mathbf x$ for a given
+ * cell $K$. Its purpose is to compute the following kinds of data:
*
* - Data that results from the application of the mapping itself, e.g.,
- * computing the location $\mathbf x_q = \mathbf F_K(\hat{\mathbf x}_q)$
- * of quadrature points on the real cell, and that is directly useful
- * to users of FEValues, for example during assembly.
+ * computing the location $\mathbf x_q = \mathbf F_K(\hat{\mathbf x}_q)$ of
+ * quadrature points on the real cell, and that is directly useful to users
+ * of FEValues, for example during assembly.
* - Data that is necessary for finite element implementations to compute
- * their shape functions on the real cell. To this end, the
- * FEValues::reinit() function calls FiniteElement::fill_fe_values()
- * after the current function, and the output of this function serves
- * as input to FiniteElement::fill_fe_values(). Examples of
- * information that needs to be computed here for use by the
- * finite element classes is the Jacobian of the mapping,
- * $\hat\nabla \mathbf F_K(\hat{\mathbf x})$ or its inverse,
- * for example to transform the gradients of shape functions on
- * the reference cell to the gradients of shape functions on
- * the real cell.
+ * their shape functions on the real cell. To this end, the
+ * FEValues::reinit() function calls FiniteElement::fill_fe_values() after
+ * the current function, and the output of this function serves as input to
+ * FiniteElement::fill_fe_values(). Examples of information that needs to be
+ * computed here for use by the finite element classes is the Jacobian of
+ * the mapping, $\hat\nabla \mathbf F_K(\hat{\mathbf x})$ or its inverse,
+ * for example to transform the gradients of shape functions on the
+ * reference cell to the gradients of shape functions on the real cell.
*
* The information computed by this function is used to fill the various
- * member variables of the output argument of this function. Which of
- * the member variables of that structure should be filled is determined
- * by the update flags stored in the Mapping::InternalDataBase object
- * passed to this function.
+ * member variables of the output argument of this function. Which of the
+ * member variables of that structure should be filled is determined by the
+ * update flags stored in the Mapping::InternalDataBase object passed to
+ * this function.
*
* An extensive discussion of the interaction between this function and
* FEValues can be found in the
* @ref FE_vs_Mapping_vs_FEValues
- * documentation
- * module.
+ * documentation module.
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] cell_similarity Whether or not the cell given as first
- * argument is simply a translation, rotation, etc of the cell for
- * which this function was called the most recent time. This
- * information is computed simply by matching the vertices (as stored
- * by the Triangulation) between the previous and the current cell.
- * The value passed here may be modified by implementations of
- * this function and should then be returned (see the discussion of the
- * return value of this function).
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * object is used both to map the location of quadrature points,
- * as well as to compute the JxW values for each quadrature
- * point (which involves the quadrature weights).
- * @param[in] internal_data A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the Mapping::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p internal_data object.
- * @return An updated value of the @p cell_similarity argument to
- * this function. The returned value will be used for the corresponding
- * argument when FEValues::reinit() calls
- * FiniteElement::fill_fe_values(). In most cases, derived classes will
- * simply want to return the value passed for @p cell_similarity.
- * However, implementations of this function may downgrade the
- * level of cell similarity. This is, for example, the case for
- * classes that take not only into account the locations of the
- * vertices of a cell (as reported by the Triangulation), but also
- * other information specific to the mapping. The purpose is that
- * FEValues::reinit() can compute whether a cell is similar to the
- * previous one only based on the cell's vertices, whereas the
- * mapping may also consider displacement fields (e.g., in the
- * MappingQ1Eulerian and MappingFEField classes). In such cases,
- * the mapping may conclude that the previously computed
- * cell similarity is too optimistic, and invalidate it for
- * subsequent use in FiniteElement::fill_fe_values() by
- * returning a less optimistic cell similarity value.
+ * argument is simply a translation, rotation, etc of the cell for which
+ * this function was called the most recent time. This information is
+ * computed simply by matching the vertices (as stored by the Triangulation)
+ * between the previous and the current cell. The value passed here may be
+ * modified by implementations of this function and should then be returned
+ * (see the discussion of the return value of this function).
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The object is used both
+ * to map the location of quadrature points, as well as to compute the JxW
+ * values for each quadrature point (which involves the quadrature weights).
+ * @param[in] internal_data A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * Mapping::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p internal_data object.
+ * @return An updated value of the @p cell_similarity argument to this
+ * function. The returned value will be used for the corresponding argument
+ * when FEValues::reinit() calls FiniteElement::fill_fe_values(). In most
+ * cases, derived classes will simply want to return the value passed for @p
+ * cell_similarity. However, implementations of this function may downgrade
+ * the level of cell similarity. This is, for example, the case for classes
+ * that take not only into account the locations of the vertices of a cell
+ * (as reported by the Triangulation), but also other information specific
+ * to the mapping. The purpose is that FEValues::reinit() can compute
+ * whether a cell is similar to the previous one only based on the cell's
+ * vertices, whereas the mapping may also consider displacement fields
+ * (e.g., in the MappingQ1Eulerian and MappingFEField classes). In such
+ * cases, the mapping may conclude that the previously computed cell
+ * similarity is too optimistic, and invalidate it for subsequent use in
+ * FiniteElement::fill_fe_values() by returning a less optimistic cell
+ * similarity value.
*
- * @note FEValues ensures that this function is always called with
- * the same pair of @p internal_data and @p output_data objects. In
- * other words, if an implementation of this function knows that it
- * has written a piece of data into the output argument in a previous
- * call, then there is no need to copy it there again in a later
- * call if the implementation knows that this is the same value.
+ * @note FEValues ensures that this function is always called with the same
+ * pair of @p internal_data and @p output_data objects. In other words, if
+ * an implementation of this function knows that it has written a piece of
+ * data into the output argument in a previous call, then there is no need
+ * to copy it there again in a later call if the implementation knows that
+ * this is the same value.
*/
virtual
CellSimilarity::Similarity
dealii::internal::FEValues::MappingRelatedData<dim,spacedim> &output_data) const = 0;
/**
- * This function is the equivalent to Mapping::fill_fe_values(),
- * but for faces of cells. See there for an extensive discussion
- * of its purpose. It is called by FEFaceValues::reinit().
+ * This function is the equivalent to Mapping::fill_fe_values(), but for
+ * faces of cells. See there for an extensive discussion of its purpose. It
+ * is called by FEFaceValues::reinit().
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] face_no The number of the face of the given cell for which
- * information is requested.
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * object is used both to map the location of quadrature points,
- * as well as to compute the JxW values for each quadrature
- * point (which involves the quadrature weights).
- * @param[in] internal_data A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the Mapping::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p internal_data object.
+ * information is requested.
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The object is used both
+ * to map the location of quadrature points, as well as to compute the JxW
+ * values for each quadrature point (which involves the quadrature weights).
+ * @param[in] internal_data A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * Mapping::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p internal_data object.
*/
virtual void
fill_fe_face_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
dealii::internal::FEValues::MappingRelatedData<dim,spacedim> &output_data) const = 0;
/**
- * This function is the equivalent to Mapping::fill_fe_values(),
- * but for subfaces (i.e., children of faces) of cells.
- * See there for an extensive discussion
- * of its purpose. It is called by FESubfaceValues::reinit().
+ * This function is the equivalent to Mapping::fill_fe_values(), but for
+ * subfaces (i.e., children of faces) of cells. See there for an extensive
+ * discussion of its purpose. It is called by FESubfaceValues::reinit().
*
- * @param[in] cell The cell of the triangulation for which this function
- * is to compute a mapping from the reference cell to.
+ * @param[in] cell The cell of the triangulation for which this function is
+ * to compute a mapping from the reference cell to.
* @param[in] face_no The number of the face of the given cell for which
- * information is requested.
- * @param[in] subface_no The number of the child of a face of the
- * given cell for which information is requested.
- * @param[in] quadrature A reference to the quadrature formula in use
- * for the current evaluation. This quadrature object is the same
- * as the one used when creating the @p internal_data object. The
- * object is used both to map the location of quadrature points,
- * as well as to compute the JxW values for each quadrature
- * point (which involves the quadrature weights).
- * @param[in] internal_data A reference to an object previously
- * created by get_data() and that may be used to store information
- * the mapping can compute once on the reference cell. See the
- * documentation of the Mapping::InternalDataBase class for an
- * extensive description of the purpose of these objects.
- * @param[out] output_data A reference to an object whose member
- * variables should be computed. Not all of the members of this
- * argument need to be filled; which ones need to be filled is
- * determined by the update flags stored inside the
- * @p internal_data object.
+ * information is requested.
+ * @param[in] subface_no The number of the child of a face of the given cell
+ * for which information is requested.
+ * @param[in] quadrature A reference to the quadrature formula in use for
+ * the current evaluation. This quadrature object is the same as the one
+ * used when creating the @p internal_data object. The object is used both
+ * to map the location of quadrature points, as well as to compute the JxW
+ * values for each quadrature point (which involves the quadrature weights).
+ * @param[in] internal_data A reference to an object previously created by
+ * get_data() and that may be used to store information the mapping can
+ * compute once on the reference cell. See the documentation of the
+ * Mapping::InternalDataBase class for an extensive description of the
+ * purpose of these objects.
+ * @param[out] output_data A reference to an object whose member variables
+ * should be computed. Not all of the members of this argument need to be
+ * filled; which ones need to be filled is determined by the update flags
+ * stored inside the @p internal_data object.
*/
virtual void
fill_fe_subface_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
*
* <li> @p mapping_covariant: maps a field of one-forms on the reference
* cell to a field of one-forms on the physical cell. (Theoretically this
- * would refer to a DerivativeForm<1,dim,1> but we canonically identify
- * this type with a Tensor<1,dim>). Mathematically, it is the pull back of the
+ * would refer to a DerivativeForm<1,dim,1> but we canonically identify this
+ * type with a Tensor<1,dim>). Mathematically, it is the pull back of the
* differential form
* @f[
* \mathbf u(\mathbf x) = J(\hat{\mathbf x})(J(\hat{\mathbf x})^{T} J(\hat{\mathbf x}))^{-1}\hat{\mathbf
* because we assume that the mapping $\mathbf F_K$ is always invertible,
* and consequently its Jacobian $J$ is an invertible matrix.
*
- * <li> @p mapping_piola: A field of <i>dim-1</i>-forms on the reference cell
- * is also represented by a vector field, but again transforms differently,
- * namely by the Piola transform
+ * <li> @p mapping_piola: A field of <i>dim-1</i>-forms on the reference
+ * cell is also represented by a vector field, but again transforms
+ * differently, namely by the Piola transform
* @f[
* \mathbf u(\mathbf x) = \frac{1}{\text{det}\;J(\mathbf x)}
* J(\mathbf x) \hat{\mathbf u}(\mathbf x).
* @f]
* </ul>
*
- * @param[in] input An array (or part of an array) of input objects that should
- * be mapped.
+ * @param[in] input An array (or part of an array) of input objects that
+ * should be mapped.
* @param[in] type The kind of mapping to be applied.
- * @param[in] internal A pointer to an object of type Mapping::InternalDataBase
- * that contains information previously stored by the mapping. The object
- * pointed to was created by the get_data(), get_face_data(), or
- * get_subface_data() function, and will have been updated as part of a
- * call to fill_fe_values(), fill_fe_face_values(), or fill_fe_subface_values()
- * for the current cell, before calling the current function. In other words,
- * this object also represents with respect to which cell the transformation
- * should be applied to.
- * @param[out] output An array (or part of an array) into which the transformed
- * objects should be placed. (Note that the array view is @p const, but the
- * tensors it points to are not.)
+ * @param[in] internal A pointer to an object of type
+ * Mapping::InternalDataBase that contains information previously stored by
+ * the mapping. The object pointed to was created by the get_data(),
+ * get_face_data(), or get_subface_data() function, and will have been
+ * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
+ * fill_fe_subface_values() for the current cell, before calling the current
+ * function. In other words, this object also represents with respect to
+ * which cell the transformation should be applied to.
+ * @param[out] output An array (or part of an array) into which the
+ * transformed objects should be placed. (Note that the array view is @p
+ * const, but the tensors it points to are not.)
*/
virtual
void
/**
* Transform a field of differential forms from the reference cell to the
- * physical cell. It is useful to think of $\mathbf{T} = \nabla \mathbf u$ and
- * $\hat{\mathbf T} = \hat \nabla \hat{\mathbf u}$, with $\mathbf u$ a vector
- * field. The mapping types currently implemented by derived classes are:
+ * physical cell. It is useful to think of $\mathbf{T} = \nabla \mathbf u$
+ * and $\hat{\mathbf T} = \hat \nabla \hat{\mathbf u}$, with $\mathbf u$ a
+ * vector field. The mapping types currently implemented by derived classes
+ * are:
* <ul>
* <li> @p mapping_covariant: maps a field of forms on the reference cell to
* a field of forms on the physical cell. Mathematically, it is the pull
* 1@></code> with a <code>Tensor@<1,dim@></code> when using
* mapping_covariant() in the function transform() above this one.
*
- * @param[in] input An array (or part of an array) of input objects that should
- * be mapped.
+ * @param[in] input An array (or part of an array) of input objects that
+ * should be mapped.
* @param[in] type The kind of mapping to be applied.
- * @param[in] internal A pointer to an object of type Mapping::InternalDataBase
- * that contains information previously stored by the mapping. The object
- * pointed to was created by the get_data(), get_face_data(), or
- * get_subface_data() function, and will have been updated as part of a
- * call to fill_fe_values(), fill_fe_face_values(), or fill_fe_subface_values()
- * for the current cell, before calling the current function. In other words,
- * this object also represents with respect to which cell the transformation
- * should be applied to.
- * @param[out] output An array (or part of an array) into which the transformed
- * objects should be placed. (Note that the array view is @p const, but the
- * tensors it points to are not.)
+ * @param[in] internal A pointer to an object of type
+ * Mapping::InternalDataBase that contains information previously stored by
+ * the mapping. The object pointed to was created by the get_data(),
+ * get_face_data(), or get_subface_data() function, and will have been
+ * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
+ * fill_fe_subface_values() for the current cell, before calling the current
+ * function. In other words, this object also represents with respect to
+ * which cell the transformation should be applied to.
+ * @param[out] output An array (or part of an array) into which the
+ * transformed objects should be placed. (Note that the array view is @p
+ * const, but the tensors it points to are not.)
*/
virtual
void
/**
* Transform a tensor field from the reference cell to the physical cell.
- * These tensors are usually the Jacobians in the reference cell of
- * vector fields that have been pulled back from the physical cell. The
- * mapping types currently implemented by derived classes are:
+ * These tensors are usually the Jacobians in the reference cell of vector
+ * fields that have been pulled back from the physical cell. The mapping
+ * types currently implemented by derived classes are:
* <ul>
* <li> @p mapping_contravariant_gradient: it assumes $\mathbf u(\mathbf x)
* = J \hat{\mathbf u}$ so that
* J(\hat{\mathbf x})^{-1}.
* @f]
* <li> @p mapping_piola_gradient: it assumes $\mathbf u(\mathbf x) =
- * \frac{1}{\text{det}\;J(\mathbf x)} J(\mathbf x) \hat{\mathbf u}(\mathbf x)$
- * so that
+ * \frac{1}{\text{det}\;J(\mathbf x)} J(\mathbf x) \hat{\mathbf u}(\mathbf
+ * x)$ so that
* @f[
* \mathbf T(\mathbf x) =
* \frac{1}{\text{det}\;J(\mathbf x)}
* </ul>
*
* @todo The formulas for mapping_covariant_gradient,
- * mapping_contravariant_gradient and mapping_piola_gradient are only
- * true as stated for linear mappings. If, for example, the mapping is
- * bilinear (or has a higher order polynomial degree) then there is a
- * missing term associated with the derivative of $J$.
+ * mapping_contravariant_gradient and mapping_piola_gradient are only true
+ * as stated for linear mappings. If, for example, the mapping is bilinear
+ * (or has a higher order polynomial degree) then there is a missing term
+ * associated with the derivative of $J$.
*
- * @param[in] input An array (or part of an array) of input objects that should
- * be mapped.
+ * @param[in] input An array (or part of an array) of input objects that
+ * should be mapped.
* @param[in] type The kind of mapping to be applied.
- * @param[in] internal A pointer to an object of type Mapping::InternalDataBase
- * that contains information previously stored by the mapping. The object
- * pointed to was created by the get_data(), get_face_data(), or
- * get_subface_data() function, and will have been updated as part of a
- * call to fill_fe_values(), fill_fe_face_values(), or fill_fe_subface_values()
- * for the current cell, before calling the current function. In other words,
- * this object also represents with respect to which cell the transformation
- * should be applied to.
- * @param[out] output An array (or part of an array) into which the transformed
- * objects should be placed. (Note that the array view is @p const, but the
- * tensors it points to are not.)
+ * @param[in] internal A pointer to an object of type
+ * Mapping::InternalDataBase that contains information previously stored by
+ * the mapping. The object pointed to was created by the get_data(),
+ * get_face_data(), or get_subface_data() function, and will have been
+ * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
+ * fill_fe_subface_values() for the current cell, before calling the current
+ * function. In other words, this object also represents with respect to
+ * which cell the transformation should be applied to.
+ * @param[out] output An array (or part of an array) into which the
+ * transformed objects should be placed. (Note that the array view is @p
+ * const, but the tensors it points to are not.)
*/
virtual
void
*
* The mapping types currently implemented by derived classes are:
* <ul>
- * <li> @p mapping_covariant_gradient: maps a field of forms on the reference cell to
- * a field of forms on the physical cell. Mathematically, it is the pull
- * back of the differential form
+ * <li> @p mapping_covariant_gradient: maps a field of forms on the
+ * reference cell to a field of forms on the physical cell. Mathematically,
+ * it is the pull back of the differential form
* @f[
* \mathbf T_{ijk}(\mathbf x) = \hat{\mathbf T}_{iJK}(\hat{\mathbf x}) J_{jJ}^{\dagger} J_{kK}^{\dagger}@f],
*
* </ul>
*
* Hessians of spacedim-vector valued differentiable functions are
- * transformed this way (After subtraction of the product of the
- * derivative with the Jacobian gradient).
+ * transformed this way (After subtraction of the product of the derivative
+ * with the Jacobian gradient).
*
* In the case when dim=spacedim the previous formula reduces to
* @f[J^{\dagger} = J^{-1}@f]
*
- * @param[in] input An array (or part of an array) of input objects that should
- * be mapped.
+ * @param[in] input An array (or part of an array) of input objects that
+ * should be mapped.
* @param[in] type The kind of mapping to be applied.
- * @param[in] internal A pointer to an object of type Mapping::InternalDataBase
- * that contains information previously stored by the mapping. The object
- * pointed to was created by the get_data(), get_face_data(), or
- * get_subface_data() function, and will have been updated as part of a
- * call to fill_fe_values(), fill_fe_face_values(), or fill_fe_subface_values()
- * for the current cell, before calling the current function. In other words,
- * this object also represents with respect to which cell the transformation
- * should be applied to.
- * @param[out] output An array (or part of an array) into which the transformed
- * objects should be placed. (Note that the array view is @p const, but the
- * tensors it points to are not.)
+ * @param[in] internal A pointer to an object of type
+ * Mapping::InternalDataBase that contains information previously stored by
+ * the mapping. The object pointed to was created by the get_data(),
+ * get_face_data(), or get_subface_data() function, and will have been
+ * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
+ * fill_fe_subface_values() for the current cell, before calling the current
+ * function. In other words, this object also represents with respect to
+ * which cell the transformation should be applied to.
+ * @param[out] output An array (or part of an array) into which the
+ * transformed objects should be placed. (Note that the array view is @p
+ * const, but the tensors it points to are not.)
*/
virtual
void
/**
* Transform a field of 3-differential forms from the reference cell to the
- * physical cell. It is useful to think of $\mathbf{T}_{ijk} = D^2_{jk} \mathbf u_i$ and
- * $\mathbf{\hat T}_{IJK} = \hat D^2_{JK} \mathbf{\hat u}_I$, with $\mathbf u_i$ a vector
- * field.
+ * physical cell. It is useful to think of $\mathbf{T}_{ijk} = D^2_{jk}
+ * \mathbf u_i$ and $\mathbf{\hat T}_{IJK} = \hat D^2_{JK} \mathbf{\hat
+ * u}_I$, with $\mathbf u_i$ a vector field.
*
* The mapping types currently implemented by derived classes are:
* <ul>
* J_{jJ}(\hat{\mathbf x})^{-1} J_{kK}(\hat{\mathbf x})^{-1}.
* @f]
* <li> @p mapping_piola_hessian: it assumes $\mathbf u_i(\mathbf x) =
- * \frac{1}{\text{det}\;J(\mathbf x)} J_{iI}(\mathbf x) \hat{\mathbf u}(\mathbf x)$
- * so that
+ * \frac{1}{\text{det}\;J(\mathbf x)} J_{iI}(\mathbf x) \hat{\mathbf
+ * u}(\mathbf x)$ so that
* @f[
* \mathbf T_{ijk}(\mathbf x) =
* \frac{1}{\text{det}\;J(\mathbf x)}
* @f]
* </ul>
*
- * @param[in] input An array (or part of an array) of input objects that should
- * be mapped.
+ * @param[in] input An array (or part of an array) of input objects that
+ * should be mapped.
* @param[in] type The kind of mapping to be applied.
- * @param[in] internal A pointer to an object of type Mapping::InternalDataBase
- * that contains information previously stored by the mapping. The object
- * pointed to was created by the get_data(), get_face_data(), or
- * get_subface_data() function, and will have been updated as part of a
- * call to fill_fe_values(), fill_fe_face_values(), or fill_fe_subface_values()
- * for the current cell, before calling the current function. In other words,
- * this object also represents with respect to which cell the transformation
- * should be applied to.
- * @param[out] output An array (or part of an array) into which the transformed
- * objects should be placed.
+ * @param[in] internal A pointer to an object of type
+ * Mapping::InternalDataBase that contains information previously stored by
+ * the mapping. The object pointed to was created by the get_data(),
+ * get_face_data(), or get_subface_data() function, and will have been
+ * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
+ * fill_fe_subface_values() for the current cell, before calling the current
+ * function. In other words, this object also represents with respect to
+ * which cell the transformation should be applied to.
+ * @param[out] output An array (or part of an array) into which the
+ * transformed objects should be placed.
*/
virtual
void
protected:
/**
- * A class derived from MappingQGeneric that provides the generic
- * mapping with support points on boundary objects so that the
- * corresponding Q3 mapping ends up being C1.
+ * A class derived from MappingQGeneric that provides the generic mapping
+ * with support points on boundary objects so that the corresponding Q3
+ * mapping ends up being C1.
*/
class MappingC1Generic : public MappingQGeneric<dim,spacedim>
{
/**
* For <tt>dim=2,3</tt>. Append the support points of all shape functions
- * located on bounding lines to the vector @p a. Points located on the line
- * but on vertices are not included.
+ * located on bounding lines to the vector @p a. Points located on the
+ * line but on vertices are not included.
*
- * Needed by the <tt>compute_support_points_simple(laplace)</tt> functions.
- * For <tt>dim=1</tt> this function is empty.
+ * Needed by the <tt>compute_support_points_simple(laplace)</tt>
+ * functions. For <tt>dim=1</tt> this function is empty.
*
* This function chooses the respective points not such that they are
- * interpolating the boundary (as does the base class), but rather such that
- * the resulting cubic mapping is a continuous one.
+ * interpolating the boundary (as does the base class), but rather such
+ * that the resulting cubic mapping is a continuous one.
*/
virtual void
add_line_support_points (const typename Triangulation<dim>::cell_iterator &cell,
* <tt>dim=1</tt> and 2 this function is empty.
*
* This function chooses the respective points not such that they are
- * interpolating the boundary (as does the base class), but rather such that
- * the resulting cubic mapping is a continuous one.
+ * interpolating the boundary (as does the base class), but rather such
+ * that the resulting cubic mapping is a continuous one.
*/
virtual void
add_quad_support_points(const typename Triangulation<dim>::cell_iterator &cell,
* {\mathbf x}(\hat {\mathbf x}) = \begin{pmatrix} h_x & 0 & 0 \\ 0 & h_y & 0
* \\ 0 & 0 & h_z \end{pmatrix} \hat{\mathbf x} + {\mathbf v}_0
* @f}
- * in 3d,
- * where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$ are the
- * extents of the cell along the axes.
+ * in 3d, where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$
+ * are the extents of the cell along the axes.
*
* The class is intended for efficiency, and it does not do a whole lot of
* error checking. If you apply this mapping to a cell that does not conform
* Storage for internal data of the mapping. See Mapping::InternalDataBase
* for an extensive description.
*
- * This includes data that is computed once when the object is created
- * (in get_data()) as well as data the class wants to store from between
- * the call to fill_fe_values(), fill_fe_face_values(), or
+ * This includes data that is computed once when the object is created (in
+ * get_data()) as well as data the class wants to store from between the
+ * call to fill_fe_values(), fill_fe_face_values(), or
* fill_fe_subface_values() until possible later calls from the finite
- * element to functions such as transform(). The latter class of
- * member variables are marked as 'mutable'.
+ * element to functions such as transform(). The latter class of member
+ * variables are marked as 'mutable'.
*/
class InternalData : public Mapping<dim, spacedim>::InternalDataBase
{
* Storage for internal data of this mapping. See Mapping::InternalDataBase
* for an extensive description.
*
- * This includes data that is computed once when the object is created
- * (in get_data()) as well as data the class wants to store from between
- * the call to fill_fe_values(), fill_fe_face_values(), or
+ * This includes data that is computed once when the object is created (in
+ * get_data()) as well as data the class wants to store from between the
+ * call to fill_fe_values(), fill_fe_face_values(), or
* fill_fe_subface_values() until possible later calls from the finite
- * element to functions such as transform(). The latter class of
- * member variables are marked as 'mutable', along with scratch arrays.
+ * element to functions such as transform(). The latter class of member
+ * variables are marked as 'mutable', along with scratch arrays.
*/
class InternalData : public Mapping<dim,spacedim>::InternalDataBase
{
const typename MappingFEField<dim, spacedim>::InternalData &data) const;
/**
- * See the documentation of the base class for
- * detailed information.
+ * See the documentation of the base class for detailed information.
*/
virtual void
compute_shapes_virtual (const std::vector<Point<dim> > &unit_points,
/**
* A class that implements a polynomial mapping $Q_p$ of degree $p$ on cells
- * at the boundary of the domain (or, if requested in the constructor,
- * for all cells) and linear mappings for interior cells.
+ * at the boundary of the domain (or, if requested in the constructor, for all
+ * cells) and linear mappings for interior cells.
*
- * The class is in fact poorly named since (unless explicitly specified
- * during the construction of the object, see below), it does not actually use
+ * The class is in fact poorly named since (unless explicitly specified during
+ * the construction of the object, see below), it does not actually use
* mappings of degree $p$ <i>everywhere</i>, but only on cells at the
* boundary. This is in contrast to the MappingQGeneric class which indeed
- * does use a polynomial mapping $Q_p$ of degree $p$ everywhere. The point
- * of the current class is that in many situations, curved domains
- * are only provided with information about how exactly edges at the
- * boundary are shaped, but we do not know anything about internal
- * edges. Thus, in the absence of other information, we can only assume
- * that internal edges are straight lines, and in that case internal
- * cells may as well be treated is bilinear quadrilaterals or trilinear
- * hexahedra. (An example of how such meshes look is shown in step-1
- * already, but it is also discussed in the "Results" section of step-6.)
- * Because bi-/trilinear mappings are significantly cheaper to compute
- * than higher order mappings, it is advantageous in such situations
- * to use the higher order mapping only on cells at the boundary of the
- * domain. This class implements exactly this behavior.
+ * does use a polynomial mapping $Q_p$ of degree $p$ everywhere. The point of
+ * the current class is that in many situations, curved domains are only
+ * provided with information about how exactly edges at the boundary are
+ * shaped, but we do not know anything about internal edges. Thus, in the
+ * absence of other information, we can only assume that internal edges are
+ * straight lines, and in that case internal cells may as well be treated is
+ * bilinear quadrilaterals or trilinear hexahedra. (An example of how such
+ * meshes look is shown in step-1 already, but it is also discussed in the
+ * "Results" section of step-6.) Because bi-/trilinear mappings are
+ * significantly cheaper to compute than higher order mappings, it is
+ * advantageous in such situations to use the higher order mapping only on
+ * cells at the boundary of the domain. This class implements exactly this
+ * behavior.
*
* There are a number of special cases worth considering:
* - If you want to use a higher order mapping for all cells, you can
- * achieve this by setting the second argument to the constructor
- * to true. This only makes sense if you can actually provide
- * information about how interior edges and faces of the mesh
- * should be curved. This is typically done by associating
- * a Manifold with interior cells and edges. A simple example of this
- * is discussed in the "Results" section of step-6; a full discussion
- * of manifolds is provided in step-53.
+ * achieve this by setting the second argument to the constructor to true.
+ * This only makes sense if you can actually provide information about how
+ * interior edges and faces of the mesh should be curved. This is typically
+ * done by associating a Manifold with interior cells and edges. A simple
+ * example of this is discussed in the "Results" section of step-6; a full
+ * discussion of manifolds is provided in step-53.
* - If you pass true as the second argument to this class, then it
- * is in fact completely equivalent to generating a
- * MappingQGeneric object right away.
+ * is in fact completely equivalent to generating a MappingQGeneric object
+ * right away.
* - This class is also entirely equivalent to MappingQGeneric if the
- * polynomial degree provided is one. This is because in that case,
- * no distinction between the mapping used on cells in the interior
- * and on the boundary of the domain can be made.
+ * polynomial degree provided is one. This is because in that case, no
+ * distinction between the mapping used on cells in the interior and on the
+ * boundary of the domain can be made.
* - If you are working on meshes embedded in higher space dimensions,
- * i.e., if dim!=spacedim, then every cell is considered to be
- * at the boundary of the domain and consequently a higher order
- * mapping is used for all cells; again this class is then equivalent
- * to using MappingQGeneric right away.
+ * i.e., if dim!=spacedim, then every cell is considered to be at the boundary
+ * of the domain and consequently a higher order mapping is used for all
+ * cells; again this class is then equivalent to using MappingQGeneric right
+ * away.
*
- * @author Ralf Hartmann, 2000, 2001, 2005; Guido Kanschat 2000, 2001, Wolfgang Bangerth, 2015
+ * @author Ralf Hartmann, 2000, 2001, 2005; Guido Kanschat 2000, 2001,
+ * Wolfgang Bangerth, 2015
*/
template <int dim, int spacedim=dim>
class MappingQ : public Mapping<dim,spacedim>
{
public:
/**
- * Constructor. @p polynomial_degree denotes the polynomial degree
- * of the polynomials that are used to map cells boundary.
+ * Constructor. @p polynomial_degree denotes the polynomial degree of the
+ * polynomials that are used to map cells boundary.
*
* The second argument determines whether the higher order mapping should
* also be used on interior cells. If its value is <code>false</code> (the
unsigned int get_degree () const;
/**
- * Always returns @p true because the default implementation of
- * functions in this class preserves vertex locations.
+ * Always returns @p true because the default implementation of functions in
+ * this class preserves vertex locations.
*/
virtual
bool preserves_vertex_locations () const;
* Storage for internal data of this mapping. See Mapping::InternalDataBase
* for an extensive description.
*
- * This includes data that is computed once when the object is created
- * (in get_data()) as well as data the class wants to store from between
- * the call to fill_fe_values(), fill_fe_face_values(), or
+ * This includes data that is computed once when the object is created (in
+ * get_data()) as well as data the class wants to store from between the
+ * call to fill_fe_values(), fill_fe_face_values(), or
* fill_fe_subface_values() until possible later calls from the finite
- * element to functions such as transform(). The latter class of
- * member variables are marked as 'mutable'.
+ * element to functions such as transform(). The latter class of member
+ * variables are marked as 'mutable'.
*
- * The current class uses essentially the same fields for storage
- * as the MappingQGeneric class. Consequently, it inherits from
- * MappingQGeneric::InternalData, rather than from Mapping::InternalDataBase.
- * The principal difference to MappingQGeneric::InternalData is that
- * MappingQ switches between $Q_1$ and $Q_p$ mappings depending
- * on the cell we are on, so the internal data object needs to
- * also store a pointer to an InternalData object that pertains
- * to a $Q_1$ mapping.
+ * The current class uses essentially the same fields for storage as the
+ * MappingQGeneric class. Consequently, it inherits from
+ * MappingQGeneric::InternalData, rather than from
+ * Mapping::InternalDataBase. The principal difference to
+ * MappingQGeneric::InternalData is that MappingQ switches between $Q_1$ and
+ * $Q_p$ mappings depending on the cell we are on, so the internal data
+ * object needs to also store a pointer to an InternalData object that
+ * pertains to a $Q_1$ mapping.
*/
class InternalData : public Mapping<dim,spacedim>::InternalDataBase
{
mutable bool use_mapping_q1_on_current_cell;
/**
- * A pointer to a structure to store the information for the pure
- * $Q_1$ mapping that is, by default, used on all interior cells.
+ * A pointer to a structure to store the information for the pure $Q_1$
+ * mapping that is, by default, used on all interior cells.
*/
std_cxx11::unique_ptr<typename MappingQGeneric<dim,spacedim>::InternalData> mapping_q1_data;
/**
- * A pointer to a structure to store the information for the full
- * $Q_p$ mapping that is, by default, used on all boundary cells.
+ * A pointer to a structure to store the information for the full $Q_p$
+ * mapping that is, by default, used on all boundary cells.
*/
std_cxx11::unique_ptr<typename MappingQGeneric<dim,spacedim>::InternalData> mapping_qp_data;
};
/**
* Pointer to a Q1 mapping. This mapping is used on interior cells unless
- * use_mapping_q_on_all_cells was set in the call to the
- * constructor. The mapping is also used on any cell in the
- * transform_real_to_unit_cell() to compute a cheap initial
- * guess for the position of the point before we employ the
- * more expensive Newton iteration using the full mapping.
+ * use_mapping_q_on_all_cells was set in the call to the constructor. The
+ * mapping is also used on any cell in the transform_real_to_unit_cell() to
+ * compute a cheap initial guess for the position of the point before we
+ * employ the more expensive Newton iteration using the full mapping.
*
* @note MappingQEulerian resets this pointer to an object of type
- * MappingQ1Eulerian to ensure that the Q1 mapping also knows
- * about the proper shifts and transformations of the Eulerian
- * displacements. This also means that we really need to store
- * our own Q1 mapping here, rather than simply resorting to
- * StaticMappingQ1::mapping.
+ * MappingQ1Eulerian to ensure that the Q1 mapping also knows about the
+ * proper shifts and transformations of the Eulerian displacements. This
+ * also means that we really need to store our own Q1 mapping here, rather
+ * than simply resorting to StaticMappingQ1::mapping.
*
- * @note If the polynomial degree used for the current object is one,
- * then the qp_mapping and q1_mapping variables point to the same
- * underlying object.
+ * @note If the polynomial degree used for the current object is one, then
+ * the qp_mapping and q1_mapping variables point to the same underlying
+ * object.
*/
std_cxx11::shared_ptr<const MappingQGeneric<dim,spacedim> > q1_mapping;
/**
* Pointer to a Q_p mapping. This mapping is used on boundary cells unless
- * use_mapping_q_on_all_cells was set in the call to the
- * constructor (in which case it is used for all cells).
+ * use_mapping_q_on_all_cells was set in the call to the constructor (in
+ * which case it is used for all cells).
*
* @note MappingQEulerian and MappingC1 reset this pointer to an object of
- * their own implementation to ensure that the Q_p mapping also knows
- * about the proper shifts and transformations of the Eulerian
- * displacements (Eulerian case) and proper choice of support
- * points (C1 case).
+ * their own implementation to ensure that the Q_p mapping also knows about
+ * the proper shifts and transformations of the Eulerian displacements
+ * (Eulerian case) and proper choice of support points (C1 case).
*
- * @note If the polynomial degree used for the current object is one,
- * then the qp_mapping and q1_mapping variables point to the same
- * underlying object.
+ * @note If the polynomial degree used for the current object is one, then
+ * the qp_mapping and q1_mapping variables point to the same underlying
+ * object.
*/
std_cxx11::shared_ptr<const MappingQGeneric<dim,spacedim> > qp_mapping;
};
* Implementation of a $d$-linear mapping from the reference cell to a general
* quadrilateral/hexahedron.
*
- * The mapping implemented by this class maps the reference (unit) cell
- * to a general grid cell with
- * straight lines in $d$ dimensions. (Note, however, that in 3D the
- * <i>faces</i> of a general, trilinearly mapped cell may be curved, even if the
- * edges are not). This is the standard mapping used for polyhedral domains. It
- * is also the mapping used throughout deal.II for many functions that come in
- * two variants, one that allows to pass a mapping argument explicitly and one
- * that simply falls back to the MappingQ1 class declared here. (Or, in fact,
- * to an object of kind MappingQGeneric(1), which implements exactly the
- * functionality of this class.)
+ * The mapping implemented by this class maps the reference (unit) cell to a
+ * general grid cell with straight lines in $d$ dimensions. (Note, however,
+ * that in 3D the <i>faces</i> of a general, trilinearly mapped cell may be
+ * curved, even if the edges are not). This is the standard mapping used for
+ * polyhedral domains. It is also the mapping used throughout deal.II for many
+ * functions that come in two variants, one that allows to pass a mapping
+ * argument explicitly and one that simply falls back to the MappingQ1 class
+ * declared here. (Or, in fact, to an object of kind MappingQGeneric(1), which
+ * implements exactly the functionality of this class.)
*
- * The shape functions for this mapping are the same as for the finite
- * element FE_Q of polynomial degree 1. Therefore, coupling these two
- * yields an isoparametric element.
+ * The shape functions for this mapping are the same as for the finite element
+ * FE_Q of polynomial degree 1. Therefore, coupling these two yields an
+ * isoparametric element.
*
- * @note This class is, in all reality, nothing more than a different
- * name for calling MappingQGeneric with a polynomial degree of one as
- * argument.
+ * @note This class is, in all reality, nothing more than a different name for
+ * calling MappingQGeneric with a polynomial degree of one as argument.
*
- * @author Guido Kanschat, 2000, 2001; Ralf Hartmann, 2000, 2001, 2005, Wolfgang Bangerth, 2015
+ * @author Guido Kanschat, 2000, 2001; Ralf Hartmann, 2000, 2001, 2005,
+ * Wolfgang Bangerth, 2015
*/
template <int dim, int spacedim=dim>
class MappingQ1 : public MappingQGeneric<dim,spacedim>
/**
- * Many places in the library by default use (bi-,tri-)linear mappings
- * unless users explicitly provide a different mapping to use. In these
- * cases, the called function has to create a $Q_1$ mapping object, i.e.,
- * an object of kind MappingQGeneric(1). This is costly. It would also be
- * costly to create such objects as static objects in the affected
- * functions, because static objects are never destroyed throughout the
- * lifetime of a program, even though they only have to be created once
- * the first time code runs through a particular function.
+ * Many places in the library by default use (bi-,tri-)linear mappings unless
+ * users explicitly provide a different mapping to use. In these cases, the
+ * called function has to create a $Q_1$ mapping object, i.e., an object of
+ * kind MappingQGeneric(1). This is costly. It would also be costly to create
+ * such objects as static objects in the affected functions, because static
+ * objects are never destroyed throughout the lifetime of a program, even
+ * though they only have to be created once the first time code runs through a
+ * particular function.
*
- * In order to avoid creation of (static or dynamic) $Q_1$ mapping objects
- * in these contexts throughout the library, this class defines a static
- * $Q_1$ mapping object. This object can then be used in all of those
- * places where such an object is needed.
+ * In order to avoid creation of (static or dynamic) $Q_1$ mapping objects in
+ * these contexts throughout the library, this class defines a static $Q_1$
+ * mapping object. This object can then be used in all of those places where
+ * such an object is needed.
*/
template <int dim, int spacedim=dim>
struct StaticMappingQ1
{
/**
- * The static $Q_1$ mapping object discussed in the documentation
- * of this class.
+ * The static $Q_1$ mapping object discussed in the documentation of this
+ * class.
*/
static MappingQGeneric<dim, spacedim> mapping;
};
const DoFHandler<dim,spacedim> &shiftmap_dof_handler);
/**
- * Return the mapped vertices of the cell. For the current class, this function does
- * not use the support points from the geometry of the current cell but
- * instead evaluates an externally given displacement field in addition to
- * the geometry of the cell.
+ * Return the mapped vertices of the cell. For the current class, this
+ * function does not use the support points from the geometry of the current
+ * cell but instead evaluates an externally given displacement field in
+ * addition to the geometry of the cell.
*/
virtual
std_cxx11::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell>
protected:
/**
- * Compute mapping-related information for a cell.
- * See the documentation of Mapping::fill_fe_values() for
- * a discussion of purpose, arguments, and return value of this function.
+ * Compute mapping-related information for a cell. See the documentation of
+ * Mapping::fill_fe_values() for a discussion of purpose, arguments, and
+ * return value of this function.
*
- * This function overrides the function in
- * the base class since we cannot use any cell similarity for this class.
+ * This function overrides the function in the base class since we cannot
+ * use any cell similarity for this class.
*/
virtual
CellSimilarity::Similarity
internal::FEValues::MappingRelatedData<dim,spacedim> &output_data) const;
/**
- * Compute the support points of the mapping. For the current class, these are
- * the vertices, as obtained by calling Mapping::get_vertices().
- * See the documentation of MappingQGeneric::compute_mapping_support_points()
- * for more information.
+ * Compute the support points of the mapping. For the current class, these
+ * are the vertices, as obtained by calling Mapping::get_vertices(). See the
+ * documentation of MappingQGeneric::compute_mapping_support_points() for
+ * more information.
*/
virtual
std::vector<Point<spacedim> >
* relative to the original positions of the cells of the triangulation.
* @param[in] euler_vector A finite element function in the space defined by
* the second argument. The first dim components of this function will be
- * interpreted as the displacement we use in defining the mapping,
- * relative to the location of cells of the underlying triangulation.
+ * interpreted as the displacement we use in defining the mapping, relative
+ * to the location of cells of the underlying triangulation.
*/
MappingQEulerian (const unsigned int degree,
const DoFHandler<dim,spacedim> &euler_dof_handler,
const DoFHandler<dim,spacedim> &euler_dof_handler) DEAL_II_DEPRECATED;
/**
- * Return the mapped vertices of the cell. For the current class, this function does
- * not use the support points from the geometry of the current cell but
- * instead evaluates an externally given displacement field in addition to
- * the geometry of the cell.
+ * Return the mapped vertices of the cell. For the current class, this
+ * function does not use the support points from the geometry of the current
+ * cell but instead evaluates an externally given displacement field in
+ * addition to the geometry of the cell.
*/
virtual
std_cxx11::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell>
protected:
/**
- * Compute mapping-related information for a cell.
- * See the documentation of Mapping::fill_fe_values() for
- * a discussion of purpose, arguments, and return value of this function.
+ * Compute mapping-related information for a cell. See the documentation of
+ * Mapping::fill_fe_values() for a discussion of purpose, arguments, and
+ * return value of this function.
*
- * This function overrides the function in
- * the base class since we cannot use any cell similarity for this class.
+ * This function overrides the function in the base class since we cannot
+ * use any cell similarity for this class.
*/
virtual
CellSimilarity::Similarity
private:
/**
- * A class derived from MappingQGeneric that provides the generic
- * mapping with support points on boundary objects so that the
- * corresponding Q3 mapping ends up being C1.
+ * A class derived from MappingQGeneric that provides the generic mapping
+ * with support points on boundary objects so that the corresponding Q3
+ * mapping ends up being C1.
*/
class MappingQEulerianGeneric : public MappingQGeneric<dim,spacedim>
{
const MappingQEulerian<dim,VectorType,spacedim> &mapping_q_eulerian);
/**
- * Return the mapped vertices of the cell. For the current class, this function does
- * not use the support points from the geometry of the current cell but
- * instead evaluates an externally given displacement field in addition to
- * the geometry of the cell.
+ * Return the mapped vertices of the cell. For the current class, this
+ * function does not use the support points from the geometry of the
+ * current cell but instead evaluates an externally given displacement
+ * field in addition to the geometry of the cell.
*/
virtual
std_cxx11::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell>
get_vertices (const typename Triangulation<dim,spacedim>::cell_iterator &cell) const;
/**
- * Compute the positions of the support points in the current configuration.
- * See the documentation of MappingQGeneric::compute_mapping_support_points()
- * for more information.
+ * Compute the positions of the support points in the current
+ * configuration. See the documentation of
+ * MappingQGeneric::compute_mapping_support_points() for more information.
*/
virtual
std::vector<Point<spacedim> >
* FEValues object used to query the the given finite element field at the
* support points in the reference configuration.
*
- * The variable is marked as mutable since we have to call FEValues::reinit
- * from compute_mapping_support_points, a function that is 'const'.
+ * The variable is marked as mutable since we have to call
+ * FEValues::reinit from compute_mapping_support_points, a function that
+ * is 'const'.
*/
mutable FEValues<dim,spacedim> fe_values;
/**
- * This class implements the functionality for polynomial mappings
- * $Q_p$ of polynomial degree $p$ that will be used on all cells of
- * the mesh. The MappingQ1 and MappingQ classes specialize this
- * behavior slightly.
+ * This class implements the functionality for polynomial mappings $Q_p$ of
+ * polynomial degree $p$ that will be used on all cells of the mesh. The
+ * MappingQ1 and MappingQ classes specialize this behavior slightly.
*
- * The class is poorly named. It should really have been called
- * MappingQ because it consistently uses $Q_p$ mappings on all cells
- * of a triangulation. However, the name MappingQ was already taken
- * when we rewrote the entire class hierarchy for mappings. One might
- * argue that one should always use MappingQGeneric over the existing
- * class MappingQ (which, unless explicitly specified during the
- * construction of the object, only uses mappings of degree $p$ <i>on
- * cells at the boundary of the domain</i>). On the other hand, there
- * are good reasons to use MappingQ in many situations: in many
- * situations, curved domains are only provided with information about
- * how exactly edges at the boundary are shaped, but we do not know
- * anything about internal edges. Thus, in the absence of other
- * information, we can only assume that internal edges are straight
- * lines, and in that case internal cells may as well be treated is
- * bilinear quadrilaterals or trilinear hexahedra. (An example of how
- * such meshes look is shown in step-1 already, but it is also
- * discussed in the "Results" section of step-6.) Because
- * bi-/trilinear mappings are significantly cheaper to compute than
- * higher order mappings, it is advantageous in such situations to use
- * the higher order mapping only on cells at the boundary of the
- * domain -- i.e., the behavior of MappingQ. Of course,
- * MappingQGeneric also uses bilinear mappings for interior cells as
- * long as it has no knowledge about curvature of interior edges, but
- * it implements this the expensive way: as a general $Q_p$ mapping
- * where the mapping support points just <i>happen</i> to be arranged
- * along linear or bilinear edges or faces.
+ * The class is poorly named. It should really have been called MappingQ
+ * because it consistently uses $Q_p$ mappings on all cells of a
+ * triangulation. However, the name MappingQ was already taken when we rewrote
+ * the entire class hierarchy for mappings. One might argue that one should
+ * always use MappingQGeneric over the existing class MappingQ (which, unless
+ * explicitly specified during the construction of the object, only uses
+ * mappings of degree $p$ <i>on cells at the boundary of the domain</i>). On
+ * the other hand, there are good reasons to use MappingQ in many situations:
+ * in many situations, curved domains are only provided with information about
+ * how exactly edges at the boundary are shaped, but we do not know anything
+ * about internal edges. Thus, in the absence of other information, we can
+ * only assume that internal edges are straight lines, and in that case
+ * internal cells may as well be treated is bilinear quadrilaterals or
+ * trilinear hexahedra. (An example of how such meshes look is shown in step-1
+ * already, but it is also discussed in the "Results" section of step-6.)
+ * Because bi-/trilinear mappings are significantly cheaper to compute than
+ * higher order mappings, it is advantageous in such situations to use the
+ * higher order mapping only on cells at the boundary of the domain -- i.e.,
+ * the behavior of MappingQ. Of course, MappingQGeneric also uses bilinear
+ * mappings for interior cells as long as it has no knowledge about curvature
+ * of interior edges, but it implements this the expensive way: as a general
+ * $Q_p$ mapping where the mapping support points just <i>happen</i> to be
+ * arranged along linear or bilinear edges or faces.
*
* There are a number of special cases worth considering:
* - If you really want to use a higher order mapping for all cells,
- * you can do this using the current class, but this only makes
- * sense if you can actually provide information about how interior
- * edges and faces of the mesh should be curved. This is typically
- * done by associating a Manifold with interior cells and
- * edges. A simple example of this is discussed in the "Results"
- * section of step-6; a full discussion of manifolds is provided in
- * step-53.
+ * you can do this using the current class, but this only makes sense if you
+ * can actually provide information about how interior edges and faces of the
+ * mesh should be curved. This is typically done by associating a Manifold
+ * with interior cells and edges. A simple example of this is discussed in the
+ * "Results" section of step-6; a full discussion of manifolds is provided in
+ * step-53.
* - If you are working on meshes that describe a (curved) manifold
- * embedded in higher space dimensions, i.e., if dim!=spacedim, then
- * every cell is at the boundary of the domain you will likely
- * already have attached a manifold object to all cells that can
- * then also be used by the mapping classes for higher order
- * mappings.
+ * embedded in higher space dimensions, i.e., if dim!=spacedim, then every
+ * cell is at the boundary of the domain you will likely already have attached
+ * a manifold object to all cells that can then also be used by the mapping
+ * classes for higher order mappings.
*
*
* @author Wolfgang Bangerth, 2015
{
public:
/**
- * Constructor. @p polynomial_degree denotes the polynomial degree
- * of the polynomials that are used to map cells from the reference
- * to the real cell.
+ * Constructor. @p polynomial_degree denotes the polynomial degree of the
+ * polynomials that are used to map cells from the reference to the real
+ * cell.
*/
MappingQGeneric (const unsigned int polynomial_degree);
unsigned int get_degree () const;
/**
- * Always returns @p true because the default implementation of
- * functions in this class preserves vertex locations.
+ * Always returns @p true because the default implementation of functions in
+ * this class preserves vertex locations.
*/
virtual
bool preserves_vertex_locations () const;
* Storage for internal data of polynomial mappings. See
* Mapping::InternalDataBase for an extensive description.
*
- * For the current class, the InternalData class stores
- * data that is computed once when the object is created
- * (in get_data()) as well as data the class wants to store from between
- * the call to fill_fe_values(), fill_fe_face_values(), or
- * fill_fe_subface_values() until possible later calls from the finite
- * element to functions such as transform(). The latter class of
- * member variables are marked as 'mutable'.
+ * For the current class, the InternalData class stores data that is
+ * computed once when the object is created (in get_data()) as well as data
+ * the class wants to store from between the call to fill_fe_values(),
+ * fill_fe_face_values(), or fill_fe_subface_values() until possible later
+ * calls from the finite element to functions such as transform(). The
+ * latter class of member variables are marked as 'mutable'.
*/
class InternalData : public Mapping<dim,spacedim>::InternalDataBase
{
public:
/**
- * Constructor. The argument denotes the polynomial degree of
- * the mapping to which this object will correspond.
+ * Constructor. The argument denotes the polynomial degree of the mapping
+ * to which this object will correspond.
*/
InternalData(const unsigned int polynomial_degree);
/**
- * Initialize the object's member variables related to cell data
- * based on the given arguments.
+ * Initialize the object's member variables related to cell data based on
+ * the given arguments.
*
- * The function also calls compute_shape_function_values() to
- * actually set the member variables related to the values and
- * derivatives of the mapping shape functions.
+ * The function also calls compute_shape_function_values() to actually set
+ * the member variables related to the values and derivatives of the
+ * mapping shape functions.
*/
void
initialize (const UpdateFlags update_flags,
const unsigned int n_original_q_points);
/**
- * Initialize the object's member variables related to cell and
- * face data based on the given arguments. In order to initialize
- * cell data, this function calls initialize().
+ * Initialize the object's member variables related to cell and face data
+ * based on the given arguments. In order to initialize cell data, this
+ * function calls initialize().
*/
void
initialize_face (const UpdateFlags update_flags,
const unsigned int n_original_q_points);
/**
- * Compute the values and/or derivatives of the shape functions
- * used for the mapping.
+ * Compute the values and/or derivatives of the shape functions used for
+ * the mapping.
*
- * Which values, derivatives, or higher order derivatives are
- * computed is determined by which of the member arrays have
- * nonzero sizes. They are typically set to their appropriate
- * sizes by the initialize() and initialize_face() functions,
- * which indeed call this function internally. However, it is
- * possible (and at times useful) to do the resizing by hand and
- * then call this function directly. An example is in a Newton
- * iteration where we update the location of a quadrature point
- * (e.g., in MappingQ::transform_real_to_uni_cell()) and need to
- * re-compute the mapping and its derivatives at this location,
- * but have already sized all internal arrays correctly.
+ * Which values, derivatives, or higher order derivatives are computed is
+ * determined by which of the member arrays have nonzero sizes. They are
+ * typically set to their appropriate sizes by the initialize() and
+ * initialize_face() functions, which indeed call this function
+ * internally. However, it is possible (and at times useful) to do the
+ * resizing by hand and then call this function directly. An example is in
+ * a Newton iteration where we update the location of a quadrature point
+ * (e.g., in MappingQ::transform_real_to_uni_cell()) and need to re-
+ * compute the mapping and its derivatives at this location, but have
+ * already sized all internal arrays correctly.
*/
void compute_shape_function_values (const std::vector<Point<dim> > &unit_points);
std::vector<std::vector<Tensor<1,dim> > > unit_tangentials;
/**
- * The polynomial degree of the mapping. Since the objects here
- * are also used (with minor adjustments) by MappingQ, we need to
- * store this.
+ * The polynomial degree of the mapping. Since the objects here are also
+ * used (with minor adjustments) by MappingQ, we need to store this.
*/
unsigned int polynomial_degree;
* use this class (e.g. the Mapping_Q() class), the number of shape
* functions may also be different.
*
- * In general, it is $(p+1)^\text{dim}$, where $p$ is the
- * polynomial degree of the mapping.
+ * In general, it is $(p+1)^\text{dim}$, where $p$ is the polynomial
+ * degree of the mapping.
*/
const unsigned int n_shape_functions;
protected:
/**
- * The degree of the polynomials used as shape functions for the mapping
- * of cells.
+ * The degree of the polynomials used as shape functions for the mapping of
+ * cells.
*/
const unsigned int polynomial_degree;
const std_cxx11::unique_ptr<FE_Q<dim> > fe_q;
/**
- * A table of weights by which we multiply the locations of the
- * support points on the perimeter of a quad to get the location of
- * interior support points.
+ * A table of weights by which we multiply the locations of the support
+ * points on the perimeter of a quad to get the location of interior support
+ * points.
*
- * Sizes: support_point_weights_on_quad.size()= number of inner unit_support_points
- * support_point_weights_on_quad[i].size()= number of outer unit_support_points,
- * i.e. unit_support_points on the boundary of the quad
+ * Sizes: support_point_weights_on_quad.size()= number of inner
+ * unit_support_points support_point_weights_on_quad[i].size()= number of
+ * outer unit_support_points, i.e. unit_support_points on the boundary of
+ * the quad
*
* For the definition of this vector see equation (8) of the `mapping'
* report.
Table<2,double> support_point_weights_on_quad;
/**
- * A table of weights by which we multiply the locations of the
- * support points on the perimeter of a hex to get the location of
- * interior support points.
+ * A table of weights by which we multiply the locations of the support
+ * points on the perimeter of a hex to get the location of interior support
+ * points.
*
* For the definition of this vector see equation (8) of the `mapping'
* report.
Table<2,double> support_point_weights_on_hex;
/**
- * Return the locations of support points for the mapping. For
- * example, for $Q_1$ mappings these are the vertices, and for higher
- * order polynomial mappings they are the vertices plus interior
- * points on edges, faces, and the cell interior that are placed
- * in consultation with the Manifold description of the domain and
- * its boundary. However, other
- * classes may override this function differently. In particular,
- * the MappingQ1Eulerian class does exactly this by not computing
- * the support points from the geometry of the current cell but
- * instead evaluating an externally given displacement field in
- * addition to the geometry of the cell.
+ * Return the locations of support points for the mapping. For example, for
+ * $Q_1$ mappings these are the vertices, and for higher order polynomial
+ * mappings they are the vertices plus interior points on edges, faces, and
+ * the cell interior that are placed in consultation with the Manifold
+ * description of the domain and its boundary. However, other classes may
+ * override this function differently. In particular, the MappingQ1Eulerian
+ * class does exactly this by not computing the support points from the
+ * geometry of the current cell but instead evaluating an externally given
+ * displacement field in addition to the geometry of the cell.
*
- * The default implementation of this function is appropriate for
- * most cases. It takes the locations of support points on the
- * boundary of the cell from the underlying manifold. Interior
- * support points (ie. support points in quads for 2d, in hexes for
- * 3d) are then computed using the solution of a Laplace equation
- * with the position of the outer support points as boundary values,
- * in order to make the transformation as smooth as possible.
+ * The default implementation of this function is appropriate for most
+ * cases. It takes the locations of support points on the boundary of the
+ * cell from the underlying manifold. Interior support points (ie. support
+ * points in quads for 2d, in hexes for 3d) are then computed using the
+ * solution of a Laplace equation with the position of the outer support
+ * points as boundary values, in order to make the transformation as smooth
+ * as possible.
*
- * The function works its way from the vertices (which it takes from
- * the given cell) via the support points on the line (for which it
- * calls the add_line_support_points() function) and the support
- * points on the quad faces (in 3d, for which it calls the
- * add_quad_support_points() function). It then adds interior
- * support points that are either computed by interpolation from the
- * surrounding points using weights computed by solving a Laplace
- * equation, or if dim<spacedim, it asks the underlying manifold for
- * the locations of interior points.
+ * The function works its way from the vertices (which it takes from the
+ * given cell) via the support points on the line (for which it calls the
+ * add_line_support_points() function) and the support points on the quad
+ * faces (in 3d, for which it calls the add_quad_support_points() function).
+ * It then adds interior support points that are either computed by
+ * interpolation from the surrounding points using weights computed by
+ * solving a Laplace equation, or if dim<spacedim, it asks the underlying
+ * manifold for the locations of interior points.
*/
virtual
std::vector<Point<spacedim> >
const Point<dim> &initial_p_unit) const;
/**
- * For <tt>dim=2,3</tt>. Append the support points of all shape
- * functions located on bounding lines of the given cell to the
- * vector @p a. Points located on the vertices of a line are not
- * included.
+ * For <tt>dim=2,3</tt>. Append the support points of all shape functions
+ * located on bounding lines of the given cell to the vector @p a. Points
+ * located on the vertices of a line are not included.
*
- * Needed by the @p compute_support_points() function. For
- * <tt>dim=1</tt> this function is empty. The function uses the
- * underlying manifold object of the line (or, if none is set, of
- * the cell) for the location of the requested points.
+ * Needed by the @p compute_support_points() function. For <tt>dim=1</tt>
+ * this function is empty. The function uses the underlying manifold object
+ * of the line (or, if none is set, of the cell) for the location of the
+ * requested points.
*
- * This function is made virtual in order to allow derived classes
- * to choose shape function support points differently than the
- * present class, which chooses the points as interpolation points
- * on the boundary.
+ * This function is made virtual in order to allow derived classes to choose
+ * shape function support points differently than the present class, which
+ * chooses the points as interpolation points on the boundary.
*/
virtual
void
std::vector<Point<spacedim> > &a) const;
/**
- * For <tt>dim=3</tt>. Append the support points of all shape
- * functions located on bounding faces (quads in 3d) of the given
- * cell to the vector @p a. Points located on the vertices or lines
- * of a quad are not included.
+ * For <tt>dim=3</tt>. Append the support points of all shape functions
+ * located on bounding faces (quads in 3d) of the given cell to the vector
+ * @p a. Points located on the vertices or lines of a quad are not included.
*
- * Needed by the @p compute_support_points() function. For
- * <tt>dim=1</tt> and <tt>dim=2</tt> this function is empty. The
- * function uses the underlying manifold object of the quad (or, if
- * none is set, of the cell) for the location of the requested
- * points.
+ * Needed by the @p compute_support_points() function. For <tt>dim=1</tt>
+ * and <tt>dim=2</tt> this function is empty. The function uses the
+ * underlying manifold object of the quad (or, if none is set, of the cell)
+ * for the location of the requested points.
*
- * This function is made virtual in order to allow derived classes
- * to choose shape function support points differently than the
- * present class, which chooses the points as interpolation points
- * on the boundary.
+ * This function is made virtual in order to allow derived classes to choose
+ * shape function support points differently than the present class, which
+ * chooses the points as interpolation points on the boundary.
*/
virtual
void
std::vector<Point<spacedim> > &a) const;
/**
- * Make MappingQ a friend since it needs to call the
- * fill_fe_values() functions on its MappingQGeneric(1)
- * sub-object.
+ * Make MappingQ a friend since it needs to call the fill_fe_values()
+ * functions on its MappingQGeneric(1) sub-object.
*/
template <int, int> friend class MappingQ;
};
const bool only_locally_owned = false);
/**
- * Constructor. Store a collection of material ids which iterators
- * shall have to be evaluated to true and state if the iterator must be
- * locally owned.
+ * Constructor. Store a collection of material ids which iterators shall
+ * have to be evaluated to true and state if the iterator must be locally
+ * owned.
*/
MaterialIdEqualTo (const std::set<types::material_id> material_ids,
const bool only_locally_owned = false);
*
* @image html hyper_cubes.png
*
- * If @p dim < @p spacedim, this will create a @p dim dimensional object
- * in the first @p dim coordinate directions embedded into the @p spacedim
- * dimensional space with the remaining entries set to zero. For example,
- * a <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
+ * If @p dim < @p spacedim, this will create a @p dim dimensional object in
+ * the first @p dim coordinate directions embedded into the @p spacedim
+ * dimensional space with the remaining entries set to zero. For example, a
+ * <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
*
* See also subdivided_hyper_cube() for a coarse mesh consisting of several
* cells. See hyper_rectangle(), if different lengths in different ordinate
* @image html simplex_2d.png
* @image html simplex_3d.png
*
- * @param tria The Triangulation to create. It needs to be empty upon calling this
- * function.
+ * @param tria The Triangulation to create. It needs to be empty upon
+ * calling this function.
*
* @param vertices The dim+1 corners of the simplex.
*
- * @note Implemented for <tt>Triangulation@<2,2@></tt>, <tt>Triangulation@<3,3@></tt>.
+ * @note Implemented for <tt>Triangulation@<2,2@></tt>,
+ * <tt>Triangulation@<3,3@></tt>.
*
* @author Guido Kanschat
* @date 2015
* cells. Thus, the number of cells filling the given volume is
* <tt>repetitions<sup>dim</sup></tt>.
*
- * If @p dim < @p spacedim, this will create a @p dim dimensional object
- * in the first @p dim coordinate directions embedded into the @p spacedim
- * dimensional space with the remaining entries set to zero. For example,
- * a <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
+ * If @p dim < @p spacedim, this will create a @p dim dimensional object in
+ * the first @p dim coordinate directions embedded into the @p spacedim
+ * dimensional space with the remaining entries set to zero. For example, a
+ * <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
*
* @note The triangulation needs to be void upon calling this function.
*/
* 2<sup>i</sup>. For instance, the center point (1,-1,1) yields a material
* id 5.
*
- * If @p dim < @p spacedim, this will create a @p dim dimensional object
- * in the first @p dim coordinate directions embedded into the @p spacedim
- * dimensional space with the remaining entries set to zero. For example,
- * a <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with z=0,
- * defined by the two opposing corners @p p1 and @p p2.
+ * If @p dim < @p spacedim, this will create a @p dim dimensional object in
+ * the first @p dim coordinate directions embedded into the @p spacedim
+ * dimensional space with the remaining entries set to zero. For example, a
+ * <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with
+ * z=0, defined by the two opposing corners @p p1 and @p p2.
*
* @note The triangulation needs to be void upon calling this function.
*/
* be true. That means the boundary indicator is 0 on the left and 1 on the
* right. See step-15 for details.
*
- * If @p dim < @p spacedim, this will create a @p dim dimensional object
- * in the first @p dim coordinate directions embedded into the @p spacedim
- * dimensional space with the remaining entries set to zero. For example,
- * a <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with z=0,
- * defined by the two opposing corners @p p1 and @p p2.
+ * If @p dim < @p spacedim, this will create a @p dim dimensional object in
+ * the first @p dim coordinate directions embedded into the @p spacedim
+ * dimensional space with the remaining entries set to zero. For example, a
+ * <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with
+ * z=0, defined by the two opposing corners @p p1 and @p p2.
*
* @note For an example of the use of this function see the step-28 tutorial
* program.
*
- * @param tria The Triangulation to create. It needs to be empty upon calling this
- * function.
+ * @param tria The Triangulation to create. It needs to be empty upon
+ * calling this function.
*
- * @param repetitions A vector of dim positive values denoting the number of cells
- * to generate in that direction.
+ * @param repetitions A vector of dim positive values denoting the number of
+ * cells to generate in that direction.
*
* @param p1 First corner point.
*
*
* @image html cheese_2d.png
*
- * If @p dim < @p spacedim, this will create a @p dim dimensional object
- * in the first @p dim coordinate directions embedded into the @p spacedim
+ * If @p dim < @p spacedim, this will create a @p dim dimensional object in
+ * the first @p dim coordinate directions embedded into the @p spacedim
* dimensional space with the remaining entries set to zero.
*
- * @param tria The Triangulation to create. It needs to be empty upon calling this
- * function.
+ * @param tria The Triangulation to create. It needs to be empty upon
+ * calling this function.
*
* @param holes Positive number of holes in each of the dim directions.
-
* @author Guido Kanschat
* @date 2015
*/
/**
* A subdivided parallelepiped.
*
- * @param tria The Triangulation to create. It needs to be empty upon calling this
- * function.
+ * @param tria The Triangulation to create. It needs to be empty upon
+ * calling this function.
*
* @param origin First corner of the parallelepiped.
*
- * @param edges An array of @p dim tensors describing the length and direction of the edges
- * from @p origin.
+ * @param edges An array of @p dim tensors describing the length and
+ * direction of the edges from @p origin.
*
- * @param subdivisions Number of subdivisions in each of the dim directions. Each
- * entry must be positive. An empty vector is equivalent to one subdivision in
- * each direction.
+ * @param subdivisions Number of subdivisions in each of the dim directions.
+ * Each entry must be positive. An empty vector is equivalent to one
+ * subdivision in each direction.
*
* @param colorize Assign different boundary ids if set to true.
*
const double radius = 1.);
/**
- * Creates a hyper sphere, i.e., a surface of a ball in @p spacedim
- * dimensions.
- * This function only exists for dim+1=spacedim in 2 and 3 space
- * dimensions.
- *
- * You should attach a SphericalManifold to the cells and faces for correct
- * placement of vertices upon refinement and to be able to use higher order
- * mappings.
- *
- * The following pictures are generated with:
- * @code
- * Triangulation<2,3> triangulation;
- *
- * static SphericalManifold<2,3> surface_description;
- *
- * GridGenerator::hyper_sphere(triangulation);
- *
- * triangulation.set_all_manifold_ids(0);
- * triangulation.set_manifold (0, surface_description);
- * triangulation.refine_global(3);
- * @endcode
- *
- * See the
- * @ref manifold "documentation module on manifolds"
- * for
- * more details.
- *
+ * Creates a hyper sphere, i.e., a surface of a ball in @p spacedim
+ * dimensions. This function only exists for dim+1=spacedim in 2 and 3 space
+ * dimensions.
+ *
+ * You should attach a SphericalManifold to the cells and faces for correct
+ * placement of vertices upon refinement and to be able to use higher order
+ * mappings.
+ *
+ * The following pictures are generated with:
+ * @code
+ * Triangulation<2,3> triangulation;
+ *
+ * static SphericalManifold<2,3> surface_description;
+ *
+ * GridGenerator::hyper_sphere(triangulation);
+ *
+ * triangulation.set_all_manifold_ids(0);
+ * triangulation.set_manifold (0, surface_description);
+ * triangulation.refine_global(3);
+ * @endcode
+ *
+ * See the
+ * @ref manifold "documentation module on manifolds"
+ * for more details.
+ *
* @image html sphere.png
* @image html sphere_section.png
- *
- * @note The triangulation needs to be void upon calling this function.
- */
+ *
+ * @note The triangulation needs to be void upon calling this function.
+ */
template <int dim, int spacedim>
void hyper_sphere (Triangulation<dim,spacedim> &tria,
*
* You should attach a SphericalManifold to the cells and faces for correct
* placement of vertices upon refinement and to be able to use higher order
- * mappings. Alternatively, it is also possible to attach a HyperShellBoundary
- * to the inner and outer boundary. This will create inferior meshes as
- * described below.
+ * mappings. Alternatively, it is also possible to attach a
+ * HyperShellBoundary to the inner and outer boundary. This will create
+ * inferior meshes as described below.
*
* In 2d, the number <tt>n_cells</tt> of elements for this initial
* triangulation can be chosen arbitrarily. If the number of initial cells
* is zero (as is the default), then it is computed adaptively such that the
* resulting elements have the least aspect ratio.
*
- * In 3d, only certain numbers are allowed, 6 (or the default 0) for a surface based on a
- * hexahedron (i.e. 6 panels on the inner sphere extruded in radial
- * direction to form 6 cells), 12 for the rhombic dodecahedron, and 96 (see
- * below).
+ * In 3d, only certain numbers are allowed, 6 (or the default 0) for a
+ * surface based on a hexahedron (i.e. 6 panels on the inner sphere extruded
+ * in radial direction to form 6 cells), 12 for the rhombic dodecahedron,
+ * and 96 (see below).
*
- * While the SphericalManifold, that is demonstrated in the documentation of the
+ * While the SphericalManifold, that is demonstrated in the documentation of
+ * the
* @ref manifold "documentation module on manifolds",
- * creates reasonable meshes
- * for any number of @p n_cells if attached to all cells and boundaries, the
- * situation is less than ideal when only attaching a HyperShellBoundary. Then,
- * only vertices on the boundaries are placed at the correct distance from the
- * center. As an example, the 3d meshes give rise to the following meshes
- * upon one refinement:
+ * creates reasonable meshes for any number of @p n_cells if attached to all
+ * cells and boundaries, the situation is less than ideal when only
+ * attaching a HyperShellBoundary. Then, only vertices on the boundaries are
+ * placed at the correct distance from the center. As an example, the 3d
+ * meshes give rise to the following meshes upon one refinement:
*
* @image html hypershell3d-6.png
* @image html hypershell3d-12.png
* the corresponding side walls in z direction. The bottom and top get the
* next two free boundary indicators.
*
- * @note The 2d input triangulation @p input must be a coarse mesh that
- * has no refined cells.
+ * @note The 2d input triangulation @p input must be a coarse mesh that has
+ * no refined cells.
*/
void
extrude_triangulation (const Triangulation<2, 2> &input,
///@}
/**
- * @name Creating lower-dimensional meshes from parts of higher-dimensional meshes
+ * @name Creating lower-dimensional meshes from parts of higher-dimensional
+ * meshes
*/
///@{
*
* @tparam MeshType A type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
- * The map that is returned will be
- * between cell iterators pointing into the container describing the surface
- * mesh and face iterators of the volume mesh container. If MeshType is
- * DoFHandler or hp::DoFHandler, then the function will re-build the
- * triangulation underlying the second argument and return a map between
- * appropriate iterators into the MeshType arguments. However, the function
- * will not actually distribute degrees of freedom on this newly created
- * surface mesh.
- *
- * @tparam dim The dimension of the cells of the volume mesh. For example, if
- * dim==2, then the cells are quadrilaterals that either live in the
- * plane, or form a surface in a higher-dimensional space. The dimension
- * of the cells of the surface mesh is consequently dim-1.
+ * The map that is returned will be between cell iterators pointing into the
+ * container describing the surface mesh and face iterators of the volume
+ * mesh container. If MeshType is DoFHandler or hp::DoFHandler, then the
+ * function will re-build the triangulation underlying the second argument
+ * and return a map between appropriate iterators into the MeshType
+ * arguments. However, the function will not actually distribute degrees of
+ * freedom on this newly created surface mesh.
+ *
+ * @tparam dim The dimension of the cells of the volume mesh. For example,
+ * if dim==2, then the cells are quadrilaterals that either live in the
+ * plane, or form a surface in a higher-dimensional space. The dimension of
+ * the cells of the surface mesh is consequently dim-1.
* @tparam spacedim The dimension of the space in which both the volume and
- * the surface mesh live.
+ * the surface mesh live.
*
* @param[in] volume_mesh A container of cells that define the volume mesh.
- * @param[out] surface_mesh A container whose associated triangulation
- * will be built to consist of the cells that correspond to the (selected
- * portion of) the boundary of the volume mesh.
- * @param[in] boundary_ids A list of boundary indicators denoting that subset
- * of faces of volume cells for which this function should extract
- * the surface mesh. If left at its default, i.e., if the set is empty,
- * then the function operates on <i>all</i> boundary faces.
+ * @param[out] surface_mesh A container whose associated triangulation will
+ * be built to consist of the cells that correspond to the (selected portion
+ * of) the boundary of the volume mesh.
+ * @param[in] boundary_ids A list of boundary indicators denoting that
+ * subset of faces of volume cells for which this function should extract
+ * the surface mesh. If left at its default, i.e., if the set is empty, then
+ * the function operates on <i>all</i> boundary faces.
*
* @return A map that for each cell of the surface mesh (key) returns an
- * iterator to the corresponding face of a cell of the volume mesh (value).
- * The keys include both active and non-active cells of the surface mesh.
- * For dim=2 (i.e., where volume cells are quadrilaterals and surface
- * cells are lines), the order of vertices of surface cells and the
- * corresponding volume faces match. For dim=3 (i.e., where volume cells
- * are hexahedra and surface cells are quadrilaterals), the order of
- * vertices may not match in order to ensure that each surface cell
- * has a right-handed coordinate system when viewed from one of the
- * two sides of the surface connecting the cells of the surface mesh.
+ * iterator to the corresponding face of a cell of the volume mesh (value).
+ * The keys include both active and non-active cells of the surface mesh.
+ * For dim=2 (i.e., where volume cells are quadrilaterals and surface cells
+ * are lines), the order of vertices of surface cells and the corresponding
+ * volume faces match. For dim=3 (i.e., where volume cells are hexahedra and
+ * surface cells are quadrilaterals), the order of vertices may not match in
+ * order to ensure that each surface cell has a right-handed coordinate
+ * system when viewed from one of the two sides of the surface connecting
+ * the cells of the surface mesh.
*
* @note The algorithm outlined above assumes that all faces on higher
* refinement levels always have exactly the same boundary indicator as
*
* @ingroup grid
* @ingroup input
- * @author Wolfgang Bangerth, 1998, 2000, Luca Heltai, 2004, 2007, Jean-Paul Pelteret 2015, Timo Heister 2015, Krzysztof Bzowski, 2015
+ * @author Wolfgang Bangerth, 1998, 2000, Luca Heltai, 2004, 2007, Jean-Paul
+ * Pelteret 2015, Timo Heister 2015, Krzysztof Bzowski, 2015
*/
template <int dim, int spacedim=dim>
void read_ucd (std::istream &in);
/**
- * Read grid data from an Abaqus file. Numerical and constitutive data
- * is ignored.
+ * Read grid data from an Abaqus file. Numerical and constitutive data is
+ * ignored.
*
- * @note The current implementation of this mesh reader is suboptimal,
- * and may therefore be slow for large meshes.
+ * @note The current implementation of this mesh reader is suboptimal, and
+ * may therefore be slow for large meshes.
*
* @note Usage tips for Cubit:
* - Multiple material-id's can be defined in the mesh.
- * This is done by specifying blocksets in the pre-processor.
+ * 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.
+ * 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.
*
* @note 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.
+ * correctly imported, but older (or newer) versions of Abaqus may also
+ * generate valid input decks.
* - Files generated using Cubit 11.x, 12.x and 13.x are valid, but only
- * when using a specific set of export steps. These are as follows:
+ * 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.
+ * toolbar on the right.
* - Select "Export Mesh" under "Operation" by clicking on the
- * necessary icon in the toolbar on the right.
+ * 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.
+ * 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.
+ * ID's". An invalid file will encounter errors if this box is left checked.
* - Click apply.
*/
void read_abaqus (std::istream &in);
bool color_lines_on_user_flag;
/**
- * The number of points on a boundary face that are plotted
- * in addition to the vertices of the face.
+ * The number of points on a boundary face that are plotted in addition to
+ * the vertices of the face.
*
- * This number is only used if the mapping used is not simply
- * the standard $Q_1$ mapping (i.e., an object of kind
- * MappingQGeneric(1)) that may describe edges of cells as
- * curved and that will then be approximated using line
- * segments with a number of intermediate points as described
+ * This number is only used if the mapping used is not simply the standard
+ * $Q_1$ mapping (i.e., an object of kind MappingQGeneric(1)) that may
+ * describe edges of cells as curved and that will then be approximated
+ * using line segments with a number of intermediate points as described
* by the current variable.
*/
unsigned int n_boundary_face_points;
* default value of this argument is to impose no limit on the number of
* cells.
*
- * @param[in] top_fraction_of_cells The requested fraction of cells to be refined.
+ * @param[in] top_fraction_of_cells The requested fraction of cells to be
+ * refined.
*
* @param[in] bottom_fraction_of_cells The requested fraction of cells to be
* coarsened.
* mesh is not changed until you call
* Triangulation::execute_coarsening_and_refinement().
*
- * @param[in,out] triangulation The triangulation whose cells this function is
- * supposed to mark for coarsening and refinement.
+ * @param[in,out] triangulation The triangulation whose cells this function
+ * is supposed to mark for coarsening and refinement.
*
- * @param[in] criteria The refinement criterion for each mesh cell.
- * Entries may not be negative.
+ * @param[in] criteria The refinement criterion for each mesh cell. Entries
+ * may not be negative.
*
* @param[in] top_fraction_of_cells The fraction of cells to be refined. If
* this number is zero, no cells will be refined. If it equals one, the
* @param[in] bottom_fraction_of_cells The fraction of cells to be
* coarsened. If this number is zero, no cells will be coarsened.
*
- * @param[in] max_n_cells This argument 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.
+ * @param[in] max_n_cells This argument 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 VectorType, int spacedim>
void
* @param[in] bottom_fraction The fraction of the estimate coarsened. If
* this number is zero, no cells will be coarsened.
*
- * @param[in] max_n_cells This argument 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.
+ * @param[in] max_n_cells This argument 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 VectorType, int spacedim>
void
* do its work in linear time; if it is not orientable, then it aborts in
* linear time as well.
*
- * Both algorithms are described in the paper
- * "On orienting edges of unstructured two- and three-dimensional meshes",
- * R. Agelek, M. Anderson, W. Bangerth, W. L. Barth (submitted, 2015).
- * A preprint is available as <a href="http://arxiv.org/abs/1512.02137">arxiv
+ * Both algorithms are described in the paper "On orienting edges of
+ * unstructured two- and three-dimensional meshes", R. Agelek, M. Anderson, W.
+ * Bangerth, W. L. Barth (submitted, 2015). A preprint is available as <a
+ * href="http://arxiv.org/abs/1512.02137">arxiv
* 1512.02137</a>.
*
*
void build_graph (const std::vector<CellData<2> > &inquads);
/**
- * Orient the internal data into deal.II format The orientation algorithm
- * is as follows
+ * Orient the internal data into deal.II format The orientation
+ * algorithm is as follows
*
* 1) Find an unoriented quad (A)
*
/**
* Return whether the cell is consistently oriented at present (i.e.
- * only considering those edges that are already oriented. This is
- * a sanity check that should be called from inside an assert macro.
+ * only considering those edges that are already oriented. This is a
+ * sanity check that should be called from inside an assert macro.
*/
bool cell_is_consistent (const unsigned int cell_num) const;
* Find and return the number of the used vertex in a given mesh that is
* located closest to a given point.
*
- * @param mesh A variable of a type that satisfies the requirements of
- * the
+ * @param mesh A variable of a type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
* @param p The point for which we want to find the closest vertex.
* @return The index of the closest vertex found.
* simultaneously delivers the local coordinate of the given point without
* additional computational cost.
*
- * @param mesh A variable of a type that satisfies the requirements of
- * the
+ * @param mesh A variable of a type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
* @param p The point for which we want to find the surrounding cell.
* @return An iterator into the mesh that points to the surrounding cell.
*
* @param mapping The mapping used to determine whether the given point is
* inside a given cell.
- * @param mesh A variable of a type that satisfies the requirements of
- * the
+ * @param mesh A variable of a type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
* @param p The point for which we want to find the surrounding cell.
* @return An pair of an iterators into the mesh that points to the
* @param cell An iterator pointing to a cell of the mesh.
* @return A list of active descendants of the given cell
*
- * @note Since in C++ the MeshType template argument can not be
- * deduced from a function call, you will have to specify it after the
- * function name, as for example in
+ * @note Since in C++ the MeshType template argument can not be deduced from
+ * a function call, you will have to specify it after the function name, as
+ * for example in
* @code
* GridTools::get_active_child_cells<DoFHandler<dim> > (cell)
* @endcode
std::vector<typename MeshType::active_cell_iterator> &active_neighbors);
/**
- * Extract and return the active cell layer around a subdomain (set of active
- * cells) in the @p mesh (i.e. those that share a common set of vertices
- * with the subdomain but are not a part of it).
- * Here, the "subdomain" consists of exactly all of those cells for which the
- * @p predicate returns @p true.
+ * Extract and return the active cell layer around a subdomain (set of
+ * active cells) in the @p mesh (i.e. those that share a common set of
+ * vertices with the subdomain but are not a part of it). Here, the
+ * "subdomain" consists of exactly all of those cells for which the @p
+ * predicate returns @p true.
*
- * An example of a custom predicate is one that checks for a given material id
+ * An example of a custom predicate is one that checks for a given material
+ * id
* @code
* template<int dim>
* bool
* GridTools::compute_active_cell_halo_layer(tria, pred_mat_id<dim>);
* @endcode
*
- * Predicates that are frequently useful can be found in namespace IteratorFilters.
- * For example, it is possible to extracting a layer based on material id
+ * Predicates that are frequently useful can be found in namespace
+ * IteratorFilters. For example, it is possible to extracting a layer based
+ * on material id
* @code
* GridTools::compute_active_cell_halo_layer(tria,
* IteratorFilters::MaterialIdEqualTo(1, true));
*
* @tparam MeshType A type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
- * @param[in] mesh A mesh (i.e. objects of type Triangulation,
- * DoFHandler, or hp::DoFHandler).
+ * @param[in] mesh A mesh (i.e. objects of type Triangulation, DoFHandler,
+ * or hp::DoFHandler).
* @param[in] predicate A function (or object of a type with an operator())
* defining the subdomain around which the halo layer is to be extracted. It
* is a function that takes in an active cell and returns a boolean.
- * @return A list of active cells sharing at least one common vertex with the
- * predicated subdomain.
+ * @return A list of active cells sharing at least one common vertex with
+ * the predicated subdomain.
*
* @author Jean-Paul Pelteret, Denis Davydov, Wolfgang Bangerth, 2015
*/
const std_cxx11::function<bool (const typename MeshType::active_cell_iterator &)> &predicate);
/**
- * Extract and return ghost cells which are the active cell layer
- * around all locally owned cells. This is most relevant for
+ * Extract and return ghost cells which are the active cell layer around all
+ * locally owned cells. This is most relevant for
* parallel::shared::Triangulation where it will return a subset of all
* ghost cells on a processor, but for parallel::distributed::Triangulation
* this will return all the ghost cells.
*
* @tparam MeshType A type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
- * @param[in] mesh A mesh (i.e. objects of type Triangulation,
- * DoFHandler, or hp::DoFHandler).
+ * @param[in] mesh A mesh (i.e. objects of type Triangulation, DoFHandler,
+ * or hp::DoFHandler).
* @return A list of ghost cells
*
* @author Jean-Paul Pelteret, Denis Davydov, Wolfgang Bangerth, 2015
* Return the adjacent cells of all the vertices. If a vertex is also a
* hanging node, the associated coarse cell is also returned. The vertices
* are ordered by the vertex index. This is the number returned by the
- * function <code>cell-@>vertex_index()</code>. Notice that only the
- * indices marked in the array returned by
+ * function <code>cell-@>vertex_index()</code>. Notice that only the indices
+ * marked in the array returned by
* Triangulation<dim,spacedim>::get_used_vertices() are used.
*/
template <int dim, int spacedim>
vertex_to_cell_map(const Triangulation<dim,spacedim> &triangulation);
/**
- * Compute a globally unique index for each vertex and hanging node associated
- * with a locally owned active cell. The vertices of a ghost cell that are
- * hanging nodes of a locally owned cells have a global index. However, the
- * other vertices of the cells that do not <i>touch</i> an active cell do not
- * have a global index on this processor.
+ * Compute a globally unique index for each vertex and hanging node
+ * associated with a locally owned active cell. The vertices of a ghost cell
+ * that are hanging nodes of a locally owned cells have a global index.
+ * However, the other vertices of the cells that do not <i>touch</i> an
+ * active cell do not have a global index on this processor.
*
* The key of the map is the local index of the vertex and the value is the
* global index. The indices need to be recomputed after refinement or
/*@{*/
/**
- * Given two meshes (i.e. objects of type Triangulation,
- * DoFHandler, or hp::DoFHandler) that are based on the same coarse mesh,
- * this function figures out a set of cells that are matched between the two
- * meshes and where at most one of the meshes is more refined on this cell.
- * In other words, it finds the smallest cells that are common to both
- * meshes, and that together completely cover the domain.
+ * Given two meshes (i.e. objects of type Triangulation, DoFHandler, or
+ * hp::DoFHandler) that are based on the same coarse mesh, this function
+ * figures out a set of cells that are matched between the two meshes and
+ * where at most one of the meshes is more refined on this cell. In other
+ * words, it finds the smallest cells that are common to both meshes, and
+ * that together completely cover the domain.
*
* This function is useful, for example, in time-dependent or nonlinear
* application, where one has to integrate a solution defined on one mesh
/*@}*/
/**
* @name Extracting and creating patches of cells surrounding a single cell,
- * and creating triangulation out of them
+ * and creating triangulation out of them
*/
/*@{*/
/**
* This function takes a vector of active cells (hereafter named @p
- * patch_cells) as input argument, and returns a vector of their
- * parent cells with the coarsest common level of refinement. In
- * other words, find that set of cells living at the same refinement
- * level so that all cells in the input vector are children of the
- * cells in the set, or are in the set itself.
- *
- * @tparam Container In C++, the compiler can not determine the type
- * of <code>Container</code> from the function call. You need to
- * specify it as an explicit template argument following the
- * function name. This type has to satisfy the requirements of a
- * mesh container (see
+ * patch_cells) as input argument, and returns a vector of their parent
+ * cells with the coarsest common level of refinement. In other words, find
+ * that set of cells living at the same refinement level so that all cells
+ * in the input vector are children of the cells in the set, or are in the
+ * set itself.
+ *
+ * @tparam Container In C++, the compiler can not determine the type of
+ * <code>Container</code> from the function call. You need to specify it as
+ * an explicit template argument following the function name. This type has
+ * to satisfy the requirements of a mesh container (see
* @ref ConceptMeshType).
*
- * @param[in] patch_cells A vector of active cells for which
- * this function finds the parents at the coarsest common
- * level. This vector of cells typically results from
- * calling the function GridTools::get_patch_around_cell().
- * @return A list of cells with the coarsest common level of
- * refinement of the input cells.
+ * @param[in] patch_cells A vector of active cells for which this function
+ * finds the parents at the coarsest common level. This vector of cells
+ * typically results from calling the function
+ * GridTools::get_patch_around_cell().
+ * @return A list of cells with the coarsest common level of refinement of
+ * the input cells.
*
* @author Arezou Ghesmati, Wolfgang Bangerth, 2015
*/
get_cells_at_coarsest_common_level(const std::vector<typename Container::active_cell_iterator> &patch_cells);
/**
- * This function constructs a Triangulation (named @p
- * local_triangulation) from a given vector of active cells. This
- * vector (which we think of the cells corresponding to a "patch")
- * contains active cells that are part of an existing global
- * Triangulation. The goal of this function is to build a local
- * Triangulation that contains only the active cells given in
- * @p patch (and potentially a minimum number of additional cells
- * required to form a valid Triangulation).
- * The function also returns a map that allows to identify the cells in
- * the output Triangulation and corresponding cells in the input
- * list.
- *
- * The operation implemented by this function is frequently used in
- * the definition of error estimators that need to solve "local"
- * problems on each cell and its neighbors. A similar construction is
- * necessary in the definition of the Clement interpolation operator
- * in which one needs to solve a local problem on all cells within
- * the support of a shape function. This function then builds a
- * complete Triangulation from a list of cells that make up such a
- * patch; one can then later attach a DoFHandler to such a
- * Triangulation.
- *
- * If the list of input cells contains only cells at the same
- * refinement level, then the output Triangulation simply consists
- * of a Triangulation containing only exactly these patch cells. On
- * the other hand, if the input cells live on different refinement
- * levels, i.e., the Triangulation of which they are part is
- * adaptively refined, then the construction of the output
- * Triangulation is not so simple because the coarsest level of a
- * Triangulation can not contain hanging nodes. Rather, we first
- * have to find the common refinement level of all input cells,
- * along with their common parents (see
- * GridTools::get_cells_at_coarsest_common_level()), build a
- * Triangulation from those, and then adaptively refine it so that
+ * This function constructs a Triangulation (named @p local_triangulation)
+ * from a given vector of active cells. This vector (which we think of the
+ * cells corresponding to a "patch") contains active cells that are part of
+ * an existing global Triangulation. The goal of this function is to build a
+ * local Triangulation that contains only the active cells given in @p patch
+ * (and potentially a minimum number of additional cells required to form a
+ * valid Triangulation). The function also returns a map that allows to
+ * identify the cells in the output Triangulation and corresponding cells in
+ * the input list.
+ *
+ * The operation implemented by this function is frequently used in the
+ * definition of error estimators that need to solve "local" problems on
+ * each cell and its neighbors. A similar construction is necessary in the
+ * definition of the Clement interpolation operator in which one needs to
+ * solve a local problem on all cells within the support of a shape
+ * function. This function then builds a complete Triangulation from a list
+ * of cells that make up such a patch; one can then later attach a
+ * DoFHandler to such a Triangulation.
+ *
+ * If the list of input cells contains only cells at the same refinement
+ * level, then the output Triangulation simply consists of a Triangulation
+ * containing only exactly these patch cells. On the other hand, if the
+ * input cells live on different refinement levels, i.e., the Triangulation
+ * of which they are part is adaptively refined, then the construction of
+ * the output Triangulation is not so simple because the coarsest level of a
+ * Triangulation can not contain hanging nodes. Rather, we first have to
+ * find the common refinement level of all input cells, along with their
+ * common parents (see GridTools::get_cells_at_coarsest_common_level()),
+ * build a Triangulation from those, and then adaptively refine it so that
* the input cells all also exist in the output Triangulation.
*
- * A consequence of this procedure is that that output Triangulation
- * may contain more active cells than the ones that exist in the
- * input vector. On the other hand, one typically wants to solve
- * the local problem not on the entire output Triangulation, but
- * only on those cells of it that correspond to cells in the input
- * list. In this case, a user typically wants to assign degrees of
- * freedom only on cells that are part of the "patch", and somehow
- * ignore those excessive cells. The current function supports this
- * common requirement by setting the user flag for the cells in the
- * output Triangulation that match with cells in the input
- * list. Cells which are not part of the original patch will not
- * have their @p user_flag set; we can then avoid assigning degrees of
- * freedom using the FE_Nothing<dim> element.
- *
- * @tparam Container In C++, the compiler can not determine the type
- * of <code>Container</code> from the function call. You need to
- * specify it as an explicit template argument following the
- * function name. This type that satisfies the requirements of a
- * mesh container (see
+ * A consequence of this procedure is that that output Triangulation may
+ * contain more active cells than the ones that exist in the input vector.
+ * On the other hand, one typically wants to solve the local problem not on
+ * the entire output Triangulation, but only on those cells of it that
+ * correspond to cells in the input list. In this case, a user typically
+ * wants to assign degrees of freedom only on cells that are part of the
+ * "patch", and somehow ignore those excessive cells. The current function
+ * supports this common requirement by setting the user flag for the cells
+ * in the output Triangulation that match with cells in the input list.
+ * Cells which are not part of the original patch will not have their @p
+ * user_flag set; we can then avoid assigning degrees of freedom using the
+ * FE_Nothing<dim> element.
+ *
+ * @tparam Container In C++, the compiler can not determine the type of
+ * <code>Container</code> from the function call. You need to specify it as
+ * an explicit template argument following the function name. This type that
+ * satisfies the requirements of a mesh container (see
* @ref ConceptMeshType).
*
* @param[in] patch A vector of active cells from a common triangulation.
- * These cells may or may not all be at the same refinement level.
+ * These cells may or may not all be at the same refinement level.
* @param[out] local_triangulation A triangulation whose active cells
- * correspond to the given vector of active cells in @p patch.
- * @param[out] patch_to_global_tria_map A map between the local triangulation
- * which is built as explained above, and the cell iterators in the input list.
+ * correspond to the given vector of active cells in @p patch.
+ * @param[out] patch_to_global_tria_map A map between the local
+ * triangulation which is built as explained above, and the cell iterators
+ * in the input list.
*
- * @author Arezou Ghesmati, Wolfgang Bangerth, 2015
+ * @author Arezou Ghesmati, Wolfgang Bangerth, 2015
*/
template <class Container>
void
/**
* A @p dim $\times$ @p dim rotation matrix that describes how vector
- * valued DoFs of the first face should be modified prior to
- * constraining to the DoFs of the second face.
+ * valued DoFs of the first face should be modified prior to constraining
+ * to the DoFs of the second face.
*
- * The rotation matrix is used in
- * DoFTools::make_periodicity_constriants() by applying the rotation to
- * all vector valued blocks listed in the parameter
- * @p first_vector_components of the finite element space.
- * For more details see DoFTools::make_periodicity_constraints() and
- * the glossary
+ * The rotation matrix is used in DoFTools::make_periodicity_constriants()
+ * by applying the rotation to all vector valued blocks listed in the
+ * parameter @p first_vector_components of the finite element space. For
+ * more details see DoFTools::make_periodicity_constraints() and the
+ * glossary
* @ref GlossPeriodicConstraints "glossary entry on periodic conditions".
*/
FullMatrix<double> matrix;
* @p face1 and @p face2 are considered equal, if a one to one matching
* between its vertices can be achieved via an orthogonal equality relation.
*
- * Here, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered equal,
- * if $M\cdot v_1 + offset - v_2$ is parallel to the unit vector in unit
+ * Here, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered equal, if
+ * $M\cdot v_1 + offset - v_2$ is parallel to the unit vector in unit
* direction @p direction. If the parameter @p matrix is a reference to a
- * spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is
- * the identity matrix.
+ * spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is the
+ * identity matrix.
*
* If the matching was successful, the _relative_ orientation of @p face1
* with respect to @p face2 is returned in the bitset @p orientation, where
/**
- * This function will collect periodic face pairs on the coarsest mesh
- * level of the given @p mesh (a Triangulation or DoFHandler) and
- * add them to the vector @p matched_pairs leaving the original contents
- * intact.
+ * This function will collect periodic face pairs on the coarsest mesh level
+ * of the given @p mesh (a Triangulation or DoFHandler) and add them to the
+ * vector @p matched_pairs leaving the original contents intact.
*
* Define a 'first' boundary as all boundary faces having boundary_id @p
* b_id1 and a 'second' boundary consisting of all faces belonging to @p
* orthogonal_equality().
*
* The bitset that is returned inside of PeriodicFacePair encodes the
- * _relative_ orientation of the first face with respect to the second
- * face, see the documentation of orthogonal_equality() for further
- * details.
+ * _relative_ orientation of the first face with respect to the second face,
+ * see the documentation of orthogonal_equality() for further details.
*
* The @p direction refers to the space direction in which periodicity is
* enforced. When maching periodic faces this vector component is ignored.
*
* The @p offset is a vector tangential to the faces that is added to the
* location of vertices of the 'first' boundary when attempting to match
- * them to the corresponding vertices of the 'second' boundary. This can
- * be used to implement conditions such as $u(0,y)=u(1,y+1)$.
+ * them to the corresponding vertices of the 'second' boundary. This can be
+ * used to implement conditions such as $u(0,y)=u(1,y+1)$.
*
* Optionally, a $dim\times dim$ rotation @p matrix can be specified that
* describes how vector valued DoFs of the first face should be modified
- * prior to constraining to the DoFs of the second face.
- * The @p matrix is used in two places. First, @p matrix will be supplied
- * to orthogonal_equality() and used for matching faces: Two vertices
- * $v_1$ and $v_2$ match if
- * $\text{matrix}\cdot v_1 + \text{offset} - v_2$
- * is parallel to the unit vector in unit direction @p direction.
- * (For more details see DoFTools::make_periodicity_constraints(), the
- * glossary
+ * prior to constraining to the DoFs of the second face. The @p matrix is
+ * used in two places. First, @p matrix will be supplied to
+ * orthogonal_equality() and used for matching faces: Two vertices $v_1$ and
+ * $v_2$ match if $\text{matrix}\cdot v_1 + \text{offset} - v_2$ is parallel
+ * to the unit vector in unit direction @p direction. (For more details see
+ * DoFTools::make_periodicity_constraints(), the glossary
* @ref GlossPeriodicConstraints "glossary entry on periodic conditions"
- * and step-45). Second, @p matrix will be stored in the
- * PeriodicFacePair collection @p matched_pairs for further use.
+ * and step-45). Second, @p matrix will be stored in the PeriodicFacePair
+ * collection @p matched_pairs for further use.
*
* @tparam MeshType A type that satisfies the requirements of the
* @ref ConceptMeshType "MeshType concept".
* periodicity algebraically.
*
* @note Because elements will be added to @p matched_pairs (and existing
- * entries will be preserved), it is possible to call this function
- * several times with different boundary ids to generate a vector with
- * all periodic pairs.
+ * entries will be preserved), it is possible to call this function several
+ * times with different boundary ids to generate a vector with all periodic
+ * pairs.
*
* @author Daniel Arndt, Matthias Maier, 2013 - 2015
*/
/*@{*/
/**
- * Copy boundary ids to manifold ids on faces and edges at the boundary.
- * The default manifold_id for new Triangulation objects is
+ * Copy boundary ids to manifold ids on faces and edges at the boundary. The
+ * default manifold_id for new Triangulation objects is
* numbers::invalid_manifold_id. This function copies the boundary_ids of
- * the boundary faces and edges to the manifold_ids of the same faces
- * and edges, allowing the user to change the boundary_ids and use them for
+ * the boundary faces and edges to the manifold_ids of the same faces and
+ * edges, allowing the user to change the boundary_ids and use them for
* boundary conditions regardless of the geometry, which will use
* manifold_ids to create new points. Only active cells will be iterated
* over. This is a function you'd typically call when there is only one
* on the first grid will point to cell 1 on the second grid.
*
* @tparam MeshType This class may be used with any class that satisfies the
- * @ref ConceptMeshType "MeshType concept". The extension to other classes
- * offering iterator functions and some minor additional requirements is
- * simple.
+ * @ref ConceptMeshType "MeshType concept".
+ * The extension to other classes offering iterator functions and some minor
+ * additional requirements is simple.
*
* Note that this class could in principle be based on the C++
* <tt>std::map<Key,Value></tt> data type. Instead, it uses another data
* system. This point is a singular point of the coordinate transformation,
* and there taking averages does not make any sense.
*
- * This class is used in step-1 and step-2 to describe the boundaries
- * of circles. Its use is also discussed in the results section of
- * step-6.
+ * This class is used in step-1 and step-2 to describe the boundaries of
+ * circles. Its use is also discussed in the results section of step-6.
*
* @ingroup manifold
*
};
/**
- * Manifold identifier of this object. This identifier should be used
- * to identify the manifold to which this object belongs, and from which
- * this object will collect information on how to add points upon
- * refinement.
+ * Manifold identifier of this object. This identifier should be used to
+ * identify the manifold to which this object belongs, and from which this
+ * object will collect information on how to add points upon refinement.
*/
types::manifold_id manifold_id;
* list either the boundary indicator zero (if on the boundary) or
* numbers::internal_face_boundary_id (if in the interior).
*
- * You will get an error if you try to set the boundary indicator of
- * an interior edge or face, i.e., an edge or face that is not at the
- * boundary of the mesh. However, one may sometimes want to set the
- * manifold indicator to an interior object. In this case, set its
- * boundary indicator to numbers::internal_face_boundary_id, to
- * indicate that you understand that it is an interior object, but set
- * its manifold id to the value you want.
+ * You will get an error if you try to set the boundary indicator of an
+ * interior edge or face, i.e., an edge or face that is not at the boundary of
+ * the mesh. However, one may sometimes want to set the manifold indicator to
+ * an interior object. In this case, set its boundary indicator to
+ * numbers::internal_face_boundary_id, to indicate that you understand that it
+ * is an interior object, but set its manifold id to the value you want.
*
* @ingroup grid
*/
std::vector<types::manifold_id> get_manifold_ids() const;
/**
- * Copy @p old_tria to this triangulation. This operation is not cheap, so you
- * should be careful with using this. We do not implement this function as a
- * copy constructor, since it makes it easier to maintain collections of
- * triangulations if you can assign them values later on.
+ * Copy @p old_tria to this triangulation. This operation is not cheap, so
+ * you should be careful with using this. We do not implement this function
+ * as a copy constructor, since it makes it easier to maintain collections
+ * of triangulations if you can assign them values later on.
*
* Keep in mind that this function also copies the pointer to the boundary
* descriptor previously set by the @p set_boundary function and to the
enum CellStatus
{
/**
- * The cell will not be refined or coarsened and might or might not
- * move to a different processor.
+ * The cell will not be refined or coarsened and might or might not move
+ * to a different processor.
*/
CELL_PERSIST,
/**
/**
* A structure used to accumulate the results of the cell_weights slot
- * functions below. It takes an iterator range and returns the sum of values.
+ * functions below. It takes an iterator range and returns the sum of
+ * values.
*/
template<typename T>
struct CellWeightSum
/**
* A structure that has boost::signal objects for a number of actions that a
- * triangulation can do to itself. Please refer to the
- * "Getting notice when a triangulation changes" section in the general
- * documentation of the Triangulation class for more information
- * and examples.
+ * triangulation can do to itself. Please refer to the "Getting notice when
+ * a triangulation changes" section in the general documentation of the
+ * Triangulation class for more information and examples.
*
* For documentation on signals, see
* http://www.boost.org/doc/libs/release/libs/signals2 .
{
/**
* This signal is triggered whenever the
- * Triangulation::create_triangulation or Triangulation::copy_triangulation()
- * is called. This signal is also triggered when loading a triangulation from an
- * archive via Triangulation::load().
+ * Triangulation::create_triangulation or
+ * Triangulation::copy_triangulation() is called. This signal is also
+ * triggered when loading a triangulation from an archive via
+ * Triangulation::load().
*/
boost::signals2::signal<void ()> create;
/**
- * This signal is triggered at the beginning of execution of
- * the Triangulation::execute_coarsening_and_refinement() function (which is
- * itself called by other functions such as Triangulation::refine_global() ).
- * At the time this signal is triggered, the triangulation is still unchanged.
+ * This signal is triggered at the beginning of execution of the
+ * Triangulation::execute_coarsening_and_refinement() function (which is
+ * itself called by other functions such as Triangulation::refine_global()
+ * ). At the time this signal is triggered, the triangulation is still
+ * unchanged.
*/
boost::signals2::signal<void ()> pre_refinement;
/**
* This signal is triggered for each cell that is going to be coarsened.
*
- * @note This signal is triggered with the immediate parent cell of a set of
- * active cells as argument. The children of this parent cell will subsequently
- * be coarsened away.
+ * @note This signal is triggered with the immediate parent cell of a set
+ * of active cells as argument. The children of this parent cell will
+ * subsequently be coarsened away.
*/
boost::signals2::signal<void (const typename Triangulation<dim, spacedim>::cell_iterator &cell)> pre_coarsening_on_cell;
/**
* This signal is triggered for each cell that just has been refined.
*
- * @note The signal parameter @p cell corresponds to the immediate parent cell
- * of a set of newly created active cells.
+ * @note The signal parameter @p cell corresponds to the immediate parent
+ * cell of a set of newly created active cells.
*/
boost::signals2::signal<void (const typename Triangulation<dim, spacedim>::cell_iterator &cell)> post_refinement_on_cell;
/**
* This signal is triggered whenever the triangulation owning the signal
- * is copied by another triangulation using Triangulation::copy_triangulation()
- * (i.e. it is triggered on the <i>old</i> triangulation, but the new one is
- * passed as an argument).
+ * is copied by another triangulation using
+ * Triangulation::copy_triangulation() (i.e. it is triggered on the
+ * <i>old</i> triangulation, but the new one is passed as an argument).
*/
boost::signals2::signal<void (const Triangulation<dim, spacedim> &destination_tria)> copy;
/**
- * This signal is triggered whenever the Triangulation::clear()
- * function is called. This signal is also triggered when loading a
- * triangulation from an archive via Triangulation::load() as the previous
- * content of the triangulation is first destroyed.
+ * This signal is triggered whenever the Triangulation::clear() function
+ * is called. This signal is also triggered when loading a triangulation
+ * from an archive via Triangulation::load() as the previous content of
+ * the triangulation is first destroyed.
*/
boost::signals2::signal<void ()> clear;
/**
* This is a catch-all signal that is triggered whenever the create,
- * post_refinement, or clear signals are triggered.
- * In effect, it can be used to indicate to an object connected to
- * the signal that the triangulation has been changed, whatever the
- * exact cause of the change.
+ * post_refinement, or clear signals are triggered. In effect, it can be
+ * used to indicate to an object connected to the signal that the
+ * triangulation has been changed, whatever the exact cause of the change.
*
- * @note The cell-level signals @p pre_coarsening_on_cell and
- * @p post_refinement_on_cell are not connected to this signal.
+ * @note The cell-level signals @p pre_coarsening_on_cell and @p
+ * post_refinement_on_cell are not connected to this signal.
*/
boost::signals2::signal<void ()> any_change;
/**
* This signal is triggered for each cell during every automatic or manual
- * repartitioning. This signal is
- * somewhat special in that it is only triggered for distributed parallel
- * calculations and only if functions are connected to it. It is intended to
- * allow a weighted repartitioning of the domain to balance the computational
- * load across processes in a different way than balancing the number of cells.
- * Any connected function is expected to take an iterator to a cell, and a
- * CellStatus argument that indicates whether this cell is going to be refined,
- * coarsened or left untouched (see the documentation of the CellStatus enum
- * for more information). The function is expected to return an unsigned
- * integer, which is interpreted as the additional computational load of this
- * cell. If this cell is going to be coarsened, the signal is called for the
- * parent cell and you need to provide the weight of the future parent
- * cell. If this cell is going to be refined the function should return a
- * weight, which will be equally assigned to every future child
- * cell of the current cell. As a reference a value of 1000 is added for
- * every cell to the total weight. This means a signal return value of 1000
- * (resulting in a weight of 2000) means that it is twice as expensive for
- * a process to handle this particular cell. If several functions are
- * connected to this signal, their return values will be summed to calculate
- * the final weight.
+ * repartitioning. This signal is somewhat special in that it is only
+ * triggered for distributed parallel calculations and only if functions
+ * are connected to it. It is intended to allow a weighted repartitioning
+ * of the domain to balance the computational load across processes in a
+ * different way than balancing the number of cells. Any connected
+ * function is expected to take an iterator to a cell, and a CellStatus
+ * argument that indicates whether this cell is going to be refined,
+ * coarsened or left untouched (see the documentation of the CellStatus
+ * enum for more information). The function is expected to return an
+ * unsigned integer, which is interpreted as the additional computational
+ * load of this cell. If this cell is going to be coarsened, the signal is
+ * called for the parent cell and you need to provide the weight of the
+ * future parent cell. If this cell is going to be refined the function
+ * should return a weight, which will be equally assigned to every future
+ * child cell of the current cell. As a reference a value of 1000 is added
+ * for every cell to the total weight. This means a signal return value of
+ * 1000 (resulting in a weight of 2000) means that it is twice as
+ * expensive for a process to handle this particular cell. If several
+ * functions are connected to this signal, their return values will be
+ * summed to calculate the final weight.
*/
boost::signals2::signal<unsigned int (const cell_iterator &,
const CellStatus),
*/
/**
- * Iterator to the first used vertex. This function can only be used if dim is
- * not one.
+ * Iterator to the first used vertex. This function can only be used if dim
+ * is not one.
*/
vertex_iterator begin_vertex() const;
/**
* Iterator past the end; this iterator serves for comparisons of iterators
- * with past-the-end or before-the-beginning states. This function can only be
- * used if dim is not one.
+ * with past-the-end or before-the-beginning states. This function can only
+ * be used if dim is not one.
*/
vertex_iterator end_vertex() const;
/**
* Return a reference to the current object.
*
- * This doesn't seem to be very useful but allows to write code that
- * can access the underlying triangulation for anything that satisfies
- * the
+ * This doesn't seem to be very useful but allows to write code that can
+ * access the underlying triangulation for anything that satisfies the
* @ref ConceptMeshType "MeshType concept"
- * (which may not only be a
- * triangulation, but also a DoFHandler, for example).
+ * (which may not only be a triangulation, but also a DoFHandler, for
+ * example).
*/
Triangulation<dim,spacedim> &
get_triangulation ();
/**
- * Return a reference to the current object. This is the const-version
- * of the previous function.
+ * Return a reference to the current object. This is the const-version of
+ * the previous function.
*/
const Triangulation<dim,spacedim> &
get_triangulation () const;
/**
* Access the value of the user pointer. It is in the responsibility of the
* user to make sure that the pointer points to something useful. You should
- * use the new style cast operator to maintain a minimum of type safety, e.g.
+ * use the new style cast operator to maintain a minimum of type safety,
+ * e.g.
*
* @note User pointers and user indices are mutually exclusive. Therefore,
* you can only use one of them, unless you call
/**
- * Specialization of <code>TriaAccessor<structdim, dim, spacedim></code>.
- * This class represent vertices in a triangulation of dimensionality
- * <code>dim</code> (i.e. 1 for a triangulation of lines, 2 for a triangulation
- * of quads, and 3 for a triangulation of hexes) that is embedded in a space of
- * dimensionality <code>spacedim</code> (for <code>spacedim==dim</code> the
- * triangulation represents a domain in ${\mathbb R}^\text{dim}$, for
- * <code>spacedim@>dim</code> the triangulation is of a manifold embedded in
- * a higher dimensional space).
+ * Specialization of <code>TriaAccessor<structdim, dim, spacedim></code>. This
+ * class represent vertices in a triangulation of dimensionality
+ * <code>dim</code> (i.e. 1 for a triangulation of lines, 2 for a
+ * triangulation of quads, and 3 for a triangulation of hexes) that is
+ * embedded in a space of dimensionality <code>spacedim</code> (for
+ * <code>spacedim==dim</code> the triangulation represents a domain in
+ * ${\mathbb R}^\text{dim}$, for <code>spacedim@>dim</code> the triangulation
+ * is of a manifold embedded in a higher dimensional space).
*
* @ingroup Accessors
* @author Bruno Turcksin, 2015
typedef void AccessorData;
/**
- * Constructor. The second argument is the global index of the vertex we point to.
+ * Constructor. The second argument is the global index of the vertex we
+ * point to.
*/
TriaAccessor (const Triangulation<dim,spacedim> *tria,
const unsigned int vertex_index);
/**
* Constructor. This constructor exists in order to maintain interface
- * compatibility with the other accessor classes. @p index can be used to set
- * the global index of the vertex we point to.
+ * compatibility with the other accessor classes. @p index can be used to
+ * set the global index of the vertex we point to.
*/
TriaAccessor (const Triangulation<dim,spacedim> *tria = NULL,
const int level = 0,
/**
* Return the center of this object, which of course coincides with the
- * location of the vertex this object refers to. The parameters
- * @p respect_manifold and @p use_laplace_transformation are not used. They
- * are there to provide the same interface as
+ * location of the vertex this object refers to. The parameters @p
+ * respect_manifold and @p use_laplace_transformation are not used. They are
+ * there to provide the same interface as
* <code>TriaAccessor<structdim,dim,spacedim></code>.
*/
Point<spacedim> center (const bool respect_manifold=false,
* @ref GlossArtificialCell).
* This function counts over all of them, including ghost and artificial
* active cells. This implies that the index returned by this function
- * uniquely identifies a cell within the triangulation on a single processor,
- * but does not uniquely identify the cell among the (parts of the)
- * triangulation that is shared among processors. If you would like to identify
- * active cells across processors, you need to consider the CellId of a cell
- * returned by CellAccessor::id().
+ * uniquely identifies a cell within the triangulation on a single
+ * processor, but does not uniquely identify the cell among the (parts of
+ * the) triangulation that is shared among processors. If you would like to
+ * identify active cells across processors, you need to consider the CellId
+ * of a cell returned by CellAccessor::id().
*/
unsigned int active_cell_index () const;
*
* The number of points requested is given by the size of the vector @p
* points. It is the task of derived classes to arrange the points in
- * approximately equal distances along the length of the line
- * segment on the boundary bounded by the vertices of the first
- * argument.
+ * approximately equal distances along the length of the line segment on the
+ * boundary bounded by the vertices of the first argument.
*
- * Among other places in the library, this function is called by
- * the Mapping classes, for example the @p MappingQGeneric class. On
- * the other hand, not all mapping classes actually require intermediate
- * points on lines (for example, $Q_1$ mappings do not). Consequently
- * this function is not made pure virtual, to allow users to define
- * their own boundary classes without having to overload this function.
- * However, the default implementation throws an error in any case and
- * can, consequently, not be used if you use a mapping that does need
- * the information provided by this function.
+ * Among other places in the library, this function is called by the Mapping
+ * classes, for example the @p MappingQGeneric class. On the other hand, not
+ * all mapping classes actually require intermediate points on lines (for
+ * example, $Q_1$ mappings do not). Consequently this function is not made
+ * pure virtual, to allow users to define their own boundary classes without
+ * having to overload this function. However, the default implementation
+ * throws an error in any case and can, consequently, not be used if you use
+ * a mapping that does need the information provided by this function.
*/
virtual
void
* to arrange the points such they split the quad into <tt>(m+1)(m+1)</tt>
* approximately equal-sized subquads.
*
- * Among other places in the library, this function is called by
- * the Mapping classes, for example the @p MappingQGeneric class. On
- * the other hand, not all mapping classes actually require intermediate
- * points on quads (for example, $Q_1$ mappings do not). Consequently
- * this function is not made pure virtual, to allow users to define
- * their own boundary classes without having to overload this function.
- * However, the default implementation throws an error in any case and
- * can, consequently, not be used if you use a mapping that does need
- * the information provided by this function.
+ * Among other places in the library, this function is called by the Mapping
+ * classes, for example the @p MappingQGeneric class. On the other hand, not
+ * all mapping classes actually require intermediate points on quads (for
+ * example, $Q_1$ mappings do not). Consequently this function is not made
+ * pure virtual, to allow users to define their own boundary classes without
+ * having to overload this function. However, the default implementation
+ * throws an error in any case and can, consequently, not be used if you use
+ * a mapping that does need the information provided by this function.
*/
virtual
void
* The objects pointed to are accessors, derived from TriaAccessorBase. Which
* kind of accessor is determined by the template argument <em>Accessor</em>.
* These accessors are not so much data structures as they are a collection of
- * functions providing access to the data stored in Triangulation or DoFHandler
- * objects. Using these accessors, the structure of these classes is hidden
- * from the application program.
+ * functions providing access to the data stored in Triangulation or
+ * DoFHandler objects. Using these accessors, the structure of these classes
+ * is hidden from the application program.
*
* <h3>Which iterator to use when</h3>
*
const hp::FECollection<dim,spacedim> &get_fe () const;
/**
- * Return a constant reference to the triangulation underlying this object.
+ * Return a constant reference to the triangulation underlying this
+ * object.
*
* @deprecated Use get_triangulation() instead.
*/
const Triangulation<dim,spacedim> &get_tria () const DEAL_II_DEPRECATED;
/**
- * Return a constant reference to the triangulation underlying this object.
+ * Return a constant reference to the triangulation underlying this
+ * object.
*/
const Triangulation<dim,spacedim> &get_triangulation () const;
explicit FECollection (const FiniteElement<dim,spacedim> &fe);
/**
- * Constructor. This constructor creates a FECollection from two
- * finite elements.
+ * Constructor. This constructor creates a FECollection from two finite
+ * elements.
*/
FECollection (const FiniteElement<dim,spacedim> &fe1,
const FiniteElement<dim,spacedim> &fe2);
/**
- * Constructor. This constructor creates a FECollection from three
- * finite elements.
+ * Constructor. This constructor creates a FECollection from three finite
+ * elements.
*/
FECollection (const FiniteElement<dim,spacedim> &fe1,
const FiniteElement<dim,spacedim> &fe2,
const FiniteElement<dim,spacedim> &fe3);
/**
- * Constructor. This constructor creates a FECollection from four
- * finite elements.
+ * Constructor. This constructor creates a FECollection from four finite
+ * elements.
*/
FECollection (const FiniteElement<dim,spacedim> &fe1,
const FiniteElement<dim,spacedim> &fe2,
const FiniteElement<dim,spacedim> &fe4);
/**
- * Constructor. This constructor creates a FECollection from five
- * finite elements.
+ * Constructor. This constructor creates a FECollection from five finite
+ * elements.
*/
FECollection (const FiniteElement<dim,spacedim> &fe1,
const FiniteElement<dim,spacedim> &fe2,
const FiniteElement<dim,spacedim> &fe5);
/**
- * Constructor. Same as above but for any number of elements. Pointers
- * to the elements are passed in a vector to this constructor.
- * As above, the finite element objects pointed to by the argument are
- * not actually used other than to create copies internally. Consequently,
- * you can delete these pointers immediately again after calling this
- * constructor.
+ * Constructor. Same as above but for any number of elements. Pointers to
+ * the elements are passed in a vector to this constructor. As above, the
+ * finite element objects pointed to by the argument are not actually used
+ * other than to create copies internally. Consequently, you can delete
+ * these pointers immediately again after calling this constructor.
*/
FECollection (const std::vector<const FiniteElement<dim,spacedim>*> &fes);
/**
* Try to find a least dominant finite element inside this FECollection
- * which dominates other finite elements provided as fe_indices in @p fes .
- * For example, if FECollection consists of {Q1,Q2,Q3,Q4} and we are looking
- * for the least dominant FE for Q3 and Q4 (@p fes is {2,3}), then the
- * answer is Q3 and therefore this function will return its index in
+ * which dominates other finite elements provided as fe_indices in @p fes
+ * . For example, if FECollection consists of {Q1,Q2,Q3,Q4} and we are
+ * looking for the least dominant FE for Q3 and Q4 (@p fes is {2,3}), then
+ * the answer is Q3 and therefore this function will return its index in
* FECollection, namely 2.
*
* For the purpose of this function by domination we consider either
* this_element_dominate or either_element_can_dominate ; therefore the
- * element can dominate itself. Thus if FECollection contains {Q1,Q2,Q4,Q3}
- * and @p fes = {3}, the function returns 3.
+ * element can dominate itself. Thus if FECollection contains
+ * {Q1,Q2,Q4,Q3} and @p fes = {3}, the function returns 3.
*
* If we were not able to find a finite element, the function returns
* numbers::invalid_unsigned_int .
*
- * Note that for the cases like when FECollection consists of
- * {FE_Nothing x FE_Nothing, Q1xQ2, Q2xQ1} with @p fes = {1}, the function
- * will not find the most dominating element as the default behavior of
- * FE_Nothing is to return FiniteElementDomination::no_requirements when
- * comparing for face domination. This, therefore, can't be considered as a
+ * Note that for the cases like when FECollection consists of {FE_Nothing
+ * x FE_Nothing, Q1xQ2, Q2xQ1} with @p fes = {1}, the function will not
+ * find the most dominating element as the default behavior of FE_Nothing
+ * is to return FiniteElementDomination::no_requirements when comparing
+ * for face domination. This, therefore, can't be considered as a
* dominating element in the sense described above .
*/
unsigned int
const dealii::UpdateFlags update_flags);
/**
* Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * that it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*/
FEValuesBase (const dealii::hp::FECollection<dim,FEValuesType::space_dimension> &fe_collection,
const dealii::hp::QCollection<q_dim> &q_collection,
/**
* Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * that it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*
* The finite element collection parameter is actually ignored, but is in
* the signature of this function to make it compatible with the signature
* constructor of this class with index given by
* <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
* the finite element. As above, if the mapping collection contains only a
- * single element (a frequent case if one wants to use a $Q_1$ mapping
- * for all finite elements in an hp discretization), then this single
- * mapping is used unless a different value for this argument is
- * specified.
+ * single element (a frequent case if one wants to use a $Q_1$ mapping for
+ * all finite elements in an hp discretization), then this single mapping
+ * is used unless a different value for this argument is specified.
*/
template <typename DoFHandlerType, bool lda>
void
/**
* Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * that it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*
* The finite element collection parameter is actually ignored, but is in
* the signature of this function to make it compatible with the signature
* constructor of this class with index given by
* <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
* the finite element. As above, if the mapping collection contains only a
- * single element (a frequent case if one wants to use a $Q_1$ mapping
- * for all finite elements in an hp discretization), then this single
- * mapping is used unless a different value for this argument is
- * specified.
+ * single element (a frequent case if one wants to use a $Q_1$ mapping for
+ * all finite elements in an hp discretization), then this single mapping
+ * is used unless a different value for this argument is specified.
*/
template <typename DoFHandlerType, bool lda>
void
/**
* Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * that it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*
* The finite element collection parameter is actually ignored, but is in
* the signature of this function to make it compatible with the signature
* constructor of this class with index given by
* <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
* the finite element. As above, if the mapping collection contains only a
- * single element (a frequent case if one wants to use a $Q_1$ mapping
- * for all finite elements in an hp discretization), then this single
- * mapping is used unless a different value for this argument is
- * specified.
+ * single element (a frequent case if one wants to use a $Q_1$ mapping for
+ * all finite elements in an hp discretization), then this single mapping
+ * is used unless a different value for this argument is specified.
*/
template <typename DoFHandlerType, bool lda>
void
/**
* Many places in the library by default use (bi-,tri-)linear mappings
* unless users explicitly provide a different mapping to use. In these
- * cases, the called function has to create a $Q_1$ mapping object, i.e.,
- * an object of kind MappingQGeneric(1). This is costly. It would also be
+ * cases, the called function has to create a $Q_1$ mapping object, i.e., an
+ * object of kind MappingQGeneric(1). This is costly. It would also be
* costly to create such objects as static objects in the affected
* functions, because static objects are never destroyed throughout the
- * lifetime of a program, even though they only have to be created once
- * the first time code runs through a particular function.
+ * lifetime of a program, even though they only have to be created once the
+ * first time code runs through a particular function.
*
* In order to avoid creation of (static or dynamic) $Q_1$ mapping objects
* in these contexts throughout the library, this class defines a static
- * collection of mappings with a single $Q_1$ mapping object. This collection
- * can then be used in all of those places where such a collection is
- * needed.
+ * collection of mappings with a single $Q_1$ mapping object. This
+ * collection can then be used in all of those places where such a
+ * collection is needed.
*/
template<int dim, int spacedim=dim>
struct StaticMappingQ1
*
* \f[ r_i = \int_Z (\mathbf w \cdot \nabla)u\, v_i \, dx. \f]
*
- * \warning This is not the residual consistent with cell_matrix(),
- * but with its transpose.
+ * \warning This is not the residual consistent with cell_matrix(), but
+ * with its transpose.
*/
template <int dim>
inline void
/**
- * Vector-valued advection residual operator in strong form
- *
- *
- * \f[ r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr)
- * \cdot\mathbf v_i \, dx. \f]
- *
- * \warning This is not the residual consistent with cell_matrix(),
- * but with its transpose.
- */
+ * Vector-valued advection residual operator in strong form
+ *
+ *
+ * \f[ r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr)
+ * \cdot\mathbf v_i \, dx. \f]
+ *
+ * \warning This is not the residual consistent with cell_matrix(), but
+ * with its transpose.
+ */
template <int dim>
inline void
cell_residual (
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected by the same velocity.
/**
- * Scalar case: Residual for upwind flux at the boundary for weak advection operator. This is the
- * value of the trial function at the outflow boundary and the value of the incoming boundary
- * condition on the inflow boundary:
+ * Scalar case: Residual for upwind flux at the boundary for weak
+ * advection operator. This is the value of the trial function at the
+ * outflow boundary and the value of the incoming boundary condition on
+ * the inflow boundary:
* @f[
* a_{ij} = \int_{\partial\Omega}
* (\mathbf w\cdot\mathbf n)
* @f]
*
* Here, the numerical flux $\widehat u$ is the upwind value at the face,
- * namely the finite element function whose values are given in the argument
- * `input` on the outflow boundary.
- * On the inflow boundary, it is the inhomogenous boundary value in the argument `data`.
+ * namely the finite element function whose values are given in the
+ * argument `input` on the outflow boundary. On the inflow boundary, it is
+ * the inhomogenous boundary value in the argument `data`.
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected by the same velocity.
/**
- * Vector-valued case: Residual for upwind flux at the boundary for weak advection operator. This is the
- * value of the trial function at the outflow boundary and the value of the incoming boundary
- * condition on the inflow boundary:
+ * Vector-valued case: Residual for upwind flux at the boundary for weak
+ * advection operator. This is the value of the trial function at the
+ * outflow boundary and the value of the incoming boundary condition on
+ * the inflow boundary:
* @f[
* a_{ij} = \int_{\partial\Omega}
* (\mathbf w\cdot\mathbf n)
* @f]
*
* Here, the numerical flux $\widehat u$ is the upwind value at the face,
- * namely the finite element function whose values are given in the argument
- * `input` on the outflow boundary.
- * On the inflow boundary, it is the inhomogenous boundary value in the argument `data`.
+ * namely the finite element function whose values are given in the
+ * argument `input` on the outflow boundary. On the inflow boundary, it is
+ * the inhomogenous boundary value in the argument `data`.
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected by the same velocity.
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected the same way.
/**
- * Scalar case: Upwind flux in the interior for weak advection operator. Matrix entries
- * correspond to the upwind value of the trial function, multiplied by the
- * jump of the test functions
+ * Scalar case: Upwind flux in the interior for weak advection operator.
+ * Matrix entries correspond to the upwind value of the trial function,
+ * multiplied by the jump of the test functions
* @f[
* a_{ij} = \int_F \left|\mathbf w
* \cdot \mathbf n\right|
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected the same way.
/**
- * Vector-valued case: Upwind flux in the interior for weak advection operator. Matrix entries
- * correspond to the upwind value of the trial function, multiplied by the
- * jump of the test functions
+ * Vector-valued case: Upwind flux in the interior for weak advection
+ * operator. Matrix entries correspond to the upwind value of the trial
+ * function, multiplied by the jump of the test functions
* @f[
* a_{ij} = \int_F \left|\mathbf w
* \cdot \mathbf n\right|
*
* The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
* vectors, one for each velocity component. Each of the vectors must
- * either have only a single entry, if the advection velocity is
- * constant, or have an entry for each quadrature point.
+ * either have only a single entry, if the advection velocity is constant,
+ * or have an entry for each quadrature point.
*
* The finite element can have several components, in which case each
* component is advected the same way.
size_type block_size (const unsigned int i) const;
/**
- * String representation of the block sizes. The output is of the
- * form `[nb->b1,b2,b3|s]`, where `nb` is n_blocks(), `s`
- * is total_size() and `b1` etc. are the values of block_size().
+ * String representation of the block sizes. The output is of the form
+ * `[nb->b1,b2,b3|s]`, where `nb` is n_blocks(), `s` is total_size() and
+ * `b1` etc. are the values of block_size().
*/
std::string to_string () const;
* const auto block_op_a = block_operator(A);
* @endcode
*
- * A BlockLinearOperator can be sliced to a LinearOperator at any time.
- * This removes all information about the underlying block structure
- * (beacuse above <code>std::function</code> objects are no longer
- * available) - the linear operator interface, however, remains intact.
+ * A BlockLinearOperator can be sliced to a LinearOperator at any time. This
+ * removes all information about the underlying block structure (beacuse above
+ * <code>std::function</code> objects are no longer available) - the linear
+ * operator interface, however, remains intact.
*
- * @note This class makes heavy use of <code>std::function</code> objects
- * and lambda functions. This flexibiliy comes with a run-time penalty.
- * Only use this object to encapsulate object with medium to large
- * individual block sizes, and small block structure (as a rule of thumb,
- * matrix blocks greater than $1000\times1000$).
+ * @note This class makes heavy use of <code>std::function</code> objects and
+ * lambda functions. This flexibiliy comes with a run-time penalty. Only use
+ * this object to encapsulate object with medium to large individual block
+ * sizes, and small block structure (as a rule of thumb, matrix blocks greater
+ * than $1000\times1000$).
*
* @note This class is only available if deal.II was configured with C++11
* support, i.e., if <code>DEAL_II_WITH_CXX11</code> is enabled during cmake
/**
* Create an empty BlockLinearOperator object.
*
- * All<code>std::function</code> member objects of this class and its
- * base class LinearOperator are initialized with default variants that
- * throw an exception upon invocation.
+ * All<code>std::function</code> member objects of this class and its base
+ * class LinearOperator are initialized with default variants that throw an
+ * exception upon invocation.
*/
BlockLinearOperator()
: LinearOperator<Range, Domain>()
default;
/**
- * Templated copy constructor that creates a BlockLinearOperator object
- * from an object @p op for which the conversion function
+ * Templated copy constructor that creates a BlockLinearOperator object from
+ * an object @p op for which the conversion function
* <code>block_operator</code> is defined.
*/
template<typename Op>
/**
* Create a BlockLinearOperator from a two-dimensional array @p ops of
- * LinearOperator. This constructor calls the corresponding
- * block_operator() specialization.
+ * LinearOperator. This constructor calls the corresponding block_operator()
+ * specialization.
*/
template<size_t m, size_t n>
BlockLinearOperator(const std::array<std::array<BlockType, n>, m> &ops)
}
/**
- * Create a block-diagonal BlockLinearOperator from a one-dimensional
- * array @p ops of LinearOperator. This constructor calls the
- * corresponding block_operator() specialization.
+ * Create a block-diagonal BlockLinearOperator from a one-dimensional array
+ * @p ops of LinearOperator. This constructor calls the corresponding
+ * block_operator() specialization.
*/
template<size_t m>
BlockLinearOperator(const std::array<BlockType, m> &ops)
/**
* Copy assignment from a one-dimensional array @p ops of LinearOperator
- * that creates a block-diagonal BlockLinearOperator.
- * This assignment operator calls the corresponding block_operator()
- * specialization.
+ * that creates a block-diagonal BlockLinearOperator. This assignment
+ * operator calls the corresponding block_operator() specialization.
*/
template <size_t m>
BlockLinearOperator<Range, Domain> &
}
/**
- * Return the number of blocks in a column (i.e, the number of "block
- * rows", or the number $m$, if interpreted as a $m\times n$ block
- * system).
+ * Return the number of blocks in a column (i.e, the number of "block rows",
+ * or the number $m$, if interpreted as a $m\times n$ block system).
*/
std::function<unsigned int()> n_block_rows;
/**
- * Return the number of blocks in a row (i.e, the number of "block
- * columns", or the number $n$, if interpreted as a $m\times n$ block
- * system).
+ * Return the number of blocks in a row (i.e, the number of "block columns",
+ * or the number $n$, if interpreted as a $m\times n$ block system).
*/
std::function<unsigned int()> n_block_cols;
/**
* Access the block with the given coordinates. This
- * <code>std::function</code> object returns a LinearOperator
- * representing the $(i,j)$-th block of the BlockLinearOperator.
+ * <code>std::function</code> object returns a LinearOperator representing
+ * the $(i,j)$-th block of the BlockLinearOperator.
*/
std::function<BlockType(unsigned int, unsigned int)> block;
};
/**
* @relates BlockLinearOperator
*
- * A function that encapsulates a @p block_matrix into a
- * BlockLinearOperator.
+ * A function that encapsulates a @p block_matrix into a BlockLinearOperator.
*
* All changes made on the block structure and individual blocks of @p
* block_matrix after the creation of the BlockLinearOperator object are
/**
* @relates BlockLinearOperator
*
- * A variant of above function that encapsulates a given collection @p ops
- * of LinearOperators into a block structure. Here, it is assumed that
- * Range and Domain are blockvectors, i.e., derived from
+ * A variant of above function that encapsulates a given collection @p ops of
+ * LinearOperators into a block structure. Here, it is assumed that Range and
+ * Domain are blockvectors, i.e., derived from
* @ref BlockVectorBase.
- * The individual linear operators in @p ops must act on
- * the underlying vector type of the block vectors, i.e., on
- * Domain::BlockType yielding a result in Range::BlockType.
+ * The individual linear operators in @p ops must act on the underlying vector
+ * type of the block vectors, i.e., on Domain::BlockType yielding a result in
+ * Range::BlockType.
*
* The list @p ops is best passed as an initializer list. Consider for example
* a linear operator block (acting on Vector<double>)
* initialized as null_operator (with correct reinit_range_vector and
* reinit_domain_vector methods).
*
- * All changes made on the individual diagonal blocks of @p block_matrix
- * after the creation of the BlockLinearOperator object are reflected by
- * the operator object.
+ * All changes made on the individual diagonal blocks of @p block_matrix after
+ * the creation of the BlockLinearOperator object are reflected by the
+ * operator object.
*
* @ingroup LAOperators
*/
* @relates BlockLinearOperator
*
* This function implements forward substitution to invert a lower block
- * triangular matrix. As arguments, it takes a BlockLinearOperator
- * @p block_operator representing a block lower triangular matrix, as well as
- * a BlockLinearOperator @p diagonal_inverse representing inverses of
- * diagonal blocks of @p block_operator.
+ * triangular matrix. As arguments, it takes a BlockLinearOperator @p
+ * block_operator representing a block lower triangular matrix, as well as a
+ * BlockLinearOperator @p diagonal_inverse representing inverses of diagonal
+ * blocks of @p block_operator.
*
* Let us assume we have a linear system with the following block structure:
*
* A0n x0 + A1n x1 + ... + Ann xn = yn
* @endcode
*
- * First of all, <code>x0 = A00^-1 y0</code>. Then, we can use x0 to recover x1:
+ * First of all, <code>x0 = A00^-1 y0</code>. Then, we can use x0 to recover
+ * x1:
* @code
* x1 = A11^-1 ( y1 - A01 x0 )
* @endcode
* @endcode
*
* @note We are not using all blocks of the BlockLinearOperator arguments:
- * Just the lower triangular block matrix of @p block_operator is used as
- * well as the diagonal of @p diagonal_inverse.
+ * Just the lower triangular block matrix of @p block_operator is used as well
+ * as the diagonal of @p diagonal_inverse.
*
* @ingroup LAOperators
*/
* @relates BlockLinearOperator
*
* This function implements back substitution to invert an upper block
- * triangular matrix. As arguments, it takes a BlockLinearOperator
- * @p block_operator representing an upper block triangular matrix, as well
- * as a BlockLinearOperator @p diagonal_inverse representing inverses of
- * diagonal blocks of @p block_operator.
+ * triangular matrix. As arguments, it takes a BlockLinearOperator @p
+ * block_operator representing an upper block triangular matrix, as well as a
+ * BlockLinearOperator @p diagonal_inverse representing inverses of diagonal
+ * blocks of @p block_operator.
*
* Let us assume we have a linear system with the following block structure:
*
* Ann xn = yn
* @endcode
*
- * First of all, <code>xn = Ann^-1 yn</code>. Then, we can use xn to recover x(n-1):
+ * First of all, <code>xn = Ann^-1 yn</code>. Then, we can use xn to recover
+ * x(n-1):
* @code
* x(n-1) = A(n-1)(n-1)^-1 ( y(n-1) - A(n-1)n x(n-1) )
* @endcode
* @endcode
*
* @note We are not using all blocks of the BlockLinearOperator arguments:
- * Just the upper triangular block matrix of @p block_operator is used as
- * well as the diagonal of @p diagonal_inverse.
-
+ * Just the upper triangular block matrix of @p block_operator is used as well
+ * as the diagonal of @p diagonal_inverse.
*
* @ingroup LAOperators
*/
*
* Now, we are ready to build a <i>2x2</i> BlockMatrixArray.
* @line Block
- * First, we enter the matrix <tt>A</tt> multiplied by 2 in the
- * upper left block
+ * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left
+ * block
* @line enter
* Now -1 times <tt>B1</tt> in the upper right block.
* @line enter
- * We add the transpose of <tt>B2</tt> to the upper right block
- * and continue in a similar fashion. In the end, the block matrix structure
- * is printed into an LaTeX table.
+ * We add the transpose of <tt>B2</tt> to the upper right block and continue
+ * in a similar fashion. In the end, the block matrix structure is printed
+ * into an LaTeX table.
* @until latex
*
* Now, we set up vectors to be multiplied with this matrix and do a
* Copying matrices is an expensive operation that we do not want to happen
* by accident through compiler generated code for <code>operator=</code>.
* (This would happen, for example, if one accidentally declared a function
- * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
- * The functionality of copying matrices is implemented in this member function
- * instead. All copy operations of objects of this type therefore require an
- * explicit function call.
+ * argument of the current type <i>by value</i> rather than <i>by
+ * reference</i>.) The functionality of copying matrices is implemented in
+ * this member function instead. All copy operations of objects of this type
+ * therefore require an explicit function call.
*
* The source matrix may be a matrix of arbitrary type, as long as its data
* type is convertible to the data type of this matrix.
* Copying matrices is an expensive operation that we do not want to happen
* by accident through compiler generated code for <code>operator=</code>.
* (This would happen, for example, if one accidentally declared a function
- * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
- * The functionality of copying matrices is implemented in this member function
- * instead. All copy operations of objects of this type therefore require an
- * explicit function call.
+ * argument of the current type <i>by value</i> rather than <i>by
+ * reference</i>.) The functionality of copying matrices is implemented in
+ * this member function instead. All copy operations of objects of this type
+ * therefore require an explicit function call.
*
* The source matrix may be a matrix of arbitrary type, as long as its data
* type is convertible to the data type of this matrix.
/**
- * This function takes a ConstraintMatrix @p constraint_matrix and an
- * operator exemplar @p exemplar (this exemplar is usually a linear
- * operator that describes the system matrix - it is only used to create
- * domain and range vectors of appropriate sizes, its action <tt>vmult</tt>
- * is never used). A LinearOperator object associated with the "homogeneous
- * action" of the underlying ConstraintMatrix object is returned:
+ * This function takes a ConstraintMatrix @p constraint_matrix and an operator
+ * exemplar @p exemplar (this exemplar is usually a linear operator that
+ * describes the system matrix - it is only used to create domain and range
+ * vectors of appropriate sizes, its action <tt>vmult</tt> is never used). A
+ * LinearOperator object associated with the "homogeneous action" of the
+ * underlying ConstraintMatrix object is returned:
*
- * Applying the LinearOperator object on a vector <code>u</code> results in
- * a vector <code>v</code> that stores the result of calling
+ * Applying the LinearOperator object on a vector <code>u</code> results in a
+ * vector <code>v</code> that stores the result of calling
* ConstraintMatrix::distribute() on <code>u</code> - with one important
* difference: inhomogeneities are not applied, but always treated as 0
* instead.
*
* The LinearOperator object created by this function is primarily used
- * internally in constrained_linear_operator() to build up a modified
- * system of linear equations. How to solve a linear system of equations
- * with this approach is explained in detail in the
+ * internally in constrained_linear_operator() to build up a modified system
+ * of linear equations. How to solve a linear system of equations with this
+ * approach is explained in detail in the
* @ref constraints
* module.
*
* @author Mauro Bardelloni, Matthias Maier, 2015
*
* @note Currently, this function may not work correctly for distributed data
- * structures.
+ * structures.
*
* @relates LinearOperator
* @ingroup constraints
/**
- * Given a ConstraintMatrix @p constraint_matrix and an operator exemplar
- * @p exemplar, return a LinearOperator that is the projection to the
- * subspace of constrained degrees of freedom, i.e. all entries of the
- * result vector that correspond to unconstrained degrees of freedom are
- * set to zero.
+ * Given a ConstraintMatrix @p constraint_matrix and an operator exemplar @p
+ * exemplar, return a LinearOperator that is the projection to the subspace of
+ * constrained degrees of freedom, i.e. all entries of the result vector that
+ * correspond to unconstrained degrees of freedom are set to zero.
*
* @author Mauro Bardelloni, Matthias Maier, 2015
*
/**
- * Given a ConstraintMatrix object @p constraint_matrix and a
- * LinearOperator @p linop, this function creates a LinearOperator object
- * consisting of the composition of three operations and a regularization:
+ * Given a ConstraintMatrix object @p constraint_matrix and a LinearOperator
+ * @p linop, this function creates a LinearOperator object consisting of the
+ * composition of three operations and a regularization:
* @code
* Ct * linop * C + Id_c;
* @endcode
* Ct = transpose_operator(C);
* Id_c = project_to_constrained_linear_operator(constraint_matrix, linop);
* @endcode
- * and <code>Id_c</code> is the projection to the subspace consisting of
- * all vector entries associated with constrained degrees of freedoms.
+ * and <code>Id_c</code> is the projection to the subspace consisting of all
+ * vector entries associated with constrained degrees of freedoms.
*
* This LinearOperator object is used together with
- * constrained_right_hand_side() to build up the following modified system
- * of linear equations:
+ * constrained_right_hand_side() to build up the following modified system of
+ * linear equations:
* @f[
* (C^T A C + Id_c) x = C^T (b - A\,k)
* @f]
* @author Mauro Bardelloni, Matthias Maier, 2015
*
* @note Currently, this function may not work correctly for distributed data
- * structures.
+ * structures.
*
* @relates LinearOperator
* @ingroup constraints
/**
- * Given a ConstraintMatrix object @p constraint_matrix, a LinearOperator
- * @p linop and a right-hand side @p right_hand_side, this function creates
- * a PackagedOperation that stores the following computation:
+ * Given a ConstraintMatrix object @p constraint_matrix, a LinearOperator @p
+ * linop and a right-hand side @p right_hand_side, this function creates a
+ * PackagedOperation that stores the following computation:
* @code
* Ct * (right_hand_side - linop * k)
* @endcode
* @endcode
*
* This LinearOperator object is used together with
- * constrained_right_hand_side() to build up the following modified system
- * of linear equations:
+ * constrained_right_hand_side() to build up the following modified system of
+ * linear equations:
* @f[
* (C^T A C + Id_c) x = C^T (b - A\,k)
* @f]
* @author Mauro Bardelloni, Matthias Maier, 2015
*
* @note Currently, this function may not work correctly for distributed data
- * structures.
+ * structures.
*
* @relates LinearOperator
* @ingroup constraints
/**
* Constructor. The supplied IndexSet defines which indices might be
* constrained inside this ConstraintMatrix. In a calculation with a
- * DoFHandler object based on parallel::distributed::Triangulation
- * or parallel::shared::Triangulation, one should use the set of locally
+ * DoFHandler object based on parallel::distributed::Triangulation or
+ * parallel::shared::Triangulation, one should use the set of locally
* relevant dofs (see
* @ref GlossLocallyRelevantDof).
*
* The given IndexSet allows the ConstraintMatrix to save memory by just not
- * caring about degrees of freedom that are not of importance to the
- * current processor. Alternatively, if no such IndexSet is provided,
- * internal data structures for <i>all</i> possible indices will be created,
- * leading to memory consumption on every processor that is proportional to
- * the <i>overall</i> size of the problem, not just proportional to the
- * size of the portion of the overall problem that is handled by the current
+ * caring about degrees of freedom that are not of importance to the current
+ * processor. Alternatively, if no such IndexSet is provided, internal data
+ * structures for <i>all</i> possible indices will be created, leading to
+ * memory consumption on every processor that is proportional to the
+ * <i>overall</i> size of the problem, not just proportional to the size of
+ * the portion of the overall problem that is handled by the current
* processor.
*/
explicit ConstraintMatrix (const IndexSet &local_constraints = IndexSet());
/**
* Close the filling of entries. Since the lines of a matrix of this type
* are usually filled in an arbitrary order and since we do not want to use
- * associative constrainers to store the lines, we need to sort the lines and
- * within the lines the columns before usage of the matrix. This is done
+ * associative constrainers to store the lines, we need to sort the lines
+ * and within the lines the columns before usage of the matrix. This is done
* through this function.
*
* Also, zero entries are discarded, since they are not needed.
*
* @param[in] local_vector Vector of local contributions.
* @param[in] local_dof_indices Local degrees of freedom indices
- * corresponding to the vector of local contributions.
+ * corresponding to the vector of local contributions.
* @param[out] global_vector The global vector to which all local
- * contributions will be added.
+ * contributions will be added.
*/
template <class InVector, class OutVector>
void
* the constraint $x_3=\frac 12 x_1 + \frac 12 x_2$, then this function will
* read the values of $x_1$ and $x_1$ from the given vector and set the
* element $x_3$ according to this constraints. Similarly, if the current
- * object stores the constraint $x_{42}=208$, then this function will set the
- * 42nd element of the given vector to 208.
+ * object stores the constraint $x_{42}=208$, then this function will set
+ * the 42nd element of the given vector to 208.
*
* @note If this function is called with a parallel vector @p vec, then the
* vector must not contain ghost elements.
/**
* Assignment from different matrix classes. This assignment operator uses
- * iterators of the typename MatrixType. Therefore, sparse matrices are possible
- * sources.
+ * iterators of the typename MatrixType. Therefore, sparse matrices are
+ * possible sources.
*/
template <typename MatrixType>
void copy_from (const MatrixType &);
/**
* Transposing assignment from different matrix classes. This assignment
- * operator uses iterators of the typename MatrixType. Therefore, sparse matrices
- * are possible sources.
+ * operator uses iterators of the typename MatrixType. Therefore, sparse
+ * matrices are possible sources.
*/
template <typename MatrixType>
void copy_transposed (const MatrixType &);
/**
* Numerical vector of data. This class derives from both
* ::dealii::LinearAlgebra::ReadWriteVector and
- * ::dealii::LinearAlgebra::VectorSpaceVector. As opposed to the array of the
- * C++ standard library, this class implements an element of a vector space
- * suitable for numerical computations.
+ * ::dealii::LinearAlgebra::VectorSpaceVector. As opposed to the array of
+ * the C++ standard library, this class implements an element of a vector
+ * space suitable for numerical computations.
*
* @author Bruno Turcksin, 2015.
*/
virtual void add(const Number a, const VectorSpaceVector<Number> &V);
/**
- * Multiple addition of a multiple of a vector, i.e. <tt>*this += a*V+b*W</tt>.
+ * Multiple addition of a multiple of a vector, i.e. <tt>*this +=
+ * a*V+b*W</tt>.
*/
virtual void add(const Number a, const VectorSpaceVector<Number> &V,
const Number b, const VectorSpaceVector<Number> &W);
virtual typename VectorSpaceVector<Number>::real_type l2_norm();
/**
- * Return the maximum norm of the vector (i.e., the maximum absolute
- * value among all entries and among all processors).
+ * Return the maximum norm of the vector (i.e., the maximum absolute value
+ * among all entries and among all processors).
*/
virtual typename VectorSpaceVector<Number>::real_type linfty_norm();
const VectorSpaceVector<Number> &W);
/**
- * Return the global size of the vector, equal to the sum of the number
- * of locally owned indices among all processors.
+ * Return the global size of the vector, equal to the sum of the number of
+ * locally owned indices among all processors.
*/
size_type size() const;
/**
* Return an index set that describes which elements of this vector are
- * owned by the current processor. As a consequence, the index sets returned
- * on different procesors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set. Obviously, if a vector is
- * created on only one processor, then the result would satisfy
+ * owned by the current processor. As a consequence, the index sets
+ * returned on different procesors if this is a distributed vector will
+ * form disjoint sets that add up to the complete index set. Obviously, if
+ * a vector is created on only one processor, then the result would
+ * satisfy
* @code
* vec.locally_owned_elements() == complete_index_set(vec.size())
* @endcode
const bool scientific=true,
const bool across=true) const;
/**
- * Write the vector en bloc to a file. This is done in a binary mode, so the
- * output is neither readable by humans nor (probably) by other computers
- * using a different operating system or number format.
+ * Write the vector en bloc to a file. This is done in a binary mode, so
+ * the output is neither readable by humans nor (probably) by other
+ * computers using a different operating system or number format.
*/
void block_write (std::ostream &out) const;
*
* The vector is resized if necessary.
*
- * A primitive form of error checking is performed which will recognize the
- * bluntest attempts to interpret some data as a vector stored bitwise to a
- * file, but not more.
+ * A primitive form of error checking is performed which will recognize
+ * the bluntest attempts to interpret some data as a vector stored bitwise
+ * to a file, but not more.
*/
void block_read (std::istream &in);
private:
/**
- * Compute the L1 norm in a recursive way by dividing the vector on smaller
- * and smaller intervals. This reduces the numerical error on large vector.
+ * Compute the L1 norm in a recursive way by dividing the vector on
+ * smaller and smaller intervals. This reduces the numerical error on
+ * large vector.
*/
typename VectorSpaceVector<Number>::real_type l1_norm_recursive(unsigned int i,
unsigned int j);
/**
- * Compute the squared L2 norm in a recursive way by dividing the vector on
- * smaller and smaller intervals. This reduces the numerical error on large
- * vector.
+ * Compute the squared L2 norm in a recursive way by dividing the vector
+ * on smaller and smaller intervals. This reduces the numerical error on
+ * large vector.
*/
typename VectorSpaceVector<Number>::real_type l2_norm_squared_recursive(
unsigned int i,
unsigned int j);
/**
- * Serialize the data of this object using boost. This function is necessary
- * to use boost::archive::text_iarchive and boost::archive::text_oarchive.
+ * Serialize the data of this object using boost. This function is
+ * necessary to use boost::archive::text_iarchive and
+ * boost::archive::text_oarchive.
*/
template <typename Archive>
void serialize(Archive &ar, const unsigned int version);
* const auto op = (op_a + k * op_b) * op_c;
* @endcode
*
- * @note This class makes heavy use of <code>std::function</code> objects
- * and lambda functions. This flexibility comes with a run-time penalty.
- * Only use this object to encapsulate matrix object of medium to large
- * size (as a rule of thumb, sparse matrices with a size $1000\times1000$,
- * or larger).
+ * @note This class makes heavy use of <code>std::function</code> objects and
+ * lambda functions. This flexibility comes with a run-time penalty. Only use
+ * this object to encapsulate matrix object of medium to large size (as a rule
+ * of thumb, sparse matrices with a size $1000\times1000$, or larger).
*
* @note This class is only available if deal.II was configured with C++11
* support, i.e., if <code>DEAL_II_WITH_CXX11</code> is enabled during cmake
LinearOperator (const LinearOperator<Range, Domain> &) = default;
/**
- * Templated copy constructor that creates a LinearOperator object from
- * an object @p op for which the conversion function
+ * Templated copy constructor that creates a LinearOperator object from an
+ * object @p op for which the conversion function
* <code>linear_operator</code> is defined.
*/
template<typename Op,
/**
* @relates LinearOperator
*
- * Returns the transpose linear operations of
- * @p op.
+ * Returns the transpose linear operations of @p op.
*
* @ingroup LAOperators
*/
*
* Returns a LinearOperator that is the identity of the vector space @p Range.
*
- * The function takes an <code>std::function</code> object
- * @p reinit_vector
- * as an argument to initialize the <code>reinit_range_vector</code> and
+ * The function takes an <code>std::function</code> object @p reinit_vector as
+ * an argument to initialize the <code>reinit_range_vector</code> and
* <code>reinit_domain_vector</code> objects of the LinearOperator object.
*
* @ingroup LAOperators
/**
* Set several elements in the specified row of the matrix with column
* indices as given by <tt>col_indices</tt> to the respective value. This is
- * the function doing the actual work for the ones adding full matrices.
- * The global locations <tt>row_index</tt> and <tt>col_indices</tt> are
+ * the function doing the actual work for the ones adding full matrices. The
+ * global locations <tt>row_index</tt> and <tt>col_indices</tt> are
* translated into locations in this block and ExcBlockIndexMismatch is
* thrown, if the global index does not point into the block referred to by
* #row and #column.
const bool col_indices_are_sorted = false);
/**
- * Matrix-vector-multiplication, forwarding to the same function in MatrixType.
- * No index computations are done, thus, the vectors need to have sizes
- * matching #matrix.
+ * Matrix-vector-multiplication, forwarding to the same function in
+ * MatrixType. No index computations are done, thus, the vectors need to
+ * have sizes matching #matrix.
*/
template<class VectorType>
void vmult (VectorType &w, const VectorType &v) const;
/**
- * Matrix-vector-multiplication, forwarding to the same function in MatrixType.
- * No index computations are done, thus, the vectors need to have sizes
- * matching #matrix.
+ * Matrix-vector-multiplication, forwarding to the same function in
+ * MatrixType. No index computations are done, thus, the vectors need to
+ * have sizes matching #matrix.
*/
template<class VectorType>
void vmult_add (VectorType &w, const VectorType &v) const;
/**
- * Matrix-vector-multiplication, forwarding to the same function in MatrixType.
- * No index computations are done, thus, the vectors need to have sizes
- * matching #matrix.
+ * Matrix-vector-multiplication, forwarding to the same function in
+ * MatrixType. No index computations are done, thus, the vectors need to
+ * have sizes matching #matrix.
*/
template<class VectorType>
void Tvmult (VectorType &w, const VectorType &v) const;
/**
- * Matrix-vector-multiplication, forwarding to the same function in MatrixType.
- * No index computations are done, thus, the vectors need to have sizes
- * matching #matrix.
+ * Matrix-vector-multiplication, forwarding to the same function in
+ * MatrixType. No index computations are done, thus, the vectors need to
+ * have sizes matching #matrix.
*/
template<class VectorType>
void Tvmult_add (VectorType &w, const VectorType &v) const;
}
/**
- * Subtract a constant @p offset (of the @p Range space) from the result of a
- * PackagedOperation.
+ * Subtract a constant @p offset (of the @p Range space) from the result of
+ * a PackagedOperation.
*/
PackagedOperation<Range> &operator-=(const Range &offset)
{
* and call collect_sizes() to update the block system's knowledge of
* its individual block's sizes.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const size_type num_blocks,
const size_type block_size = 0,
* called, all vectors remain the same and reinit() is called for each
* vector.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*
* Note that you must call this (or the other reinit() functions)
* function, rather than calling the reinit() functions of an individual
* <code>2^64-1</code> or approximately <code>10^19</code> if 64 bit
* integers are enabled (see the glossary entry on
* @ref GlobalDoFIndex
- * for
- * further information).
+ * for further information).
*
* The second relevant index type is the local index used within one MPI
* rank. As opposed to the global index, the implementation assumes 32-bit
* allocates memory for this vector. Recommended initialization function
* when several vectors with the same layout should be created.
*
- * If the flag @p omit_zeroing_entries is set to false, the memory will be initialized
- * with zero, otherwise the memory will be untouched (and the user must
- * make sure to fill it with reasonable data before using it).
+ * If the flag @p omit_zeroing_entries is set to false, the memory will
+ * be initialized with zero, otherwise the memory will be untouched (and
+ * the user must make sure to fill it with reasonable data before using
+ * it).
*/
template <typename Number2>
void reinit(const Vector<Number2> &in_vector,
* Checks whether the given partitioner is compatible with the
* partitioner used for this vector. Two partitioners are compatible if
* they have the same local size and the same ghost indices. They do not
- * necessarily need to be the same data field of the shared
- * pointer. This is a local operation only, i.e., if only some
- * processors decide that the partitioning is not compatible, only these
- * processors will return @p false, whereas the other processors will
- * return @p true.
+ * necessarily need to be the same data field of the shared pointer.
+ * This is a local operation only, i.e., if only some processors decide
+ * that the partitioning is not compatible, only these processors will
+ * return @p false, whereas the other processors will return @p true.
*/
bool
partitioners_are_compatible (const Utilities::MPI::Partitioner &part) const;
/**
* Interface for using PARPACK. PARPACK is a collection of Fortran77
- * subroutines designed to solve large scale eigenvalue problems.
- * Here we interface to the routines <code>pdneupd</code>,
- * <code>pdseupd</code>, <code>pdnaupd</code>, <code>pdsaupd</code> of
- * PARPACK. The package is designed to compute a few eigenvalues and
- * corresponding eigenvectors of a general n by n matrix A. It is most
- * appropriate for large sparse matrices A.
+ * subroutines designed to solve large scale eigenvalue problems. Here we
+ * interface to the routines <code>pdneupd</code>, <code>pdseupd</code>,
+ * <code>pdnaupd</code>, <code>pdsaupd</code> of PARPACK. The package is
+ * designed to compute a few eigenvalues and corresponding eigenvectors of a
+ * general n by n matrix A. It is most appropriate for large sparse matrices
+ * A.
*
* In this class we make use of the method applied to the generalized
- * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$
- * is a system matrix, $B$ is a mass matrix, and $\lambda, x$ are a
- * set of eigenvalues and eigenvectors respectively.
+ * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
+ * system matrix, $B$ is a mass matrix, and $\lambda, x$ are a set of
+ * eigenvalues and eigenvectors respectively.
*
- * The ArpackSolver can be used in application codes in the
- * following way:
+ * The ArpackSolver can be used in application codes in the following way:
* @code
* SolverControl solver_control (1000, 1e-9);
* const unsigned int num_arnoldi_vectors = 2*size_of_spectrum + 2;
* x,
* size_of_spectrum);
* @endcode
- * for the generalized eigenvalue problem $Ax=B\lambda x$, where the
- * variable <code>size_of_spectrum</code> tells PARPACK the number of
- * eigenvector/eigenvalue pairs to solve for. Here,
- * <code>lambda</code> is a vector that will contain the eigenvalues
- * computed, <code>x</code> a vector of objects of type <code>V</code>
- * that will contain the eigenvectors computed. <code>OP</code> is an
- * inverse operation for the matrix <code>A - sigma * B</code>, where
- * <code> sigma </code> is a shift value, set to zero by default.
+ * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
+ * <code>size_of_spectrum</code> tells PARPACK the number of
+ * eigenvector/eigenvalue pairs to solve for. Here, <code>lambda</code> is a
+ * vector that will contain the eigenvalues computed, <code>x</code> a vector
+ * of objects of type <code>V</code> that will contain the eigenvectors
+ * computed. <code>OP</code> is an inverse operation for the matrix <code>A -
+ * sigma * B</code>, where <code> sigma </code> is a shift value, set to zero
+ * by default.
*
- * Through the AdditionalData the user can specify some of the
- * parameters to be set.
+ * Through the AdditionalData the user can specify some of the parameters to
+ * be set.
*
- * The class is intended to be used with MPI and can work on arbitrary
- * vector and matrix distributed classes. Both symmetric and
- * non-symmetric <code>A</code> are supported.
+ * The class is intended to be used with MPI and can work on arbitrary vector
+ * and matrix distributed classes. Both symmetric and non-symmetric
+ * <code>A</code> are supported.
*
- * For further information on how the PARPACK routines
- * <code>pdneupd</code>, <code>pdseupd</code>, <code>pdnaupd</code>,
- * <code>pdsaupd</code> work and also how to set the parameters
- * appropriately please take a look into the PARPACK manual.
+ * For further information on how the PARPACK routines <code>pdneupd</code>,
+ * <code>pdseupd</code>, <code>pdnaupd</code>, <code>pdsaupd</code> work and
+ * also how to set the parameters appropriately please take a look into the
+ * PARPACK manual.
*
* @author Denis Davydov, 2015.
*/
typedef types::global_dof_index size_type;
/**
- * An enum that lists the possible choices for which eigenvalues to
- * compute in the solve() function.
+ * An enum that lists the possible choices for which eigenvalues to compute
+ * in the solve() function.
*
- * A particular choice is limited based on symmetric or
- * non-symmetric matrix <code>A</code> considered.
+ * A particular choice is limited based on symmetric or non-symmetric matrix
+ * <code>A</code> considered.
*/
enum WhichEigenvalues
{
};
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should it
+ * be needed.
*/
struct AdditionalData
{
void set_shift(const double s );
/**
- * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by
- * calling the <code>pd(n/s)eupd</code> and <code>pd(n/s)aupd</code>
- * functions of PARPACK.
+ * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by calling
+ * the <code>pd(n/s)eupd</code> and <code>pd(n/s)aupd</code> functions of
+ * PARPACK.
*/
template <typename MatrixType1,
typename MatrixType2, typename INVERSE>
protected:
/**
- * Reference to the object that controls convergence of the
- * iterative solver.
+ * Reference to the object that controls convergence of the iterative
+ * solver.
*/
SolverControl &solver_control;
int ldv;
/**
- * Double precision vector of size ldv by NCV. Will contains the
- * final set of Arnoldi basis vectors.
+ * Double precision vector of size ldv by NCV. Will contains the final set
+ * of Arnoldi basis vectors.
*/
std::vector<double> v;
/**
- * The initial residual vector, possibly from a previous run. On
- * output, it contains the final residual vector.
+ * The initial residual vector, possibly from a previous run. On output, it
+ * contains the final residual vector.
*/
std::vector<double> resid;
int ldz;
/**
- * A vector of minimum size of nloc by NEV+1. Z contains the
- * B-orthonormal Ritz vectors of the eigensystem A*z = lambda*B*z
- * corresponding to the Ritz value approximations.
+ * A vector of minimum size of nloc by NEV+1. Z contains the B-orthonormal
+ * Ritz vectors of the eigensystem A*z = lambda*B*z corresponding to the
+ * Ritz value approximations.
*/
std::vector<double> z;
* Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
* size <tt>block_size</tt> each.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const unsigned int num_blocks,
const size_type block_size,
* If the number of blocks is the same as before this function was called,
* all vectors remain the same and reinit() is called for each vector.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*
* Note that you must call this (or the other reinit() functions)
* function, rather than calling the reinit() functions of an individual
is_hermitian (const double tolerance = 1.e-12);
/**
- * Print the PETSc matrix object values using PETSc internal matrix
- * viewer function <tt>MatView</tt>. The default format prints the non-
- * zero matrix elements. For other valid view formats, consult
- * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatView.html
+ * Print the PETSc matrix object values using PETSc internal matrix viewer
+ * function <tt>MatView</tt>. The default format prints the non- zero
+ * matrix elements. For other valid view formats, consult
+ * http://www.mcs.anl.gov/petsc/petsc-
+ * current/docs/manualpages/Mat/MatView.html
*/
void write_ascii (const PetscViewerFormat format = PETSC_VIEWER_DEFAULT);
* Print the elements of a matrix to the given output stream.
*
* @param[in,out] out The output stream to which to write.
- * @param[in] alternative_output This argument is ignored. It exists
- * for compatibility with similar functions in other matrix classes.
+ * @param[in] alternative_output This argument is ignored. It exists for
+ * compatibility with similar functions in other matrix classes.
*/
void print (std::ostream &out,
const bool alternative_output = false) const;
* @p communicator argument denotes which MPI channel each of these
* blocks shall communicate.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const unsigned int n_blocks,
const MPI_Comm &communicator,
* called, all vectors remain the same and reinit() is called for each
* vector.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*
* Note that you must call this (or the other reinit() functions)
* function, rather than calling the reinit() functions of an individual
* the collective MPI functions and wait for all the other processes to
* join in on this. Since the other processes don't call this function,
* you will either get a time-out on the first process, or, worse, by the
- * time the next a call to a PETSc function generates an MPI message on the
- * other processes, you will get a cryptic message that only a subset of
- * processes attempted a communication. These bugs can be very hard to
+ * time the next a call to a PETSc function generates an MPI message on
+ * the other processes, you will get a cryptic message that only a subset
+ * of processes attempted a communication. These bugs can be very hard to
* figure out, unless you are well-acquainted with the communication model
* of MPI, and know which functions may generate MPI messages.
*
* @p communicator denotes the MPI communicator henceforth to be used
* for this vector.
*
- * If @p omit_zeroing_entries is false, the vector is filled by zeros. Otherwise, the
- * elements are left an unspecified state.
+ * If @p omit_zeroing_entries is false, the vector is filled by zeros.
+ * Otherwise, the elements are left an unspecified state.
*/
void reinit (const MPI_Comm &communicator,
const size_type N,
* The same applies as for the other @p reinit function.
*
* The elements of @p v are not copied, i.e. this function is the same
- * as calling <tt>reinit(v.size(), v.local_size(), omit_zeroing_entries)</tt>.
+ * as calling <tt>reinit(v.size(), v.local_size(),
+ * omit_zeroing_entries)</tt>.
*/
void reinit (const Vector &v,
const bool omit_zeroing_entries = false);
AdditionalData additional_data;
/**
- * Initializes the preconditioner object without knowing a particular matrix.
- * This function sets up appropriate parameters to the underlying PETSc object
- * after it has been created.
+ * Initializes the preconditioner object without knowing a particular
+ * matrix. This function sets up appropriate parameters to the underlying
+ * PETSc object after it has been created.
*/
void initialize();
};
AdditionalData additional_data;
/**
- * Initializes the preconditioner object without knowing a particular matrix.
- * This function sets up appropriate parameters to the underlying PETSc object
- * after it has been created.
+ * Initializes the preconditioner object without knowing a particular
+ * matrix. This function sets up appropriate parameters to the underlying
+ * PETSc object after it has been created.
*/
void initialize();
/**
* Set this flag to true if you have a symmetric system matrix and you
* want to use a solver which assumes a symmetric preconditioner like
- * CG. The relaxation is done with SSOR/Jacobi when set to true and
- * with SOR/Jacobi otherwise.
+ * CG. The relaxation is done with SSOR/Jacobi when set to true and with
+ * SOR/Jacobi otherwise.
*/
bool symmetric_operator;
AdditionalData additional_data;
/**
- * Initializes the preconditioner object without knowing a particular matrix.
- * This function sets up appropriate parameters to the underlying PETSc object
- * after it has been created.
+ * Initializes the preconditioner object without knowing a particular
+ * matrix. This function sets up appropriate parameters to the underlying
+ * PETSc object after it has been created.
*/
void initialize();
SolverControl &control() const;
/**
- * initialize the solver with the preconditioner.
- * This function is intended for use with SLEPc spectral transformation class.
+ * initialize the solver with the preconditioner. This function is
+ * intended for use with SLEPc spectral transformation class.
*/
void initialize(const PreconditionerBase &preconditioner);
#ifdef DEAL_II_WITH_SLEPC
/**
- * Make the transformation class a friend, since it needs to set the KSP solver.
+ * Make the transformation class a friend, since it needs to set the KSP
+ * solver.
*/
friend class SLEPcWrappers::TransformationBase;
#endif
* Despite the fact that it would seem to be an obvious win, setting the
* @p preset_nonzero_locations flag to @p true doesn't seem to accelerate
* program. Rather on the contrary, it seems to be able to slow down
- * entire programs somewhat. This is surprising, since we can use efficient
- * function calls into PETSc that allow to create multiple entries at
- * once; nevertheless, given the fact that it is inefficient, the
- * respective flag has a default value equal to @p false.
+ * entire programs somewhat. This is surprising, since we can use
+ * efficient function calls into PETSc that allow to create multiple
+ * entries at once; nevertheless, given the fact that it is inefficient,
+ * the respective flag has a default value equal to @p false.
*/
template <typename SparsityPatternType>
void reinit (const SparsityPatternType &sparsity_pattern,
* reduces memory consumption, or if for efficiency the same amount of
* memory is used for less data.
*
- * If @p omit_zeroing_entries is false, the vector is filled by zeros. Otherwise, the
- * elements are left an unspecified state.
+ * If @p omit_zeroing_entries is false, the vector is filled by zeros.
+ * Otherwise, the elements are left an unspecified state.
*/
void reinit (const size_type N,
const bool omit_zeroing_entries = false);
};
/**
- * Constructor, sets the relaxation parameter, domain and range sizes
- * to their default.
+ * Constructor, sets the relaxation parameter, domain and range sizes to
+ * their default.
*/
PreconditionRichardson();
/**
- * Jacobi preconditioner using matrix built-in function. The <tt>MatrixType</tt>
- * class used is required to have a function <tt>precondition_Jacobi(VectorType&,
- * const VectorType&, double</tt>). This class satisfies the
+ * Jacobi preconditioner using matrix built-in function. The
+ * <tt>MatrixType</tt> class used is required to have a function
+ * <tt>precondition_Jacobi(VectorType&, const VectorType&, double</tt>). This
+ * class satisfies the
* @ref ConceptRelaxationType "relaxation concept".
*
* @code
/**
- * SSOR preconditioner using matrix built-in function. The <tt>MatrixType</tt>
- * class used is required to have a function <tt>precondition_SSOR(VectorType&,
- * const VectorType&, double)</tt>. This class satisfies the
+ * SSOR preconditioner using matrix built-in function. The
+ * <tt>MatrixType</tt> class used is required to have a function
+ * <tt>precondition_SSOR(VectorType&, const VectorType&, double)</tt>. This
+ * class satisfies the
* @ref ConceptRelaxationType "relaxation concept".
*
* @code
/**
* Permuted SOR preconditioner using matrix built-in function. The
- * <tt>MatrixType</tt> class used is required to have functions <tt>PSOR(VectorType&,
- * const VectorType&, double)</tt> and <tt>TPSOR(VectorType&, const VectorType&,
- * double)</tt>.
+ * <tt>MatrixType</tt> class used is required to have functions
+ * <tt>PSOR(VectorType&, const VectorType&, double)</tt> and
+ * <tt>TPSOR(VectorType&, const VectorType&, double)</tt>.
*
* @code
* // Declare related objects
typedef typename MatrixType::size_type size_type;
/**
- * Parameters for PreconditionPSOR.
- */
+ * Parameters for PreconditionPSOR.
+ */
class AdditionalData
{
public:
* matrices. This preconditioner is similar to a Jacobi preconditioner if the
* degree variable is set to one, otherwise some higher order polynomial
* corrections are used. This preconditioner needs access to the diagonal of
- * the matrix it acts on and needs a respective <tt>vmult</tt>
- * implementation. However, it does not need to explicitly know the matrix
- * entries.
+ * the matrix it acts on and needs a respective <tt>vmult</tt> implementation.
+ * However, it does not need to explicitly know the matrix entries.
*
* This class is useful e.g. in multigrid smoother objects, since it is
* trivially %parallel (assuming that matrix-vector products are %parallel).
protected:
/**
* Initialize matrix and block size for permuted preconditioning.
- * Additionally to the parameters of the other initialize() function, we hand
- * over two index vectors with the permutation and its inverse. For the
+ * Additionally to the parameters of the other initialize() function, we
+ * hand over two index vectors with the permutation and its inverse. For the
* meaning of these vectors see PreconditionBlockSOR.
*
* In a second step, the inverses of the diagonal blocks may be computed.
* which it stores all or a subset of elements. The latter case in important
* in parallel computations, where $N$ may be so large that no processor can
* actually all elements of a solution vector, but where this is also not
- * necessary: one typically only has to store the values of degrees of freedom
- * that live on cells that are locally owned plus potentially those degrees of
- * freedom that live on ghost cells.
+ * necessary: one typically only has to store the values of degrees of
+ * freedom that live on cells that are locally owned plus potentially those
+ * degrees of freedom that live on ghost cells.
*
* This class allows to access individual elements to be read or written.
* However, it does not allow global operations such as taking the norm.
* from VectorSpaceVector such as TrilinosWrappers::MPI::Vector and
* PETScWrappers::MPI::Vector.
*
- * <h3>Storing elements</h3>
- * Most of the time, one will simply read from or write into a vector of the
- * current class using the global numbers of these degrees of freedom. This is
- * done using operator() or operator[] which call global_to_local() to transform
- * the <i>global</i> index into a <i>local</i> one. In such cases, it is clear
- * that one can only access elements of the vector that the current object
- * indeed stores.
+ * <h3>Storing elements</h3> Most of the time, one will simply read from or
+ * write into a vector of the current class using the global numbers of
+ * these degrees of freedom. This is done using operator() or operator[]
+ * which call global_to_local() to transform the <i>global</i> index into a
+ * <i>local</i> one. In such cases, it is clear that one can only access
+ * elements of the vector that the current object indeed stores.
*
- * However, it is also possible to access elements in the order in which they
- * are stored by the current object. In other words, one is not interested in
- * accessing elements with their <i>global</i> indices, but instead using an
- * enumeration that only takes into account the elements that are actually
- * stored. This is facilitated by the local_element() function. To this end,
- * it is necessary to know <i>in which order</i> the current class stores its
- * element. The elements of all the consecutive ranges are stored in ascending
- * order of the first index of each range. The function
- * largest_range_starting_index() of IndexSet can be used to get the first
- * index of the largest range.
+ * However, it is also possible to access elements in the order in which
+ * they are stored by the current object. In other words, one is not
+ * interested in accessing elements with their <i>global</i> indices, but
+ * instead using an enumeration that only takes into account the elements
+ * that are actually stored. This is facilitated by the local_element()
+ * function. To this end, it is necessary to know <i>in which order</i> the
+ * current class stores its element. The elements of all the consecutive
+ * ranges are stored in ascending order of the first index of each range.
+ * The function largest_range_starting_index() of IndexSet can be used to
+ * get the first index of the largest range.
*
* @author Bruno Turcksin, 2015.
*/
ReadWriteVector (const ReadWriteVector<Number> &in_vector);
/**
- * Constructs a vector given the size, the stored elements have their index
- * in [0,size).
+ * Constructs a vector given the size, the stored elements have their
+ * index in [0,size).
*/
explicit ReadWriteVector (const size_type size);
* Sets the global size of the vector to @p size. The stored elements have
* their index in [0,size).
*
- * If the flag @p omit_zeroing_entries is set to false, the memory will be initialized
- * with zero, otherwise the memory will be untouched (and the user must
- * make sure to fill it with reasonable data before using it).
+ * If the flag @p omit_zeroing_entries is set to false, the memory will be
+ * initialized with zero, otherwise the memory will be untouched (and the
+ * user must make sure to fill it with reasonable data before using it).
*/
void reinit (const size_type size,
const bool omit_zeroing_entries = false);
* Uses the same IndexSet as the one of the input vector @p in_vector and
* allocates memory for this vector.
*
- * If the flag @p omit_zeroing_entries is set to false, the memory will be initialized
- * with zero, otherwise the memory will be untouched (and the user must
- * make sure to fill it with reasonable data before using it).
+ * If the flag @p omit_zeroing_entries is set to false, the memory will be
+ * initialized with zero, otherwise the memory will be untouched (and the
+ * user must make sure to fill it with reasonable data before using it).
*/
template <typename Number2>
void reinit(const ReadWriteVector<Number2> &in_vector,
const bool omit_zeroing_entries = false);
/**
- * Initializes the vector. The indices are specified by
- * @p locally_stored_indices.
+ * Initializes the vector. The indices are specified by @p
+ * locally_stored_indices.
*
- * If the flag @p omit_zeroing_entries is set to false, the memory will be initialized
- * with zero, otherwise the memory will be untouched (and the user must
- * make sure to fill it with reasonable data before using it).
+ * If the flag @p omit_zeroing_entries is set to false, the memory will be
+ * initialized with zero, otherwise the memory will be untouched (and the
+ * user must make sure to fill it with reasonable data before using it).
* locally_stored_indices.
*/
void reinit (const IndexSet &locally_stored_indices,
* only swaps the pointers to the data of the two vectors and therefore
* does not need to allocate temporary storage and move data around.
*
- * This function is analog to the the @p swap function of all C++
- * standard containers. Also, there is a global function
- * <tt>swap(u,v)</tt> that simply calls <tt>u.swap(v)</tt>, again in
- * analogy to standard functions.
+ * This function is analog to the the @p swap function of all C++ standard
+ * containers. Also, there is a global function <tt>swap(u,v)</tt> that
+ * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
+ * functions.
*/
void swap (ReadWriteVector<Number> &v);
#ifdef DEAL_II_WITH_PETSC
/**
- * Imports all the elements present in the vector's IndexSet from the input
- * vector @p petsc_vec.
+ * Imports all the elements present in the vector's IndexSet from the
+ * input vector @p petsc_vec.
*/
ReadWriteVector<Number> &
operator= (const PETScWrappers::MPI::Vector &petsc_vec);
#ifdef DEAL_II_WITH_TRILINOS
/**
- * Imports all the elements present in the vector's IndexSet from the input
- * vector @p trilinos_vec.
+ * Imports all the elements present in the vector's IndexSet from the
+ * input vector @p trilinos_vec.
*/
ReadWriteVector<Number> &
operator= (const TrilinosWrappers::MPI::Vector &trilinos_vec);
ReadWriteVector<Number> &operator = (const Number s);
/**
- * The value returned by this function denotes the dimension of the vector spaces
- * that are modeled by objects of this kind. However, objects of the current
- * class do not actually stores all elements of vectors of this space but
- * may, in fact store only a subset. The number of elements stored is
- * returned by n_elements() and is smaller or equal to the number returned
- * by the current function.
+ * The value returned by this function denotes the dimension of the vector
+ * spaces that are modeled by objects of this kind. However, objects of
+ * the current class do not actually stores all elements of vectors of
+ * this space but may, in fact store only a subset. The number of elements
+ * stored is returned by n_elements() and is smaller or equal to the
+ * number returned by the current function.
*/
size_type size() const;
const IndexSet &get_stored_elements () const;
/**
- * Make the @p ReadWriteVector class a bit like the <tt>vector<></tt> class of
- * the C++ standard library by returning iterators to the start and end
- * of the <i>locally stored</i> elements of this vector.
+ * Make the @p ReadWriteVector class a bit like the <tt>vector<></tt>
+ * class of the C++ standard library by returning iterators to the start
+ * and end of the <i>locally stored</i> elements of this vector.
*/
iterator begin ();
iterator end ();
/**
- * Returns a constant iterator pointing to the element past the end of
- * the array of the locally stored entries.
+ * Returns a constant iterator pointing to the element past the end of the
+ * array of the locally stored entries.
*/
const_iterator end () const;
//@}
/**
* Read access to the data in the position corresponding to @p
- * global_index. An exception is thrown if @p global_index is not stored by
- * the current object.
+ * global_index. An exception is thrown if @p global_index is not stored
+ * by the current object.
*/
Number operator () (const size_type global_index) const;
/**
* Read and write access to the data in the position corresponding to @p
- * global_index. An exception is thrown if @p global_index is not stored by
- * the current object.
+ * global_index. An exception is thrown if @p global_index is not stored
+ * by the current object.
*/
Number &operator () (const size_type global_index);
/**
* Read access to the data in the position corresponding to @p
- * global_index. An exception is thrown if @p global_index is not stored by
- * the current object.
+ * global_index. An exception is thrown if @p global_index is not stored
+ * by the current object.
*
* This function does the same thing as operator().
*/
/**
* Read and write access to the data in the position corresponding to @p
- * global_index. An exception is thrown if @p global_index is not stored by
- * the current object.
+ * global_index. An exception is thrown if @p global_index is not stored
+ * by the current object.
*
* This function does the same thing as operator().
*/
/**
* Instead of getting individual elements of a vector, this function
* allows to get a whole set of elements at once. The indices of the
- * elements to be read are stated in the first argument, the
- * corresponding values are returned in the second.
+ * elements to be read are stated in the first argument, the corresponding
+ * values are returned in the second.
*/
template <typename Number2>
void extract_subvector_to (const std::vector<size_type> &indices,
Number local_element (const size_type local_index) const;
/**
- * Read and write access to the data field specified by @p local_index. When
- * you access elements in the order in which they are stored, it is necessary
- * that you know in which they are stored. In other words, you need to
- * know the map between the global indices of the elements this class
- * stores, and the local indices into the contiguous array of these global
- * elements. For this, see the general documentation of this class.
+ * Read and write access to the data field specified by @p local_index.
+ * When you access elements in the order in which they are stored, it is
+ * necessary that you know in which they are stored. In other words, you
+ * need to know the map between the global indices of the elements this
+ * class stores, and the local indices into the contiguous array of these
+ * global elements. For this, see the general documentation of this class.
*
* Performance: Direct array access (fast).
*/
//@{
/**
- * This function adds a whole set of values stored in @p values to the vector
- * components specified by @p indices.
+ * This function adds a whole set of values stored in @p values to the
+ * vector components specified by @p indices.
*/
template <typename Number2>
void add (const std::vector<size_type> &indices,
const std::vector<Number2> &values);
/**
- * This function is similar to the previous one but takes a ReadWriteVector
- * of values.
+ * This function is similar to the previous one but takes a
+ * ReadWriteVector of values.
*/
template <typename Number2>
void add (const std::vector<size_type> &indices,
*
* This class implements the step() and Tstep() functions expected by the
* @ref ConceptRelaxationType "relaxation concept".
- * They perform an additive
- * Schwarz method on the blocks provided in the block list of AdditionalData.
- * Differing from PreconditionBlockJacobi, these blocks may be of varying
- * size, non- contiguous, and overlapping. On the other hand, this class does
- * not implement the preconditioner interface expected by Solver objects.
+ * They perform an additive Schwarz method on the blocks provided in the block
+ * list of AdditionalData. Differing from PreconditionBlockJacobi, these
+ * blocks may be of varying size, non- contiguous, and overlapping. On the
+ * other hand, this class does not implement the preconditioner interface
+ * expected by Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
*
* This class implements the step() and Tstep() functions expected by the
* @ref ConceptRelaxationType "relaxation concept".
- * They perform a
- * multiplicative Schwarz method on the blocks provided in the block list of
- * AdditionalData. Differing from PreconditionBlockSOR, these blocks may be
- * of varying size, non-contiguous, and overlapping. On the other hand, this
- * class does not implement the preconditioner interface expected by Solver
- * objects.
+ * They perform a multiplicative Schwarz method on the blocks provided in the
+ * block list of AdditionalData. Differing from PreconditionBlockSOR, these
+ * blocks may be of varying size, non-contiguous, and overlapping. On the
+ * other hand, this class does not implement the preconditioner interface
+ * expected by Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
*
* This class implements the step() and Tstep() functions expected by the
* @ref ConceptRelaxationType "relaxation concept".
- * They perform a
- * multiplicative Schwarz method on the blocks provided in the block list of
- * AdditionalData in symmetric fashion. Differing from PreconditionBlockSSOR,
- * these blocks may be of varying size, non-contiguous, and overlapping. On
- * the other hand, this class does not implement the preconditioner interface
- * expected by Solver objects.
+ * They perform a multiplicative Schwarz method on the blocks provided in the
+ * block list of AdditionalData in symmetric fashion. Differing from
+ * PreconditionBlockSSOR, these blocks may be of varying size, non-contiguous,
+ * and overlapping. On the other hand, this class does not implement the
+ * preconditioner interface expected by Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
/**
* @relates LinearOperator
*
- * Returns a LinearOperator that performs the operations
- * associated with the Schur complement. There are two additional
- * helper functions, condense_schur_rhs() and postprocess_schur_solution(), that are likely
- * necessary to be used in order to perform any useful tasks in linear
- * algebra with this operator.
+ * Returns a LinearOperator that performs the operations associated with the
+ * Schur complement. There are two additional helper functions,
+ * condense_schur_rhs() and postprocess_schur_solution(), that are likely
+ * necessary to be used in order to perform any useful tasks in linear algebra
+ * with this operator.
*
* We construct the definition of the Schur complement in the following way:
*
- * Consider a general system of linear equations that can be
- * decomposed into two major sets of equations:
+ * Consider a general system of linear equations that can be decomposed into
+ * two major sets of equations:
* @f{eqnarray*}{
* \mathbf{K}\mathbf{d} = \mathbf{f}
* \quad \Rightarrow\quad
* f \\ g
* \end{array}\right),
* @f}
- * where $ A,B,C,D $ represent general subblocks of the matrix
- * $ \mathbf{K} $ and, similarly, general subvectors of
- * $ \mathbf{d},\mathbf{f} $ are given by $ x,y,f,g $ .
+ * where $ A,B,C,D $ represent general subblocks of the matrix $ \mathbf{K} $
+ * and, similarly, general subvectors of $ \mathbf{d},\mathbf{f} $ are given
+ * by $ x,y,f,g $ .
*
* This is equivalent to the following two statements:
* @f{eqnarray*}{
* (2) \quad Cx + Dy &=& g \quad .
* @f}
*
- * Assuming that $ A,D $ are both square and invertible, we could
- * then perform one of two possible substitutions,
+ * Assuming that $ A,D $ are both square and invertible, we could then perform
+ * one of two possible substitutions,
* @f{eqnarray*}{
* (3) \quad x &=& A^{-1}(f - By) \quad \text{from} \quad (1) \\
* (4) \quad y &=& D^{-1}(g - Cx) \quad \text{from} \quad (2) ,
* @f}
- * which amount to performing block Gaussian elimination on
- * this system of equations.
+ * which amount to performing block Gaussian elimination on this system of
+ * equations.
*
- * For the purpose of the current implementation, we choose to
- * substitute (3) into (2)
+ * For the purpose of the current implementation, we choose to substitute (3)
+ * into (2)
* @f{eqnarray*}{
* C \: A^{-1}(f - By) + Dy &=& g \\
* -C \: A^{-1} \: By + Dy &=& g - C \: A^{-1} \: f \quad .
* (5) \quad (D - C\: A^{-1} \:B)y = g - C \: A^{-1} f
* \quad \Rightarrow \quad Sy = g'
* @f]
- * with $ S = (D - C\: A^{-1} \:B) $ being the Schur complement
- * and the modified right-hand side vector $ g' = g - C \: A^{-1} f $ arising from
- * the condensation step.
- * Note that for this choice of $ S $, submatrix $ D $
- * need not be invertible and may thus be the null matrix.
- * Ideally $ A $ should be well-conditioned.
+ * with $ S = (D - C\: A^{-1} \:B) $ being the Schur complement and the
+ * modified right-hand side vector $ g' = g - C \: A^{-1} f $ arising from the
+ * condensation step. Note that for this choice of $ S $, submatrix $ D $ need
+ * not be invertible and may thus be the null matrix. Ideally $ A $ should be
+ * well-conditioned.
*
- * So for any arbitrary vector $ a $, the Schur complement
- * performs the following operation:
+ * So for any arbitrary vector $ a $, the Schur complement performs the
+ * following operation:
* @f[
* (6) \quad Sa = (D - C \: A^{-1} \: B)a
* @f]
*
- * A typical set of steps needed the solve a linear system (1),(2)
- * would be:
+ * A typical set of steps needed the solve a linear system (1),(2) would be:
* 1. Define the inverse matrix @p A_inv (using inverse_operator()).
* 2. Define the Schur complement $ S $ (using schur_complement()).
* 3. Define iterative inverse matrix $ S^{-1} $ such that (6)
- * holds.
- * It is necessary to use a solver with a preconditioner
- * to compute the approximate inverse operation of $ S $ since
- * we never compute $ S $ directly, but rather the result of
- * its operation.
- * To achieve this, one may again use the inverse_operator() in
- * conjunction with the Schur complement that we've just
- * constructed.
- * Observe that the both $ S $ and its preconditioner operate
- * over the same space as $ D $.
+ * holds. It is necessary to use a solver with a preconditioner to compute the
+ * approximate inverse operation of $ S $ since we never compute $ S $
+ * directly, but rather the result of its operation. To achieve this, one may
+ * again use the inverse_operator() in conjunction with the Schur complement
+ * that we've just constructed. Observe that the both $ S $ and its
+ * preconditioner operate over the same space as $ D $.
* 4. Perform pre-processing step on the RHS of (5) using
- * condense_schur_rhs():
+ * condense_schur_rhs():
* @f[
* g' = g - C \: A^{-1} \: f
* @f]
* y = S^{-1} g'
* @f]
* 6. Perform the post-processing step from (3) using
- * postprocess_schur_solution():
+ * postprocess_schur_solution():
* @f[
* x = A^{-1} (f - By)
* @f]
*
* In the above example, the preconditioner for $ S $ was defined as the
* preconditioner for $ D $, which is valid since they operate on the same
- * space.
- * However, if $ D $ and $ S $ are too dissimilar, then this may lead to
- * a large number of solver iterations as $ \text{prec}(D) $ is not a good
+ * space. However, if $ D $ and $ S $ are too dissimilar, then this may lead
+ * to a large number of solver iterations as $ \text{prec}(D) $ is not a good
* approximation for $ S^{-1} $.
*
* A better preconditioner in such a case would be one that provides a more
- * representative approximation for $ S^{-1} $.
- * One approach is shown in step-22, where $ D $ is the null matrix and the
- * preconditioner for $ S^{-1} $ is derived from the mass matrix over this
- * space.
+ * representative approximation for $ S^{-1} $. One approach is shown in
+ * step-22, where $ D $ is the null matrix and the preconditioner for $ S^{-1}
+ * $ is derived from the mass matrix over this space.
*
* From another viewpoint, a similar result can be achieved by first
* constructing an object that represents an approximation for $ S $ wherein
- * expensive operation, namely $ A^{-1} $, is approximated.
- * Thereafter we construct the approximate inverse operator $ \tilde{S}^{-1} $
- * which is then used as the preconditioner for computing $ S^{-1} $.
+ * expensive operation, namely $ A^{-1} $, is approximated. Thereafter we
+ * construct the approximate inverse operator $ \tilde{S}^{-1} $ which is then
+ * used as the preconditioner for computing $ S^{-1} $.
* @code
* // Construction of approximate inverse of Schur complement
* const auto A_inv_approx = linear_operator(preconditioner_A);
* y = S_inv * rhs; // Solve for y
* x = postprocess_schur_solution (A_inv,B,y,f);
* @endcode
- * Note that due to the construction of @c S_inv_approx and subsequently
- * @c S_inv, there are a pair of nested iterative solvers which could
- * collectively consume a lot of resources.
- * Therefore care should be taken in the choices leading to the construction
- * of the iterative inverse_operators.
+ * Note that due to the construction of @c S_inv_approx and subsequently @c
+ * S_inv, there are a pair of nested iterative solvers which could
+ * collectively consume a lot of resources. Therefore care should be taken in
+ * the choices leading to the construction of the iterative inverse_operators.
* One might consider the use of a IterationNumberControl (or a similar
- * mechanism) to limit the number of inner solver iterations.
- * This controls the accuracy of the approximate inverse operation
- * $ \tilde{S}^{-1} $ which acts only as the preconditioner for
- * $ S^{-1} $.
- * Furthermore, the preconditioner to $ \tilde{S}^{-1} $, which in this example is
- * $ \text{prec}(D) $, should ideally be computationally inexpensive.
+ * mechanism) to limit the number of inner solver iterations. This controls
+ * the accuracy of the approximate inverse operation $ \tilde{S}^{-1} $ which
+ * acts only as the preconditioner for $ S^{-1} $. Furthermore, the
+ * preconditioner to $ \tilde{S}^{-1} $, which in this example is $
+ * \text{prec}(D) $, should ideally be computationally inexpensive.
*
- * However, if an iterative solver based on IterationNumberControl is used as a
- * preconditioner then the preconditioning operation is not a linear operation.
- * Here a flexible solver like SolverFGMRES (flexible GMRES) is best employed as an
- * outer solver in order to deal with the variable behaviour of the preconditioner.
- * Otherwise the iterative solver can stagnate somewhere near the tolerance of the
- * preconditioner or generally behave erratically.
- * Alternatively, using a ReductionControl would ensure that the preconditioner
- * always solves to the same tolerance, thereby rendering its behaviour constant.
+ * However, if an iterative solver based on IterationNumberControl is used as
+ * a preconditioner then the preconditioning operation is not a linear
+ * operation. Here a flexible solver like SolverFGMRES (flexible GMRES) is
+ * best employed as an outer solver in order to deal with the variable
+ * behaviour of the preconditioner. Otherwise the iterative solver can
+ * stagnate somewhere near the tolerance of the preconditioner or generally
+ * behave erratically. Alternatively, using a ReductionControl would ensure
+ * that the preconditioner always solves to the same tolerance, thereby
+ * rendering its behaviour constant.
*
- * Further examples of this functionality can be found in
- * the test-suite, such as
- * <code>tests/lac/schur_complement_01.cc</code> .
- * The solution of a multi-component problem (namely step-22) using the
- * schur_complement can be found in
- * <code>tests/lac/schur_complement_03.cc</code> .
+ * Further examples of this functionality can be found in the test-suite, such
+ * as <code>tests/lac/schur_complement_01.cc</code> . The solution of a multi-
+ * component problem (namely step-22) using the schur_complement can be found
+ * in <code>tests/lac/schur_complement_03.cc</code> .
*
* @see
* @ref GlossBlockLA "Block (linear algebra)"
*
* For the system of equations
* @f{eqnarray*}{
- Ax + By &=& f \\
- Cx + Dy &=& g \quad ,
+ * Ax + By &=& f \\
+ * Cx + Dy &=& g \quad ,
* @f}
- * this operation performs the pre-processing (condensation)
- * step on the RHS subvector @p g so that the Schur complement
- * can be used to solve this system of equations.
- * More specifically, it produces an object that represents the
- * condensed form of the subvector @p g, namely
+ * this operation performs the pre-processing (condensation) step on the RHS
+ * subvector @p g so that the Schur complement can be used to solve this
+ * system of equations. More specifically, it produces an object that
+ * represents the condensed form of the subvector @p g, namely
* @f[
- g' = g - C \: A^{-1} \: f
- @f]
+ * g' = g - C \: A^{-1} \: f
+ * @f]
*
* @see
* @ref GlossBlockLA "Block (linear algebra)"
*
* For the system of equations
* @f{eqnarray*}{
- Ax + By &=& f \\
- Cx + Dy &=& g \quad ,
+ * Ax + By &=& f \\
+ * Cx + Dy &=& g \quad ,
* @f}
- * this operation performs the post-processing step of the
- * Schur complement to solve for the second subvector @p x once
- * subvector @p y is known, with the result that
+ * this operation performs the post-processing step of the Schur complement to
+ * solve for the second subvector @p x once subvector @p y is known, with the
+ * result that
* @f[
- x = A^{-1}(f - By)
- @f]
+ * x = A^{-1}(f - By)
+ * @f]
*
* @see
* @ref GlossBlockLA "Block (linear algebra)"
DEAL_II_NAMESPACE_OPEN
/**
- * Base namespace for solver classes using the SLEPc solvers which are selected
- * based on flags passed to the eigenvalue problem solver context. Derived
- * classes set the right flags to set the right solver.
+ * Base namespace for solver classes using the SLEPc solvers which are
+ * selected based on flags passed to the eigenvalue problem solver context.
+ * Derived classes set the right flags to set the right solver.
*
* The SLEPc solvers are intended to be used for solving the generalized
* eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
*
* For cases when spectral transformations are used in conjunction with
* Krylov-type solvers or Davidson-type eigensolvers are employed one can
- * additionally specify which linear solver and preconditioner to use.
- * This can be achieved as follows
+ * additionally specify which linear solver and preconditioner to use. This
+ * can be achieved as follows
* @code
* PETScWrappers::PreconditionBoomerAMG::AdditionalData data;
* data.symmetric_operator = true;
* eigensolver.solve (stiffness_matrix,mass_matrix,eigenvalues,eigenfunctions,eigenfunctions.size());
* @endcode
*
- * In order to support this usage case, different from PETSc wrappers, the classes
- * in this namespace are written in such a way that the underlying SLEPc objects
- * are initialized in constructors. By doing so one also avoid caching of different
- * settings (such as target eigenvalue or type of the problem); instead those are
- * applied straight away when the corresponding functions of the wrapper classes
- * are called.
+ * In order to support this usage case, different from PETSc wrappers, the
+ * classes in this namespace are written in such a way that the underlying
+ * SLEPc objects are initialized in constructors. By doing so one also avoid
+ * caching of different settings (such as target eigenvalue or type of the
+ * problem); instead those are applied straight away when the corresponding
+ * functions of the wrapper classes are called.
*
* An alternative implementation to the one above is to use the API internals
* directly within the application code. In this way the calling sequence
* specific vector class used (i.e. local_dofs for MPI vectors). However,
* while copying eigenvectors, at least twice the memory size of
* <tt>eigenvectors</tt> is being used (and can be more). To avoid doing
- * this, the fairly standard calling sequence executed here is used:
- * Set up matrices for solving; Actually solve the system; Gather the solution(s).
+ * this, the fairly standard calling sequence executed here is used: Set
+ * up matrices for solving; Actually solve the system; Gather the
+ * solution(s).
*
* @note Note that the number of converged eigenvectors can be larger than
* the number of eigenvectors requested; this is due to a round off error
/**
* Set the initial vector space for the solver.
*
- * By default, SLEPc initializes the starting vector or the initial subspace randomly.
+ * By default, SLEPc initializes the starting vector or the initial
+ * subspace randomly.
*/
template <typename Vector>
void
EPSLanczosReorthogType reorthog;
/**
- * Constructor. By default sets the type of reorthogonalization used during the Lanczos iteration to full.
+ * Constructor. By default sets the type of reorthogonalization used
+ * during the Lanczos iteration to full.
*/
AdditionalData(const EPSLanczosReorthogType r = EPS_LANCZOS_REORTHOG_FULL);
};
struct AdditionalData
{
/**
- * Use double expansion in search subspace.
- */
+ * Use double expansion in search subspace.
+ */
bool double_expansion;
/**
void set_matrix_mode(const STMatMode mode);
/**
- * Set solver to be used when solving a system of
- * linear algebraic equations inside the eigensolver.
+ * Set solver to be used when solving a system of linear algebraic
+ * equations inside the eigensolver.
*/
void
set_solver(const PETScWrappers::SolverBase &solver);
* @see Y. Saad: "Iterative methods for Sparse Linear Systems", section 6.7.3
* for details.
*
- * The coefficients, eigenvalues and condition number (computed as the ratio of
- * the largest over smallest eigenvalue) can be obtained by connecting a
- * function as a slot to the solver using one of the functions
- * @p connect_coefficients_slot, @p connect_eigenvalues_slot and
- * @p connect_condition_number_slot. These slots will then be called from the
+ * The coefficients, eigenvalues and condition number (computed as the ratio
+ * of the largest over smallest eigenvalue) can be obtained by connecting a
+ * function as a slot to the solver using one of the functions @p
+ * connect_coefficients_slot, @p connect_eigenvalues_slot and @p
+ * connect_condition_number_slot. These slots will then be called from the
* solver with the estimates as argument.
*
* @deprecated Alternatively these estimates can be written to deallog by
/**
* Connect a slot to retrieve the CG coefficients. The slot will be called
* with alpha as the first argument and with beta as the second argument,
- * where alpha and beta follow the notation in
- * Y. Saad: "Iterative methods for Sparse Linear Systems", section 6.7.
- * Called once per iteration
+ * where alpha and beta follow the notation in Y. Saad: "Iterative methods
+ * for Sparse Linear Systems", section 6.7. Called once per iteration
*/
boost::signals2::connection
connect_coefficients_slot(
const std_cxx11::function<void (double,double)> &slot);
/**
- * Connect a slot to retrieve the estimated condition number.
- * Called on each iteration if every_iteration=true, otherwise called once
- * when iterations are ended (i.e., either because convergence has been
- * achieved, or because divergence has been detected).
+ * Connect a slot to retrieve the estimated condition number. Called on each
+ * iteration if every_iteration=true, otherwise called once when iterations
+ * are ended (i.e., either because convergence has been achieved, or because
+ * divergence has been detected).
*/
boost::signals2::connection
connect_condition_number_slot(const std_cxx11::function<void (double)> &slot,
const bool every_iteration=false);
/**
- * Connect a slot to retrieve the estimated eigenvalues.
- * Called on each iteration if every_iteration=true, otherwise called once
- * when iterations are ended (i.e., either because convergence has been
- * achieved, or because divergence has been detected).
+ * Connect a slot to retrieve the estimated eigenvalues. Called on each
+ * iteration if every_iteration=true, otherwise called once when iterations
+ * are ended (i.e., either because convergence has been achieved, or because
+ * divergence has been detected).
*/
boost::signals2::connection
connect_eigenvalues_slot(
const VectorType &d) const;
/**
- * Estimates the eigenvalues from diagonal and offdiagonal. Uses
- * these estimate to compute the condition number. Calls the signals
+ * Estimates the eigenvalues from diagonal and offdiagonal. Uses these
+ * estimate to compute the condition number. Calls the signals
* eigenvalues_signal and cond_signal with these estimates as arguments.
* Outputs the eigenvalues/condition-number to deallog if
* log_eigenvalues/log_cond is true.
AdditionalData additional_data;
/**
- * Signal used to retrieve the CG coefficients.
- * Called on each iteration.
+ * Signal used to retrieve the CG coefficients. Called on each iteration.
*/
boost::signals2::signal<void (double,double)> coefficients_signal;
/**
- * Signal used to retrieve the estimated condition number.
- * Called once when all iterations are ended.
+ * Signal used to retrieve the estimated condition number. Called once when
+ * all iterations are ended.
*/
boost::signals2::signal<void (double)> condition_number_signal;
/**
- * Signal used to retrieve the estimated condition numbers.
- * Called on each iteration.
+ * Signal used to retrieve the estimated condition numbers. Called on each
+ * iteration.
*/
boost::signals2::signal<void (double)> all_condition_numbers_signal;
/**
- * Signal used to retrieve the estimated eigenvalues.
- * Called once when all iterations are ended.
+ * Signal used to retrieve the estimated eigenvalues. Called once when all
+ * iterations are ended.
*/
boost::signals2::signal<void (const std::vector<double> &)> eigenvalues_signal;
/**
- * Signal used to retrieve the estimated eigenvalues.
- * Called on each iteration.
+ * Signal used to retrieve the estimated eigenvalues. Called on each
+ * iteration.
*/
boost::signals2::signal<void (const std::vector<double> &)> all_eigenvalues_signal;
{
public:
/**
- * Constructor. Prepares an array of @p VectorType of length @p max_size.
+ * Constructor. Prepares an array of @p VectorType of length @p
+ * max_size.
*/
TmpVectors(const unsigned int max_size,
VectorMemory<VectorType> &vmem);
*
* <h3>Eigenvalue and condition number estimates</h3>
*
- * This class can estimate eigenvalues and condition number during the solution
- * process. This is done by creating the Hessenberg matrix during the inner
- * iterations. The eigenvalues are estimated as the eigenvalues of the
+ * This class can estimate eigenvalues and condition number during the
+ * solution process. This is done by creating the Hessenberg matrix during the
+ * inner iterations. The eigenvalues are estimated as the eigenvalues of the
* Hessenberg matrix and the condition number is estimated as the ratio of the
* largest and smallest singular value of the Hessenberg matrix. The estimates
- * can be obtained by connecting a function as a slot using
- * @p connect_condition_number_slot and @p connect_eigenvalues_slot. These slots
+ * can be obtained by connecting a function as a slot using @p
+ * connect_condition_number_slot and @p connect_eigenvalues_slot. These slots
* will then be called from the solver with the estimates as argument.
*
*
const PreconditionerType &precondition);
/**
- * Connect a slot to retrieve the estimated condition number.
- * Called on each outer iteration if every_iteration=true, otherwise called
- * once when iterations are ended (i.e., either because convergence has been
- * achieved, or because divergence has been detected).
+ * Connect a slot to retrieve the estimated condition number. Called on each
+ * outer iteration if every_iteration=true, otherwise called once when
+ * iterations are ended (i.e., either because convergence has been achieved,
+ * or because divergence has been detected).
*/
boost::signals2::connection
connect_condition_number_slot(const std_cxx11::function<void (double)> &slot,
const bool every_iteration=false);
/**
- * Connect a slot to retrieve the estimated eigenvalues.
- * Called on each outer iteration if every_iteration=true, otherwise called
- * once when iterations are ended (i.e., either because convergence has been
- * achieved, or because divergence has been detected).
+ * Connect a slot to retrieve the estimated eigenvalues. Called on each
+ * outer iteration if every_iteration=true, otherwise called once when
+ * iterations are ended (i.e., either because convergence has been achieved,
+ * or because divergence has been detected).
*/
boost::signals2::connection
connect_eigenvalues_slot(
AdditionalData additional_data;
/**
- * Signal used to retrieve the estimated condition number.
- * Called once when all iterations are ended.
+ * Signal used to retrieve the estimated condition number. Called once when
+ * all iterations are ended.
*/
boost::signals2::signal<void (double)> condition_number_signal;
/**
- * Signal used to retrieve the estimated condition numbers.
- * Called on each outer iteration.
+ * Signal used to retrieve the estimated condition numbers. Called on each
+ * outer iteration.
*/
boost::signals2::signal<void (double)> all_condition_numbers_signal;
/**
- * Signal used to retrieve the estimated eigenvalues.
- * Called once when all iterations are ended.
+ * Signal used to retrieve the estimated eigenvalues. Called once when all
+ * iterations are ended.
*/
boost::signals2::signal<void (const std::vector<std::complex<double> > &)> eigenvalues_signal;
/**
- * Signal used to retrieve the estimated eigenvalues.
- * Called on each outer iteration.
+ * Signal used to retrieve the estimated eigenvalues. Called on each outer
+ * iteration.
*/
boost::signals2::signal<void (const std::vector<std::complex<double> > &)> all_eigenvalues_signal;
bool &re_orthogonalize);
/**
- * Estimates the eigenvalues from the Hessenberg matrix, H_orig, generated
- * during the inner iterations. Uses these estimate to compute the condition
- * number. Calls the signals eigenvalues_signal and cond_signal with these
- * estimates as arguments. Outputs the eigenvalues to deallog if
- * log_eigenvalues is true.
- */
+ * Estimates the eigenvalues from the Hessenberg matrix, H_orig, generated
+ * during the inner iterations. Uses these estimate to compute the condition
+ * number. Calls the signals eigenvalues_signal and cond_signal with these
+ * estimates as arguments. Outputs the eigenvalues to deallog if
+ * log_eigenvalues is true.
+ */
static void
compute_eigs_and_cond(
const FullMatrix<double> &H_orig ,
/**
* Return the dimension of the codomain (or range) space. It calls the
- * inherited SparseMatrix::m() function. To remember: the matrix is
- * of dimension $m \times n$.
+ * inherited SparseMatrix::m() function. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type m () const;
/**
* Return the dimension of the domain space. It calls the inherited
- * SparseMatrix::n() function. To remember: the matrix is of dimension
- * $m \times n$.
+ * SparseMatrix::n() function. To remember: the matrix is of dimension $m
+ * \times n$.
*/
size_type n () const;
*
* @ingroup Solvers Preconditioners
*
- * @author Wolfgang Bangerth, 2004; extension for full compatibility
- * with LinearOperator class: Jean-Paul Pelteret, 2015
+ * @author Wolfgang Bangerth, 2004; extension for full compatibility with
+ * LinearOperator class: Jean-Paul Pelteret, 2015
*/
class SparseDirectUMFPACK : public Subscriptor
{
//TODO: Add multithreading to the other vmult functions.
/**
- * Sparse matrix. This class implements the functionality to store
- * matrix entry values in the locations denoted by a
- * SparsityPattern. See
+ * Sparse matrix. This class implements the functionality to store matrix
+ * entry values in the locations denoted by a SparsityPattern. See
* @ref Sparsity
- * for a discussion about the
- * separation between sparsity patterns and matrices.
+ * for a discussion about the separation between sparsity patterns and
+ * matrices.
*
* The elements of a SparseMatrix are stored in the same order in which the
* SparsityPattern class stores its entries. Within each row, elements are
* generally stored left-to-right in increasing column index order; the
- * exception to this rule is that if the matrix is square (m() ==
- * n()), then the diagonal entry is stored as the first element in
- * each row to make operations like applying a Jacobi or SSOR preconditioner
- * faster. As a consequence, if you traverse the elements of a row of a
- * SparseMatrix with the help of iterators into this object (using
- * SparseMatrix::begin and SparseMatrix::end) you will find that the elements
- * are not sorted by column index within each row whenever the matrix is
- * square.
+ * exception to this rule is that if the matrix is square (m() == n()), then
+ * the diagonal entry is stored as the first element in each row to make
+ * operations like applying a Jacobi or SSOR preconditioner faster. As a
+ * consequence, if you traverse the elements of a row of a SparseMatrix with
+ * the help of iterators into this object (using SparseMatrix::begin and
+ * SparseMatrix::end) you will find that the elements are not sorted by column
+ * index within each row whenever the matrix is square.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
* Copying matrices is an expensive operation that we do not want to happen
* by accident through compiler generated code for <code>operator=</code>.
* (This would happen, for example, if one accidentally declared a function
- * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
- * The functionality of copying matrices is implemented in this member function
- * instead. All copy operations of objects of this type therefore require an
- * explicit function call.
+ * argument of the current type <i>by value</i> rather than <i>by
+ * reference</i>.) The functionality of copying matrices is implemented in
+ * this member function instead. All copy operations of objects of this type
+ * therefore require an explicit function call.
*
* The source matrix may be a matrix of arbitrary type, as long as its data
* type is convertible to the data type of this matrix.
* away and only non-zero data is added. The default value is <tt>true</tt>,
* i.e., zero values won't be added into the matrix.
*
- * If anyway a new element will be inserted and it does not exist,
- * allocates the entry.
+ * If anyway a new element will be inserted and it does not exist, allocates
+ * the entry.
*
- * @note You may need to insert some zero elements to keep a
- * symmetric sparsity pattern for the matrix.
+ * @note You may need to insert some zero elements to keep a symmetric
+ * sparsity pattern for the matrix.
*/
void set (const size_type i, const size_type j,
const number value, const bool elide_zero_values = true);
* Copying matrices is an expensive operation that we do not want to happen
* by accident through compiler generated code for <code>operator=</code>.
* (This would happen, for example, if one accidentally declared a function
- * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
- * The functionality of copying matrices is implemented in this member function
- * instead. All copy operations of objects of this type therefore require an
- * explicit function call.
+ * argument of the current type <i>by value</i> rather than <i>by
+ * reference</i>.) The functionality of copying matrices is implemented in
+ * this member function instead. All copy operations of objects of this type
+ * therefore require an explicit function call.
*
* The source matrix may be a matrix of arbitrary type, as long as its data
* type is convertible to the data type of this matrix.
* Objects of this class are constructed by passing a vector of indices of the
* degrees of freedom of the Lagrange multiplier. In the actual
* preconditioning method, these rows are traversed in the order in which the
- * appear in the matrix. Since this is a Gauß-Seidel like procedure,
- * remember to have a good ordering in advance (for transport dominated
- * problems, Cuthill-McKee algorithms are a good means for this, if points on
- * the inflow boundary are chosen as starting points for the renumbering).
+ * appear in the matrix. Since this is a Gauß-Seidel like procedure, remember
+ * to have a good ordering in advance (for transport dominated problems,
+ * Cuthill-McKee algorithms are a good means for this, if points on the inflow
+ * boundary are chosen as starting points for the renumbering).
*
* For each selected degree of freedom, a local system of equations is built
* by the degree of freedom itself and all other values coupling immediately,
~SparseVanka();
/**
- * Parameters for SparseVanka.
- */
+ * Parameters for SparseVanka.
+ */
class AdditionalData
{
public:
const bool conserve_mem;
/**
- * Number of threads to be used when building the inverses. Only relevant in
- * multithreaded mode.
+ * Number of threads to be used when building the inverses. Only relevant
+ * in multithreaded mode.
*/
const unsigned int n_threads;
};
const Vector<number2> &src) const;
/**
- * Apply transpose preconditioner. This function takes the residual in
- * @p src and returns the resulting update vector in @p dst.
+ * Apply transpose preconditioner. This function takes the residual in @p
+ * src and returns the resulting update vector in @p dst.
*/
template<typename number2>
void Tvmult (Vector<number2> &dst,
/**
- * A class that can store which elements of a matrix are nonzero (or,
- * in fact, <i>may</i> be nonzero) and for which we have to allocate
- * memory to store their values. This class is an example of the
- * "static" type of sparsity patters (see
+ * A class that can store which elements of a matrix are nonzero (or, in fact,
+ * <i>may</i> be nonzero) and for which we have to allocate memory to store
+ * their values. This class is an example of the "static" type of sparsity
+ * patters (see
* @ref Sparsity).
- * It uses the
- * <a href="https://en.wikipedia.org/wiki/Sparse_matrix">compressed
- * row storage (CSR)</a> format to store data, and is used as the
- * basis for the SparseMatrix class.
+ * It uses the <a
+ * href="https://en.wikipedia.org/wiki/Sparse_matrix">compressed row storage
+ * (CSR)</a> format to store data, and is used as the basis for the
+ * SparseMatrix class.
*
* The elements of a SparsityPattern, corresponding to the places where
* SparseMatrix objects can store nonzero entries, are stored row-by-row.
*
* @param[in] m The number of rows.
* @param[in] n The number of columns.
- * @param[in] row_lengths Possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @param[in] row_lengths Possible number of nonzero entries for each row.
+ * This vector must have one entry for each row.
*/
SparsityPattern (const size_type m,
const size_type n,
* Initialize a quadratic pattern of size <tt>m x m</tt>.
*
* @param[in] m The number of rows and columns.
- * @param[in] row_lengths Maximum number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @param[in] row_lengths Maximum number of nonzero entries for each row.
+ * This vector must have one entry for each row.
*/
SparsityPattern (const size_type m,
const std::vector<unsigned int> &row_lengths);
void print_gnuplot (std::ostream &out) const;
/**
- * Prints the sparsity of the matrix in a .svg file which can be opened in a web browser.
- * The .svg file contains squares which correspond to the entries in the matrix. An entry
- * in the matrix which contains a non-zero value corresponds with a red square while a
- * zero-valued entry in the matrix correspond with a white square.
+ * Prints the sparsity of the matrix in a .svg file which can be opened in a
+ * web browser. The .svg file contains squares which correspond to the
+ * entries in the matrix. An entry in the matrix which contains a non-zero
+ * value corresponds with a red square while a zero-valued entry in the
+ * matrix correspond with a white square.
*/
void print_svg (std::ostream &out) const;
* instead.
*
* @param[in,out] dsp The locally built sparsity pattern to be modified.
-
* @param owned_set_per_cpu Typically the value given by
* DoFHandler::locally_owned_dofs_per_processor.
*
* on the same Epetra_map is intended. In that case, the same communicator
* is used for data exchange.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const std::vector<Epetra_Map> &partitioning,
const bool omit_zeroing_entries = false);
* with a distributed vector based on the same initialization is intended.
* In that case, the same communicator is used for data exchange.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const std::vector<IndexSet> &partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD,
* elements in the first argument, and with the respective sizes. Since no
* distribution map is given, all vectors are local vectors.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const std::vector<size_type> &N,
const bool omit_zeroing_entries=false);
* Epetra_Maps given in the input argument, according to the parallel
* distribution of the individual components described in the maps.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*
* This function is deprecated.
*/
* index sets given in the input argument, according to the parallel
* distribution of the individual components described in the maps.
*
- * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
+ * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
+ * zeros.
*/
void reinit (const std::vector<IndexSet> ¶llel_partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD,
const dealii::parallel::distributed::Vector<double> &src) const;
/**
- * Return a reference to the underlaying Trilinos Epetra_Operator.
- * So you can use the preconditioner with unwrapped Trilinos solver.
+ * Return a reference to the underlaying Trilinos Epetra_Operator. So you
+ * can use the preconditioner with unwrapped Trilinos solver.
*
- * Calling this function from an uninitialized object will cause an exception.
+ * Calling this function from an uninitialized object will cause an
+ * exception.
*/
Epetra_Operator &trilinos_operator() const;
* Specifies the constant modes (near null space) of the matrix. This
* parameter tells AMG whether we work on a scalar equation (where the
* near null space only consists of ones, and default value is OK) or on
- * a vector-valued equation.
- * For vector-valued equation problem with <tt>n_component</tt>, the
- * provided @p constant_modes should fulfill the following requirements:
+ * a vector-valued equation. For vector-valued equation problem with
+ * <tt>n_component</tt>, the provided @p constant_modes should fulfill
+ * the following requirements:
* <ul>
* <li> n_component.size() == <tt>n_component</tt> </li>
- * <li> n_component[*].size() == n_dof_local or
- * n_component[*].size() == n_dof_global </li>
- * <li> n_component[<tt>ic</tt>][<tt>id</tt>] == "<tt>id</tt><em>th</em>
- * DoF is corresponding to component <tt>ic</tt> </li>
+ * <li> n_component[*].size() == n_dof_local or n_component[*].size()
+ * == n_dof_global </li>
+ * <li> n_component[<tt>ic</tt>][<tt>id</tt>] ==
+ * "<tt>id</tt><em>th</em> DoF is corresponding to component <tt>ic</tt>
+ * </li>
* </ul>
*/
std::vector<std::vector<bool> > constant_modes;
*
* For the case that the matrix is constructed without a sparsity pattern
* and new matrix entries are added on demand, please note the following
- * behavior imposed by the underlying Epetra_FECrsMatrix data
- * structure: If the same matrix entry is inserted more than once, the
- * matrix entries will be added upon calling compress() (since Epetra does
- * not track values to the same entry before the final compress() is
- * called), even if VectorOperation::insert is specified as argument to
- * compress(). In the case you cannot make sure that matrix entries are
- * only set once, initialize the matrix with a sparsity pattern to fix the
- * matrix structure before inserting elements.
+ * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
+ * If the same matrix entry is inserted more than once, the matrix entries
+ * will be added upon calling compress() (since Epetra does not track
+ * values to the same entry before the final compress() is called), even
+ * if VectorOperation::insert is specified as argument to compress(). In
+ * the case you cannot make sure that matrix entries are only set once,
+ * initialize the matrix with a sparsity pattern to fix the matrix
+ * structure before inserting elements.
*/
void set (const size_type i,
const size_type j,
*
* For the case that the matrix is constructed without a sparsity pattern
* and new matrix entries are added on demand, please note the following
- * behavior imposed by the underlying Epetra_FECrsMatrix data
- * structure: If the same matrix entry is inserted more than once, the
- * matrix entries will be added upon calling compress() (since Epetra does
- * not track values to the same entry before the final compress() is
- * called), even if VectorOperation::insert is specified as argument to
- * compress(). In the case you cannot make sure that matrix entries are
- * only set once, initialize the matrix with a sparsity pattern to fix the
- * matrix structure before inserting elements.
+ * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
+ * If the same matrix entry is inserted more than once, the matrix entries
+ * will be added upon calling compress() (since Epetra does not track
+ * values to the same entry before the final compress() is called), even
+ * if VectorOperation::insert is specified as argument to compress(). In
+ * the case you cannot make sure that matrix entries are only set once,
+ * initialize the matrix with a sparsity pattern to fix the matrix
+ * structure before inserting elements.
*/
void set (const std::vector<size_type> &indices,
const FullMatrix<TrilinosScalar> &full_matrix,
*
* For the case that the matrix is constructed without a sparsity pattern
* and new matrix entries are added on demand, please note the following
- * behavior imposed by the underlying Epetra_FECrsMatrix data
- * structure: If the same matrix entry is inserted more than once, the
- * matrix entries will be added upon calling compress() (since Epetra does
- * not track values to the same entry before the final compress() is
- * called), even if VectorOperation::insert is specified as argument to
- * compress(). In the case you cannot make sure that matrix entries are
- * only set once, initialize the matrix with a sparsity pattern to fix the
- * matrix structure before inserting elements.
+ * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
+ * If the same matrix entry is inserted more than once, the matrix entries
+ * will be added upon calling compress() (since Epetra does not track
+ * values to the same entry before the final compress() is called), even
+ * if VectorOperation::insert is specified as argument to compress(). In
+ * the case you cannot make sure that matrix entries are only set once,
+ * initialize the matrix with a sparsity pattern to fix the matrix
+ * structure before inserting elements.
*/
void set (const size_type row,
const std::vector<size_type> &col_indices,
*
* For the case that the matrix is constructed without a sparsity pattern
* and new matrix entries are added on demand, please note the following
- * behavior imposed by the underlying Epetra_FECrsMatrix data
- * structure: If the same matrix entry is inserted more than once, the
- * matrix entries will be added upon calling compress() (since Epetra does
- * not track values to the same entry before the final compress() is
- * called), even if VectorOperation::insert is specified as argument to
- * compress(). In the case you cannot make sure that matrix entries are
- * only set once, initialize the matrix with a sparsity pattern to fix the
- * matrix structure before inserting elements.
+ * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
+ * If the same matrix entry is inserted more than once, the matrix entries
+ * will be added upon calling compress() (since Epetra does not track
+ * values to the same entry before the final compress() is called), even
+ * if VectorOperation::insert is specified as argument to compress(). In
+ * the case you cannot make sure that matrix entries are only set once,
+ * initialize the matrix with a sparsity pattern to fix the matrix
+ * structure before inserting elements.
*/
void set (const size_type row,
const size_type n_cols,
/**
* Reinit functionality. This function sets the calling vector to the
* dimension and the parallel distribution of the input vector, but does
- * not copy the elements in <tt>v</tt>. If <tt>omit_zeroing_entries</tt> is not
- * <tt>true</tt>, the elements in the vector are initialized with zero,
- * otherwise the content will be left unchanged and the user has to set
- * all elements.
+ * not copy the elements in <tt>v</tt>. If <tt>omit_zeroing_entries</tt>
+ * is not <tt>true</tt>, the elements in the vector are initialized with
+ * zero, otherwise the content will be left unchanged and the user has
+ * to set all elements.
*
* This function has a third argument, <tt>allow_different_maps</tt>,
* that allows for an exchange of data between two equal-sized vectors
* application of this function is to generate a replication of a whole
* vector on each machine, when the calling vector is built according to
* the localized vector class TrilinosWrappers::Vector, and <tt>v</tt>
- * is a distributed vector. In this case, the variable <tt>omit_zeroing_entries</tt>
- * needs to be set to <tt>false</tt>, since it does not make sense to
- * exchange data between differently parallelized vectors without
- * touching the elements.
+ * is a distributed vector. In this case, the variable
+ * <tt>omit_zeroing_entries</tt> needs to be set to <tt>false</tt>,
+ * since it does not make sense to exchange data between differently
+ * parallelized vectors without touching the elements.
*/
void reinit (const VectorBase &v,
const bool omit_zeroing_entries = false,
/**
* Reinit functionality. This function destroys the old vector content
* and generates a new one based on the input partitioning. The flag
- * <tt>omit_zeroing_entries</tt> determines whether the vector should be filled with
- * zero (false) or left untouched (true).
+ * <tt>omit_zeroing_entries</tt> determines whether the vector should be
+ * filled with zero (false) or left untouched (true).
*
*
* Depending on whether the @p parallel_partitioning argument uniquely
* is generated. This initialization function is appropriate when the data
* in the localized vector should be imported from a distributed vector
* that has been initialized with the same communicator. The variable
- * <tt>omit_zeroing_entries</tt> determines whether the vector should be filled with zero
- * or left untouched.
+ * <tt>omit_zeroing_entries</tt> determines whether the vector should be
+ * filled with zero or left untouched.
*
* Which element of the @p input_map argument are set is in fact ignored,
* the only thing that matters is the size of the index space described by
* generated. This initialization function is appropriate in case the data
* in the localized vector should be imported from a distributed vector
* that has been initialized with the same communicator. The variable
- * <tt>omit_zeroing_entries</tt> determines whether the vector should be filled with zero
- * (false) or left untouched (true).
+ * <tt>omit_zeroing_entries</tt> determines whether the vector should be
+ * filled with zero (false) or left untouched (true).
*
* Which element of the @p input_map argument are set is in fact ignored,
* the only thing that matters is the size of the index space described by
* <tt>reinit(N)</tt>. This cited behaviour is analogous to that of the
* standard library containers.
*
- * If @p omit_zeroing_entries is false, the vector is filled by zeros. Otherwise, the
- * elements are left an unspecified state.
+ * If @p omit_zeroing_entries is false, the vector is filled by zeros.
+ * Otherwise, the elements are left an unspecified state.
*
* This function is virtual in order to allow for derived classes to handle
* memory separately.
*/
/**
- * VectorSpaceVector is an abstract class that is used to define the interface
- * that vector classes need to implement when they want to implement global
- * operations. This class is complementary of ReadWriteVector which allows
- * the access of individual elements but does not allow global operations.
+ * VectorSpaceVector is an abstract class that is used to define the
+ * interface that vector classes need to implement when they want to
+ * implement global operations. This class is complementary of
+ * ReadWriteVector which allows the access of individual elements but does
+ * not allow global operations.
*
* @author Bruno Turcksin, 2015.
*/
* @endcode
*
* The reason this function exists is that this operation involves less
- * memory transfer than calling the two functions separately. This
- * method only needs to load three vectors, @p this, @p V, @p W, whereas
- * calling separate methods means to load the calling vector @p this
- * twice. Since most vector operations are memory transfer limited, this
- * reduces the time by 25\% (or 50\% if @p W equals @p this).
+ * memory transfer than calling the two functions separately. This method
+ * only needs to load three vectors, @p this, @p V, @p W, whereas calling
+ * separate methods means to load the calling vector @p this twice. Since
+ * most vector operations are memory transfer limited, this reduces the
+ * time by 25\% (or 50\% if @p W equals @p this).
*/
virtual Number add_and_dot(const Number a,
const VectorSpaceVector<Number> &V,
/**
* Return an index set that describes which elements of this vector are
- * owned by the current processor. As a consequence, the index sets returned
- * on different procesors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set. Obviously, if a vector is
- * created on only one processor, then the result would satisfy
+ * owned by the current processor. As a consequence, the index sets
+ * returned on different procesors if this is a distributed vector will
+ * form disjoint sets that add up to the complete index set. Obviously, if
+ * a vector is created on only one processor, then the result would
+ * satisfy
* @code
* vec.locally_owned_elements() == complete_index_set(vec.size())
* @endcode
* have of the original object. Notice that it is your own responsibility to
* ensure that the memory you are pointing to is big enough.
*
- * Similarly to what happens in the base class, if
- * 'omit_zeroing_entries' is false, then the entire content of the
- * vector is set to 0, otherwise the content of the memory is left
- * unchanged.
+ * Similarly to what happens in the base class, if 'omit_zeroing_entries' is
+ * false, then the entire content of the vector is set to 0, otherwise the
+ * content of the memory is left unchanged.
*
* Notice that the following snippet of code may not produce what you
* expect:
/**
* Constructor for the reduced functionality. This constructor is equivalent
- * to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * to the other one except that it makes the object use a $Q_1$ mapping
+ * (i.e., an object of type MappingQGeneric(1)) implicitly.
*/
FEEvaluation (const FiniteElement<dim> &fe,
const Quadrature<1> &quadrature,
/**
* Constructor. This constructor is equivalent to the other one except
- * that it makes the object use a $Q_1$ mapping (i.e., an object of
- * type MappingQGeneric(1)) implicitly.
+ * that it makes the object use a $Q_1$ mapping (i.e., an object of type
+ * MappingQGeneric(1)) implicitly.
*/
MappingDataOnTheFly (const Quadrature<1> &quadrature,
const UpdateFlags update_flags);
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but using a $Q_1$ mapping.
+ * Initializes the data structures. Same as above, but using a $Q_1$
+ * mapping.
*/
template <typename DoFHandlerType, typename QuadratureType>
void reinit (const DoFHandlerType &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but using a $Q_1$ mapping.
+ * Initializes the data structures. Same as above, but using a $Q_1$
+ * mapping.
*/
template <typename DoFHandlerType, typename QuadratureType>
void reinit (const std::vector<const DoFHandlerType *> &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but using a $Q_1$ mapping.
+ * Initializes the data structures. Same as above, but using a $Q_1$
+ * mapping.
*/
template <typename DoFHandlerType, typename QuadratureType>
void reinit (const std::vector<const DoFHandlerType *> &dof_handler,
* Objects of this class contain one or more objects of type FEValues,
* FEFaceValues or FESubfaceValues to be used in local integration. They are
* stored in an array of pointers to the base classes FEValuesBase. The
- * template parameter VectorType allows the use of different data types for the
- * global system.
+ * template parameter VectorType allows the use of different data types for
+ * the global system.
*
* Additionally, this function contains space to store the values of finite
* element functions stored in #global_data in the quadrature points. These
* arguments are the name of the vector and indicators, which information
* is to be extracted from the vector. The name refers to an entry in a
* AnyData object, which will be identified by initialize(). The three
- * bool parameters indicate, whether values, gradients and Hessians of
- * the finite element function are to be computed on each cell or face.
+ * bool parameters indicate, whether values, gradients and Hessians of the
+ * finite element function are to be computed on each cell or face.
*/
void add(const std::string &name,
const bool values = true,
* transforming a triplet of iterative solver, matrix and preconditioner into
* a coarse grid solver.
*
- * The type of the matrix (i.e. the template parameter @p MatrixType) should be
- * derived from @p Subscriptor to allow for the use of a smart pointer to it.
+ * The type of the matrix (i.e. the template parameter @p MatrixType) should
+ * be derived from @p Subscriptor to allow for the use of a smart pointer to
+ * it.
*
* @author Guido Kanschat, 1999, Ralf Hartmann, 2002.
*/
/**
* Multilevel matrix selecting from block matrices. This class implements the
- * interface defined by MGMatrixBase. The template parameter @p MatrixType should
- * be a block matrix class like BlockSparseMatrix or @p BlockSparseMatrixEZ.
- * Then, this class stores a pointer to a MGLevelObject of this matrix class.
- * In each @p vmult, the block selected on initialization will be multiplied
- * with the vector provided.
+ * interface defined by MGMatrixBase. The template parameter @p MatrixType
+ * should be a block matrix class like BlockSparseMatrix or @p
+ * BlockSparseMatrixEZ. Then, this class stores a pointer to a MGLevelObject
+ * of this matrix class. In each @p vmult, the block selected on
+ * initialization will be multiplied with the vector provided.
*
* @author Guido Kanschat, 2002
*/
* Initialize for matrices. This function initializes the smoothing
* operator with the same smoother for each level.
*
- * @p additional_data is an object of type @p RelaxationType::AdditionalData and is
- * handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p
+ * RelaxationType::AdditionalData and is handed to the initialization
+ * function of the relaxation method.
*/
template <typename MatrixType2>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* matrices and initializes the smoothing operator with the according
* smoother for each level.
*
- * @p additional_data is an object of type @p RelaxationType::AdditionalData and is
- * handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p RelaxationType::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* This function stores pointers to the level matrices and initializes the
* smoothing operator with the same smoother for each level.
*
- * @p additional_data is an object of type @p RelaxationType::AdditionalData and is
- * handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p RelaxationType::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* This function stores pointers to the level matrices and initializes the
* smoothing operator with the according smoother for each level.
*
- * @p additional_data is an object of type @p RelaxationType::AdditionalData and is
- * handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p RelaxationType::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* matrices and initializes the smoothing operator with the same smoother
* for each level.
*
- * @p additional_data is an object of type @p PreconditionerType::AdditionalData
- * and is handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p
+ * PreconditionerType::AdditionalData and is handed to the initialization
+ * function of the relaxation method.
*/
template <typename MatrixType2>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* matrices and initializes the smoothing operator with the according
* smoother for each level.
*
- * @p additional_data is an object of type @p PreconditionerType::AdditionalData
- * and is handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p
+ * PreconditionerType::AdditionalData and is handed to the initialization
+ * function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* This function stores pointers to the level matrices and initializes the
* smoothing operator with the same smoother for each level.
*
- * @p additional_data is an object of type @p PreconditionerType::AdditionalData
- * and is handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p
+ * PreconditionerType::AdditionalData and is handed to the initialization
+ * function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
* This function stores pointers to the level matrices and initializes the
* smoothing operator with the according smoother for each level.
*
- * @p additional_data is an object of type @p PreconditionerType::AdditionalData
- * and is handed to the initialization function of the relaxation method.
+ * @p additional_data is an object of type @p
+ * PreconditionerType::AdditionalData and is handed to the initialization
+ * function of the relaxation method.
*/
template <typename MatrixType2, class DATA>
void initialize (const MGLevelObject<MatrixType2> &matrices,
/**
* Implementation of transfer between the global vectors and the multigrid
- * levels for use in the derived class MGTransferPrebuilt and other
- * classes. This class is a specialization for the case of
+ * levels for use in the derived class MGTransferPrebuilt and other classes.
+ * This class is a specialization for the case of
* parallel::distributed::Vector that requires a few different calling
* routines as compared to the %parallel vectors in the PETScWrappers and
* TrilinosWrappers namespaces.
* multi-level preconditioning and provide the standard interface for LAC
* iterative methods.
*
- * Furthermore, it needs functions <tt>void copy_to_mg(const VectorType&)</tt> to
- * store @p src in the right hand side of the multi-level method and <tt>void
- * copy_from_mg(VectorType&)</tt> to store the result of the v-cycle in @p dst.
+ * Furthermore, it needs functions <tt>void copy_to_mg(const VectorType&)</tt>
+ * to store @p src in the right hand side of the multi-level method and
+ * <tt>void copy_from_mg(VectorType&)</tt> to store the result of the v-cycle
+ * in @p dst.
*
* @author Guido Kanschat, 1999, 2000, 2001, 2002
*/
*
* @pre This class only makes sense if the first template argument,
* <code>dim</code> equals the dimension of the DoFHandler type given as the
- * second template argument, i.e., if <code>dim == DoFHandlerType::dimension</code>. This
- * redundancy is a historical relic from the time where the library had only a
- * single DoFHandler class and this class consequently only a single template
- * argument.
+ * second template argument, i.e., if <code>dim ==
+ * DoFHandlerType::dimension</code>. This redundancy is a historical relic
+ * from the time where the library had only a single DoFHandler class and this
+ * class consequently only a single template argument.
*
* @ingroup output
* @author Wolfgang Bangerth, 1999
/**
* Build one patch. This function is called in a WorkStream context.
*
- * The first argument here is the iterator, the second the scratch data object.
- * All following are tied to particular values when calling WorkStream::run().
- * The function does not take a CopyData object but rather allocates one
- * on its own stack for memory access efficiency reasons.
+ * The first argument here is the iterator, the second the scratch data
+ * object. All following are tied to particular values when calling
+ * WorkStream::run(). The function does not take a CopyData object but
+ * rather allocates one on its own stack for memory access efficiency
+ * reasons.
*/
void build_one_patch
(const std::pair<cell_iterator, unsigned int> *cell_and_index,
*
* @pre This class only makes sense if the first template argument,
* <code>dim</code> equals the dimension of the DoFHandler type given as the
- * second template argument, i.e., if <code>dim == DoFHandlerType::dimension</code>. This
- * redundancy is a historical relic from the time where the library had only a
- * single DoFHandler class and this class consequently only a single template
- * argument.
+ * second template argument, i.e., if <code>dim ==
+ * DoFHandlerType::dimension</code>. This redundancy is a historical relic
+ * from the time where the library had only a single DoFHandler class and this
+ * class consequently only a single template argument.
*
* @todo Reimplement this whole class using actual FEFaceValues and
* MeshWorker.
*
* @pre This class only makes sense if the first template argument,
* <code>dim</code> equals the dimension of the DoFHandler type given as the
- * second template argument, i.e., if <code>dim == DoFHandlerType::dimension</code>. This
- * redundancy is a historical relic from the time where the library had only a
- * single DoFHandler class and this class consequently only a single template
- * argument.
+ * second template argument, i.e., if <code>dim ==
+ * DoFHandlerType::dimension</code>. This redundancy is a historical relic
+ * from the time where the library had only a single DoFHandler class and this
+ * class consequently only a single template argument.
*
* @ingroup output
* @author Wolfgang Bangerth, 2000
{
/**
* All small temporary data objects that are needed once per thread by the
- * several functions of the error estimator are gathered in this
- * struct. The reason for this structure is mainly that we have a number
- * of functions that operate on cells or faces and need a number of small
+ * several functions of the error estimator are gathered in this struct.
+ * The reason for this structure is mainly that we have a number of
+ * functions that operate on cells or faces and need a number of small
* temporary data objects. Since these functions may run in parallel, we
* cannot make these objects member variables of the enclosing class. On
* the other hand, declaring them locally in each of these functions would
/**
* A vector to store the jump of the normal vectors in the quadrature
- * points for each of the solution vectors (i.e. a temporary
- * value). This vector is not allocated inside the functions that use
- * it, but rather globally, since memory allocation is slow, in
- * particular in presence of multiple threads where synchronisation
- * makes things even slower.
+ * points for each of the solution vectors (i.e. a temporary value).
+ * This vector is not allocated inside the functions that use it, but
+ * rather globally, since memory allocation is slow, in particular in
+ * presence of multiple threads where synchronisation makes things even
+ * slower.
*/
std::vector<std::vector<std::vector<number> > > phi;
std::vector<Tensor<1,spacedim> > normal_vectors;
/**
- * Normal vectors of the opposing face.
- */
+ * Normal vectors of the opposing face.
+ */
std::vector<Tensor<1,spacedim> > neighbor_normal_vectors;
/**
}
/**
- * A factor to scale the integral for the face at the boundary.
- * Used for Neumann BC.
+ * A factor to scale the integral for the face at the boundary. Used for
+ * Neumann BC.
*/
template <typename DoFHandlerType>
double boundary_face_factor(const typename DoFHandlerType::active_cell_iterator &cell,
/**
- * A factor to scale the integral for the regular face.
+ * A factor to scale the integral for the regular face.
*/
template <typename DoFHandlerType>
double regular_face_factor(const typename DoFHandlerType::active_cell_iterator &cell,
}
/**
- * A factor used when summing up all the contribution
- * from different faces of each cell.
+ * A factor used when summing up all the contribution from different faces
+ * of each cell.
*/
template <typename DoFHandlerType>
double cell_factor(const typename DoFHandlerType::active_cell_iterator &cell,
/**
- * The same applies as for the
- * function above, except that
- * integration is over face
- * @p face_no of @p cell, where
- * the respective neighbor is
- * refined, so that the
- * integration is a bit more
- * complex.
+ * The same applies as for the function above, except that integration is
+ * over face @p face_no of @p cell, where the respective neighbor is
+ * refined, so that the integration is a bit more complex.
*/
template <typename InputVector, typename DoFHandlerType>
void
* explicit Mapping argument and one that does not. The second one generally
* calls the first with an implicit $Q_1$ argument (i.e., with an argument of
* kind MappingQGeneric(1)). If your intend your code to use a different
- * mapping than a (bi-/tri-)linear one, then you need to call the
- * functions <b>with</b> mapping argument should be used.
+ * mapping than a (bi-/tri-)linear one, then you need to call the functions
+ * <b>with</b> mapping argument should be used.
*
* All functions take a sparse matrix object to hold the matrix to be created.
* The functions assume that the matrix is initialized with a sparsity pattern
* char</tt>s as parameter @p boundary_functions containing the keys zero and
* 2). The size of the matrix is equal to the number of degrees of freedom
* that have support on the boundary, i.e. it is <em>not</em> a matrix on all
- * degrees of freedom, but only a subset. (The $\phi_i$ in the formula are
- * the subset of basis functions which have at least part of their support
- * on $\Gamma$.) In order to determine which shape functions are to be
+ * degrees of freedom, but only a subset. (The $\phi_i$ in the formula are the
+ * subset of basis functions which have at least part of their support on
+ * $\Gamma$.) In order to determine which shape functions are to be
* considered, and in order to determine in which order, the function takes a
* @p dof_to_boundary_mapping; this object maps global DoF numbers to a
* numbering of the degrees of freedom located on the boundary, and can be
/**
- * Put another mnemonic string (and hence @p VectorType) into the class. This
- * method adds storage space for variables equal to the number of true
+ * Put another mnemonic string (and hence @p VectorType) into the class.
+ * This method adds storage space for variables equal to the number of true
* values in component_mask. This also adds extra entries for points that
* are already in the class, so @p add_field_name and @p add_points can be
* called in any order.
const ComponentMask &component_mask = ComponentMask());
/**
- * Put another mnemonic string (and hence @p VectorType) into the class. This
- * method adds storage space for n_components variables. This also adds
+ * Put another mnemonic string (and hence @p VectorType) into the class.
+ * This method adds storage space for n_components variables. This also adds
* extra entries for points that are already in the class, so @p
* add_field_name and @p add_points can be called in any order. This method
* generates a std::vector 0, ..., n_components-1 and calls the previous
/**
- * Extract values at the points actually requested from the VectorType supplied
- * and add them to the new dataset in vector_name. Unlike the other
+ * Extract values at the points actually requested from the VectorType
+ * supplied and add them to the new dataset in vector_name. Unlike the other
* evaluate_field methods this method does not care if the dof_handler has
* been modified because it uses calls to @p VectorTools::point_value to
* extract there data. Therefore, if only this method is used, the class is
* explicit Mapping argument and one that does not. The second one generally
* calls the first with an implicit $Q_1$ argument (i.e., with an argument of
* kind MappingQGeneric(1)). If your intend your code to use a different
- * mapping than a (bi-/tri-)linear one, then you need to call the
- * functions <b>with</b> mapping argument should be used.
+ * mapping than a (bi-/tri-)linear one, then you need to call the functions
+ * <b>with</b> mapping argument should be used.
*
*
* <h3>Description of operations</h3>
* with the hanging nodes from space @p dof afterwards, to make the result
* continuous again.
*
- * The template argument <code>DoFHandlerType</code> may either be of type DoFHandler or
- * hp::DoFHandler.
+ * The template argument <code>DoFHandlerType</code> may either be of type
+ * DoFHandler or hp::DoFHandler.
*
* See the general documentation of this namespace for further information.
*
const bool project_to_boundary_first = false);
/**
- * Calls the project() function above, with a collection of
- * $Q_1$ mapping objects, i.e., with hp::StaticMappingQ1::mapping_collection.
+ * Calls the project() function above, with a collection of $Q_1$ mapping
+ * objects, i.e., with hp::StaticMappingQ1::mapping_collection.
*/
template <int dim, typename VectorType, int spacedim>
void project (const hp::DoFHandler<dim,spacedim> &dof,
/**
* Calls the other interpolate_boundary_values() function, see above, with
- * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments apply as for the
- * previous function, in particular about the use of the component mask and
- * the requires size of the function object.
+ * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments
+ * apply as for the previous function, in particular about the use of the
+ * component mask and the requires size of the function object.
*
* @see
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
/**
* Calls the other interpolate_boundary_values() function, see above, with
- * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments apply as for the
- * previous function, in particular about the use of the component mask and
- * the requires size of the function object.
+ * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments
+ * apply as for the previous function, in particular about the use of the
+ * component mask and the requires size of the function object.
*/
template <typename DoFHandlerType>
void
/**
* Calls the other interpolate_boundary_values() function, see above, with
- * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments apply as for the
- * previous function, in particular about the use of the component mask and
- * the requires size of the function object.
+ * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments
+ * apply as for the previous function, in particular about the use of the
+ * component mask and the requires size of the function object.
*
* @ingroup constraints
*
/**
* Calls the other interpolate_boundary_values() function, see above, with
- * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments apply as for the
- * previous function, in particular about the use of the component mask and
- * the requires size of the function object.
+ * <tt>mapping=MappingQGeneric@<dim,spacedim@>(1)</tt>. The same comments
+ * apply as for the previous function, in particular about the use of the
+ * component mask and the requires size of the function object.
*
* @ingroup constraints
*/
* = \sum_{k \in {\cal K}} \int_{\Gamma_k} \varphi_i f_k,
* \qquad \forall \varphi_i \in V_h
* @f}
- * where $\Gamma = \bigcup_{k \in {\cal
- * K}} \Gamma_k$, $\Gamma_k \subset \partial\Omega$, $\cal K$ is the set of
- * indices and $f_k$ the corresponding boundary functions represented in the
- * function map argument @p boundary_values to this function, and the
- * integrals are evaluated by quadrature. This problem has a non-unique
- * solution in the interior, but it is well defined for the degrees of
- * freedom on the part of the boundary, $\Gamma$, for which we do the
- * integration. The values of $u_h|_\Gamma$, i.e., the nodal values of the
- * degrees of freedom of this function along the boundary, are then what is
- * computed by this function.
+ * where $\Gamma = \bigcup_{k \in {\cal K}} \Gamma_k$, $\Gamma_k \subset
+ * \partial\Omega$, $\cal K$ is the set of indices and $f_k$ the
+ * corresponding boundary functions represented in the function map argument
+ * @p boundary_values to this function, and the integrals are evaluated by
+ * quadrature. This problem has a non-unique solution in the interior, but
+ * it is well defined for the degrees of freedom on the part of the
+ * boundary, $\Gamma$, for which we do the integration. The values of
+ * $u_h|_\Gamma$, i.e., the nodal values of the degrees of freedom of this
+ * function along the boundary, are then what is computed by this function.
*
* @param[in] mapping The mapping that will be used in the transformations
* necessary to integrate along the boundary.
* @param[in] dof The DoFHandler that describes the finite element space and
* the numbering of degrees of freedom.
- * @param[in] boundary_functions A map from boundary indicators to pointers to
- * functions that describe the desired values on those parts of the boundary
- * marked with this boundary indicator (see
+ * @param[in] boundary_functions A map from boundary indicators to pointers
+ * to functions that describe the desired values on those parts of the
+ * boundary marked with this boundary indicator (see
* @ref GlossBoundaryIndicator "Boundary indicator").
* The projection happens on only those parts of the boundary whose
* indicators are represented in this map.
* by the boundary parts in @p boundary_functions) and the computed dof
* value for this degree of freedom. For each degree of freedom at the
* boundary, if its index already exists in @p boundary_values then its
- * boundary value will be overwritten, otherwise a new entry with proper index
- * and boundary value for this degree of freedom will be inserted into
+ * boundary value will be overwritten, otherwise a new entry with proper
+ * index and boundary value for this degree of freedom will be inserted into
* @p boundary_values.
* @param[in] component_mapping It is sometimes convenient to project a
* vector-valued function onto only parts of a finite element space (for
* @image html no_normal_flux_1.png
* </p>
*
- * Here, we have two cells that use a bilinear mapping (i.e., MappingQGeneric(1)).
- * Consequently, for each of the cells, the normal vector is perpendicular
- * to the straight edge. If the two edges at the top and right are meant to
- * approximate a curved boundary (as indicated by the dashed line), then
- * neither of the two computed normal vectors are equal to the exact normal
- * vector (though they approximate it as the mesh is refined further). What
- * is worse, if we constrain $\vec u \cdot \vec n= \vec u_\Gamma \cdot \vec
- * n$ at the common vertex with the normal vector from both cells, then we
- * constrain the vector $\vec u$ with respect to two linearly independent
- * vectors; consequently, the constraint would be $\vec u=\vec u_\Gamma$ at
- * this point (i.e. <i>all</i> components of the vector), which is not what
- * we wanted.
+ * Here, we have two cells that use a bilinear mapping (i.e.,
+ * MappingQGeneric(1)). Consequently, for each of the cells, the normal
+ * vector is perpendicular to the straight edge. If the two edges at the top
+ * and right are meant to approximate a curved boundary (as indicated by the
+ * dashed line), then neither of the two computed normal vectors are equal
+ * to the exact normal vector (though they approximate it as the mesh is
+ * refined further). What is worse, if we constrain $\vec u \cdot \vec n=
+ * \vec u_\Gamma \cdot \vec n$ at the common vertex with the normal vector
+ * from both cells, then we constrain the vector $\vec u$ with respect to
+ * two linearly independent vectors; consequently, the constraint would be
+ * $\vec u=\vec u_\Gamma$ at this point (i.e. <i>all</i> components of the
+ * vector), which is not what we wanted.
*
* To deal with this situation, the algorithm works in the following way: at
* each point where we want to constrain $\vec u$, we first collect all
* @f{align*}{
* d_K = \| u-u_h \|_X
* @f}
- * where $X$ denotes the norm
- * chosen and $u$ represents the exact solution.
+ * where $X$ denotes the norm chosen and $u$ represents the exact solution.
*
* It is assumed that the number of components of the function @p
* exact_solution matches that of the finite element used by @p dof.
* @f{align*}{
* \textrm{error} = \sqrt{\sum_K \|u-u_h\|_{L_2(K)}^2}
* @f}
- * Obviously, if you are interested in computing
- * the $L_1$ norm of the error, the correct form of the last two lines would
- * have been
+ * Obviously, if you are interested in computing the $L_1$ norm of the
+ * error, the correct form of the last two lines would have been
* @code
* const double total_local_error = local_errors.l1_norm();
* const double total_global_error
* Compute the mean value of one component of the solution.
*
* This function integrates the chosen component over the whole domain and
- * returns the result, i.e. it computes $\frac{1}{|\Omega|}\int_\Omega [u_h(x)]_c \; dx$ where
- * $c$ is the vector component and $u_h$ is the function representation of
- * the nodal vector given as fourth argument. The integral is evaluated
- * numerically using the quadrature formula given as third argument.
+ * returns the result, i.e. it computes $\frac{1}{|\Omega|}\int_\Omega
+ * [u_h(x)]_c \; dx$ where $c$ is the vector component and $u_h$ is the
+ * function representation of the nodal vector given as fourth argument. The
+ * integral is evaluated numerically using the quadrature formula given as
+ * third argument.
*
* This function is used in the "Possibilities for extensions" part of the
* results section of
*/
//@{
/**
- * Given a DoFHandler containing at least a spacedim vector field,
- * this function interpolates the Triangulation at the support
- * points of a FE_Q() finite element of the same degree as the
- * degree of the required components.
+ * Given a DoFHandler containing at least a spacedim vector field, this
+ * function interpolates the Triangulation at the support points of a FE_Q()
+ * finite element of the same degree as the degree of the required
+ * components.
*
* Curved manifold are respected, and the resulting VectorType will be
* geometrically consistent. The resulting map is guaranteed to be
- * interpolatory at the support points of a FE_Q() finite element of
- * the same degree as the degree of the required components.
+ * interpolatory at the support points of a FE_Q() finite element of the
+ * same degree as the degree of the required components.
*
* If the underlying finite element is an FE_Q(1)^spacedim, then the
* resulting @p VectorType is a finite element field representation of the
* the first spacedim components of the FiniteElement are assumed to
* represent the geometry of the problem.
*
- * This function is only implemented for FiniteElements where the
- * specified components are primitive.
+ * This function is only implemented for FiniteElements where the specified
+ * components are primitive.
*
* @author Luca Heltai, 2015
*/
projects / dealii.git / commitdiff