From: Timo Heister Date: Sun, 7 Feb 2016 01:35:23 +0000 (-0500) Subject: run wrapcomments X-Git-Tag: v8.4.0-rc2~22^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2144%2Fhead;p=dealii.git run wrapcomments this sadly kills some of the manual indentation of @param and other commands --- diff --git a/include/deal.II/algorithms/named_selection.h b/include/deal.II/algorithms/named_selection.h index cab97cb94d..bc8de044b4 100644 --- a/include/deal.II/algorithms/named_selection.h +++ b/include/deal.II/algorithms/named_selection.h @@ -58,9 +58,8 @@ public: /** - * 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(). */ diff --git a/include/deal.II/algorithms/newton.h b/include/deal.II/algorithms/newton.h index b6719e71e0..f29da514c1 100644 --- a/include/deal.II/algorithms/newton.h +++ b/include/deal.II/algorithms/newton.h @@ -53,10 +53,10 @@ namespace Algorithms * objects. All vectors of in are forwarded to the inner Operator * objects, with additional information added as follows. * - * When calling (*#residual)(), the AnyData in given to the - * Newton iteration is prepended by a vector "Newton iterate", the - * current value of the Newton iterate, which can be used to evaluate the - * residual at this point. + * When calling (*#residual)(), the AnyData in given to the Newton + * iteration is prepended by a vector "Newton iterate", 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 "Newton * residual" is inserted before "Newton iterate". diff --git a/include/deal.II/algorithms/theta_timestepping.h b/include/deal.II/algorithms/theta_timestepping.h index 761eff58bf..6bbe3c632c 100644 --- a/include/deal.II/algorithms/theta_timestepping.h +++ b/include/deal.II/algorithms/theta_timestepping.h @@ -206,8 +206,8 @@ namespace Algorithms * #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); diff --git a/include/deal.II/algorithms/timestep_control.h b/include/deal.II/algorithms/timestep_control.h index fea9763be4..925feec792 100644 --- a/include/deal.II/algorithms/timestep_control.h +++ b/include/deal.II/algorithms/timestep_control.h @@ -141,7 +141,7 @@ namespace Algorithms * 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); diff --git a/include/deal.II/base/aligned_vector.h b/include/deal.II/base/aligned_vector.h index 4b5c350ab4..5f9d441dfb 100644 --- a/include/deal.II/base/aligned_vector.h +++ b/include/deal.II/base/aligned_vector.h @@ -357,11 +357,11 @@ namespace internal /** * 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 */ diff --git a/include/deal.II/base/array_view.h b/include/deal.II/base/array_view.h index f70aa0600b..c9d63d81cf 100644 --- a/include/deal.II/base/array_view.h +++ b/include/deal.II/base/array_view.h @@ -28,23 +28,21 @@ DEAL_II_NAMESPACE_OPEN /** - * 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 operator[]. 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 + * operator[]. 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 operator[] 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 operator[] 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 array = get_data(); // a writable array * @@ -55,17 +53,16 @@ DEAL_II_NAMESPACE_OPEN * 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 @@ -75,8 +72,8 @@ class ArrayView { 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; @@ -84,20 +81,20 @@ public: * 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); @@ -105,9 +102,9 @@ public: /** * 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. */ @@ -120,20 +117,20 @@ public: 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 view object. 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 + * view object. 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; @@ -190,17 +187,16 @@ ArrayView::operator[](const std::size_t i) const /** - * 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 entire - * vector. + * @param[in] vector The vector for which we want to have an array view + * object. The array view corresponds to the entire vector. * * @relates ArrayView */ @@ -215,17 +211,16 @@ make_array_view (std::vector &vector) /** - * 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 entire - * vector. + * @param[in] vector The vector for which we want to have an array view + * object. The array view corresponds to the entire vector. * * @relates ArrayView */ @@ -240,18 +235,18 @@ make_array_view (const std::vector &vector) /** - * 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 starting_index + size_of_view <= vector.size() @@ -275,18 +270,18 @@ make_array_view (std::vector &vector, /** - * 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 starting_index + size_of_view <= vector.size() @@ -310,20 +305,18 @@ make_array_view (const std::vector &vector, /** - * 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 entire - * row. + * @param[in] table The Table for which we want to have an array view object. + * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view - * should correspond. + * should correspond. * * @relates ArrayView */ @@ -340,20 +333,18 @@ make_array_view (Table<2,ElementType> &table, /** - * 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 entire - * row. + * @param[in] table The Table for which we want to have an array view object. + * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view - * should correspond. + * should correspond. * * @relates ArrayView */ @@ -376,16 +367,15 @@ make_array_view (const Table<2,ElementType> &table, * 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 entire - * row. + * @param[in] table The Table for which we want to have an array view object. + * The array view corresponds to an entire 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 */ @@ -412,19 +402,18 @@ make_array_view (Table<2,ElementType> &table, * 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 entire - * row. + * @param[in] table The Table for which we want to have an array view object. + * The array view corresponds to an entire 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 */ diff --git a/include/deal.II/base/complex_overloads.h b/include/deal.II/base/complex_overloads.h index 4bc76beccb..934bd25d44 100644 --- a/include/deal.II/base/complex_overloads.h +++ b/include/deal.II/base/complex_overloads.h @@ -27,8 +27,8 @@ template struct ProductType; #ifndef DEAL_II_HAVE_COMPLEX_OPERATOR_OVERLOADS /** - * Provide an operator* that operates on mixed complex floating - * point types. Annoyingly, the standard library does not provide such an + * Provide an operator* that operates on mixed complex floating point + * types. Annoyingly, the standard library does not provide such an * operator... * * @relates ProductType @@ -45,8 +45,8 @@ operator*(const std::complex &left, const std::complex &right) /** * Provide an operator* 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 diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h index 5118d62945..1c1eea79c5 100644 --- a/include/deal.II/base/data_out_base.h +++ b/include/deal.II/base/data_out_base.h @@ -744,8 +744,8 @@ namespace DataOutBase /** * 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. */ @@ -839,9 +839,9 @@ namespace DataOutBase 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; @@ -1478,9 +1478,9 @@ namespace DataOutBase * declared somewhere before the object data. This may be in an external * data file or at the beginning of the output file. Setting the * external_data 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: diff --git a/include/deal.II/base/derivative_form.h b/include/deal.II/base/derivative_form.h index dc7306aced..5ed26c6783 100644 --- a/include/deal.II/base/derivative_form.h +++ b/include/deal.II/base/derivative_form.h @@ -26,29 +26,28 @@ DEAL_II_NAMESPACE_OPEN * 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 diff --git a/include/deal.II/base/exceptions.h b/include/deal.II/base/exceptions.h index 588855e54e..770bd2a679 100644 --- a/include/deal.II/base/exceptions.h +++ b/include/deal.II/base/exceptions.h @@ -1008,8 +1008,8 @@ namespace StandardExceptions "information."); /** - * Some of our numerical classes allow for setting all entries to zero - * using the assignment operator =. + * Some of our numerical classes allow for setting all entries to zero using + * the assignment operator =. * * In many cases, this assignment operator makes sense only for the * argument zero. In other cases, this exception is thrown. diff --git a/include/deal.II/base/function.h b/include/deal.II/base/function.h index 9e93934d6e..1f1e93a4b9 100644 --- a/include/deal.II/base/function.h +++ b/include/deal.II/base/function.h @@ -311,15 +311,15 @@ public: std::vector > &values) const; /** - * Compute the Hessian of a given component at point p, - * that is the gradient of the gradient of the function. + * Compute the Hessian of a given component at point p, that is the + * gradient of the gradient of the function. */ virtual SymmetricTensor<2,dim,Number> hessian (const Point &p, const unsigned int component = 0) const; /** - * Compute the Hessian of all components at point p and store - * them in values. + * Compute the Hessian of all components at point p and store them + * in values. */ virtual void vector_hessian (const Point &p, std::vector > &values) const; @@ -426,21 +426,21 @@ class ConstantFunction : public ZeroFunction { 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 std::vector object as an argument. The number - * of components is determined by values.size(). + * Constructor; takes an std::vector object as an argument. + * The number of components is determined by values.size(). */ ConstantFunction (const std::vector &values); /** - * Constructor; takes an Vector object as an argument. The number - * of components is determined by values.size(). + * Constructor; takes an Vector object as an argument. The + * number of components is determined by values.size(). */ ConstantFunction (const Vector &values); @@ -524,15 +524,17 @@ public: /** - * Substitute function value with value of a ConstantFunction@ - * object and keep the current selection pattern. + * Substitute function value with value of a ConstantFunction@ 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 ComponentSelectFunction@ - * 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 + * ComponentSelectFunction@ 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 &f); @@ -679,11 +681,11 @@ private: * 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 x that can be called as diff --git a/include/deal.II/base/function.templates.h b/include/deal.II/base/function.templates.h index bfb6d6689e..65355b0be0 100644 --- a/include/deal.II/base/function.templates.h +++ b/include/deal.II/base/function.templates.h @@ -788,11 +788,11 @@ void VectorFunctionFromTensorFunction::vector_value ( /** - * Member function vector_value_list is the interface for giving - * a list of points (vector >) of which to evaluate - * using the vector_value member function. Again, this function - * is written so as to not replicate the function definition but passes - * each point on to vector_value to be evaluated. + * Member function vector_value_list is the interface for giving a + * list of points (vector >) of which to evaluate + * using the vector_value member function. Again, this function is + * written so as to not replicate the function definition but passes each + * point on to vector_value to be evaluated. */ template void VectorFunctionFromTensorFunction::vector_value_list ( diff --git a/include/deal.II/base/index_set.h b/include/deal.II/base/index_set.h index e806da1f48..99e191702b 100644 --- a/include/deal.II/base/index_set.h +++ b/include/deal.II/base/index_set.h @@ -52,9 +52,9 @@ DEAL_II_NAMESPACE_OPEN * 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 @@ -154,11 +154,10 @@ public: * Add a whole set of indices described by dereferencing every element of * the iterator range [begin,end). * - * @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 begin@<=end 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 begin@<=end needs to be satisfied. */ template void add_indices (const ForwardIterator &begin, @@ -224,7 +223,8 @@ public: 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; @@ -428,8 +428,8 @@ public: 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: diff --git a/include/deal.II/base/logstream.h b/include/deal.II/base/logstream.h index 5f63bb8f8c..2f1b9bab8b 100644 --- a/include/deal.II/base/logstream.h +++ b/include/deal.II/base/logstream.h @@ -248,11 +248,11 @@ public: /** * 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 n prefixes is - * printed. By calling this function with n=0, 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 n prefixes is printed. By calling this function with + * n=0, no console output will be written. See step-3 for an + * example usage of this method. * * The previous value of this parameter is returned. */ diff --git a/include/deal.II/base/memory_consumption.h b/include/deal.II/base/memory_consumption.h index 9cb4eb9efc..58e3aba37b 100644 --- a/include/deal.II/base/memory_consumption.h +++ b/include/deal.II/base/memory_consumption.h @@ -84,7 +84,8 @@ template class VectorizedArray; * 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 diff --git a/include/deal.II/base/mpi.h b/include/deal.II/base/mpi.h index 4a3f26915f..183d141db2 100644 --- a/include/deal.II/base/mpi.h +++ b/include/deal.II/base/mpi.h @@ -66,8 +66,7 @@ namespace Utilities /** * 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); @@ -76,9 +75,8 @@ namespace Utilities * @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); @@ -90,8 +88,8 @@ namespace Utilities * * @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 @@ -110,9 +108,8 @@ namespace Utilities /** * 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 @@ -127,10 +124,10 @@ namespace Utilities * 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 MPI_Allreduce - * 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 + * MPI_Allreduce 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 MPI_Reduce function instead of the @@ -212,9 +209,8 @@ namespace Utilities * 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 * MPI_Allreduce function, i.e. all processors receive the * result of this operation. * @@ -264,9 +260,8 @@ namespace Utilities * 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 * MPI_Allreduce function, i.e. all processors receive the * result of this operation. * @@ -332,8 +327,7 @@ namespace Utilities * 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 diff --git a/include/deal.II/base/multithread_info.h b/include/deal.II/base/multithread_info.h index 3f5f709a96..d6d4821570 100644 --- a/include/deal.II/base/multithread_info.h +++ b/include/deal.II/base/multithread_info.h @@ -103,8 +103,8 @@ private: /** - * 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 (); @@ -121,8 +121,8 @@ private: 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; }; diff --git a/include/deal.II/base/parameter_handler.h b/include/deal.II/base/parameter_handler.h index ef1b3fda56..b7be6c18c1 100644 --- a/include/deal.II/base/parameter_handler.h +++ b/include/deal.II/base/parameter_handler.h @@ -591,8 +591,7 @@ namespace Patterns * course commas are not allowed inside the values given to the constructor. * * For example, if the string to the constructor was "ucd|gmv|eps", - * 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 { @@ -1987,13 +1986,14 @@ private: std::string get_current_full_path (const std::string &name) const; /** - * Scan one line of input. input_filename and current_line_n - * are the name of the input file and the current number of the line presently - * scanned (for the logs if there are messages). Return false if line - * contained stuff that could not be understood, the uppermost subsection was - * to be left by an END or end statement, a value for a - * non-declared entry was given or the entry value did not match the regular - * expression. true otherwise. + * Scan one line of input. input_filename and + * current_line_n are the name of the input file and the current + * number of the line presently scanned (for the logs if there are + * messages). Return false if line contained stuff that could not + * be understood, the uppermost subsection was to be left by an END + * or end statement, a value for a non-declared entry was given or + * the entry value did not match the regular expression. true + * otherwise. * * The function modifies its argument, but also takes it by value, so the * caller's variable is not changed. diff --git a/include/deal.II/base/point.h b/include/deal.II/base/point.h index bfcffcf735..67a0abba54 100644 --- a/include/deal.II/base/point.h +++ b/include/deal.II/base/point.h @@ -210,8 +210,8 @@ public: /** * 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 diff --git a/include/deal.II/base/polynomial_space.h b/include/deal.II/base/polynomial_space.h index d0236848b0..728a85f561 100644 --- a/include/deal.II/base/polynomial_space.h +++ b/include/deal.II/base/polynomial_space.h @@ -146,7 +146,8 @@ public: std::vector > &fourth_derivatives) const; /** - * Computes the value of the ith polynomial at unit point p. + * Computes the value of the ith polynomial at unit point + * p. * * Consider using compute() instead. */ @@ -166,8 +167,8 @@ public: const Point &p) const; /** - * Computes the gradient of the ith polynomial at - * unit point p. + * Computes the gradient of the ith polynomial at unit point + * p. * * Consider using compute() instead. */ @@ -203,8 +204,8 @@ public: * 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); diff --git a/include/deal.II/base/polynomials_bernstein.h b/include/deal.II/base/polynomials_bernstein.h index be7fccc69f..d3a2dbb8c8 100644 --- a/include/deal.II/base/polynomials_bernstein.h +++ b/include/deal.II/base/polynomials_bernstein.h @@ -9,9 +9,10 @@ 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. * diff --git a/include/deal.II/base/polynomials_rannacher_turek.h b/include/deal.II/base/polynomials_rannacher_turek.h index 22b5a26267..16a0cf9866 100644 --- a/include/deal.II/base/polynomials_rannacher_turek.h +++ b/include/deal.II/base/polynomials_rannacher_turek.h @@ -28,14 +28,14 @@ DEAL_II_NAMESPACE_OPEN * 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 class PolynomialsRannacherTurek { @@ -46,13 +46,13 @@ public: 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 &p) const; @@ -65,23 +65,23 @@ public: Tensor compute_derivative (const unsigned int i, const Point &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 &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 &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 &unit_point, std::vector &values, diff --git a/include/deal.II/base/quadrature_lib.h b/include/deal.II/base/quadrature_lib.h index 1ddadc3d0b..1c39bbeed1 100644 --- a/include/deal.II/base/quadrature_lib.h +++ b/include/deal.II/base/quadrature_lib.h @@ -442,21 +442,17 @@ public: /** * 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 @@ -477,22 +473,22 @@ public: * 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. @@ -504,17 +500,17 @@ class QTelles: public Quadrature { 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 &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 &singularity); }; @@ -522,20 +518,18 @@ public: /*@}*/ /** -* 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 class QGaussChebyshev : public Quadrature { @@ -556,21 +550,21 @@ private: /** -* 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 class QGaussRadauChebyshev : public Quadrature { @@ -596,22 +590,20 @@ private: }; /** -* 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 class QGaussLobattoChebyshev : public Quadrature { diff --git a/include/deal.II/base/signaling_nan.h b/include/deal.II/base/signaling_nan.h index d929c442e7..6c9a42354f 100644 --- a/include/deal.II/base/signaling_nan.h +++ b/include/deal.II/base/signaling_nan.h @@ -32,29 +32,27 @@ namespace numbers 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 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 @@ -67,9 +65,9 @@ namespace numbers /** - * 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 @@ -82,9 +80,9 @@ namespace numbers /** - * 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 struct NaNInitializer > @@ -103,9 +101,9 @@ namespace numbers /** - * A specialization of the general NaNInitializer class that - * provides a function that returns a Tensor value whose - * components are invalid signaling NaN values. + * A specialization of the general NaNInitializer class that provides a + * function that returns a Tensor value whose components are + * invalid signaling NaN values. */ template struct NaNInitializer > @@ -125,9 +123,9 @@ namespace numbers /** - * A specialization of the general NaNInitializer class that - * provides a function that returns a SymmetricTensor - * value whose components are invalid signaling NaN values. + * A specialization of the general NaNInitializer class that provides a + * function that returns a SymmetricTensor value whose + * components are invalid signaling NaN values. */ template struct NaNInitializer > @@ -146,10 +144,9 @@ namespace numbers /** - * A specialization of the general NaNInitializer class that - * provides a function that returns a - * DerivativeForm value whose components are - * invalid signaling NaN values. + * A specialization of the general NaNInitializer class that provides a + * function that returns a DerivativeForm value + * whose components are invalid signaling NaN values. */ template struct NaNInitializer > @@ -172,29 +169,28 @@ namespace numbers /** - * 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 >(); * @endcode - * initializes a tensor with invalid values. + * initializes a tensor with invalid values. */ template T diff --git a/include/deal.II/base/subscriptor.h b/include/deal.II/base/subscriptor.h index 2585d8e47e..17023d8ef3 100644 --- a/include/deal.II/base/subscriptor.h +++ b/include/deal.II/base/subscriptor.h @@ -177,8 +177,8 @@ private: * constant objects also. * * In multithreaded mode, this counter may be modified by different threads. - * We thus have to mark it volatile. However, this is - * counter-productive in non-MT mode since it may pessimize code. So use the macro + * We thus have to mark it volatile. However, this is counter- + * productive in non-MT mode since it may pessimize code. So use the macro * defined in deal.II/base/config.h to selectively add volatility. */ mutable DEAL_VOLATILE unsigned int counter; diff --git a/include/deal.II/base/symmetric_tensor.h b/include/deal.II/base/symmetric_tensor.h index 64422841e9..4743fd22ad 100644 --- a/include/deal.II/base/symmetric_tensor.h +++ b/include/deal.II/base/symmetric_tensor.h @@ -2049,8 +2049,8 @@ operator-(const SymmetricTensor &left, /** - * 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 */ diff --git a/include/deal.II/base/synchronous_iterator.h b/include/deal.II/base/synchronous_iterator.h index d972a9cfec..05ec5a2094 100644 --- a/include/deal.II/base/synchronous_iterator.h +++ b/include/deal.II/base/synchronous_iterator.h @@ -39,8 +39,8 @@ DEAL_II_NAMESPACE_OPEN * std_cxx11::tuple with arguments equal to the iterator types. * * The individual iterators can be accessed using - * std_cxx11::get(synchronous_iterator.iterators) where X is the - * number corresponding to the desired iterator. + * std_cxx11::get(synchronous_iterator.iterators) 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. diff --git a/include/deal.II/base/table.h b/include/deal.II/base/table.h index 486d569e1e..f7ea7c3a44 100644 --- a/include/deal.II/base/table.h +++ b/include/deal.II/base/table.h @@ -481,12 +481,12 @@ public: void reset_values (); /** - * Set the dimensions of this object to the sizes given in the - * argument, and newly allocate the required memory. If - * omit_default_initialization is set to false, - * 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 + * omit_default_initialization is set to false, 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 &new_size, const bool omit_default_initialization = false); diff --git a/include/deal.II/base/table_indices.h b/include/deal.II/base/table_indices.h index 028bc168aa..d9cab5a156 100644 --- a/include/deal.II/base/table_indices.h +++ b/include/deal.II/base/table_indices.h @@ -48,12 +48,12 @@ public: 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 N arguments are actually used. @@ -253,8 +253,8 @@ TableIndices::serialize (Archive &ar, const unsigned int) /** - * Output operator for TableIndices objects; reports them in a list like - * this: [i1,i2,...]. + * Output operator for TableIndices objects; reports them in a list like this: + * [i1,i2,...]. * * @relates TableIndices */ diff --git a/include/deal.II/base/tensor.h b/include/deal.II/base/tensor.h index b5aa8391ed..a2168cbde2 100644 --- a/include/deal.II/base/tensor.h +++ b/include/deal.II/base/tensor.h @@ -50,9 +50,9 @@ class Tensor<-1, dim, Number> /** - * This class is a specialized version of the - * Tensor 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 Tensor + * 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@, which should expand to scalars, @@ -163,8 +163,7 @@ public: * 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; @@ -174,8 +173,8 @@ public: 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 @@ -237,16 +236,15 @@ public: 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 l2 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 l2 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; @@ -258,8 +256,8 @@ public: 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; @@ -353,8 +351,8 @@ public: /** * 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::tensor_type value_type; @@ -500,17 +498,16 @@ public: 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 l2 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 l2 norm of the vector. */ typename numbers::NumberTraits::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::real_type norm_square() const; @@ -553,8 +550,8 @@ public: 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 tensor_type; @@ -1222,8 +1219,7 @@ struct ProductType,U> /** - * 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. @@ -1241,8 +1237,7 @@ operator * (const Other object, /** - * 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. @@ -1263,8 +1258,8 @@ operator * (const Tensor<0,dim,Number> &t, * 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> */ @@ -1444,10 +1439,10 @@ operator- (const Tensor &p, const Tensor /** - * 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} @@ -1460,8 +1455,8 @@ operator- (const Tensor &p, const Tensor * 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 @@ -1484,10 +1479,10 @@ operator * (const Tensor &src1, /** - * 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} @@ -1506,8 +1501,8 @@ operator * (const Tensor &src1, * @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 @@ -1544,12 +1539,11 @@ contract (const Tensor &src1, /** - * 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} @@ -1558,10 +1552,10 @@ contract (const Tensor &src1, * @f] * * If for example the first index (index_1==0) shall be - * contracted with the third index (index_2==2), and the - * second index (index_3==1) with the first index - * (index_4==0) the invocation of this function is - * this function is + * contracted with the third index (index_2==2), and the second + * index (index_3==1) with the first index + * (index_4==0) the invocation of this function is this function + * is * @code * contract<0, 2, 1, 0>(t1, t2); * @endcode @@ -1569,8 +1563,8 @@ contract (const Tensor &src1, * @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 @@ -1627,9 +1621,9 @@ double_contract (const Tensor &src1, /** - * 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} @@ -1739,11 +1733,11 @@ cross_product_2d (const Tensor<1,dim,Number> &src) /** - * 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 - * dim==3 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 dim==3 + * case in the switch). * * @relates Tensor * @author Guido Kanschat, 2001 diff --git a/include/deal.II/base/tensor_accessors.h b/include/deal.II/base/tensor_accessors.h index bae083f881..f366cd415f 100644 --- a/include/deal.II/base/tensor_accessors.h +++ b/include/deal.II/base/tensor_accessors.h @@ -24,33 +24,33 @@ 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 t is - * a tensorial object of rank 4, the following access is valid: + * recursive application of the index operator, e.g., if t 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 and - * dealii::SymmetricTensor + * dealii::Tensor and dealii::SymmetricTensor * * 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 T with a minimal interface that provides - * a local typedef value_type and an index operator - * operator[](unsigned int) that returns a (const or - * non-const) reference of value_type: + * fully generic. More precisely, it can operate on nested c-style arrays, or + * on class types T with a minimal interface that provides a + * local typedef value_type and an index operator + * operator[](unsigned int) that returns a (const or non-const) + * reference of value_type: * @code * template<...> * class T @@ -81,20 +81,20 @@ namespace TensorAccessors /** - * 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 * - T::value_type if T is a tensorial class providing a - * typedef value_type and does not have a const qualifier. + * typedef value_type and does not have a const qualifier. * - const T::value_type if T is a tensorial class - * providing a typedef value_type and does have a const - * qualifier. + * providing a typedef value_type and does have a const + * qualifier. * - const T::value_type if T is a tensorial class - * providing a typedef value_type and does have a const - * qualifier. + * providing a typedef value_type and does have a const + * qualifier. * - A if T is of array type A[...] * - const A if T is of array type A[...] and - * does have a const qualifier. + * does have a const qualifier. */ template struct ValueType @@ -122,12 +122,11 @@ namespace TensorAccessors /** - * This class provides a local typedef @p value_type that is equal to - * the typedef value_type 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::value_type - * will also be const. + * This class provides a local typedef @p value_type that is equal to the + * typedef value_type 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::value_type will also be const. */ template struct ReturnType @@ -143,17 +142,16 @@ namespace TensorAccessors /** - * 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 - * operator[]() 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 operator[]() 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 @@ -162,11 +160,11 @@ namespace TensorAccessors * 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 operator[](unsigned int) and a @@ -175,10 +173,10 @@ namespace TensorAccessors * @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 value_type and an index operator - * operator[]() that returns a (const or non-const) - * reference of value_type. + * @tparam T A tensorial object of rank @p rank. @p T must provide a local + * typedef value_type and an index operator + * operator[]() that returns a (const or non-const) reference + * of value_type. * * @author Matthias Maier, 2015 */ @@ -206,11 +204,11 @@ namespace TensorAccessors * @endcode * This is equivalent to tensor[0][1][2][3][4] = 42.. * - * @tparam T A tensorial object of rank @p rank. @p T must provide a - * local typedef value_type and an index operator - * operator[]() that returns a (const or non-const) - * reference of value_type. 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 value_type and an index operator + * operator[]() that returns a (const or non-const) reference + * of value_type. 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 @@ -228,8 +226,8 @@ namespace TensorAccessors /** * 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}} @@ -255,12 +253,12 @@ namespace TensorAccessors * 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 */ @@ -305,9 +303,8 @@ namespace TensorAccessors * 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 */ @@ -334,9 +331,9 @@ namespace TensorAccessors * 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 struct ReferenceType diff --git a/include/deal.II/base/tensor_deprecated.h b/include/deal.II/base/tensor_deprecated.h index 9e53636c24..6f3ac96ac9 100644 --- a/include/deal.II/base/tensor_deprecated.h +++ b/include/deal.II/base/tensor_deprecated.h @@ -45,7 +45,7 @@ DeclException1 (ExcInvalidTensorContractionIndex, * product sumi,j src1[i][j]*src2[i][j]. * * @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 @@ -60,7 +60,7 @@ Number double_contract (const Tensor<2, dim, Number> &src1, * 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 @@ -72,11 +72,11 @@ void double_contract (Tensor<2,dim,Number> &dest, /** * Contract a tensor of rank 2 with a tensor of rank 2. The contraction is * performed over index index1 of the first tensor, and - * index2 of the second tensor. Note that the number of the index - * is counted from 1 on, not from zero as usual. + * index2 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 @@ -93,7 +93,7 @@ void contract (Tensor<2,dim,Number> &dest, * 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 @@ -106,11 +106,11 @@ void contract (Tensor<2,dim,Number> &dest, /** * Contract a tensor of rank 3 with a tensor of rank 2. The contraction is * performed over index index1 of the first tensor, and - * index2 of the second tensor. Note that the number of the index - * is counted from 1 on, not from zero as usual. + * index2 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 @@ -122,9 +122,9 @@ void contract (Tensor<3,dim,Number> &dest, 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 @@ -136,8 +136,7 @@ void contract (Tensor &dest, const Tensor &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 diff --git a/include/deal.II/base/tensor_product_polynomials.h b/include/deal.II/base/tensor_product_polynomials.h index 1da8defa0b..794d1da852 100644 --- a/include/deal.II/base/tensor_product_polynomials.h +++ b/include/deal.II/base/tensor_product_polynomials.h @@ -142,9 +142,9 @@ public: * 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. */ @@ -297,9 +297,9 @@ public: * 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. */ diff --git a/include/deal.II/base/tensor_product_polynomials_bubbles.h b/include/deal.II/base/tensor_product_polynomials_bubbles.h index 7e6fe73e37..0540d2a446 100644 --- a/include/deal.II/base/tensor_product_polynomials_bubbles.h +++ b/include/deal.II/base/tensor_product_polynomials_bubbles.h @@ -38,10 +38,9 @@ DEAL_II_NAMESPACE_OPEN /** * 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 */ @@ -50,10 +49,8 @@ class TensorProductPolynomialsBubbles : public TensorProductPolynomials { 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; @@ -100,16 +97,16 @@ public: const Point &p) const; /** - * Computes the order @p order derivative of the ith tensor - * product polynomial at unit_point. Here i is given in - * tensor product numbering. + * Computes the order @p order derivative of the ith tensor product + * polynomial at unit_point. Here i 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 Tensor compute_derivative (const unsigned int i, @@ -146,9 +143,10 @@ public: const Point &p) const; /** - * Returns the number of tensor product polynomials plus the bubble enrichments. - * For n 1d polynomials this is ndim+1 if the maximum - * degree of the polynomials is one and ndim+dim otherwise. + * Returns the number of tensor product polynomials plus the bubble + * enrichments. For n 1d polynomials this is ndim+1 + * if the maximum degree of the polynomials is one and + * ndim+dim otherwise. */ unsigned int n () const; }; diff --git a/include/deal.II/base/tensor_product_polynomials_const.h b/include/deal.II/base/tensor_product_polynomials_const.h index 783b2b3e62..44039c6d7b 100644 --- a/include/deal.II/base/tensor_product_polynomials_const.h +++ b/include/deal.II/base/tensor_product_polynomials_const.h @@ -103,9 +103,9 @@ public: * 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. */ diff --git a/include/deal.II/base/time_stepping.h b/include/deal.II/base/time_stepping.h index 75449f0fae..19c2923ba4 100644 --- a/include/deal.II/base/time_stepping.h +++ b/include/deal.II/base/time_stepping.h @@ -48,7 +48,7 @@ namespace TimeStepping * - 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) */ diff --git a/include/deal.II/base/utilities.h b/include/deal.II/base/utilities.h index d96ff0f53e..4223e813dd 100644 --- a/include/deal.II/base/utilities.h +++ b/include/deal.II/base/utilities.h @@ -50,8 +50,8 @@ namespace Utilities { /** - * 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 @@ -61,16 +61,17 @@ namespace Utilities * unsigned integers and long integers might experience an overflow. * * @note The use of this function is discouraged and users should use - * Utilities::to_string() instead. In its current implementation - * the function simply calls to_string@(). + * Utilities::to_string() instead. In its current + * implementation the function simply calls to_string@(). */ 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. * diff --git a/include/deal.II/base/vector_slice.h b/include/deal.II/base/vector_slice.h index e3b8efd307..50319526d8 100644 --- a/include/deal.II/base/vector_slice.h +++ b/include/deal.II/base/vector_slice.h @@ -65,16 +65,14 @@ public: 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 (); /** - * 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; @@ -85,14 +83,14 @@ public: 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; diff --git a/include/deal.II/distributed/shared_tria.h b/include/deal.II/distributed/shared_tria.h index 07bf3a5acc..3d3d66900c 100644 --- a/include/deal.II/distributed/shared_tria.h +++ b/include/deal.II/distributed/shared_tria.h @@ -55,14 +55,13 @@ namespace parallel /** * 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 @@ -78,9 +77,9 @@ namespace parallel /** * 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. */ @@ -95,35 +94,38 @@ namespace parallel 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 &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; @@ -141,13 +143,14 @@ namespace parallel /** * 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 true_subdomain_ids_of_cells; }; @@ -158,14 +161,14 @@ namespace parallel { /** - * 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 class Triangulation : public dealii::parallel::Triangulation diff --git a/include/deal.II/distributed/solution_transfer.h b/include/deal.II/distributed/solution_transfer.h index cacb6a7a94..6717495d6e 100644 --- a/include/deal.II/distributed/solution_transfer.h +++ b/include/deal.II/distributed/solution_transfer.h @@ -48,9 +48,9 @@ namespace parallel * interpolate() or deserialize() you need to supply distributed vectors * without ghost elements. * - *

Transferring a solution

Here VectorType is your favorite vector - * type, e.g. PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector, - * or corresponding blockvectors. + *

Transferring a solution

Here VectorType is your favorite + * vector type, e.g. PETScWrappers::MPI::Vector, + * TrilinosWrappers::MPI::Vector, or corresponding blockvectors. * @code * SolutionTransfer soltrans(dof_handler); * // flag some cells for refinement diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h index 7d5a97a824..1c347c6cce 100644 --- a/include/deal.II/distributed/tria.h +++ b/include/deal.II/distributed/tria.h @@ -478,26 +478,25 @@ namespace parallel * this-@>locally_owned_subdomain()), 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 (); @@ -528,27 +527,26 @@ namespace parallel * 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 (); @@ -769,8 +767,8 @@ namespace parallel * 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 @@ -785,8 +783,8 @@ namespace parallel 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 (); @@ -933,7 +931,8 @@ namespace parallel * 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 get_cell_weights(); diff --git a/include/deal.II/distributed/tria_base.h b/include/deal.II/distributed/tria_base.h index 5a5784b069..6dd25d0749 100644 --- a/include/deal.II/distributed/tria_base.h +++ b/include/deal.II/distributed/tria_base.h @@ -42,8 +42,8 @@ namespace parallel { /** * 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 class Triangulation : public dealii::Triangulation @@ -83,19 +83,19 @@ namespace parallel /** - * 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). @@ -103,9 +103,9 @@ namespace parallel 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; @@ -139,7 +139,7 @@ namespace parallel * * @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 &ghost_owners () const; /** @@ -150,14 +150,14 @@ namespace parallel * * @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 &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; @@ -179,13 +179,13 @@ namespace parallel 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 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; /** diff --git a/include/deal.II/dofs/block_info.h b/include/deal.II/dofs/block_info.h index 41432f06cb..c079c4aac5 100644 --- a/include/deal.II/dofs/block_info.h +++ b/include/deal.II/dofs/block_info.h @@ -79,10 +79,10 @@ namespace hp * } * @endcode * - * In this - * example, solution obtains the block structure needed to represent - * a finite element function on the DoFHandler. Similarly, all levels of - * mg_vector will have the block structure needed on that level. + * In this example, solution obtains the block structure needed to + * represent a finite element function on the DoFHandler. Similarly, all + * levels of mg_vector will have the block structure needed on that + * level. * * @todo Extend the functions local() and renumber() to the concept to * hpDoFHandler. diff --git a/include/deal.II/dofs/dof_handler_policy.h b/include/deal.II/dofs/dof_handler_policy.h index df37d68b7c..91f2126438 100644 --- a/include/deal.II/dofs/dof_handler_policy.h +++ b/include/deal.II/dofs/dof_handler_policy.h @@ -63,14 +63,12 @@ namespace internal 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 @@ -86,14 +84,12 @@ namespace internal std::vector &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 @@ -138,25 +134,22 @@ namespace internal }; /** - * 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 class ParallelShared : public Sequential { 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 &dof_handler, @@ -171,15 +164,14 @@ namespace internal std::vector &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 &new_numbers, diff --git a/include/deal.II/dofs/dof_renumbering.h b/include/deal.II/dofs/dof_renumbering.h index 48f8bdfc5a..9a849e0b30 100644 --- a/include/deal.II/dofs/dof_renumbering.h +++ b/include/deal.II/dofs/dof_renumbering.h @@ -738,27 +738,25 @@ namespace DoFRenumbering hierarchical (DoFHandler &dof_handler); /** - * Renumber degrees of freedom by cell. The function takes a vector of - * cell iterators (which needs to list all 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 all 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 - * dof_handler.get_triangulation().n_active_cells(). Every active - * cell iterator of that triangulation needs to be present in @p cell_order - * exactly once. + * dof_handler.get_triangulation().n_active_cells(). Every + * active cell iterator of that triangulation needs to be present in @p + * cell_order exactly once. */ template void @@ -774,28 +772,27 @@ namespace DoFRenumbering * 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 dof_handler.n_dofs() - * that contains for each degree of freedom (in their current numbering) - * their future DoF index. This vector therefore presents a - * (very particular) permutation of the current DoF indices. + * @param[out] renumbering A vector of length + * dof_handler.n_dofs() that contains for each degree of + * freedom (in their current numbering) their future DoF index. This vector + * therefore presents a (very particular) permutation 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 - * dof_handler.get_triangulation().n_active_cells(). 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 dof_handler.n_dofs(), - * the condition renumbering[inverse_renumbering[i]] == i - * will hold. + * dof_handler.get_triangulation().n_active_cells(). 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 + * dof_handler.n_dofs(), the condition + * renumbering[inverse_renumbering[i]] == i will hold. */ template void @@ -806,8 +803,8 @@ namespace DoFRenumbering const std::vector &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 void @@ -816,8 +813,8 @@ namespace DoFRenumbering const std::vector &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 void @@ -1015,14 +1012,13 @@ namespace DoFRenumbering /** * 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 void @@ -1032,9 +1028,8 @@ namespace DoFRenumbering * 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 void diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h index b0b41524e3..b1eef9f9e1 100644 --- a/include/deal.II/dofs/dof_tools.h +++ b/include/deal.II/dofs/dof_tools.h @@ -209,7 +209,8 @@ namespace DoFTools }; /** - * @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 * @{ */ /** @@ -341,131 +342,117 @@ namespace DoFTools */ /** - * 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 simulating 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 simulating 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 */ @@ -478,15 +465,15 @@ namespace DoFTools 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, * @@ -494,15 +481,14 @@ namespace DoFTools * -\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[ @@ -515,18 +501,17 @@ namespace DoFTools * \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 @@ -539,10 +524,8 @@ namespace DoFTools * 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 */ @@ -582,51 +565,47 @@ namespace DoFTools 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 faces 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 faces 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 */ @@ -637,10 +616,9 @@ namespace DoFTools /** * 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 */ @@ -654,20 +632,20 @@ namespace DoFTools /** * 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 */ @@ -682,11 +660,10 @@ namespace DoFTools * 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 void @@ -696,20 +673,19 @@ namespace DoFTools /** * 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 void @@ -855,9 +831,10 @@ namespace DoFTools * 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. @@ -1015,14 +992,14 @@ namespace DoFTools * 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 @@ -1192,7 +1169,8 @@ namespace DoFTools */ /** - * @name Identifying subsets of degrees of freedom with particular properties + * @name Identifying subsets of degrees of freedom with particular + * properties * @{ */ @@ -1534,15 +1512,17 @@ namespace DoFTools /** * - * 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 */ @@ -1552,15 +1532,17 @@ namespace DoFTools /** * - * 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 */ @@ -1570,8 +1552,8 @@ namespace DoFTools /** - * 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 void @@ -1581,10 +1563,10 @@ namespace DoFTools /** - * For each degree of freedom, return in the output array to which - * subdomain (as given by the cell->subdomain_id() - * 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 cell->subdomain_id() 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 @@ -1676,8 +1658,8 @@ namespace DoFTools * 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. * @@ -1941,10 +1923,11 @@ namespace DoFTools * * @tparam DoFHandlerType A type that is either DoFHandler or * hp::DoFHandler. In C++, the compiler can not determine the type of - * DoFHandlerType from the function call. You need to specify it - * as an explicit template argument following the function name. + * DoFHandlerType 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. @@ -1995,10 +1978,11 @@ namespace DoFTools * * @tparam DoFHandlerType A type that is either DoFHandler or * hp::DoFHandler. In C++, the compiler can not determine the type of - * DoFHandlerType from the function call. You need to specify it - * as an explicit template argument following the function name. + * DoFHandlerType 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. diff --git a/include/deal.II/dofs/function_map.h b/include/deal.II/dofs/function_map.h index b44393d0b8..5e8f2405fb 100644 --- a/include/deal.II/dofs/function_map.h +++ b/include/deal.II/dofs/function_map.h @@ -39,18 +39,18 @@ template class Function; * \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 diff --git a/include/deal.II/fe/fe.h b/include/deal.II/fe/fe.h index 162acd0e7b..1ae29d7467 100644 --- a/include/deal.II/fe/fe.h +++ b/include/deal.II/fe/fe.h @@ -40,96 +40,92 @@ namespace hp /** * 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 all possible - * interfaces (or may not yet 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 all possible interfaces (or may not yet 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"). * * *

Nomenclature

* - * 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. * *

Components and blocks

* * @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", @@ -137,22 +133,21 @@ namespace hp * 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(). @@ -160,21 +155,19 @@ namespace hp * *

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". + * 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 @@ -195,67 +188,60 @@ namespace hp * @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. * * *

Implementing finite element spaces in derived classes

* - * 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. * * *

Interpolation matrices in one dimension

* - * In one space dimension (i.e., for dim==1 and any - * value of spacedim), - * 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 dim==1 and any value of + * spacedim), 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. * *

Interpolation matrices in two dimensions

* * 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 m 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 n 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 m + * 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 + * n 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 @@ -277,21 +263,21 @@ namespace hp * 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. * * *

Interpolation matrices in three dimensions

* - * 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 @@ -368,14 +354,15 @@ namespace hp * 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. * @@ -389,7 +376,8 @@ namespace hp * etc). Other tasks can be automated by some of the functions in namespace * FETools. * - *
Computing the correct basis from a set of linearly independent functions
+ *
Computing the correct basis from a set of linearly independent + * functions
* * First, it may already be difficult to compute the basis of shape functions * for arbitrary order and dimension. On the other hand, if the @@ -415,15 +403,14 @@ namespace hp * wj. * * - * The matrix M 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 M 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 M(this->dofs_per_cell, this->dofs_per_cell); * FETools::compute_node_matrix(M, *this); @@ -435,17 +422,16 @@ namespace hp * *
Computing prolongation matrices
* - * 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 @@ -455,40 +441,38 @@ namespace hp * 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. * * *
Computing restriction matrices
* - * 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} @@ -502,63 +486,65 @@ namespace hp * \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 concatenation - * operation. I.e., we first compute the individual restrictions from each - * child, + * Consequently, restriction is typically implemented as a + * concatenation 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; childn_children(); ++child) * for (unsigned int i=0; ioverwrites, 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}$ overwrites, 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 average 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 average 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; childn_children(); ++child) * for (unsigned int i=0; idofs_per_cell (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 - * dofs_per_cell (or of size one, see below) that for each - * shape function provides a ComponentMask (of size - * fe_data.n_components()) 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.) + * dofs_per_cell (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 dofs_per_cell + * (or of size one, see below) that for each shape function provides a + * ComponentMask (of size fe_data.n_components()) 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 restriction_is_additive_flags.size() == dofs_per_cell, - * or restriction_is_additive_flags.size() == 1. In the latter - * case, the array is simply interpreted as having size - * dofs_per_cell where each element has the same value as the - * single element given. + * or restriction_is_additive_flags.size() == 1. In the latter + * case, the array is simply interpreted as having size + * dofs_per_cell where each element has the same value as the + * single element given. * - * @pre nonzero_components.size() == dofs_per_cell, - * or nonzero_components.size() == 1. In the latter - * case, the array is simply interpreted as having size - * dofs_per_cell where each element equals the component - * mask provided in the single element given. + * @pre nonzero_components.size() == dofs_per_cell, or + * nonzero_components.size() == 1. In the latter case, the + * array is simply interpreted as having size dofs_per_cell + * where each element equals the component mask provided in the single + * element given. */ FiniteElement (const FiniteElementData &fe_data, const std::vector &restriction_is_additive_flags, @@ -779,16 +761,14 @@ public: * 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 &p) const; @@ -815,16 +795,14 @@ public: * 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 &p) const; @@ -851,16 +829,14 @@ public: * 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 &p) const; @@ -887,25 +863,23 @@ public: * 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 &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 &p, @@ -923,25 +897,23 @@ public: * 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 &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 &p, @@ -966,10 +938,9 @@ public: */ /** - * 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, @@ -977,8 +948,8 @@ public: * * 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 & @@ -988,11 +959,12 @@ public: /** * 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 j,k exists in in two @@ -1007,10 +979,10 @@ public: * 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 & @@ -1099,9 +1071,9 @@ public: /** - * 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. @@ -1969,8 +1941,8 @@ public: * * @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 @@ -2201,8 +2173,8 @@ protected: * 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; @@ -2288,9 +2260,9 @@ protected: 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 restriction_is_additive_flags; @@ -2338,22 +2310,20 @@ protected: /** * Given a set of update flags, compute which other quantities also * 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 */ @@ -2363,82 +2333,79 @@ protected: /** * 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 final 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 final 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 cheaper, - * 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 cheaper, 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 * @@ -2449,45 +2416,44 @@ protected: /** * 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 * @@ -2498,45 +2464,44 @@ protected: /** * 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 * @@ -2546,30 +2511,28 @@ protected: dealii::internal::FEValues::FiniteElementRelatedData &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). * @@ -2578,59 +2541,54 @@ protected: * @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 @@ -2644,50 +2602,46 @@ protected: dealii::internal::FEValues::FiniteElementRelatedData &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 @@ -2701,54 +2655,49 @@ protected: dealii::internal::FEValues::FiniteElementRelatedData &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 diff --git a/include/deal.II/fe/fe_base.h b/include/deal.II/fe/fe_base.h index 0fe1d41270..fe4f0e9025 100644 --- a/include/deal.II/fe/fe_base.h +++ b/include/deal.II/fe/fe_base.h @@ -131,14 +131,14 @@ namespace FiniteElementDomination /** * 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, @@ -314,39 +314,39 @@ public: * 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 (1,0,0). On the other hand, - * for a $Q_3$ element in 3d, it would have entries (1,2,4,8). + * @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 (1,0,0). On the other hand, for a $Q_3$ + * element in 3d, it would have entries (1,2,4,8). * * @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 &dofs_per_object, const unsigned int n_components, diff --git a/include/deal.II/fe/fe_bdm.h b/include/deal.II/fe/fe_bdm.h index 26f1972f9c..c49e225dc1 100644 --- a/include/deal.II/fe/fe_bdm.h +++ b/include/deal.II/fe/fe_bdm.h @@ -34,8 +34,8 @@ DEAL_II_NAMESPACE_OPEN * *

Degrees of freedom

* - * @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. * @@ -105,9 +105,9 @@ private: */ 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. + * 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. */ std::vector > test_values_face; /** diff --git a/include/deal.II/fe/fe_dg_vector.h b/include/deal.II/fe/fe_dg_vector.h index 7f692654a3..0735e94073 100644 --- a/include/deal.II/fe/fe_dg_vector.h +++ b/include/deal.II/fe/fe_dg_vector.h @@ -43,10 +43,10 @@ template class MappingQ; * are suitable for DG and hybrid formulations involving these function * spaces. * - * The template argument PolynomialType refers to a vector valued polynomial - * space like PolynomialsRaviartThomas or PolynomialsNedelec. Note that the - * dimension of the polynomial space and the argument dim must - * coincide. + * The template argument PolynomialType refers to a vector valued + * polynomial space like PolynomialsRaviartThomas or PolynomialsNedelec. Note + * that the dimension of the polynomial space and the argument dim + * must coincide. * * @ingroup febase * @author Guido Kanschat diff --git a/include/deal.II/fe/fe_dgp_nonparametric.h b/include/deal.II/fe/fe_dgp_nonparametric.h index 86a69faeaf..a3e0caf6e3 100644 --- a/include/deal.II/fe/fe_dgp_nonparametric.h +++ b/include/deal.II/fe/fe_dgp_nonparametric.h @@ -255,15 +255,16 @@ template class MappingQ; * *

Implementation details

* - * 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 */ @@ -289,81 +290,81 @@ public: 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 &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 &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 &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 &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 &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 &p, diff --git a/include/deal.II/fe/fe_nothing.h b/include/deal.II/fe/fe_nothing.h index 78b16193f3..bdf1281b89 100644 --- a/include/deal.II/fe/fe_nothing.h +++ b/include/deal.II/fe/fe_nothing.h @@ -85,12 +85,12 @@ public: * 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); @@ -189,9 +189,9 @@ public: * @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 @@ -253,7 +253,8 @@ public: 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; }; diff --git a/include/deal.II/fe/fe_poly.h b/include/deal.II/fe/fe_poly.h index 802837daba..a20f52aa44 100644 --- a/include/deal.II/fe/fe_poly.h +++ b/include/deal.II/fe/fe_poly.h @@ -55,8 +55,8 @@ DEAL_II_NAMESPACE_OPEN * * 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. @@ -167,9 +167,9 @@ public: const unsigned int component) const; /** - * Return the tensor of third derivatives of the ith shape - * function at point p 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 ith shape function + * at point p 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 &p) const; @@ -395,7 +395,8 @@ protected: * 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; @@ -412,22 +413,23 @@ protected: }; /** - * 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 &output_data, @@ -436,7 +438,8 @@ protected: 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; }; diff --git a/include/deal.II/fe/fe_poly_face.h b/include/deal.II/fe/fe_poly_face.h index 889ef93295..26058410c9 100644 --- a/include/deal.II/fe/fe_poly_face.h +++ b/include/deal.II/fe/fe_poly_face.h @@ -211,7 +211,8 @@ protected: }; /** - * 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; }; diff --git a/include/deal.II/fe/fe_poly_tensor.h b/include/deal.II/fe/fe_poly_tensor.h index 20acbb6de1..a754a5980b 100644 --- a/include/deal.II/fe/fe_poly_tensor.h +++ b/include/deal.II/fe/fe_poly_tensor.h @@ -94,7 +94,8 @@ DEAL_II_NAMESPACE_OPEN * * @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 j as defined in the polynomial space PolynomialType. + * return the raw polynomial j as defined in the polynomial space + * PolynomialType. * *

Setting the transformation

* @@ -132,11 +133,10 @@ public: 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 &p) const; @@ -147,10 +147,9 @@ public: 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, @@ -162,10 +161,9 @@ public: 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, @@ -370,10 +368,10 @@ protected: 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; /** @@ -392,7 +390,8 @@ protected: /** - * 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; diff --git a/include/deal.II/fe/fe_q_base.h b/include/deal.II/fe/fe_q_base.h index 26b5774afb..601189dea1 100644 --- a/include/deal.II/fe/fe_q_base.h +++ b/include/deal.II/fe/fe_q_base.h @@ -27,9 +27,10 @@ DEAL_II_NAMESPACE_OPEN /*@{*/ /** - * 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; diff --git a/include/deal.II/fe/fe_q_bubbles.h b/include/deal.II/fe/fe_q_bubbles.h index aed380f3c9..b7ecfb9c69 100644 --- a/include/deal.II/fe/fe_q_bubbles.h +++ b/include/deal.II/fe/fe_q_bubbles.h @@ -32,22 +32,22 @@ DEAL_II_NAMESPACE_OPEN * 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 spacedim 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. * *

* @image html fe_q_bubbles_conditioning.png @@ -58,13 +58,13 @@ DEAL_II_NAMESPACE_OPEN *

Implementation

* * 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. @@ -72,12 +72,11 @@ DEAL_II_NAMESPACE_OPEN *

Numbering of the degrees of freedom (DoFs)

* * 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 @@ -85,16 +84,17 @@ class FE_Q_Bubbles : public FE_Q_Base,dim,s { 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 points.size(). - * 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 points.size(). Note that the + * first point has to be 0 and the last one 1. */ FE_Q_Bubbles (const Quadrature<1> &points); @@ -176,8 +176,8 @@ protected: 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 get_riaf_vector(const unsigned int degree); diff --git a/include/deal.II/fe/fe_rannacher_turek.h b/include/deal.II/fe/fe_rannacher_turek.h index 9f2e658207..17dbd0f9c9 100644 --- a/include/deal.II/fe/fe_rannacher_turek.h +++ b/include/deal.II/fe/fe_rannacher_turek.h @@ -36,17 +36,15 @@ DEAL_II_NAMESPACE_OPEN * *

Interpolation

* - *

Node values

- * The + *

Node values

The * @ref GlossNodes "node values" * are moments on faces. * - *

Generalized support points

- * 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. + *

Generalized support points

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 @@ -57,10 +55,9 @@ class FE_RannacherTurek : public FE_Poly, dim> { 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. */ @@ -100,8 +97,8 @@ private: */ 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 get_dpo_vector(); }; diff --git a/include/deal.II/fe/fe_system.h b/include/deal.II/fe/fe_system.h index ba2a12356d..8c936a7e12 100644 --- a/include/deal.II/fe/fe_system.h +++ b/include/deal.II/fe/fe_system.h @@ -630,8 +630,8 @@ public: * * 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 & @@ -659,10 +659,10 @@ public: * 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 & @@ -1064,9 +1064,9 @@ private: typename std::vector::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. diff --git a/include/deal.II/fe/fe_tools.h b/include/deal.II/fe/fe_tools.h index ad04f39fbd..b61a792d84 100644 --- a/include/deal.II/fe/fe_tools.h +++ b/include/deal.II/fe/fe_tools.h @@ -297,8 +297,8 @@ namespace FETools * @param isotropic_only Set to true 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 void compute_embedding_matrices(const FiniteElement &fe, @@ -321,8 +321,8 @@ namespace FETools * @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. diff --git a/include/deal.II/fe/fe_update_flags.h b/include/deal.II/fe/fe_update_flags.h index 313c0fca4c..9ae95903ad 100644 --- a/include/deal.II/fe/fe_update_flags.h +++ b/include/deal.II/fe/fe_update_flags.h @@ -53,8 +53,8 @@ template class FiniteElement; * *

Use of these flags flags

* - * 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". @@ -323,8 +323,8 @@ operator &= (UpdateFlags &f1, UpdateFlags f2) * 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 - * dimoutput 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 output 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 input argument in - * the following call to FiniteElement::fill_fe_values(). + * The data herein will then be provided as input argument in the + * following call to FiniteElement::fill_fe_values(). * * @ingroup feaccess */ @@ -366,23 +366,23 @@ namespace internal 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 JxW_values; @@ -403,8 +403,8 @@ namespace internal std::vector > 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 > jacobian_pushed_forward_grads; @@ -429,14 +429,13 @@ namespace internal /** * Array of the third derivatives of the Jacobian matrices at the * quadrature points, pushed forward to the real cell coordinates. - */ std::vector > 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 > quadrature_points; @@ -455,9 +454,8 @@ namespace internal /** * 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 output argument when dealii::FEValues::reinit() - * calls FiniteElement::fill_fe_values(). + * objects. Objects of this kind will be given as output argument + * when dealii::FEValues::reinit() calls FiniteElement::fill_fe_values(). * * @ingroup feaccess */ @@ -473,27 +471,28 @@ namespace internal 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; @@ -514,57 +513,60 @@ namespace internal 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 i * n_components + c. - 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 i * n_components + c. - 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 * [i*n_components, (i+1)*n_components). */ std::vector shape_function_to_row_table; diff --git a/include/deal.II/fe/fe_values.h b/include/deal.II/fe/fe_values.h index b88ae6e6eb..f01219e4e4 100644 --- a/include/deal.II/fe/fe_values.h +++ b/include/deal.II/fe/fe_values.h @@ -371,10 +371,10 @@ namespace FEValuesViews * 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} */ @@ -664,9 +664,9 @@ namespace FEValuesViews 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. @@ -845,10 +845,10 @@ namespace FEValuesViews * 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} */ @@ -1344,8 +1344,8 @@ namespace internal * 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 @@ -1428,7 +1428,8 @@ namespace internal *

Internals about the implementation

* * 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". * * @@ -1553,8 +1554,8 @@ public: * * @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} */ @@ -1588,8 +1589,8 @@ public: * point_noth 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 @@ -1630,10 +1631,10 @@ public: /** * Third derivatives of the function_noth shape function at the * point_noth 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 @@ -1651,15 +1652,15 @@ public: 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. @@ -2141,11 +2142,11 @@ public: * store the values of the unknowns $U_j$ of your finite element vector $U$ * (represented by the @p fe_function argument). * - * @post third_derivatives[q] will contain the third derivatives - * of the field described by fe_function at the $q$th quadrature point. - * third_derivatives[q][i][j][k] represents the $(i,j,k)$th - * component of the 3rd order tensor of third derivatives at quadrature - * point $q$. + * @post third_derivatives[q] will contain the third + * derivatives of the field described by fe_function at the $q$th quadrature + * point. third_derivatives[q][i][j][k] 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 @@ -2163,20 +2164,20 @@ public: std::vector > &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 third_derivatives[q] 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 third_derivatives[q] equals * the number of components of the finite element, i.e. * third_derivatives[q][c] returns the third derivative of the - * $c$th vector component at the $q$th quadrature point. - * Consequently, third_derivatives[q][c][i][j][k] 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, + * third_derivatives[q][c][i][j][k] 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} */ @@ -2302,9 +2303,9 @@ public: const std::vector > &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} */ @@ -2319,10 +2320,11 @@ public: const std::vector > &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} */ @@ -2339,7 +2341,8 @@ public: /** * 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} */ @@ -2357,7 +2360,8 @@ public: * 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} */ @@ -2391,10 +2395,10 @@ public: * For a face, return the outward normal vector to the cell at the * ith 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. * @@ -2409,21 +2413,21 @@ public: * * @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 > &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} * @@ -2671,14 +2675,15 @@ protected: std_cxx11::unique_ptr::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 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,FEValuesBase > fe; @@ -2786,9 +2791,9 @@ public: 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 &fe, const Quadrature &quadrature, @@ -2812,8 +2817,8 @@ public: * this class if they need information about degrees of freedom. These * functions are, above all, the * get_function_value/gradients/hessians/laplacians/third_derivatives - * 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::cell_iterator &cell); @@ -2997,9 +3002,9 @@ public: 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 &fe, const Quadrature &quadrature, @@ -3022,9 +3027,9 @@ public: * some functions of this class if they need information about degrees of * freedom. These functions are, above all, the * get_function_value/gradients/hessians/third_derivatives - * 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::cell_iterator &cell, const unsigned int face_no); @@ -3107,9 +3112,9 @@ public: 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 &fe, const Quadrature &face_quadrature, @@ -3135,9 +3140,9 @@ public: * some functions of this class if they need information about degrees of * freedom. These functions are, above all, the * get_function_value/gradients/hessians/third_derivatives - * 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::cell_iterator &cell, const unsigned int face_no, diff --git a/include/deal.II/fe/mapping.h b/include/deal.II/fe/mapping.h index 4fdb212e5f..32be5cc569 100644 --- a/include/deal.II/fe/mapping.h +++ b/include/deal.II/fe/mapping.h @@ -66,12 +66,14 @@ enum MappingType 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, @@ -114,18 +116,21 @@ enum MappingType * 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 }; @@ -133,20 +138,20 @@ enum MappingType /** * @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. * *

Mathematics of the mapping

* - * 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} @@ -158,8 +163,8 @@ enum MappingType * *

%Mapping of scalar functions

* - * 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}). @@ -168,8 +173,8 @@ enum MappingType * *

%Mapping of integrals

* - * 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 @@ -177,8 +182,8 @@ enum MappingType * \,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 @@ -198,8 +203,8 @@ enum MappingType *

%Mapping of vector fields, differential forms and gradients of vector * fields

* - * 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[ @@ -209,49 +214,50 @@ enum MappingType * \mathbf T(\mathbf x) = \mathbf A(\hat{\mathbf x}) * \hat{\mathbf T}(\hat{\mathbf x}) \mathbf B(\hat{\mathbf x}). * @f] - * The differential forms A and 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 A and 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. * *

Derivatives of the mapping

* - * 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}) @@ -318,10 +324,9 @@ public: get_vertices (const typename Triangulation::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 * cell-@>vertex() (i.e., information stored by the * triangulation). * @@ -344,9 +349,9 @@ public: * @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 @@ -354,9 +359,9 @@ public: const Point &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. @@ -376,10 +381,10 @@ public: * @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 @@ -392,8 +397,8 @@ public: * 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 project_real_point_to_unit_point_on_face (const typename Triangulation::cell_iterator &cell, @@ -454,77 +459,69 @@ public: 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 * const, 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 const 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 mutable to allow for their - * modification despite the fact that the surrounding object is - * marked as const. + * 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 const + * 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 mutable to + * allow for their modification despite the fact that the surrounding object + * is marked as const. */ class InternalDataBase { @@ -547,20 +544,18 @@ public: 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; @@ -575,25 +570,23 @@ protected: /** * Given a set of update flags, compute which other quantities also * 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 */ @@ -602,56 +595,52 @@ protected: 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 derived - * 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 derived 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 * @@ -659,34 +648,31 @@ protected: const Quadrature &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 derived - * 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 derived 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 * @@ -694,34 +680,32 @@ protected: const Quadrature &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 derived - * 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 derived 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 * @@ -729,96 +713,87 @@ protected: const Quadrature &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 @@ -829,30 +804,28 @@ protected: dealii::internal::FEValues::MappingRelatedData &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::cell_iterator &cell, @@ -862,33 +835,30 @@ protected: dealii::internal::FEValues::MappingRelatedData &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::cell_iterator &cell, @@ -930,8 +900,8 @@ public: * *
  • @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 @@ -947,29 +917,29 @@ public: * because we assume that the mapping $\mathbf F_K$ is always invertible, * and consequently its Jacobian $J$ is an invertible matrix. * - *
  • @p mapping_piola: A field of dim-1-forms on the reference cell - * is also represented by a vector field, but again transforms differently, - * namely by the Piola transform + *
  • @p mapping_piola: A field of dim-1-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] * * - * @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 @@ -980,9 +950,10 @@ public: /** * 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: *
      *
    • @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 @@ -1008,20 +979,20 @@ public: * 1@> with a Tensor@<1,dim@> 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 @@ -1032,9 +1003,9 @@ public: /** * 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: *
        *
      • @p mapping_contravariant_gradient: it assumes $\mathbf u(\mathbf x) * = J \hat{\mathbf u}$ so that @@ -1051,8 +1022,8 @@ public: * J(\hat{\mathbf x})^{-1}. * @f] *
      • @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)} @@ -1062,25 +1033,25 @@ public: *
      * * @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 @@ -1096,9 +1067,9 @@ public: * * The mapping types currently implemented by derived classes are: *
        - *
      • @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 + *
      • @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], * @@ -1107,26 +1078,26 @@ public: *
      * * 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 @@ -1137,9 +1108,9 @@ public: /** * 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: *
        @@ -1158,8 +1129,8 @@ public: * J_{jJ}(\hat{\mathbf x})^{-1} J_{kK}(\hat{\mathbf x})^{-1}. * @f] *
      • @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)} @@ -1168,19 +1139,19 @@ public: * @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. + * @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 diff --git a/include/deal.II/fe/mapping_c1.h b/include/deal.II/fe/mapping_c1.h index b61fcfaf3c..8c6512ca31 100644 --- a/include/deal.II/fe/mapping_c1.h +++ b/include/deal.II/fe/mapping_c1.h @@ -58,9 +58,9 @@ public: 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 { @@ -73,15 +73,15 @@ protected: /** * For dim=2,3. 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 compute_support_points_simple(laplace) functions. - * For dim=1 this function is empty. + * Needed by the compute_support_points_simple(laplace) + * functions. For dim=1 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::cell_iterator &cell, @@ -96,8 +96,8 @@ protected: * dim=1 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::cell_iterator &cell, diff --git a/include/deal.II/fe/mapping_cartesian.h b/include/deal.II/fe/mapping_cartesian.h index de39f49e48..f0c905245e 100644 --- a/include/deal.II/fe/mapping_cartesian.h +++ b/include/deal.II/fe/mapping_cartesian.h @@ -46,9 +46,8 @@ DEAL_II_NAMESPACE_OPEN * {\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 @@ -153,12 +152,12 @@ private: * 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::InternalDataBase { diff --git a/include/deal.II/fe/mapping_fe_field.h b/include/deal.II/fe/mapping_fe_field.h index c50d0391fe..cb0a5d7046 100644 --- a/include/deal.II/fe/mapping_fe_field.h +++ b/include/deal.II/fe/mapping_fe_field.h @@ -236,12 +236,12 @@ public: * 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::InternalDataBase { @@ -553,8 +553,7 @@ private: const typename MappingFEField::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 > &unit_points, diff --git a/include/deal.II/fe/mapping_q.h b/include/deal.II/fe/mapping_q.h index 68d0311462..6188a4e65f 100644 --- a/include/deal.II/fe/mapping_q.h +++ b/include/deal.II/fe/mapping_q.h @@ -30,58 +30,58 @@ template class TensorProductPolynomials; /** * 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$ everywhere, 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 class MappingQ : public Mapping { 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 false (the @@ -111,8 +111,8 @@ public: 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; @@ -212,21 +212,21 @@ protected: * 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::InternalDataBase { @@ -251,14 +251,14 @@ protected: 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::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::InternalData> mapping_qp_data; }; @@ -334,39 +334,36 @@ protected: /** * 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 > 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 > qp_mapping; }; diff --git a/include/deal.II/fe/mapping_q1.h b/include/deal.II/fe/mapping_q1.h index 1350491d29..40e006147c 100644 --- a/include/deal.II/fe/mapping_q1.h +++ b/include/deal.II/fe/mapping_q1.h @@ -37,26 +37,25 @@ DEAL_II_NAMESPACE_OPEN * 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 - * faces 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 faces 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 class MappingQ1 : public MappingQGeneric @@ -75,26 +74,26 @@ public: /** - * 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 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 mapping; }; diff --git a/include/deal.II/fe/mapping_q1_eulerian.h b/include/deal.II/fe/mapping_q1_eulerian.h index 9e8aeab0e1..356dba917d 100644 --- a/include/deal.II/fe/mapping_q1_eulerian.h +++ b/include/deal.II/fe/mapping_q1_eulerian.h @@ -101,10 +101,10 @@ public: const DoFHandler &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, GeometryInfo::vertices_per_cell> @@ -133,12 +133,12 @@ public: 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 @@ -149,10 +149,10 @@ protected: internal::FEValues::MappingRelatedData &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 > diff --git a/include/deal.II/fe/mapping_q_eulerian.h b/include/deal.II/fe/mapping_q_eulerian.h index 4a3e0e8824..e7bd5ce84c 100644 --- a/include/deal.II/fe/mapping_q_eulerian.h +++ b/include/deal.II/fe/mapping_q_eulerian.h @@ -101,8 +101,8 @@ public: * 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 &euler_dof_handler, @@ -117,10 +117,10 @@ public: const DoFHandler &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, GeometryInfo::vertices_per_cell> @@ -147,12 +147,12 @@ public: 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 @@ -176,9 +176,9 @@ protected: 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 { @@ -191,19 +191,19 @@ private: const MappingQEulerian &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, GeometryInfo::vertices_per_cell> get_vertices (const typename Triangulation::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 > @@ -241,8 +241,9 @@ private: * 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 fe_values; diff --git a/include/deal.II/fe/mapping_q_generic.h b/include/deal.II/fe/mapping_q_generic.h index b55e406f8d..2c1e19e71c 100644 --- a/include/deal.II/fe/mapping_q_generic.h +++ b/include/deal.II/fe/mapping_q_generic.h @@ -39,53 +39,47 @@ template class MappingQ; /** - * 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$ on - * cells at the boundary of the domain). 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 happen 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$ on cells at the boundary of the domain). 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 happen 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 @@ -95,9 +89,9 @@ class MappingQGeneric : public Mapping { 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); @@ -117,8 +111,8 @@ public: 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; @@ -203,30 +197,29 @@ public: * 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::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, @@ -234,9 +227,9 @@ public: 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, @@ -244,20 +237,19 @@ public: 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 > &unit_points); @@ -382,9 +374,8 @@ public: std::vector > > 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; @@ -394,8 +385,8 @@ public: * 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; @@ -499,8 +490,8 @@ public: 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; @@ -523,13 +514,14 @@ protected: const std_cxx11::unique_ptr > 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. @@ -537,9 +529,9 @@ protected: 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. @@ -547,35 +539,32 @@ protected: 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 > @@ -591,20 +580,18 @@ protected: const Point &initial_p_unit) const; /** - * For dim=2,3. 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 dim=2,3. 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 - * dim=1 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 dim=1 + * 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 @@ -612,21 +599,18 @@ protected: std::vector > &a) const; /** - * For dim=3. 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 dim=3. 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 - * dim=1 and dim=2 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 dim=1 + * and dim=2 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 @@ -634,9 +618,8 @@ protected: std::vector > &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 friend class MappingQ; }; diff --git a/include/deal.II/grid/filtered_iterator.h b/include/deal.II/grid/filtered_iterator.h index 243f99f05f..0be6f669c5 100644 --- a/include/deal.II/grid/filtered_iterator.h +++ b/include/deal.II/grid/filtered_iterator.h @@ -228,9 +228,9 @@ namespace IteratorFilters 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 material_ids, const bool only_locally_owned = false); diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h index 0ee05bd48e..b1c9c7701d 100644 --- a/include/deal.II/grid/grid_generator.h +++ b/include/deal.II/grid/grid_generator.h @@ -65,10 +65,10 @@ namespace GridGenerator * * @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 Triangulation@<2,3@> 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 + * Triangulation@<2,3@> 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 @@ -95,12 +95,13 @@ namespace GridGenerator * @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 Triangulation@<2,2@>, Triangulation@<3,3@>. + * @note Implemented for Triangulation@<2,2@>, + * Triangulation@<3,3@>. * * @author Guido Kanschat * @date 2015 @@ -115,10 +116,10 @@ namespace GridGenerator * cells. Thus, the number of cells filling the given volume is * repetitionsdim. * - * 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 Triangulation@<2,3@> 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 + * Triangulation@<2,3@> will be a square in the xy plane with z=0. * * @note The triangulation needs to be void upon calling this function. */ @@ -141,11 +142,11 @@ namespace GridGenerator * 2i. 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 Triangulation@<2,3@> 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 + * Triangulation@<2,3@> 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. */ @@ -181,20 +182,20 @@ namespace GridGenerator * 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 Triangulation@<2,3@> 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 + * Triangulation@<2,3@> 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. * @@ -267,15 +268,14 @@ namespace GridGenerator * * @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 */ @@ -358,17 +358,17 @@ namespace GridGenerator /** * 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. * @@ -430,38 +430,36 @@ namespace GridGenerator 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 void hyper_sphere (Triangulation &tria, @@ -629,28 +627,28 @@ namespace GridGenerator * * 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 n_cells 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 @@ -956,8 +954,8 @@ namespace GridGenerator * 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, @@ -998,7 +996,8 @@ namespace GridGenerator ///@} /** - * @name Creating lower-dimensional meshes from parts of higher-dimensional meshes + * @name Creating lower-dimensional meshes from parts of higher-dimensional + * meshes */ ///@{ @@ -1045,41 +1044,40 @@ namespace GridGenerator * * @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 all 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 all 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 diff --git a/include/deal.II/grid/grid_in.h b/include/deal.II/grid/grid_in.h index 4764ee30ed..14976f4fe1 100644 --- a/include/deal.II/grid/grid_in.h +++ b/include/deal.II/grid/grid_in.h @@ -288,7 +288,8 @@ struct SubCellData; * * @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 @@ -368,41 +369,39 @@ public: 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); diff --git a/include/deal.II/grid/grid_out.h b/include/deal.II/grid/grid_out.h index b33e11927e..8a378db460 100644 --- a/include/deal.II/grid/grid_out.h +++ b/include/deal.II/grid/grid_out.h @@ -318,14 +318,13 @@ namespace GridOutFlags 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; diff --git a/include/deal.II/grid/grid_refinement.h b/include/deal.II/grid/grid_refinement.h index 94798acc92..319e8bbc5f 100644 --- a/include/deal.II/grid/grid_refinement.h +++ b/include/deal.II/grid/grid_refinement.h @@ -67,7 +67,8 @@ namespace GridRefinement * 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. @@ -128,11 +129,11 @@ namespace GridRefinement * 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 @@ -141,13 +142,13 @@ namespace GridRefinement * @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 void @@ -205,13 +206,13 @@ namespace GridRefinement * @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 void diff --git a/include/deal.II/grid/grid_reordering.h b/include/deal.II/grid/grid_reordering.h index e0e82119e6..a5b49fa98f 100644 --- a/include/deal.II/grid/grid_reordering.h +++ b/include/deal.II/grid/grid_reordering.h @@ -471,10 +471,10 @@ DEAL_II_NAMESPACE_OPEN * 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 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 arxiv * 1512.02137. * * diff --git a/include/deal.II/grid/grid_reordering_internal.h b/include/deal.II/grid/grid_reordering_internal.h index 80e86240a9..007cc7eb47 100644 --- a/include/deal.II/grid/grid_reordering_internal.h +++ b/include/deal.II/grid/grid_reordering_internal.h @@ -207,8 +207,8 @@ namespace internal void build_graph (const std::vector > &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) * @@ -617,8 +617,8 @@ namespace internal /** * 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; diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index d73d8f9a30..c0e813e127 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -342,8 +342,7 @@ namespace GridTools * 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. @@ -401,8 +400,7 @@ namespace GridTools * 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. @@ -450,8 +448,7 @@ namespace GridTools * * @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 @@ -528,9 +525,9 @@ namespace GridTools * @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 > (cell) * @endcode @@ -555,13 +552,14 @@ namespace GridTools std::vector &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 * bool @@ -576,8 +574,9 @@ namespace GridTools * GridTools::compute_active_cell_halo_layer(tria, pred_mat_id); * @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)); @@ -593,13 +592,13 @@ namespace GridTools * * @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 */ @@ -610,16 +609,16 @@ namespace GridTools const std_cxx11::function &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 @@ -633,8 +632,8 @@ namespace GridTools * 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 cell-@>vertex_index(). Notice that only the - * indices marked in the array returned by + * function cell-@>vertex_index(). Notice that only the indices + * marked in the array returned by * Triangulation::get_used_vertices() are used. */ template @@ -642,11 +641,11 @@ namespace GridTools vertex_to_cell_map(const Triangulation &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 touch 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 touch 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 @@ -840,12 +839,12 @@ namespace GridTools /*@{*/ /** - * 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 @@ -933,7 +932,7 @@ namespace GridTools /*@}*/ /** * @name Extracting and creating patches of cells surrounding a single cell, - * and creating triangulation out of them + * and creating triangulation out of them */ /*@{*/ @@ -984,25 +983,24 @@ namespace GridTools /** * 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 Container 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 + * Container 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 */ @@ -1011,71 +1009,65 @@ namespace GridTools get_cells_at_coarsest_common_level(const std::vector &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 element. - * - * @tparam Container In C++, the compiler can not determine the type - * of Container 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 element. + * + * @tparam Container In C++, the compiler can not determine the type of + * Container 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 void @@ -1143,15 +1135,14 @@ namespace GridTools /** * 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 matrix; @@ -1164,11 +1155,11 @@ namespace GridTools * @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 v_1 and v_2 are considered equal, - * if $M\cdot v_1 + offset - v_2$ is parallel to the unit vector in unit + * Here, two vertices v_1 and v_2 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 @@ -1248,10 +1239,9 @@ namespace GridTools /** - * 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 @@ -1262,31 +1252,28 @@ namespace GridTools * 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". @@ -1297,9 +1284,9 @@ namespace GridTools * 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 */ @@ -1354,11 +1341,11 @@ namespace GridTools /*@{*/ /** - * 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 diff --git a/include/deal.II/grid/intergrid_map.h b/include/deal.II/grid/intergrid_map.h index 4c2ff2dd70..f4413d5201 100644 --- a/include/deal.II/grid/intergrid_map.h +++ b/include/deal.II/grid/intergrid_map.h @@ -67,9 +67,9 @@ DEAL_II_NAMESPACE_OPEN * 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++ * std::map data type. Instead, it uses another data diff --git a/include/deal.II/grid/manifold_lib.h b/include/deal.II/grid/manifold_lib.h index f14233f9c6..78694794e8 100644 --- a/include/deal.II/grid/manifold_lib.h +++ b/include/deal.II/grid/manifold_lib.h @@ -47,9 +47,8 @@ DEAL_II_NAMESPACE_OPEN * 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 * diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index a4723ba3a7..f6b857743e 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -124,10 +124,9 @@ struct CellData }; /** - * 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; @@ -162,13 +161,12 @@ struct CellData * 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 */ @@ -1711,10 +1709,10 @@ public: std::vector 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 @@ -1920,8 +1918,8 @@ public: 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, /** @@ -1940,7 +1938,8 @@ public: /** * 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 struct CellWeightSum @@ -1967,10 +1966,9 @@ public: /** * 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 . @@ -1979,17 +1977,19 @@ public: { /** * 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 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 pre_refinement; @@ -2003,70 +2003,69 @@ public: /** * 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::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::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 old 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 + * old triangulation, but the new one is passed as an argument). */ boost::signals2::signal &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 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 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 & 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 & get_triangulation () const; diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h index 4b862684c1..3800008757 100644 --- a/include/deal.II/grid/tria_accessor.h +++ b/include/deal.II/grid/tria_accessor.h @@ -1130,7 +1130,8 @@ public: /** * 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 @@ -1475,14 +1476,14 @@ private: /** - * Specialization of TriaAccessor. - * This class represent vertices in a triangulation of dimensionality - * dim (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 spacedim (for spacedim==dim the - * triangulation represents a domain in ${\mathbb R}^\text{dim}$, for - * spacedim@>dim the triangulation is of a manifold embedded in - * a higher dimensional space). + * Specialization of TriaAccessor. This + * class represent vertices in a triangulation of dimensionality + * dim (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 spacedim (for + * spacedim==dim the triangulation represents a domain in + * ${\mathbb R}^\text{dim}$, for spacedim@>dim the triangulation + * is of a manifold embedded in a higher dimensional space). * * @ingroup Accessors * @author Bruno Turcksin, 2015 @@ -1518,15 +1519,16 @@ public: 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 *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 *tria = NULL, const int level = 0, @@ -1675,9 +1677,9 @@ public: /** * 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 * TriaAccessor. */ Point center (const bool respect_manifold=false, @@ -2806,11 +2808,11 @@ public: * @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; diff --git a/include/deal.II/grid/tria_boundary.h b/include/deal.II/grid/tria_boundary.h index d737462b8c..127b3feb12 100644 --- a/include/deal.II/grid/tria_boundary.h +++ b/include/deal.II/grid/tria_boundary.h @@ -112,19 +112,17 @@ public: * * 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 @@ -142,15 +140,14 @@ public: * to arrange the points such they split the quad into (m+1)(m+1) * 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 diff --git a/include/deal.II/grid/tria_iterator.h b/include/deal.II/grid/tria_iterator.h index f22335720a..1286c7226b 100644 --- a/include/deal.II/grid/tria_iterator.h +++ b/include/deal.II/grid/tria_iterator.h @@ -79,9 +79,9 @@ template class TriaActiveIterator; * The objects pointed to are accessors, derived from TriaAccessorBase. Which * kind of accessor is determined by the template argument Accessor. * 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. * *

      Which iterator to use when

      * diff --git a/include/deal.II/hp/dof_handler.h b/include/deal.II/hp/dof_handler.h index e3bc3ceaf9..dd2e24e14f 100644 --- a/include/deal.II/hp/dof_handler.h +++ b/include/deal.II/hp/dof_handler.h @@ -593,14 +593,16 @@ namespace hp const hp::FECollection &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 &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 &get_triangulation () const; diff --git a/include/deal.II/hp/fe_collection.h b/include/deal.II/hp/fe_collection.h index 855ded1476..0e4ec67e63 100644 --- a/include/deal.II/hp/fe_collection.h +++ b/include/deal.II/hp/fe_collection.h @@ -68,23 +68,23 @@ namespace hp explicit FECollection (const FiniteElement &fe); /** - * Constructor. This constructor creates a FECollection from two - * finite elements. + * Constructor. This constructor creates a FECollection from two finite + * elements. */ FECollection (const FiniteElement &fe1, const FiniteElement &fe2); /** - * Constructor. This constructor creates a FECollection from three - * finite elements. + * Constructor. This constructor creates a FECollection from three finite + * elements. */ FECollection (const FiniteElement &fe1, const FiniteElement &fe2, const FiniteElement &fe3); /** - * Constructor. This constructor creates a FECollection from four - * finite elements. + * Constructor. This constructor creates a FECollection from four finite + * elements. */ FECollection (const FiniteElement &fe1, const FiniteElement &fe2, @@ -92,8 +92,8 @@ namespace hp const FiniteElement &fe4); /** - * Constructor. This constructor creates a FECollection from five - * finite elements. + * Constructor. This constructor creates a FECollection from five finite + * elements. */ FECollection (const FiniteElement &fe1, const FiniteElement &fe2, @@ -102,12 +102,11 @@ namespace hp const FiniteElement &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*> &fes); @@ -233,25 +232,25 @@ namespace hp /** * 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 diff --git a/include/deal.II/hp/fe_values.h b/include/deal.II/hp/fe_values.h index c8ce0bb7d0..abe54dc653 100644 --- a/include/deal.II/hp/fe_values.h +++ b/include/deal.II/hp/fe_values.h @@ -70,8 +70,8 @@ namespace internal 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 &fe_collection, const dealii::hp::QCollection &q_collection, @@ -249,8 +249,8 @@ namespace hp /** * 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 @@ -304,10 +304,9 @@ namespace hp * constructor of this class with index given by * cell-@>active_fe_index(), 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 void @@ -386,8 +385,8 @@ namespace hp /** * 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 @@ -440,10 +439,9 @@ namespace hp * constructor of this class with index given by * cell-@>active_fe_index(), 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 void @@ -505,8 +503,8 @@ namespace hp /** * 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 @@ -549,10 +547,9 @@ namespace hp * constructor of this class with index given by * cell-@>active_fe_index(), 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 void diff --git a/include/deal.II/hp/mapping_collection.h b/include/deal.II/hp/mapping_collection.h index e364cb9fd3..2c33579a84 100644 --- a/include/deal.II/hp/mapping_collection.h +++ b/include/deal.II/hp/mapping_collection.h @@ -114,18 +114,18 @@ namespace hp /** * 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 struct StaticMappingQ1 diff --git a/include/deal.II/integrators/advection.h b/include/deal.II/integrators/advection.h index 66bf38266e..e77d09f3b0 100644 --- a/include/deal.II/integrators/advection.h +++ b/include/deal.II/integrators/advection.h @@ -124,8 +124,8 @@ namespace LocalIntegrators * * \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 inline void @@ -161,15 +161,15 @@ namespace LocalIntegrators /** - * 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 inline void cell_residual ( @@ -298,8 +298,8 @@ namespace LocalIntegrators * * The velocity is provided as a VectorSlice, having dim * 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. @@ -352,9 +352,10 @@ namespace LocalIntegrators /** - * 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) @@ -362,14 +363,14 @@ namespace LocalIntegrators * @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 velocity is provided as a VectorSlice, having dim * 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. @@ -419,9 +420,10 @@ namespace LocalIntegrators /** - * 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) @@ -429,14 +431,14 @@ namespace LocalIntegrators * @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 velocity is provided as a VectorSlice, having dim * 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. @@ -503,8 +505,8 @@ namespace LocalIntegrators * * The velocity is provided as a VectorSlice, having dim * 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. @@ -568,9 +570,9 @@ namespace LocalIntegrators /** - * 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| @@ -581,8 +583,8 @@ namespace LocalIntegrators * * The velocity is provided as a VectorSlice, having dim * 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. @@ -646,9 +648,9 @@ namespace LocalIntegrators /** - * 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| @@ -659,8 +661,8 @@ namespace LocalIntegrators * * The velocity is provided as a VectorSlice, having dim * 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. diff --git a/include/deal.II/lac/block_indices.h b/include/deal.II/lac/block_indices.h index 4fd2823b76..c2e3833e23 100644 --- a/include/deal.II/lac/block_indices.h +++ b/include/deal.II/lac/block_indices.h @@ -119,9 +119,9 @@ public: 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; diff --git a/include/deal.II/lac/block_linear_operator.h b/include/deal.II/lac/block_linear_operator.h index 2c869f4f7b..db8f6dcbf0 100644 --- a/include/deal.II/lac/block_linear_operator.h +++ b/include/deal.II/lac/block_linear_operator.h @@ -106,16 +106,16 @@ block_back_substitution(const BlockLinearOperator &, * 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 std::function 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 + * std::function objects are no longer available) - the linear + * operator interface, however, remains intact. * - * @note This class makes heavy use of std::function 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 std::function 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 DEAL_II_WITH_CXX11 is enabled during cmake @@ -135,9 +135,9 @@ public: /** * Create an empty BlockLinearOperator object. * - * Allstd::function member objects of this class and its - * base class LinearOperator are initialized with default variants that - * throw an exception upon invocation. + * Allstd::function member objects of this class and its base + * class LinearOperator are initialized with default variants that throw an + * exception upon invocation. */ BlockLinearOperator() : LinearOperator() @@ -169,8 +169,8 @@ public: 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 * block_operator is defined. */ template @@ -181,8 +181,8 @@ public: /** * 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 BlockLinearOperator(const std::array, m> &ops) @@ -191,9 +191,9 @@ public: } /** - * 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 BlockLinearOperator(const std::array &ops) @@ -233,9 +233,8 @@ public: /** * 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 BlockLinearOperator & @@ -246,23 +245,21 @@ public: } /** - * 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 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 n_block_cols; /** * Access the block with the given coordinates. This - * std::function object returns a LinearOperator - * representing the $(i,j)$-th block of the BlockLinearOperator. + * std::function object returns a LinearOperator representing + * the $(i,j)$-th block of the BlockLinearOperator. */ std::function block; }; @@ -375,8 +372,7 @@ namespace internal /** * @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 @@ -425,13 +421,13 @@ block_operator(const BlockMatrixType &block_matrix) /** * @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) @@ -493,9 +489,9 @@ block_operator(const std::arrayx0 = A00^-1 y0. Then, we can use x0 to recover x1: + * First of all, x0 = A00^-1 y0. Then, we can use x0 to recover + * x1: * @code * x1 = A11^-1 ( y1 - A01 x0 ) * @endcode @@ -653,8 +650,8 @@ block_diagonal_operator(const LinearOperator &block_opera * @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: * @@ -754,7 +751,8 @@ block_forward_substitution(const BlockLinearOperator &block_opera * Ann xn = yn * @endcode * - * First of all, xn = Ann^-1 yn. Then, we can use xn to recover x(n-1): + * First of all, xn = Ann^-1 yn. 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 @@ -764,9 +762,8 @@ block_forward_substitution(const BlockLinearOperator &block_opera * @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 */ diff --git a/include/deal.II/lac/block_matrix_array.h b/include/deal.II/lac/block_matrix_array.h index c36397ff2e..c61b6f338a 100644 --- a/include/deal.II/lac/block_matrix_array.h +++ b/include/deal.II/lac/block_matrix_array.h @@ -84,14 +84,14 @@ DEAL_II_NAMESPACE_OPEN * * Now, we are ready to build a 2x2 BlockMatrixArray. * @line Block - * First, we enter the matrix A multiplied by 2 in the - * upper left block + * First, we enter the matrix A multiplied by 2 in the upper left + * block * @line enter * Now -1 times B1 in the upper right block. * @line enter - * We add the transpose of B2 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 B2 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 diff --git a/include/deal.II/lac/block_matrix_base.h b/include/deal.II/lac/block_matrix_base.h index 7f88abd969..60ea3c462b 100644 --- a/include/deal.II/lac/block_matrix_base.h +++ b/include/deal.II/lac/block_matrix_base.h @@ -382,10 +382,10 @@ public: * Copying matrices is an expensive operation that we do not want to happen * by accident through compiler generated code for operator=. * (This would happen, for example, if one accidentally declared a function - * argument of the current type by value rather than by reference.) - * 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 by value rather than by + * reference.) 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. diff --git a/include/deal.II/lac/chunk_sparse_matrix.h b/include/deal.II/lac/chunk_sparse_matrix.h index 280de3f2cd..32124b6ca8 100644 --- a/include/deal.II/lac/chunk_sparse_matrix.h +++ b/include/deal.II/lac/chunk_sparse_matrix.h @@ -692,10 +692,10 @@ public: * Copying matrices is an expensive operation that we do not want to happen * by accident through compiler generated code for operator=. * (This would happen, for example, if one accidentally declared a function - * argument of the current type by value rather than by reference.) - * 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 by value rather than by + * reference.) 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. diff --git a/include/deal.II/lac/constrained_linear_operator.h b/include/deal.II/lac/constrained_linear_operator.h index 57c05f92c1..729a65e9fc 100644 --- a/include/deal.II/lac/constrained_linear_operator.h +++ b/include/deal.II/lac/constrained_linear_operator.h @@ -32,30 +32,30 @@ DEAL_II_NAMESPACE_OPEN /** - * 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 vmult - * 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 vmult 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 u results in - * a vector v that stores the result of calling + * Applying the LinearOperator object on a vector u results in a + * vector v that stores the result of calling * ConstraintMatrix::distribute() on u - 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 @@ -132,11 +132,10 @@ LinearOperator distribute_constraints_linear_operator( /** - * 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 * @@ -192,9 +191,9 @@ LinearOperator project_to_constrained_linear_operator( /** - * 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 @@ -204,12 +203,12 @@ LinearOperator project_to_constrained_linear_operator( * Ct = transpose_operator(C); * Id_c = project_to_constrained_linear_operator(constraint_matrix, linop); * @endcode - * and Id_c is the projection to the subspace consisting of - * all vector entries associated with constrained degrees of freedoms. + * and Id_c 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] @@ -223,7 +222,7 @@ LinearOperator project_to_constrained_linear_operator( * @author Mauro Bardelloni, Matthias Maier, 2015 * * @note Currently, this function may not work correctly for distributed data - * structures. + * structures. * * @relates LinearOperator * @ingroup constraints @@ -243,9 +242,9 @@ constrained_linear_operator(const ConstraintMatrix &constraint_matrix, /** - * 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 @@ -256,8 +255,8 @@ constrained_linear_operator(const ConstraintMatrix &constraint_matrix, * @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] @@ -271,7 +270,7 @@ constrained_linear_operator(const ConstraintMatrix &constraint_matrix, * @author Mauro Bardelloni, Matthias Maier, 2015 * * @note Currently, this function may not work correctly for distributed data - * structures. + * structures. * * @relates LinearOperator * @ingroup constraints diff --git a/include/deal.II/lac/constraint_matrix.h b/include/deal.II/lac/constraint_matrix.h index ffb964b38c..e413a6b033 100644 --- a/include/deal.II/lac/constraint_matrix.h +++ b/include/deal.II/lac/constraint_matrix.h @@ -175,18 +175,18 @@ public: /** * 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 all possible indices will be created, - * leading to memory consumption on every processor that is proportional to - * the overall 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 all possible indices will be created, leading to + * memory consumption on every processor that is proportional to the + * overall 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()); @@ -330,8 +330,8 @@ public: /** * 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. @@ -680,9 +680,9 @@ public: * * @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 void @@ -1010,8 +1010,8 @@ public: * 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. diff --git a/include/deal.II/lac/full_matrix.h b/include/deal.II/lac/full_matrix.h index 9840caa34b..9cadd62a46 100644 --- a/include/deal.II/lac/full_matrix.h +++ b/include/deal.II/lac/full_matrix.h @@ -312,16 +312,16 @@ public: /** * 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 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 void copy_transposed (const MatrixType &); diff --git a/include/deal.II/lac/la_vector.h b/include/deal.II/lac/la_vector.h index 38368ecfcc..cfb00525fb 100644 --- a/include/deal.II/lac/la_vector.h +++ b/include/deal.II/lac/la_vector.h @@ -43,9 +43,9 @@ namespace LinearAlgebra /** * 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. */ @@ -143,7 +143,8 @@ namespace LinearAlgebra virtual void add(const Number a, const VectorSpaceVector &V); /** - * Multiple addition of a multiple of a vector, i.e. *this += a*V+b*W. + * Multiple addition of a multiple of a vector, i.e. *this += + * a*V+b*W. */ virtual void add(const Number a, const VectorSpaceVector &V, const Number b, const VectorSpaceVector &W); @@ -180,8 +181,8 @@ namespace LinearAlgebra virtual typename VectorSpaceVector::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::real_type linfty_norm(); @@ -199,17 +200,18 @@ namespace LinearAlgebra const VectorSpaceVector &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 @@ -224,9 +226,9 @@ namespace LinearAlgebra 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; @@ -237,9 +239,9 @@ namespace LinearAlgebra * * 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); @@ -257,24 +259,26 @@ namespace LinearAlgebra 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::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::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 void serialize(Archive &ar, const unsigned int version); diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index b6c64fcaea..66cd6c39de 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -99,11 +99,10 @@ null_operator(const LinearOperator &); * const auto op = (op_a + k * op_b) * op_c; * @endcode * - * @note This class makes heavy use of std::function 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 std::function 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 DEAL_II_WITH_CXX11 is enabled during cmake @@ -170,8 +169,8 @@ public: LinearOperator (const LinearOperator &) = 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 * linear_operator is defined. */ template &first_op, /** * @relates LinearOperator * - * Returns the transpose linear operations of - * @p op. + * Returns the transpose linear operations of @p op. * * @ingroup LAOperators */ @@ -692,9 +690,8 @@ inverse_operator(const LinearOperatorstd::function object - * @p reinit_vector - * as an argument to initialize the reinit_range_vector and + * The function takes an std::function object @p reinit_vector as + * an argument to initialize the reinit_range_vector and * reinit_domain_vector objects of the LinearOperator object. * * @ingroup LAOperators diff --git a/include/deal.II/lac/matrix_block.h b/include/deal.II/lac/matrix_block.h index 665d8a7881..8cec4e6dea 100644 --- a/include/deal.II/lac/matrix_block.h +++ b/include/deal.II/lac/matrix_block.h @@ -194,8 +194,8 @@ public: /** * Set several elements in the specified row of the matrix with column * indices as given by col_indices to the respective value. This is - * the function doing the actual work for the ones adding full matrices. - * The global locations row_index and col_indices are + * the function doing the actual work for the ones adding full matrices. The + * global locations row_index and col_indices 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. @@ -231,33 +231,33 @@ public: 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 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 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 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 void Tvmult_add (VectorType &w, const VectorType &v) const; diff --git a/include/deal.II/lac/packaged_operation.h b/include/deal.II/lac/packaged_operation.h index 140389121a..6750437a17 100644 --- a/include/deal.II/lac/packaged_operation.h +++ b/include/deal.II/lac/packaged_operation.h @@ -229,8 +229,8 @@ public: } /** - * 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 &operator-=(const Range &offset) { diff --git a/include/deal.II/lac/parallel_block_vector.h b/include/deal.II/lac/parallel_block_vector.h index 2e8ea3ed8c..2d5928786c 100644 --- a/include/deal.II/lac/parallel_block_vector.h +++ b/include/deal.II/lac/parallel_block_vector.h @@ -211,7 +211,8 @@ namespace parallel * and call collect_sizes() to update the block system's knowledge of * its individual block's sizes. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const size_type num_blocks, const size_type block_size = 0, @@ -226,7 +227,8 @@ namespace parallel * called, all vectors remain the same and reinit() is called for each * vector. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, 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 diff --git a/include/deal.II/lac/parallel_vector.h b/include/deal.II/lac/parallel_vector.h index 1ffb35a167..099d02f51c 100644 --- a/include/deal.II/lac/parallel_vector.h +++ b/include/deal.II/lac/parallel_vector.h @@ -150,8 +150,7 @@ namespace parallel * 2^64-1 or approximately 10^19 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 @@ -270,9 +269,10 @@ namespace parallel * 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 void reinit(const Vector &in_vector, @@ -998,11 +998,10 @@ namespace parallel * 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; diff --git a/include/deal.II/lac/parpack_solver.h b/include/deal.II/lac/parpack_solver.h index 3e1e0e08f3..935fe0e383 100644 --- a/include/deal.II/lac/parpack_solver.h +++ b/include/deal.II/lac/parpack_solver.h @@ -70,20 +70,19 @@ extern "C" { /** * Interface for using PARPACK. PARPACK is a collection of Fortran77 - * subroutines designed to solve large scale eigenvalue problems. - * Here we interface to the routines pdneupd, - * pdseupd, pdnaupd, pdsaupd 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 pdneupd, pdseupd, + * pdnaupd, pdsaupd 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; @@ -104,26 +103,26 @@ extern "C" { * x, * size_of_spectrum); * @endcode - * for the generalized eigenvalue problem $Ax=B\lambda x$, where the - * variable size_of_spectrum tells PARPACK the number of - * eigenvector/eigenvalue pairs to solve for. Here, - * lambda is a vector that will contain the eigenvalues - * computed, x a vector of objects of type V - * that will contain the eigenvectors computed. OP is an - * inverse operation for the matrix A - sigma * B, where - * sigma is a shift value, set to zero by default. + * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable + * size_of_spectrum tells PARPACK the number of + * eigenvector/eigenvalue pairs to solve for. Here, lambda is a + * vector that will contain the eigenvalues computed, x a vector + * of objects of type V that will contain the eigenvectors + * computed. OP is an inverse operation for the matrix A - + * sigma * B, where sigma 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 A 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 + * A are supported. * - * For further information on how the PARPACK routines - * pdneupd, pdseupd, pdnaupd, - * pdsaupd 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 pdneupd, + * pdseupd, pdnaupd, pdsaupd work and + * also how to set the parameters appropriately please take a look into the + * PARPACK manual. * * @author Denis Davydov, 2015. */ @@ -137,11 +136,11 @@ public: 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 A considered. + * A particular choice is limited based on symmetric or non-symmetric matrix + * A considered. */ enum WhichEigenvalues { @@ -203,8 +202,8 @@ public: }; /** - * 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 { @@ -240,9 +239,9 @@ public: void set_shift(const double s ); /** - * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by - * calling the pd(n/s)eupd and pd(n/s)aupd - * functions of PARPACK. + * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by calling + * the pd(n/s)eupd and pd(n/s)aupd functions of + * PARPACK. */ template @@ -259,8 +258,8 @@ public: 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; @@ -315,14 +314,14 @@ protected: 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 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 resid; @@ -332,9 +331,9 @@ protected: 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 z; diff --git a/include/deal.II/lac/petsc_block_vector.h b/include/deal.II/lac/petsc_block_vector.h index 923538336a..9dc85b424c 100644 --- a/include/deal.II/lac/petsc_block_vector.h +++ b/include/deal.II/lac/petsc_block_vector.h @@ -158,7 +158,8 @@ namespace PETScWrappers * Reinitialize the BlockVector to contain num_blocks blocks of * size block_size each. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const unsigned int num_blocks, const size_type block_size, @@ -172,7 +173,8 @@ namespace PETScWrappers * 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 omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, 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 diff --git a/include/deal.II/lac/petsc_matrix_base.h b/include/deal.II/lac/petsc_matrix_base.h index 6b76cb158d..51bcad37d0 100644 --- a/include/deal.II/lac/petsc_matrix_base.h +++ b/include/deal.II/lac/petsc_matrix_base.h @@ -851,10 +851,11 @@ namespace PETScWrappers is_hermitian (const double tolerance = 1.e-12); /** - * Print the PETSc matrix object values using PETSc internal matrix - * viewer function MatView. 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 MatView. 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); @@ -862,8 +863,8 @@ namespace PETScWrappers * 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; diff --git a/include/deal.II/lac/petsc_parallel_block_vector.h b/include/deal.II/lac/petsc_parallel_block_vector.h index 7dc02a5679..ac8fa4e1b4 100644 --- a/include/deal.II/lac/petsc_parallel_block_vector.h +++ b/include/deal.II/lac/petsc_parallel_block_vector.h @@ -174,7 +174,8 @@ namespace PETScWrappers * @p communicator argument denotes which MPI channel each of these * blocks shall communicate. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const unsigned int n_blocks, const MPI_Comm &communicator, @@ -192,7 +193,8 @@ namespace PETScWrappers * called, all vectors remain the same and reinit() is called for each * vector. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, 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 diff --git a/include/deal.II/lac/petsc_parallel_vector.h b/include/deal.II/lac/petsc_parallel_vector.h index d6df272919..6b668464ec 100644 --- a/include/deal.II/lac/petsc_parallel_vector.h +++ b/include/deal.II/lac/petsc_parallel_vector.h @@ -79,9 +79,9 @@ namespace PETScWrappers * 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. * @@ -324,8 +324,8 @@ namespace PETScWrappers * @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, @@ -338,7 +338,8 @@ namespace PETScWrappers * 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 reinit(v.size(), v.local_size(), omit_zeroing_entries). + * as calling reinit(v.size(), v.local_size(), + * omit_zeroing_entries). */ void reinit (const Vector &v, const bool omit_zeroing_entries = false); diff --git a/include/deal.II/lac/petsc_precondition.h b/include/deal.II/lac/petsc_precondition.h index b9d882a384..957f539957 100644 --- a/include/deal.II/lac/petsc_precondition.h +++ b/include/deal.II/lac/petsc_precondition.h @@ -168,9 +168,9 @@ namespace PETScWrappers 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(); }; @@ -242,9 +242,9 @@ namespace PETScWrappers 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(); @@ -678,8 +678,8 @@ namespace PETScWrappers /** * 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; @@ -754,9 +754,9 @@ namespace PETScWrappers 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(); diff --git a/include/deal.II/lac/petsc_solver.h b/include/deal.II/lac/petsc_solver.h index b8ef85797d..61adf24b45 100644 --- a/include/deal.II/lac/petsc_solver.h +++ b/include/deal.II/lac/petsc_solver.h @@ -157,8 +157,8 @@ namespace PETScWrappers 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); @@ -251,7 +251,8 @@ namespace PETScWrappers #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 diff --git a/include/deal.II/lac/petsc_sparse_matrix.h b/include/deal.II/lac/petsc_sparse_matrix.h index fd82fb7a29..655379cf6c 100644 --- a/include/deal.II/lac/petsc_sparse_matrix.h +++ b/include/deal.II/lac/petsc_sparse_matrix.h @@ -182,10 +182,10 @@ namespace PETScWrappers * 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 void reinit (const SparsityPatternType &sparsity_pattern, diff --git a/include/deal.II/lac/petsc_vector.h b/include/deal.II/lac/petsc_vector.h index 4d30460ea5..f1fb5f5de8 100644 --- a/include/deal.II/lac/petsc_vector.h +++ b/include/deal.II/lac/petsc_vector.h @@ -167,8 +167,8 @@ namespace PETScWrappers * 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); diff --git a/include/deal.II/lac/precondition.h b/include/deal.II/lac/precondition.h index 500ce4d961..5cf413b32d 100644 --- a/include/deal.II/lac/precondition.h +++ b/include/deal.II/lac/precondition.h @@ -206,8 +206,8 @@ public: }; /** - * 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(); @@ -445,9 +445,10 @@ protected: /** - * Jacobi preconditioner using matrix built-in function. The MatrixType - * class used is required to have a function precondition_Jacobi(VectorType&, - * const VectorType&, double). This class satisfies the + * Jacobi preconditioner using matrix built-in function. The + * MatrixType class used is required to have a function + * precondition_Jacobi(VectorType&, const VectorType&, double). This + * class satisfies the * @ref ConceptRelaxationType "relaxation concept". * * @code @@ -579,9 +580,10 @@ public: /** - * SSOR preconditioner using matrix built-in function. The MatrixType - * class used is required to have a function precondition_SSOR(VectorType&, - * const VectorType&, double). This class satisfies the + * SSOR preconditioner using matrix built-in function. The + * MatrixType class used is required to have a function + * precondition_SSOR(VectorType&, const VectorType&, double). This + * class satisfies the * @ref ConceptRelaxationType "relaxation concept". * * @code @@ -664,9 +666,9 @@ private: /** * Permuted SOR preconditioner using matrix built-in function. The - * MatrixType class used is required to have functions PSOR(VectorType&, - * const VectorType&, double) and TPSOR(VectorType&, const VectorType&, - * double). + * MatrixType class used is required to have functions + * PSOR(VectorType&, const VectorType&, double) and + * TPSOR(VectorType&, const VectorType&, double). * * @code * // Declare related objects @@ -704,8 +706,8 @@ public: typedef typename MatrixType::size_type size_type; /** - * Parameters for PreconditionPSOR. - */ + * Parameters for PreconditionPSOR. + */ class AdditionalData { public: @@ -797,9 +799,8 @@ private: * 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 vmult - * implementation. However, it does not need to explicitly know the matrix - * entries. + * the matrix it acts on and needs a respective vmult 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). diff --git a/include/deal.II/lac/precondition_block.h b/include/deal.II/lac/precondition_block.h index f4fb158311..fcaab69bf2 100644 --- a/include/deal.II/lac/precondition_block.h +++ b/include/deal.II/lac/precondition_block.h @@ -172,8 +172,8 @@ public: 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. diff --git a/include/deal.II/lac/read_write_vector.h b/include/deal.II/lac/read_write_vector.h index 8eacdada28..207ccb289c 100644 --- a/include/deal.II/lac/read_write_vector.h +++ b/include/deal.II/lac/read_write_vector.h @@ -63,9 +63,9 @@ namespace LinearAlgebra * 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. @@ -73,24 +73,23 @@ namespace LinearAlgebra * from VectorSpaceVector such as TrilinosWrappers::MPI::Vector and * PETScWrappers::MPI::Vector. * - *

      Storing elements

      - * 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 global index into a local one. In such cases, it is clear - * that one can only access elements of the vector that the current object - * indeed stores. + *

      Storing elements

      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 global index into a + * local 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 global 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 in which order 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 global 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 in which order 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. */ @@ -128,8 +127,8 @@ namespace LinearAlgebra ReadWriteVector (const ReadWriteVector &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); @@ -148,9 +147,9 @@ namespace LinearAlgebra * 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); @@ -159,21 +158,21 @@ namespace LinearAlgebra * 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 void reinit(const ReadWriteVector &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, @@ -186,10 +185,10 @@ namespace LinearAlgebra * 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 - * swap(u,v) that simply calls u.swap(v), 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 swap(u,v) that + * simply calls u.swap(v), again in analogy to standard + * functions. */ void swap (ReadWriteVector &v); @@ -208,8 +207,8 @@ namespace LinearAlgebra #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 & operator= (const PETScWrappers::MPI::Vector &petsc_vec); @@ -217,8 +216,8 @@ namespace LinearAlgebra #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 & operator= (const TrilinosWrappers::MPI::Vector &trilinos_vec); @@ -231,12 +230,12 @@ namespace LinearAlgebra ReadWriteVector &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; @@ -253,9 +252,9 @@ namespace LinearAlgebra const IndexSet &get_stored_elements () const; /** - * Make the @p ReadWriteVector class a bit like the vector<> class of - * the C++ standard library by returning iterators to the start and end - * of the locally stored elements of this vector. + * Make the @p ReadWriteVector class a bit like the vector<> + * class of the C++ standard library by returning iterators to the start + * and end of the locally stored elements of this vector. */ iterator begin (); @@ -272,8 +271,8 @@ namespace LinearAlgebra 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; //@} @@ -286,22 +285,22 @@ namespace LinearAlgebra /** * 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(). */ @@ -309,8 +308,8 @@ namespace LinearAlgebra /** * 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(). */ @@ -319,8 +318,8 @@ namespace LinearAlgebra /** * 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 void extract_subvector_to (const std::vector &indices, @@ -348,12 +347,12 @@ namespace LinearAlgebra 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). */ @@ -367,16 +366,16 @@ namespace LinearAlgebra //@{ /** - * 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 void add (const std::vector &indices, const std::vector &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 void add (const std::vector &indices, diff --git a/include/deal.II/lac/relaxation_block.h b/include/deal.II/lac/relaxation_block.h index 3b054611f4..ffeb83c3ec 100644 --- a/include/deal.II/lac/relaxation_block.h +++ b/include/deal.II/lac/relaxation_block.h @@ -236,11 +236,11 @@ protected: * * 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 @@ -321,12 +321,11 @@ public: * * 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 @@ -402,12 +401,11 @@ public: * * 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 diff --git a/include/deal.II/lac/schur_complement.h b/include/deal.II/lac/schur_complement.h index 9ee77775bb..fcdb7c04ef 100644 --- a/include/deal.II/lac/schur_complement.h +++ b/include/deal.II/lac/schur_complement.h @@ -34,16 +34,16 @@ DEAL_II_NAMESPACE_OPEN /** * @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 @@ -58,9 +58,9 @@ DEAL_II_NAMESPACE_OPEN * 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*}{ @@ -68,17 +68,17 @@ DEAL_II_NAMESPACE_OPEN * (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 . @@ -88,36 +88,30 @@ DEAL_II_NAMESPACE_OPEN * (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] @@ -126,7 +120,7 @@ DEAL_II_NAMESPACE_OPEN * 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] @@ -167,22 +161,20 @@ DEAL_II_NAMESPACE_OPEN * * 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); @@ -199,34 +191,31 @@ DEAL_II_NAMESPACE_OPEN * 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 - * tests/lac/schur_complement_01.cc . - * The solution of a multi-component problem (namely step-22) using the - * schur_complement can be found in - * tests/lac/schur_complement_03.cc . + * Further examples of this functionality can be found in the test-suite, such + * as tests/lac/schur_complement_01.cc . The solution of a multi- + * component problem (namely step-22) using the schur_complement can be found + * in tests/lac/schur_complement_03.cc . * * @see * @ref GlossBlockLA "Block (linear algebra)" @@ -354,17 +343,16 @@ schur_complement(const LinearOperator &A_inv, * * 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)" @@ -437,15 +425,15 @@ condense_schur_rhs (const LinearOperator &A_inv, * * 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)" diff --git a/include/deal.II/lac/slepc_solver.h b/include/deal.II/lac/slepc_solver.h index 301a44ff07..1120c9fe8e 100644 --- a/include/deal.II/lac/slepc_solver.h +++ b/include/deal.II/lac/slepc_solver.h @@ -34,9 +34,9 @@ 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 @@ -71,8 +71,8 @@ DEAL_II_NAMESPACE_OPEN * * 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; @@ -88,12 +88,12 @@ DEAL_II_NAMESPACE_OPEN * 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 @@ -159,8 +159,9 @@ namespace SLEPcWrappers * specific vector class used (i.e. local_dofs for MPI vectors). However, * while copying eigenvectors, at least twice the memory size of * eigenvectors 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 @@ -214,7 +215,8 @@ namespace SLEPcWrappers /** * 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 void @@ -483,7 +485,8 @@ namespace SLEPcWrappers 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); }; @@ -558,8 +561,8 @@ namespace SLEPcWrappers struct AdditionalData { /** - * Use double expansion in search subspace. - */ + * Use double expansion in search subspace. + */ bool double_expansion; /** diff --git a/include/deal.II/lac/slepc_spectral_transformation.h b/include/deal.II/lac/slepc_spectral_transformation.h index 2f2479114f..530fe029e8 100644 --- a/include/deal.II/lac/slepc_spectral_transformation.h +++ b/include/deal.II/lac/slepc_spectral_transformation.h @@ -92,8 +92,8 @@ namespace SLEPcWrappers 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); diff --git a/include/deal.II/lac/solver_cg.h b/include/deal.II/lac/solver_cg.h index 611aee9a38..2cfaeb07a8 100644 --- a/include/deal.II/lac/solver_cg.h +++ b/include/deal.II/lac/solver_cg.h @@ -76,11 +76,11 @@ class PreconditionIdentity; * @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 @@ -185,29 +185,28 @@ public: /** * 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 &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 &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( @@ -232,8 +231,8 @@ protected: 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. @@ -269,32 +268,31 @@ protected: 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 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 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 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 &)> 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 &)> all_eigenvalues_signal; diff --git a/include/deal.II/lac/solver_gmres.h b/include/deal.II/lac/solver_gmres.h index d3b14946f6..c3e031f821 100644 --- a/include/deal.II/lac/solver_gmres.h +++ b/include/deal.II/lac/solver_gmres.h @@ -57,7 +57,8 @@ namespace internal { 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 &vmem); @@ -157,13 +158,13 @@ namespace internal * *

      Eigenvalue and condition number estimates

      * - * 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. * * @@ -267,20 +268,20 @@ public: 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 &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( @@ -302,26 +303,26 @@ protected: 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 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 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 > &)> 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 > &)> all_eigenvalues_signal; @@ -357,12 +358,12 @@ protected: 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 &H_orig , diff --git a/include/deal.II/lac/sparse_decomposition.h b/include/deal.II/lac/sparse_decomposition.h index cfda8fd8a7..2d89ddadac 100644 --- a/include/deal.II/lac/sparse_decomposition.h +++ b/include/deal.II/lac/sparse_decomposition.h @@ -220,15 +220,15 @@ public: /** * 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; diff --git a/include/deal.II/lac/sparse_direct.h b/include/deal.II/lac/sparse_direct.h index 79bbaa8d53..89b703ee1f 100644 --- a/include/deal.II/lac/sparse_direct.h +++ b/include/deal.II/lac/sparse_direct.h @@ -74,8 +74,8 @@ DEAL_II_NAMESPACE_OPEN * * @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 { diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h index 287ba350c8..1cde275e27 100644 --- a/include/deal.II/lac/sparse_matrix.h +++ b/include/deal.II/lac/sparse_matrix.h @@ -431,24 +431,22 @@ namespace SparseMatrixIterators //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 @ and * @; others can be generated in application programs (see the @@ -874,10 +872,10 @@ public: * Copying matrices is an expensive operation that we do not want to happen * by accident through compiler generated code for operator=. * (This would happen, for example, if one accidentally declared a function - * argument of the current type by value rather than by reference.) - * 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 by value rather than by + * reference.) 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. diff --git a/include/deal.II/lac/sparse_matrix_ez.h b/include/deal.II/lac/sparse_matrix_ez.h index 5d86c0183b..c78c25ef50 100644 --- a/include/deal.II/lac/sparse_matrix_ez.h +++ b/include/deal.II/lac/sparse_matrix_ez.h @@ -438,11 +438,11 @@ public: * away and only non-zero data is added. The default value is true, * 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); @@ -524,10 +524,10 @@ public: * Copying matrices is an expensive operation that we do not want to happen * by accident through compiler generated code for operator=. * (This would happen, for example, if one accidentally declared a function - * argument of the current type by value rather than by reference.) - * 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 by value rather than by + * reference.) 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. diff --git a/include/deal.II/lac/sparse_vanka.h b/include/deal.II/lac/sparse_vanka.h index 6930275cb5..f20a1bb27c 100644 --- a/include/deal.II/lac/sparse_vanka.h +++ b/include/deal.II/lac/sparse_vanka.h @@ -53,10 +53,10 @@ template class SparseBlockVanka; * 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, @@ -180,8 +180,8 @@ public: ~SparseVanka(); /** - * Parameters for SparseVanka. - */ + * Parameters for SparseVanka. + */ class AdditionalData { public: @@ -203,8 +203,8 @@ 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; }; @@ -232,8 +232,8 @@ public: const Vector &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 void Tvmult (Vector &dst, diff --git a/include/deal.II/lac/sparsity_pattern.h b/include/deal.II/lac/sparsity_pattern.h index 57246055f7..3403d7652d 100644 --- a/include/deal.II/lac/sparsity_pattern.h +++ b/include/deal.II/lac/sparsity_pattern.h @@ -295,15 +295,15 @@ namespace SparsityPatternIterators /** - * A class that can store which elements of a matrix are nonzero (or, - * in fact, may 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, + * may 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 - * compressed - * row storage (CSR) format to store data, and is used as the - * basis for the SparseMatrix class. + * It uses the compressed row storage + * (CSR) 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. @@ -418,8 +418,8 @@ public: * * @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, @@ -440,8 +440,8 @@ public: * Initialize a quadratic pattern of size m x m. * * @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 &row_lengths); @@ -935,10 +935,11 @@ public: 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; diff --git a/include/deal.II/lac/sparsity_tools.h b/include/deal.II/lac/sparsity_tools.h index 042c1f8f51..e5a820499c 100644 --- a/include/deal.II/lac/sparsity_tools.h +++ b/include/deal.II/lac/sparsity_tools.h @@ -206,7 +206,6 @@ namespace SparsityTools * 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. * diff --git a/include/deal.II/lac/trilinos_block_vector.h b/include/deal.II/lac/trilinos_block_vector.h index 388ecb7a26..2792388a3c 100644 --- a/include/deal.II/lac/trilinos_block_vector.h +++ b/include/deal.II/lac/trilinos_block_vector.h @@ -198,7 +198,8 @@ namespace TrilinosWrappers * on the same Epetra_map is intended. In that case, the same communicator * is used for data exchange. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const std::vector &partitioning, const bool omit_zeroing_entries = false); @@ -211,7 +212,8 @@ namespace TrilinosWrappers * with a distributed vector based on the same initialization is intended. * In that case, the same communicator is used for data exchange. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const std::vector &partitioning, const MPI_Comm &communicator = MPI_COMM_WORLD, @@ -222,7 +224,8 @@ namespace TrilinosWrappers * elements in the first argument, and with the respective sizes. Since no * distribution map is given, all vectors are local vectors. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const std::vector &N, const bool omit_zeroing_entries=false); diff --git a/include/deal.II/lac/trilinos_parallel_block_vector.h b/include/deal.II/lac/trilinos_parallel_block_vector.h index 8a8e362dac..9213f88cce 100644 --- a/include/deal.II/lac/trilinos_parallel_block_vector.h +++ b/include/deal.II/lac/trilinos_parallel_block_vector.h @@ -201,7 +201,8 @@ namespace TrilinosWrappers * Epetra_Maps given in the input argument, according to the parallel * distribution of the individual components described in the maps. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. * * This function is deprecated. */ @@ -213,7 +214,8 @@ namespace TrilinosWrappers * index sets given in the input argument, according to the parallel * distribution of the individual components described in the maps. * - * If omit_zeroing_entries==false, the vector is filled with zeros. + * If omit_zeroing_entries==false, the vector is filled with + * zeros. */ void reinit (const std::vector ¶llel_partitioning, const MPI_Comm &communicator = MPI_COMM_WORLD, diff --git a/include/deal.II/lac/trilinos_precondition.h b/include/deal.II/lac/trilinos_precondition.h index 5c3b9aa462..303d95ac29 100644 --- a/include/deal.II/lac/trilinos_precondition.h +++ b/include/deal.II/lac/trilinos_precondition.h @@ -153,10 +153,11 @@ namespace TrilinosWrappers const dealii::parallel::distributed::Vector &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; @@ -1374,15 +1375,16 @@ namespace TrilinosWrappers * 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 n_component, the - * provided @p constant_modes should fulfill the following requirements: + * a vector-valued equation. For vector-valued equation problem with + * n_component, the provided @p constant_modes should fulfill + * the following requirements: *
        *
      • n_component.size() == n_component
        • - *
      • n_component[*].size() == n_dof_local or - * n_component[*].size() == n_dof_global
        • - *
      • n_component[ic][id] == "idth - * DoF is corresponding to component ic
        • + *
      • n_component[*].size() == n_dof_local or n_component[*].size() + * == n_dof_global
        • + *
      • n_component[ic][id] == + * "idth DoF is corresponding to component ic + *
        • *
      */ std::vector > constant_modes; diff --git a/include/deal.II/lac/trilinos_sparse_matrix.h b/include/deal.II/lac/trilinos_sparse_matrix.h index d0548660a6..279039cd13 100644 --- a/include/deal.II/lac/trilinos_sparse_matrix.h +++ b/include/deal.II/lac/trilinos_sparse_matrix.h @@ -1119,14 +1119,14 @@ namespace TrilinosWrappers * * 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, @@ -1155,14 +1155,14 @@ namespace TrilinosWrappers * * 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 &indices, const FullMatrix &full_matrix, @@ -1196,14 +1196,14 @@ namespace TrilinosWrappers * * 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 &col_indices, @@ -1228,14 +1228,14 @@ namespace TrilinosWrappers * * 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, diff --git a/include/deal.II/lac/trilinos_vector.h b/include/deal.II/lac/trilinos_vector.h index 1229439623..990311d958 100644 --- a/include/deal.II/lac/trilinos_vector.h +++ b/include/deal.II/lac/trilinos_vector.h @@ -305,10 +305,10 @@ namespace TrilinosWrappers /** * 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 v. If omit_zeroing_entries is not - * true, 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 v. If omit_zeroing_entries + * is not true, 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, allow_different_maps, * that allows for an exchange of data between two equal-sized vectors @@ -316,10 +316,10 @@ namespace TrilinosWrappers * 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 v - * is a distributed vector. In this case, the variable omit_zeroing_entries - * needs to be set to false, 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 + * omit_zeroing_entries needs to be set to false, + * 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, @@ -566,8 +566,8 @@ namespace TrilinosWrappers /** * Reinit functionality. This function destroys the old vector content * and generates a new one based on the input partitioning. The flag - * omit_zeroing_entries determines whether the vector should be filled with - * zero (false) or left untouched (true). + * omit_zeroing_entries determines whether the vector should be + * filled with zero (false) or left untouched (true). * * * Depending on whether the @p parallel_partitioning argument uniquely @@ -807,8 +807,8 @@ namespace TrilinosWrappers * 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 - * omit_zeroing_entries determines whether the vector should be filled with zero - * or left untouched. + * omit_zeroing_entries 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 @@ -823,8 +823,8 @@ namespace TrilinosWrappers * 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 - * omit_zeroing_entries determines whether the vector should be filled with zero - * (false) or left untouched (true). + * omit_zeroing_entries 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 diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h index 2000f97250..3754326450 100644 --- a/include/deal.II/lac/vector.h +++ b/include/deal.II/lac/vector.h @@ -287,8 +287,8 @@ public: * reinit(N). 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. diff --git a/include/deal.II/lac/vector_space_vector.h b/include/deal.II/lac/vector_space_vector.h index 286d12f8cc..ff306146d8 100644 --- a/include/deal.II/lac/vector_space_vector.h +++ b/include/deal.II/lac/vector_space_vector.h @@ -36,10 +36,11 @@ namespace LinearAlgebra */ /** - * 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. */ @@ -140,11 +141,11 @@ namespace LinearAlgebra * @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 &V, @@ -158,10 +159,11 @@ namespace LinearAlgebra /** * 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 diff --git a/include/deal.II/lac/vector_view.h b/include/deal.II/lac/vector_view.h index 37c46f474b..1d3dcc9536 100644 --- a/include/deal.II/lac/vector_view.h +++ b/include/deal.II/lac/vector_view.h @@ -171,10 +171,9 @@ public: * 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: diff --git a/include/deal.II/matrix_free/fe_evaluation.h b/include/deal.II/matrix_free/fe_evaluation.h index 3b47afa1e4..f12d835705 100644 --- a/include/deal.II/matrix_free/fe_evaluation.h +++ b/include/deal.II/matrix_free/fe_evaluation.h @@ -1583,9 +1583,8 @@ public: /** * 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 &fe, const Quadrature<1> &quadrature, diff --git a/include/deal.II/matrix_free/mapping_data_on_the_fly.h b/include/deal.II/matrix_free/mapping_data_on_the_fly.h index 9ec2a74a2d..ed22268555 100644 --- a/include/deal.II/matrix_free/mapping_data_on_the_fly.h +++ b/include/deal.II/matrix_free/mapping_data_on_the_fly.h @@ -70,8 +70,8 @@ namespace internal /** * 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); diff --git a/include/deal.II/matrix_free/matrix_free.h b/include/deal.II/matrix_free/matrix_free.h index 109f5a2d1c..eec524e6f6 100644 --- a/include/deal.II/matrix_free/matrix_free.h +++ b/include/deal.II/matrix_free/matrix_free.h @@ -312,7 +312,8 @@ public: 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 void reinit (const DoFHandlerType &dof_handler, @@ -367,7 +368,8 @@ public: 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 void reinit (const std::vector &dof_handler, @@ -390,7 +392,8 @@ public: 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 void reinit (const std::vector &dof_handler, diff --git a/include/deal.II/meshworker/integration_info.h b/include/deal.II/meshworker/integration_info.h index 20e8e0b08e..996a2d496c 100644 --- a/include/deal.II/meshworker/integration_info.h +++ b/include/deal.II/meshworker/integration_info.h @@ -36,8 +36,8 @@ namespace MeshWorker * 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 diff --git a/include/deal.II/meshworker/vector_selector.h b/include/deal.II/meshworker/vector_selector.h index be6d2ad590..5e06d0005c 100644 --- a/include/deal.II/meshworker/vector_selector.h +++ b/include/deal.II/meshworker/vector_selector.h @@ -52,8 +52,8 @@ namespace MeshWorker * 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, diff --git a/include/deal.II/multigrid/mg_coarse.h b/include/deal.II/multigrid/mg_coarse.h index 2756c11541..db6b57a2bd 100644 --- a/include/deal.II/multigrid/mg_coarse.h +++ b/include/deal.II/multigrid/mg_coarse.h @@ -32,8 +32,9 @@ DEAL_II_NAMESPACE_OPEN * 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. */ diff --git a/include/deal.II/multigrid/mg_matrix.h b/include/deal.II/multigrid/mg_matrix.h index 85614767b9..66d1e8a33d 100644 --- a/include/deal.II/multigrid/mg_matrix.h +++ b/include/deal.II/multigrid/mg_matrix.h @@ -86,11 +86,11 @@ namespace mg /** * 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 */ diff --git a/include/deal.II/multigrid/mg_smoother.h b/include/deal.II/multigrid/mg_smoother.h index 4fb123b80c..1c007aa58f 100644 --- a/include/deal.II/multigrid/mg_smoother.h +++ b/include/deal.II/multigrid/mg_smoother.h @@ -192,8 +192,9 @@ namespace mg * 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 void initialize (const MGLevelObject &matrices, @@ -291,8 +292,8 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -304,8 +305,8 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -319,8 +320,8 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -408,8 +409,9 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -420,8 +422,9 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -433,8 +436,9 @@ public: * 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 void initialize (const MGLevelObject &matrices, @@ -448,8 +452,9 @@ public: * 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 void initialize (const MGLevelObject &matrices, diff --git a/include/deal.II/multigrid/mg_transfer.h b/include/deal.II/multigrid/mg_transfer.h index f5be890b03..4f44a5cc12 100644 --- a/include/deal.II/multigrid/mg_transfer.h +++ b/include/deal.II/multigrid/mg_transfer.h @@ -257,8 +257,8 @@ protected: /** * 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. diff --git a/include/deal.II/multigrid/multigrid.h b/include/deal.II/multigrid/multigrid.h index f2a364dab9..7f81b93a76 100644 --- a/include/deal.II/multigrid/multigrid.h +++ b/include/deal.II/multigrid/multigrid.h @@ -339,9 +339,10 @@ private: * multi-level preconditioning and provide the standard interface for LAC * iterative methods. * - * Furthermore, it needs functions void copy_to_mg(const VectorType&) to - * store @p src in the right hand side of the multi-level method and void - * copy_from_mg(VectorType&) to store the result of the v-cycle in @p dst. + * Furthermore, it needs functions void copy_to_mg(const VectorType&) + * to store @p src in the right hand side of the multi-level method and + * void copy_from_mg(VectorType&) to store the result of the v-cycle + * in @p dst. * * @author Guido Kanschat, 1999, 2000, 2001, 2002 */ diff --git a/include/deal.II/numerics/data_out.h b/include/deal.II/numerics/data_out.h index 9192ba1037..e85bb7adf5 100644 --- a/include/deal.II/numerics/data_out.h +++ b/include/deal.II/numerics/data_out.h @@ -146,10 +146,10 @@ namespace internal * * @pre This class only makes sense if the first template argument, * dim equals the dimension of the DoFHandler type given as the - * second template argument, i.e., if dim == DoFHandlerType::dimension. 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 dim == + * DoFHandlerType::dimension. 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 @@ -288,10 +288,11 @@ private: /** * 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_and_index, diff --git a/include/deal.II/numerics/data_out_faces.h b/include/deal.II/numerics/data_out_faces.h index 048c7a6318..a82feb84fe 100644 --- a/include/deal.II/numerics/data_out_faces.h +++ b/include/deal.II/numerics/data_out_faces.h @@ -99,10 +99,10 @@ namespace internal * * @pre This class only makes sense if the first template argument, * dim equals the dimension of the DoFHandler type given as the - * second template argument, i.e., if dim == DoFHandlerType::dimension. 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 dim == + * DoFHandlerType::dimension. 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. diff --git a/include/deal.II/numerics/data_out_rotation.h b/include/deal.II/numerics/data_out_rotation.h index cf841a132f..eeb10e87e6 100644 --- a/include/deal.II/numerics/data_out_rotation.h +++ b/include/deal.II/numerics/data_out_rotation.h @@ -107,10 +107,10 @@ namespace internal * * @pre This class only makes sense if the first template argument, * dim equals the dimension of the DoFHandler type given as the - * second template argument, i.e., if dim == DoFHandlerType::dimension. 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 dim == + * DoFHandlerType::dimension. 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 diff --git a/include/deal.II/numerics/error_estimator.templates.h b/include/deal.II/numerics/error_estimator.templates.h index eb3f11620f..e4f8c4b047 100644 --- a/include/deal.II/numerics/error_estimator.templates.h +++ b/include/deal.II/numerics/error_estimator.templates.h @@ -72,9 +72,9 @@ namespace internal { /** * 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 @@ -123,11 +123,11 @@ namespace internal /** * 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 > > phi; @@ -152,8 +152,8 @@ namespace internal std::vector > normal_vectors; /** - * Normal vectors of the opposing face. - */ + * Normal vectors of the opposing face. + */ std::vector > neighbor_normal_vectors; /** @@ -483,8 +483,8 @@ namespace internal } /** - * 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 double boundary_face_factor(const typename DoFHandlerType::active_cell_iterator &cell, @@ -513,7 +513,7 @@ namespace internal /** - * A factor to scale the integral for the regular face. + * A factor to scale the integral for the regular face. */ template double regular_face_factor(const typename DoFHandlerType::active_cell_iterator &cell, @@ -575,8 +575,8 @@ namespace internal } /** - * 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 double cell_factor(const typename DoFHandlerType::active_cell_iterator &cell, @@ -698,14 +698,9 @@ namespace internal /** - * 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 void diff --git a/include/deal.II/numerics/matrix_tools.h b/include/deal.II/numerics/matrix_tools.h index 8d0c2615c2..4784417ad8 100644 --- a/include/deal.II/numerics/matrix_tools.h +++ b/include/deal.II/numerics/matrix_tools.h @@ -95,8 +95,8 @@ namespace TrilinosWrappers * 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 with mapping argument should be used. + * mapping than a (bi-/tri-)linear one, then you need to call the functions + * with 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 @@ -181,9 +181,9 @@ namespace TrilinosWrappers * chars 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 not 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 diff --git a/include/deal.II/numerics/point_value_history.h b/include/deal.II/numerics/point_value_history.h index ef3765ed14..2a75666075 100644 --- a/include/deal.II/numerics/point_value_history.h +++ b/include/deal.II/numerics/point_value_history.h @@ -282,8 +282,8 @@ public: /** - * 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. @@ -292,8 +292,8 @@ public: 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 @@ -366,8 +366,8 @@ public: /** - * 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 diff --git a/include/deal.II/numerics/vector_tools.h b/include/deal.II/numerics/vector_tools.h index 96757e9fe0..635ee356d2 100644 --- a/include/deal.II/numerics/vector_tools.h +++ b/include/deal.II/numerics/vector_tools.h @@ -63,8 +63,8 @@ class ConstraintMatrix; * 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 with mapping argument should be used. + * mapping than a (bi-/tri-)linear one, then you need to call the functions + * with mapping argument should be used. * * *

      Description of operations

      @@ -392,8 +392,8 @@ namespace VectorTools * with the hanging nodes from space @p dof afterwards, to make the result * continuous again. * - * The template argument DoFHandlerType may either be of type DoFHandler or - * hp::DoFHandler. + * The template argument DoFHandlerType may either be of type + * DoFHandler or hp::DoFHandler. * * See the general documentation of this namespace for further information. * @@ -634,8 +634,8 @@ namespace VectorTools 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 void project (const hp::DoFHandler &dof, @@ -741,9 +741,9 @@ namespace VectorTools /** * Calls the other interpolate_boundary_values() function, see above, with - * mapping=MappingQGeneric@(1). 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. + * mapping=MappingQGeneric@(1). 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" @@ -760,9 +760,9 @@ namespace VectorTools /** * Calls the other interpolate_boundary_values() function, see above, with - * mapping=MappingQGeneric@(1). 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. + * mapping=MappingQGeneric@(1). 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 void @@ -866,9 +866,9 @@ namespace VectorTools /** * Calls the other interpolate_boundary_values() function, see above, with - * mapping=MappingQGeneric@(1). 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. + * mapping=MappingQGeneric@(1). 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 * @@ -887,9 +887,9 @@ namespace VectorTools /** * Calls the other interpolate_boundary_values() function, see above, with - * mapping=MappingQGeneric@(1). 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. + * mapping=MappingQGeneric@(1). 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 */ @@ -912,24 +912,23 @@ namespace VectorTools * = \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. @@ -940,8 +939,8 @@ namespace VectorTools * 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 @@ -1396,18 +1395,18 @@ namespace VectorTools * @image html no_normal_flux_1.png *

      * - * 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. all 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. all 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 @@ -1820,8 +1819,7 @@ namespace VectorTools * @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. @@ -1908,9 +1906,8 @@ namespace VectorTools * @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 @@ -2329,10 +2326,11 @@ namespace VectorTools * 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 @@ -2369,15 +2367,15 @@ namespace VectorTools */ //@{ /** - * 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 @@ -2389,8 +2387,8 @@ namespace VectorTools * 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 */