* vector_value(), and gradient analogs), while those ones will throw an
* exception when called but not overloaded.
*
- * Conversely, the functions returning all components of the function at
- * one or several points (i.e. vector_value(), vector_value_list()),
- * will <em>not</em> call the function returning one component at
- * one point repeatedly, once for each point and component. The reason is
- * efficiency: this would amount to too many virtual function calls. If you
- * have vector-valued functions, you should therefore also provide overloads
- * of the virtual functions for all components at a time.
+ * Conversely, the functions returning all components of the function at one
+ * or several points (i.e. vector_value(), vector_value_list()), will
+ * <em>not</em> call the function returning one component at one point
+ * repeatedly, once for each point and component. The reason is efficiency:
+ * this would amount to too many virtual function calls. If you have vector-
+ * valued functions, you should therefore also provide overloads of the
+ * virtual functions for all components at a time.
*
* Also note, that unless only called a very small number of times, you should
* overload all sets of functions (returning only one value, as well as those
*
* <h3>Functions that return tensors</h3>
*
- * If the functions you are dealing with have a number of
- * components that are a priori known (for example, <tt>dim</tt>
- * elements), you might consider using the TensorFunction class
- * instead. This is, in particular, true if the objects you return
- * have the properties of a tensor, i.e., they are for example
- * dim-dimensional vectors or dim-by-dim matrices. On the other hand,
+ * If the functions you are dealing with have a number of components that are
+ * a priori known (for example, <tt>dim</tt> elements), you might consider
+ * using the TensorFunction class instead. This is, in particular, true if the
+ * objects you return have the properties of a tensor, i.e., they are for
+ * example dim-dimensional vectors or dim-by-dim matrices. On the other hand,
* functions like VectorTools::interpolate or
- * VectorTools::interpolate_boundary_values definitely only want
- * objects of the current type. You can use the
- * VectorFunctionFromTensorFunction class to convert the former to the
- * latter.
+ * VectorTools::interpolate_boundary_values definitely only want objects of
+ * the current type. You can use the VectorFunctionFromTensorFunction class to
+ * convert the former to the latter.
*
*
* <h3>Functions that return different fields</h3>
*
- * Most of the time, your functions will have the form
- * $f : \Omega \rightarrow {\mathbb R}^{n_\text{components}}$. However,
- * there are occasions where you want the function to return vectors (or
- * scalars) over a different number field, for example functions that
- * return complex numbers or vectors of complex numbers:
- * $f : \Omega \rightarrow {\mathbb C}^{n_\text{components}}$. In such
- * cases, you can use the second template argument of this class: it
- * describes the scalar type to be used for each component of your return
- * values. It defaults to @p double, but in the example above, it could
- * be set to <code>std::complex@<double@></code>.
+ * Most of the time, your functions will have the form $f : \Omega \rightarrow
+ * {\mathbb R}^{n_\text{components}}$. However, there are occasions where you
+ * want the function to return vectors (or scalars) over a different number
+ * field, for example functions that return complex numbers or vectors of
+ * complex numbers: $f : \Omega \rightarrow {\mathbb
+ * C}^{n_\text{components}}$. In such cases, you can use the second template
+ * argument of this class: it describes the scalar type to be used for each
+ * component of your return values. It defaults to @p double, but in the
+ * example above, it could be set to <code>std::complex@<double@></code>.
*
*
* @ingroup functions
{
public:
/**
- * One can see an IndexSet as a container of size size(), where the
- * elements of the containers are bool values that are either false
- * or true, depending on whether a particular index is an element of
- * the IndexSet or not. In other words, an IndexSet is a bit like a
- * vector in which the elements we store are booleans. In this view,
- * the correct local typedef indicating the type of the elements of
- * the vector would then be @p bool.
+ * One can see an IndexSet as a container of size size(), where the elements
+ * of the containers are bool values that are either false or true,
+ * depending on whether a particular index is an element of the IndexSet or
+ * not. In other words, an IndexSet is a bit like a vector in which the
+ * elements we store are booleans. In this view, the correct local typedef
+ * indicating the type of the elements of the vector would then be @p bool.
*
* On the other hand, @p bool has the disadvantage that it is not a
- * numerical type that, for example, allows multiplication with a @p
- * double. In other words, one can not easily use a vector of
- * booleans in a place where other vectors are
- * allowed. Consequently, we declare the type of the elements of
- * such a vector as a signed integer. This uses the fact that in the
- * C++ language, booleans are implicitly convertible to integers. In
- * other words, declaring the type of the elements of the vector as
- * a signed integer is only a small lie, but it is a useful one.
+ * numerical type that, for example, allows multiplication with a @p double.
+ * In other words, one can not easily use a vector of booleans in a place
+ * where other vectors are allowed. Consequently, we declare the type of the
+ * elements of such a vector as a signed integer. This uses the fact that in
+ * the C++ language, booleans are implicitly convertible to integers. In
+ * other words, declaring the type of the elements of the vector as a signed
+ * integer is only a small lie, but it is a useful one.
*/
typedef signed int value_type;
* main.
* @param[in] max_num_threads The maximal number of threads this MPI
* process should utilize. If this argument is set to
- * numbers::invalid_unsigned_int (the default value),
- * then the number of threads is determined
- * automatically in the following way: the number of threads to run on
- * this MPI process is set in such a way that all of the cores in your
- * node are spoken for. In other words, if you have started one MPI
- * process per node, setting this argument is equivalent to setting it
- * to the number of cores present in the node this MPI process runs on.
- * If you have started as many MPI processes per node as there are cores
- * on each node, then this is equivalent to passing 1 as the argument.
- * On the other hand, if, for example, you start 4 MPI processes on each
- * 16-core node, then this option will start 4 worker threads for each
- * node. If you start 3 processes on an 8 core node, then they will
- * start 3, 3 and 2 threads, respectively.
+ * numbers::invalid_unsigned_int (the default value), then the number of
+ * threads is determined automatically in the following way: the number
+ * of threads to run on this MPI process is set in such a way that all
+ * of the cores in your node are spoken for. In other words, if you have
+ * started one MPI process per node, setting this argument is equivalent
+ * to setting it to the number of cores present in the node this MPI
+ * process runs on. If you have started as many MPI processes per node
+ * as there are cores on each node, then this is equivalent to passing 1
+ * as the argument. On the other hand, if, for example, you start 4 MPI
+ * processes on each 16-core node, then this option will start 4 worker
+ * threads for each node. If you start 3 processes on an 8 core node,
+ * then they will start 3, 3 and 2 threads, respectively.
*
* @note This function calls MultithreadInfo::set_thread_limit() with
* either @p max_num_threads or, following the discussion above, a
*
* @note MultithreadInfo::set_thread_limit() can only work if it is
* called before any threads are created. The safest place for a call to
- * it is therefore at the beginning of
- * <code>main()</code>. Consequently, this extends to the current class:
- * the best place to create an object of this type is also at or close
- * to the top of <code>main()</code>.
+ * it is therefore at the beginning of <code>main()</code>.
+ * Consequently, this extends to the current class: the best place to
+ * create an object of this type is also at or close to the top of
+ * <code>main()</code>.
*/
MPI_InitFinalize (int &argc,
char ** &argv,
* @ref threads
* for more information on this. Thread-based parallel methods need to
* explicitly created threads and may want to use a number of threads that is
- * related to the number of CPUs in your system. The recommended number of threads
- * can be queried using MultithreadInfo::n_threads(), while the number of cores
- * in the system is returned by MultithreadInfo::n_cores().
+ * related to the number of CPUs in your system. The recommended number of
+ * threads can be queried using MultithreadInfo::n_threads(), while the number
+ * of cores in the system is returned by MultithreadInfo::n_cores().
*
* @ingroup threads
* @author Thomas Richter, Wolfgang Bangerth, 2000
* A class that represents a point in a space with arbitrary dimension
* <tt>dim</tt>.
*
- * Objects of this class are used to represent points, i.e., vectors
- * anchored at the origin of a Cartesian vector space. They are, among
- * other uses, passed to functions that operate on points in spaces of
- * a priori fixed dimension: rather than using functions like
- * <tt>double f(double x)</tt> and <tt>double f(double x, double
- * y)</tt>, you should use <tt>double f(Point<dim> &p)</tt> instead as
- * it allows writing dimension independent code.
+ * Objects of this class are used to represent points, i.e., vectors anchored
+ * at the origin of a Cartesian vector space. They are, among other uses,
+ * passed to functions that operate on points in spaces of a priori fixed
+ * dimension: rather than using functions like <tt>double f(double x)</tt> and
+ * <tt>double f(double x, double y)</tt>, you should use <tt>double
+ * f(Point<dim> &p)</tt> instead as it allows writing dimension independent
+ * code.
*
*
- * <h3>What's a <code>Point@<dim@></code> and what is a <code>Tensor@<1,dim@></code>?</h3>
+ * <h3>What's a <code>Point@<dim@></code> and what is a
+ * <code>Tensor@<1,dim@></code>?</h3>
*
- * The Point class is derived from Tensor@<1,dim@> and consequently
- * shares the latter's member functions and other attributes. In fact,
- * it has relatively few additional functions itself (the most notable
- * exception being the distance() function to compute the Euclidean
- * distance between two points in space), and these two classes can
- * therefore often be used interchangeably.
+ * The Point class is derived from Tensor@<1,dim@> and consequently shares the
+ * latter's member functions and other attributes. In fact, it has relatively
+ * few additional functions itself (the most notable exception being the
+ * distance() function to compute the Euclidean distance between two points in
+ * space), and these two classes can therefore often be used interchangeably.
*
- * Nonetheless, there are semantic differences that make us use these
- * classes in different and well-defined contexts. Within deal.II, we
- * use the <tt>Point</tt> class to denote points in space, i.e., for
- * vectors (rank-1 tensors) that are <em>anchored at the
- * origin</em>. On the other hand, vectors that are anchored elsewhere
- * (and consequently do not represent <em>points</em> in the common
- * usage of the word) are represented by objects of type
- * Tensor@<1,dim@>. In particular, this is the case for direction
- * vectors, normal vectors, gradients, and the differences between two
- * points (i.e., what you get when you subtract one point from
- * another): all of these are represented by Tensor@<1,dim@> objects
- * rather than Point@<dim@>.
+ * Nonetheless, there are semantic differences that make us use these classes
+ * in different and well-defined contexts. Within deal.II, we use the
+ * <tt>Point</tt> class to denote points in space, i.e., for vectors (rank-1
+ * tensors) that are <em>anchored at the origin</em>. On the other hand,
+ * vectors that are anchored elsewhere (and consequently do not represent
+ * <em>points</em> in the common usage of the word) are represented by objects
+ * of type Tensor@<1,dim@>. In particular, this is the case for direction
+ * vectors, normal vectors, gradients, and the differences between two points
+ * (i.e., what you get when you subtract one point from another): all of these
+ * are represented by Tensor@<1,dim@> objects rather than Point@<dim@>.
*
- * Furthermore, the Point class is only used where the coordinates of
- * an object can be thought to possess the dimension of a length. An
- * object that represents the weight, height, and cost of an object is
- * neither a point nor a tensor (because it lacks the transformation
- * properties under rotation of the coordinate system) and should
- * consequently not be represented by either of these classes. Use an
- * array of size 3 in this case, or the <code>std_cxx11::array</code>
- * class. Alternatively, as in the case of vector-valued functions,
- * you can use objects of type Vector or <code>std::vector</code>.
+ * Furthermore, the Point class is only used where the coordinates of an
+ * object can be thought to possess the dimension of a length. An object that
+ * represents the weight, height, and cost of an object is neither a point nor
+ * a tensor (because it lacks the transformation properties under rotation of
+ * the coordinate system) and should consequently not be represented by either
+ * of these classes. Use an array of size 3 in this case, or the
+ * <code>std_cxx11::array</code> class. Alternatively, as in the case of
+ * vector-valued functions, you can use objects of type Vector or
+ * <code>std::vector</code>.
*
*
- * @tparam dim An integer that denotes the dimension of the space in which
- * a point lies. This of course equals the number of coordinates that
- * identify a point.
- * @tparam Number The data type in which the coordinates values are
- * to be stored. This will, in almost all cases, simply be the default
- * @p double, but there are cases where one may want to store coordinates
- * in a different (and always scalar) type. An example would be an interval
- * type that can store the value of a coordinate as well as its uncertainty.
- * Another example would be a type that allows for Automatic Differentiation
- * (see, for example, the Sacado type used in step-33) and thereby can
- * generate analytic (spatial) derivatives of a function when passed a
- * Point object whose coordinates are stored in such a type.
+ * @tparam dim An integer that denotes the dimension of the space in which a
+ * point lies. This of course equals the number of coordinates that identify a
+ * point.
+ * @tparam Number The data type in which the coordinates values are to be
+ * stored. This will, in almost all cases, simply be the default @p double,
+ * but there are cases where one may want to store coordinates in a different
+ * (and always scalar) type. An example would be an interval type that can
+ * store the value of a coordinate as well as its uncertainty. Another example
+ * would be a type that allows for Automatic Differentiation (see, for
+ * example, the Sacado type used in step-33) and thereby can generate analytic
+ * (spatial) derivatives of a function when passed a Point object whose
+ * coordinates are stored in such a type.
*
*
* @ingroup geomprimitives
const Number z);
/**
- * Return a unit vector in coordinate direction <tt>i</tt>, i.e., a
- * vector that is zero in all coordinates except for a single 1 in
- * the <tt>i</tt>th coordinate.
+ * Return a unit vector in coordinate direction <tt>i</tt>, i.e., a vector
+ * that is zero in all coordinates except for a single 1 in the <tt>i</tt>th
+ * coordinate.
*/
static Point<dim,Number> unit_vector(const unsigned int i);
Point<dim,Number> operator + (const Tensor<1,dim,Number> &) const;
/**
- * Subtract two points, i.e., obtain the vector that connects the
- * two. As discussed in the documentation of this class, subtracting
- * two points results in a vector anchored at one of the two points
- * (rather than at the origin) and, consequently, the result is
- * returned as a Tensor@<1,dim@> rather than as a Point@<dim@>.
+ * Subtract two points, i.e., obtain the vector that connects the two. As
+ * discussed in the documentation of this class, subtracting two points
+ * results in a vector anchored at one of the two points (rather than at the
+ * origin) and, consequently, the result is returned as a Tensor@<1,dim@>
+ * rather than as a Point@<dim@>.
*/
Tensor<1,dim,Number> operator - (const Point<dim,Number> &) const;
/**
- * Subtract a difference vector (represented by a Tensor@<1,dim@>)
- * from the current point. This results in another point and, as
- * discussed in the documentation of this class, the result is then
- * naturally returned as a Point@<dim@> object rather than as a
- * Tensor@<1,dim@>.
+ * Subtract a difference vector (represented by a Tensor@<1,dim@>) from the
+ * current point. This results in another point and, as discussed in the
+ * documentation of this class, the result is then naturally returned as a
+ * Point@<dim@> object rather than as a Tensor@<1,dim@>.
*/
Point<dim,Number> operator - (const Tensor<1,dim,Number> &) const;
* <i>(x<sup>k-i</sup>yz<sup>i+1</sup>,0,0)</i> and
* <i>(0,x<sup>i+1</sup>y<sup>k-i</sup>z,0)</i> </dl>
*
- * Note the curl of a scalar function is given by
- * $\text{curl}(f(x,y)) = \begin{pmatrix} f_{y}(x,y) \\ -f_{x}(x,y) \end{pmatrix}$.
+ * Note the curl of a scalar function is given by $\text{curl}(f(x,y)) =
+ * \begin{pmatrix} f_{y}(x,y) \\ -f_{x}(x,y) \end{pmatrix}$.
* @todo Second derivatives in 3D are missing.
*
* @ingroup Polynomials
namespace std_cxx11
{
/**
- * Implementation of a basic replacement for C++11's std::unique_ptr
- * class.
+ * Implementation of a basic replacement for C++11's std::unique_ptr class.
*
- * BOOST does not have a replacement for std::unique_ptr (because
- * unique_ptr requires move semantics that aren't available unless
- * you have a C++11 compiler -- in which case you also have
- * std::unique_ptr; see for example
+ * BOOST does not have a replacement for std::unique_ptr (because unique_ptr
+ * requires move semantics that aren't available unless you have a C++11
+ * compiler -- in which case you also have std::unique_ptr; see for example
* http://stackoverflow.com/questions/2953530/unique-ptr-boost-equivalent)
*
- * Consequently, we emulate the class by just wrapping a
- * boost::shared_ptr in the cheapest possible way -- by just
- * deriving from it and repeating the basic constructors. Everything
- * else is inherited from the shared_ptr class.
+ * Consequently, we emulate the class by just wrapping a boost::shared_ptr
+ * in the cheapest possible way -- by just deriving from it and repeating
+ * the basic constructors. Everything else is inherited from the shared_ptr
+ * class.
*
- * This replacement comes with a certain overhead: doing reference
- * counting instead of just passing ownership of pointers has a
- * cost. But we don't use unique_ptrs in expensive places, and it is
- * also a cost that will disappear once we require C++11 (and the
- * cost of course does not apply if your compiler already supports
- * C++11 and deal.II uses it).
+ * This replacement comes with a certain overhead: doing reference counting
+ * instead of just passing ownership of pointers has a cost. But we don't
+ * use unique_ptrs in expensive places, and it is also a cost that will
+ * disappear once we require C++11 (and the cost of course does not apply if
+ * your compiler already supports C++11 and deal.II uses it).
*/
template <typename T>
class unique_ptr : public boost::shared_ptr<T>
SymmetricTensor (const Number (&array) [n_independent_components]);
/**
- * Copy constructor from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Copy constructor from tensors with different underlying scalar type. This
+ * obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
explicit
/**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the right. This version of the operator is used if the scalar
- * has the same data type as is used to store the elements of the
- * symmetric tensor.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * right. This version of the operator is used if the scalar has the same data
+ * type as is used to store the elements of the symmetric tensor.
*
* @relates SymmetricTensor
*/
/**
* Multiplication of a symmetric tensor of general rank with a scalar from the
- * left. This version of the operator is used if the scalar
- * has the same data type as is used to store the elements of the
- * symmetric tensor.
+ * left. This version of the operator is used if the scalar has the same data
+ * type as is used to store the elements of the symmetric tensor.
*
* @relates SymmetricTensor
*/
* prohibited of considering this operator for multiplication with non-scalar
* types are explained in the documentation of the EnableIfScalar class.
*
- * The return type of the function is chosen so that it matches the types
- * of both the tensor and the scalar argument. For example, if you multiply
- * a <code>SymmetricTensor@<2,dim,double@></code> by <code>std::complex@<double@></code>,
- * then the result will be a <code>SymmetricTensor@<2,dim,std::complex@<double@>@></code>.
- * In other words, the type with which the returned tensor stores its
- * components equals the type you would get if you multiplied an individual
- * component of the input tensor by the scalar factor.
+ * The return type of the function is chosen so that it matches the types of
+ * both the tensor and the scalar argument. For example, if you multiply a
+ * <code>SymmetricTensor@<2,dim,double@></code> by
+ * <code>std::complex@<double@></code>, then the result will be a
+ * <code>SymmetricTensor@<2,dim,std::complex@<double@>@></code>. In other
+ * words, the type with which the returned tensor stores its components equals
+ * the type you would get if you multiplied an individual component of the
+ * input tensor by the scalar factor.
*
* @relates SymmetricTensor
* @relates EnableIfScalar
/**
- * A class with a local typedef that represents the type that results from
- * the product of two variables of type @p T and @p U. In other words,
- * we would like to infer the type of the <code>product</code> variable
- * in code like this:
+ * A class with a local typedef that represents the type that results from the
+ * product of two variables of type @p T and @p U. In other words, we would
+ * like to infer the type of the <code>product</code> variable in code like
+ * this:
* @code
* T t;
* U u;
*
* <h3>Where is this useful</h3>
*
- * The purpose of this class is principally to represent the type one needs
- * to use to represent the values or gradients of finite element fields at
+ * The purpose of this class is principally to represent the type one needs to
+ * use to represent the values or gradients of finite element fields at
* quadrature points. For example, assume you are storing the values $U_j$ of
- * unknowns in a Vector<float>, then evaluating
- * $u_h(x_q) = \sum_j U_j \varphi_j(x_q)$ at quadrature points results
- * in values $u_h(x_q)$ that need to be stored as @p double variables
- * because the $U_j$ are @p float values and the $\varphi_j(x_q)$ are
- * computed as @p double values, and the product are then @p double
- * values. On the other hand, if you store your unknowns $U_j$ as
- * <code>std::complex@<double@></code> values and you try to evaluate
+ * unknowns in a Vector<float>, then evaluating $u_h(x_q) = \sum_j U_j
+ * \varphi_j(x_q)$ at quadrature points results in values $u_h(x_q)$ that need
+ * to be stored as @p double variables because the $U_j$ are @p float values
+ * and the $\varphi_j(x_q)$ are computed as @p double values, and the product
+ * are then @p double values. On the other hand, if you store your unknowns
+ * $U_j$ as <code>std::complex@<double@></code> values and you try to evaluate
* $\nabla u_h(x_q) = \sum_j U_j \nabla\varphi_j(x_q)$ at quadrature points,
- * then the gradients $\nabla u_h(x_q)$ need to be stored as objects of
- * type <code>Tensor@<1,dim,std::complex@<double@>@></code> because
- * that's what you get when you multiply a complex number by a
- * <code>Tensor@<1,dim@></code> (the type used to represent the gradient
- * of shape functions of scalar finite elements).
+ * then the gradients $\nabla u_h(x_q)$ need to be stored as objects of type
+ * <code>Tensor@<1,dim,std::complex@<double@>@></code> because that's what you
+ * get when you multiply a complex number by a <code>Tensor@<1,dim@></code>
+ * (the type used to represent the gradient of shape functions of scalar
+ * finite elements).
*
* Likewise, if you are using a vector valued element (with dim components)
- * and the $U_j$ are stored as @p double variables, then
- * $u_h(x_q) = \sum_j U_j \varphi_j(x_q)$ needs to have type
- * <code>Tensor@<1,dim@></code> (because the shape functions have type
- * <code>Tensor@<1,dim@></code>). Finally, if you store the $U_j$ as
- * objects of type <code>std::complex@<double@></code> and you have a
- * vector valued element, then the gradients
- * $\nabla u_h(x_q) = \sum_j U_j \nabla\varphi_j(x_q)$ will result in
- * objects of type
- * <code>Tensor@<2,dim,std::complex@<double@> @></code>.
+ * and the $U_j$ are stored as @p double variables, then $u_h(x_q) = \sum_j
+ * U_j \varphi_j(x_q)$ needs to have type <code>Tensor@<1,dim@></code>
+ * (because the shape functions have type <code>Tensor@<1,dim@></code>).
+ * Finally, if you store the $U_j$ as objects of type
+ * <code>std::complex@<double@></code> and you have a vector valued element,
+ * then the gradients $\nabla u_h(x_q) = \sum_j U_j \nabla\varphi_j(x_q)$ will
+ * result in objects of type <code>Tensor@<2,dim,std::complex@<double@>
+ * @></code>.
*
- * In all of these cases, this type is used to identify which type needs
- * to be used for the result of computing the product of unknowns
- * and the values, gradients, or other properties of shape functions.
+ * In all of these cases, this type is used to identify which type needs to be
+ * used for the result of computing the product of unknowns and the values,
+ * gradients, or other properties of shape functions.
*
* @author Wolfgang Bangerth, 2015
*/
/**
- * This class provides a local typedef @p type that is equal to the
- * template argument but only if the template argument corresponds to
- * a scalar type (i.e., one of the floating point types, signed or unsigned
- * integer, or a complex number). If the template type @p T is not a scalar,
- * then no class <code>EnableIfScalar@<T@></code> is declared and,
- * consequently, no local typedef is available.
+ * This class provides a local typedef @p type that is equal to the template
+ * argument but only if the template argument corresponds to a scalar type
+ * (i.e., one of the floating point types, signed or unsigned integer, or a
+ * complex number). If the template type @p T is not a scalar, then no class
+ * <code>EnableIfScalar@<T@></code> is declared and, consequently, no local
+ * typedef is available.
*
- * The purpose of the class is to disable certain template functions if
- * one of the arguments is not a scalar number. By way of (nonsensical)
- * example, consider the following function:
+ * The purpose of the class is to disable certain template functions if one of
+ * the arguments is not a scalar number. By way of (nonsensical) example,
+ * consider the following function:
* @code
* template <typename T>
* T multiply (const T t1, const T t2) { return t1*t2; }
* @endcode
* This function can be called with any two arguments of the same type @p T.
- * This includes arguments for which this clearly makes no sense. Consequently,
- * one may want to restrict the function to only scalars, and this can be
- * written as
+ * This includes arguments for which this clearly makes no sense.
+ * Consequently, one may want to restrict the function to only scalars, and
+ * this can be written as
* @code
* template <typename T>
* typename EnableIfScalar<T>::type
* multiply (const T t1, const T t2) { return t1*t2; }
* @endcode
- * At a place where you call the function, the compiler will deduce the
- * type @p T from the arguments. For example, in
+ * At a place where you call the function, the compiler will deduce the type
+ * @p T from the arguments. For example, in
* @code
* multiply(1.234, 2.345);
* @endcode
* it will deduce @p T to be @p double, and because
* <code>EnableIfScalar@<double@>::type</code> equals @p double, the compiler
- * will instantiate a function
- * <code>double multiply(const double, const double)</code> from the template
- * above. On the other hand, in a context like
+ * will instantiate a function <code>double multiply(const double, const
+ * double)</code> from the template above. On the other hand, in a context
+ * like
* @code
* std::vector<char> v1, v2;
* multiply(v1, v2);
* @endcode
* the compiler will deduce @p T to be <code>std::vector@<char@></code> but
- * because <code>EnableIfScalar@<std::vector@<char@>@>::type</code> does not exist
- * the compiler does not consider the template for instantiation. This technique
- * is called "Substitution Failure is not an Error (SFINAE)". It makes sure that
- * the template function can not even be called, rather than leading to a
- * later error about the fact that the operation <code>t1*t2</code> is not
- * defined (or may lead to some nonsensical result). It also allows the
- * declaration of overloads of a function such as @p multiply for different
- * types of arguments, without resulting in ambiguous call errors by the
- * compiler.
+ * because <code>EnableIfScalar@<std::vector@<char@>@>::type</code> does not
+ * exist the compiler does not consider the template for instantiation. This
+ * technique is called "Substitution Failure is not an Error (SFINAE)". It
+ * makes sure that the template function can not even be called, rather than
+ * leading to a later error about the fact that the operation
+ * <code>t1*t2</code> is not defined (or may lead to some nonsensical result).
+ * It also allows the declaration of overloads of a function such as @p
+ * multiply for different types of arguments, without resulting in ambiguous
+ * call errors by the compiler.
*
* @author Wolfgang Bangerth, 2015
*/
template <int dim, typename Number> class Tensor<1,dim,Number>;
/**
- * A general tensor class with an arbitrary rank, i.e. with an
- * arbitrary number of indices. The Tensor class provides an indexing operator
- * and a bit of infrastructure, but most functionality is recursively handed
- * down to tensors of rank 1 or put into external templated functions, e.g.
- * the <tt>contract</tt> family.
- *
- * Using this tensor class for objects of rank 2 has advantages over
- * matrices in many cases since the dimension is known to the compiler
- * as well as the location of the data. It is therefore possible to
- * produce far more efficient code than for matrices with
- * runtime-dependent dimension. It also makes the code easier to read
- * because of the semantic difference between a tensor (an object that
- * relates to a coordinate system and has transformation properties
- * with regard to coordinate rotations and transforms) and matrices
- * (which we consider as operators on arbitrary vector spaces related
- * to linear algebra things).
- *
- * @tparam rank_ An integer that denotes the rank of this tensor. A
- * rank-0 tensor is a scalar, a rank-1 tensor is a vector with @p dim
- * components, a rank-2 tensor is a matrix with dim-by-dim components,
- * etc. There are specializations of this class for rank-0 and rank-1
- * tensors. There is also a related class SymmetricTensor for
- * tensors of even rank whose elements are symmetric.
+ * A general tensor class with an arbitrary rank, i.e. with an arbitrary
+ * number of indices. The Tensor class provides an indexing operator and a bit
+ * of infrastructure, but most functionality is recursively handed down to
+ * tensors of rank 1 or put into external templated functions, e.g. the
+ * <tt>contract</tt> family.
+ *
+ * Using this tensor class for objects of rank 2 has advantages over matrices
+ * in many cases since the dimension is known to the compiler as well as the
+ * location of the data. It is therefore possible to produce far more
+ * efficient code than for matrices with runtime-dependent dimension. It also
+ * makes the code easier to read because of the semantic difference between a
+ * tensor (an object that relates to a coordinate system and has
+ * transformation properties with regard to coordinate rotations and
+ * transforms) and matrices (which we consider as operators on arbitrary
+ * vector spaces related to linear algebra things).
+ *
+ * @tparam rank_ An integer that denotes the rank of this tensor. A rank-0
+ * tensor is a scalar, a rank-1 tensor is a vector with @p dim components, a
+ * rank-2 tensor is a matrix with dim-by-dim components, etc. There are
+ * specializations of this class for rank-0 and rank-1 tensors. There is also
+ * a related class SymmetricTensor for tensors of even rank whose elements are
+ * symmetric.
* @tparam dim An integer that denotes the dimension of the space in which
- * this tensor operates. This of course equals the number of coordinates that
- * identify a point and rank-1 tensor.
- * @tparam Number The data type in which the tensor elements are
- * to be stored. This will, in almost all cases, simply be the default
- * @p double, but there are cases where one may want to store elements
- * in a different (and always scalar) type. It can be used to base
- * tensors on @p float or @p complex numbers or any other data type that
- * implements basic arithmetic operations.
- * Another example would be a type that allows for Automatic Differentiation
- * (see, for example, the Sacado type used in step-33) and thereby can
- * generate analytic (spatial) derivatives of a function that takes a
- * tensor as argument.
+ * this tensor operates. This of course equals the number of coordinates that
+ * identify a point and rank-1 tensor.
+ * @tparam Number The data type in which the tensor elements are to be stored.
+ * This will, in almost all cases, simply be the default @p double, but there
+ * are cases where one may want to store elements in a different (and always
+ * scalar) type. It can be used to base tensors on @p float or @p complex
+ * numbers or any other data type that implements basic arithmetic operations.
+ * Another example would be a type that allows for Automatic Differentiation
+ * (see, for example, the Sacado type used in step-33) and thereby can
+ * generate analytic (spatial) derivatives of a function that takes a tensor
+ * as argument.
*
* @ingroup geomprimitives
* @author Wolfgang Bangerth, 1998-2005
Tensor (const array_type &initializer);
/**
- * Copy constructor from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Copy constructor from tensors with different underlying scalar type. This
+ * obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
explicit
Tensor &operator = (const Tensor<rank_,dim,Number> &rhs);
/**
- * Assignment operator from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Assignment operator from tensors with different underlying scalar type.
+ * This obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
Tensor &operator = (const Tensor<rank_,dim,OtherNumber> &rhs);
* prohibited of considering this operator for multiplication with non-scalar
* types are explained in the documentation of the EnableIfScalar class.
*
- * The return type of the function is chosen so that it matches the types
- * of both the tensor and the scalar argument. For example, if you multiply
- * a <code>Tensor@<1,dim,double@></code> by <code>std::complex@<double@></code>,
- * then the result will be a <code>Tensor@<1,dim,std::complex@<double@>@></code>.
- * In other words, the type with which the returned tensor stores its
- * components equals the type you would get if you multiplied an individual
- * component of the input tensor by the scalar factor.
+ * The return type of the function is chosen so that it matches the types of
+ * both the tensor and the scalar argument. For example, if you multiply a
+ * <code>Tensor@<1,dim,double@></code> by <code>std::complex@<double@></code>,
+ * then the result will be a
+ * <code>Tensor@<1,dim,std::complex@<double@>@></code>. In other words, the
+ * type with which the returned tensor stores its components equals the type
+ * you would get if you multiplied an individual component of the input tensor
+ * by the scalar factor.
*
* @relates Tensor
* @relates EnableIfScalar
* family.
*
* @tparam dim An integer that denotes the dimension of the space in which
- * this tensor operates. This of course equals the number of coordinates that
- * identify a point and rank-1 tensor. Since the current object is a rank-0
- * tensor (a scalar), this template argument has no meaning for this class.
- * @tparam Number The data type in which the tensor elements are
- * to be stored. This will, in almost all cases, simply be the default
- * @p double, but there are cases where one may want to store elements
- * in a different (and always scalar) type. It can be used to base
- * tensors on @p float or @p complex numbers or any other data type that
- * implements basic arithmetic operations.
- * Another example would be a type that allows for Automatic Differentiation
- * (see, for example, the Sacado type used in step-33) and thereby can
- * generate analytic (spatial) derivatives of a function that takes a
- * tensor as argument.
+ * this tensor operates. This of course equals the number of coordinates that
+ * identify a point and rank-1 tensor. Since the current object is a rank-0
+ * tensor (a scalar), this template argument has no meaning for this class.
+ * @tparam Number The data type in which the tensor elements are to be stored.
+ * This will, in almost all cases, simply be the default @p double, but there
+ * are cases where one may want to store elements in a different (and always
+ * scalar) type. It can be used to base tensors on @p float or @p complex
+ * numbers or any other data type that implements basic arithmetic operations.
+ * Another example would be a type that allows for Automatic Differentiation
+ * (see, for example, the Sacado type used in step-33) and thereby can
+ * generate analytic (spatial) derivatives of a function that takes a tensor
+ * as argument.
*
* @ingroup geomprimitives
* @author Wolfgang Bangerth, 2009
Tensor (const Tensor<0,dim,Number> &initializer);
/**
- * Copy constructor from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Copy constructor from tensors with different underlying scalar type. This
+ * obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
explicit
Tensor<0,dim,Number> &operator = (const Tensor<0,dim,Number> &rhs);
/**
- * Assignment operator from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Assignment operator from tensors with different underlying scalar type.
+ * This obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
Tensor<0,dim,Number> &operator = (const Tensor<0,dim,OtherNumber> &rhs);
* different physical units), we use the <tt>Tensor<1,dim,Number></tt> class.
*
* @tparam dim An integer that denotes the dimension of the space in which
- * this tensor operates. This of course equals the number of coordinates that
- * identify a point and rank-1 tensor.
- * @tparam Number The data type in which the tensor elements are
- * to be stored. This will, in almost all cases, simply be the default
- * @p double, but there are cases where one may want to store elements
- * in a different (and always scalar) type. It can be used to base
- * tensors on @p float or @p complex numbers or any other data type that
- * implements basic arithmetic operations.
- * Another example would be a type that allows for Automatic Differentiation
- * (see, for example, the Sacado type used in step-33) and thereby can
- * generate analytic (spatial) derivatives of a function that takes
- * a tensor as argument.
+ * this tensor operates. This of course equals the number of coordinates that
+ * identify a point and rank-1 tensor.
+ * @tparam Number The data type in which the tensor elements are to be stored.
+ * This will, in almost all cases, simply be the default @p double, but there
+ * are cases where one may want to store elements in a different (and always
+ * scalar) type. It can be used to base tensors on @p float or @p complex
+ * numbers or any other data type that implements basic arithmetic operations.
+ * Another example would be a type that allows for Automatic Differentiation
+ * (see, for example, the Sacado type used in step-33) and thereby can
+ * generate analytic (spatial) derivatives of a function that takes a tensor
+ * as argument.
*
* @ingroup geomprimitives
* @author Wolfgang Bangerth, 1998-2005
Tensor (const Tensor<1,dim,Number> &initializer);
/**
- * Copy constructor from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Copy constructor from tensors with different underlying scalar type. This
+ * obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
explicit
Tensor<1,dim,Number> &operator = (const Tensor<1,dim,Number> &rhs);
/**
- * Assignment operator from tensors with different underlying scalar
- * type. This obviously requires that the @p OtherNumber type is
- * convertible to @p Number.
+ * Assignment operator from tensors with different underlying scalar type.
+ * This obviously requires that the @p OtherNumber type is convertible to @p
+ * Number.
*/
template <typename OtherNumber>
Tensor<1,dim,Number> &operator = (const Tensor<1,dim,OtherNumber> &rhs);
* prohibited of considering this operator for multiplication with non-scalar
* types are explained in the documentation of the EnableIfScalar class.
*
- * The return type of the function is chosen so that it matches the types
- * of both the tensor and the scalar argument. For example, if you multiply
- * a <code>Tensor@<1,dim,double@></code> by <code>std::complex@<double@></code>,
- * then the result will be a <code>Tensor@<1,dim,std::complex@<double@>@></code>.
- * In other words, the type with which the returned tensor stores its
- * components equals the type you would get if you multiplied an individual
- * component of the input tensor by the scalar factor.
+ * The return type of the function is chosen so that it matches the types of
+ * both the tensor and the scalar argument. For example, if you multiply a
+ * <code>Tensor@<1,dim,double@></code> by <code>std::complex@<double@></code>,
+ * then the result will be a
+ * <code>Tensor@<1,dim,std::complex@<double@>@></code>. In other words, the
+ * type with which the returned tensor stores its components equals the type
+ * you would get if you multiplied an individual component of the input tensor
+ * by the scalar factor.
*
* @relates Tensor<1,dim,Number>
* @relates EnableIfScalar
* relies on the p4est library that does not support this. Attempts to
* refine cells anisotropically will result in errors.
*
- * @note There is
- * currently no support for distributing 1d triangulations.
+ * @note There is currently no support for distributing 1d triangulations.
*
*
* <h3> Interaction with boundary description </h3>
bool restriction_is_additive (const unsigned int index) const;
/**
- * Return a read only reference to the matrix that describes the
- * constraints at the interface between a refined and an unrefined cell.
- *
- * Some finite elements do not (yet) implement hanging node
- * constraints. If this is the case, then this function will generate an
- * exception, since no useful return value can be generated. If you should
- * have a way to live with this, then you might want to use the
- * constraints_are_implemented() function to check up front whether this
- * function will succeed or generate the exception.
+ * Return a read only reference to the matrix that describes the constraints
+ * at the interface between a refined and an unrefined cell.
+ *
+ * Some finite elements do not (yet) implement hanging node constraints. If
+ * this is the case, then this function will generate an exception, since no
+ * useful return value can be generated. If you should have a way to live
+ * with this, then you might want to use the constraints_are_implemented()
+ * function to check up front whether this function will succeed or generate
+ * the exception.
*/
const FullMatrix<double> &constraints (const dealii::internal::SubfaceCase<dim> &subface_case=dealii::internal::SubfaceCase<dim>::case_isotropic) const;
* linear combincation of them. Consequently, the linear functions are not
* within the range of the mapped $P_1$ polynomials.
*
- * <h3>Visualization of shape functions</h3>
- * In 2d, the shape functions of this element look as follows.
+ * <h3>Visualization of shape functions</h3> In 2d, the shape functions of
+ * this element look as follows.
*
* <h4>$P_0$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0000.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_0$ element, shape function 0 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_0$ element,
+ * shape function 0 </td>
*
- * <td align="center"></tr>
- * </table>
+ * <td align="center"></tr> </table>
*
* <h4>$P_1$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0002.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_1$ element, shape function 2 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_1$ element,
+ * shape function 2 </td>
*
* <td align="center"></td> </tr> </table>
*
*
* <h4>$P_2$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0005.png
* </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 4 </td>
*
- * <td align="center"> $P_2$ element, shape function 5 </td> </tr>
- * </table>
+ * <td align="center"> $P_2$ element, shape function 5 </td> </tr> </table>
*
*
* <h4>$P_3$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0009.png
* </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 8 </td>
*
- * <td align="center"> $P_3$ element, shape function 9 </td> </tr>
- * </table>
+ * <td align="center"> $P_3$ element, shape function 9 </td> </tr> </table>
*
*
- * <h4>$P_4$ element</h4>
- * <table> <tr>
- * <td align="center">
+ * <h4>$P_4$ element</h4> <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0014.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 14 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_4$ element,
+ * shape function 14 </td>
*
- * <td align="center"></td> </tr>
- * </table>
+ * <td align="center"></td> </tr> </table>
*
* @author Guido Kanschat, 2001, 2002, Ralf Hartmann 2004
*/
* within the range of the mapped $P_1$ polynomials.
*
*
- * <h3>Visualization of shape functions</h3>
- * In 2d, the shape functions of this element look as follows.
+ * <h3>Visualization of shape functions</h3> In 2d, the shape functions of
+ * this element look as follows.
*
* <h4>$P_0$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P1/P1_DGPMonomial_shape0000.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_0$ element, shape function 0 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_0$ element,
+ * shape function 0 </td>
*
- * <td align="center"></tr>
- * </table>
+ * <td align="center"></tr> </table>
*
* <h4>$P_1$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P1/P1_DGPMonomial_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P1/P1_DGPMonomial_shape0002.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_1$ element, shape function 2 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_1$ element,
+ * shape function 2 </td>
*
* <td align="center"></td> </tr> </table>
*
*
* <h4>$P_2$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P2/P2_DGPMonomial_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P2/P2_DGPMonomial_shape0005.png
* </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 4 </td>
*
- * <td align="center"> $P_2$ element, shape function 5 </td> </tr>
- * </table>
+ * <td align="center"> $P_2$ element, shape function 5 </td> </tr> </table>
*
*
* <h4>$P_3$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P3/P3_DGPMonomial_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P3/P3_DGPMonomial_shape0009.png
* </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 8 </td>
*
- * <td align="center"> $P_3$ element, shape function 9 </td> </tr>
- * </table>
+ * <td align="center"> $P_3$ element, shape function 9 </td> </tr> </table>
*
*
- * <h4>$P_4$ element</h4>
- * <table> <tr>
- * <td align="center">
+ * <h4>$P_4$ element</h4> <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P4/P4_DGPMonomial_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPMonomial/P4/P4_DGPMonomial_shape0014.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 14 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_4$ element,
+ * shape function 14 </td>
*
- * <td align="center"></td> </tr>
- * </table>
+ * <td align="center"></td> </tr> </table>
*
* @author Ralf Hartmann, 2004
*/
* (<tt>spacedim != dim</tt>).
*
*
- * <h3>Visualization of shape functions</h3>
- * In 2d, the shape functions of this element look as follows.
+ * <h3>Visualization of shape functions</h3> In 2d, the shape functions of
+ * this element look as follows.
*
* <h4>$P_0$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P1/P1_DGPNonparametric_shape0000.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_0$ element, shape function 0 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_0$ element,
+ * shape function 0 </td>
*
- * <td align="center"></tr>
- * </table>
+ * <td align="center"></tr> </table>
*
* <h4>$P_1$ element</h4>
*
- * <table>
- * <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P1/P1_DGPNonparametric_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P1/P1_DGPNonparametric_shape0002.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_1$ element, shape function 2 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_1$ element,
+ * shape function 2 </td>
*
* <td align="center"></td> </tr> </table>
*
*
* <h4>$P_2$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P2/P2_DGPNonparametric_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P2/P2_DGPNonparametric_shape0005.png
* </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 4 </td>
*
- * <td align="center"> $P_2$ element, shape function 5 </td> </tr>
- * </table>
+ * <td align="center"> $P_2$ element, shape function 5 </td> </tr> </table>
*
*
* <h4>$P_3$ element</h4>
*
- * <table> <tr>
- * <td align="center">
+ * <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P3/P3_DGPNonparametric_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P3/P3_DGPNonparametric_shape0009.png
* </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 8 </td>
*
- * <td align="center"> $P_3$ element, shape function 9 </td> </tr>
- * </table>
+ * <td align="center"> $P_3$ element, shape function 9 </td> </tr> </table>
*
*
- * <h4>$P_4$ element</h4>
- * <table> <tr>
- * <td align="center">
+ * <h4>$P_4$ element</h4> <table> <tr> <td align="center">
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P4/P4_DGPNonparametric_shape0000.png
* </td>
*
* @image html http://www.dealii.org/images/shape-functions/DGPNonparametric/P4/P4_DGPNonparametric_shape0014.png
* </td>
*
- * <td align="center">
- * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 14 </td>
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $P_4$ element,
+ * shape function 14 </td>
*
- * <td align="center"></td> </tr>
- * </table>
+ * <td align="center"></td> </tr> </table>
*
* @author Guido Kanschat, 2002
*/
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0001.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_1^H$ element, shape function 0 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_1^H$ element, shape function 0
+ * </td>
*
* <td align="center"> $Q_1^H$ element, shape function 1 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0003.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_1^H$ element, shape function 2 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_1^H$ element, shape function 2
+ * </td>
*
* <td align="center"> $Q_1^H$ element, shape function 3 </td> </tr> </table>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0001.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_2^H$ element, shape function 0 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_2^H$ element, shape function 0
+ * </td>
*
* <td align="center"> $Q_2^H$ element, shape function 1 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0003.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_2^H$ element, shape function 2 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_2^H$ element, shape function 2
+ * </td>
*
* <td align="center"> $Q_2^H$ element, shape function 3 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0005.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_2^H$ element, shape function 4 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_2^H$ element, shape function 4
+ * </td>
*
* <td align="center"> $Q_2^H$ element, shape function 5 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0007.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_2^H$ element, shape function 6 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_2^H$ element, shape function 6
+ * </td>
*
* <td align="center"> $Q_2^H$ element, shape function 7 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0001.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 0 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 0
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 1 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0003.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 2 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 2
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 3 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0005.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 4 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 4
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 5 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0007.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 6 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 6
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 7 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0009.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 8 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 8
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 9 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0011.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 10 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 10
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 11 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0013.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 12 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 12
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 13 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0015.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_3^H$ element, shape function 14 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_3^H$ element, shape function 14
+ * </td>
*
* <td align="center"> $Q_3^H$ element, shape function 15 </td> </tr> </table>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0001.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 0 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 0
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 1 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0003.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 2 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 2
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 3 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0005.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 4 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 4
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 5 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0007.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 6 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 6
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 7 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0009.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 8 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 8
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 9 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0011.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 10 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 10
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 11 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0013.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 12 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 12
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 13 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0015.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 14 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 14
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 15 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0017.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 16 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 16
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 17 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0019.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 18 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 18
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 19 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0021.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 20 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 20
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 21 </td> </tr>
*
*
* <td align="center">
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0023.png
- * </td> </tr> <tr> <td
- * align="center"> $Q_4^H$ element, shape function 22 </td>
+ * </td> </tr> <tr> <td align="center"> $Q_4^H$ element, shape function 22
+ * </td>
*
* <td align="center"> $Q_4^H$ element, shape function 23 </td> </tr>
*
public:
/**
- * Constructor. Take a finite element and the number of elements you
- * want to group together using this class.
+ * Constructor. Take a finite element and the number of elements you want to
+ * group together using this class.
*
- * The object @p fe is not actually used for anything other than creating
- * a copy that will then be owned by the current object. In other words,
- * it is completely fine to call this constructor with a temporary object
- * for the finite element, as in this code snippet:
+ * The object @p fe is not actually used for anything other than creating a
+ * copy that will then be owned by the current object. In other words, it is
+ * completely fine to call this constructor with a temporary object for the
+ * finite element, as in this code snippet:
* @code
* FESystem<dim> fe (FE_Q<dim>(2), 2);
* @endcode
- * Here, <code>FE_Q@<dim@>(2)</code> constructs an unnamed, temporary
- * object that is passed to the FESystem constructor to create a
- * finite element that consists of two components, both of which are
- * quadratic FE_Q elements. The temporary is destroyed again at the
- * end of the code that corresponds to this line, but this does not
- * matter because FESystem creates its own copy of the FE_Q object.
+ * Here, <code>FE_Q@<dim@>(2)</code> constructs an unnamed, temporary object
+ * that is passed to the FESystem constructor to create a finite element
+ * that consists of two components, both of which are quadratic FE_Q
+ * elements. The temporary is destroyed again at the end of the code that
+ * corresponds to this line, but this does not matter because FESystem
+ * creates its own copy of the FE_Q object.
*
* This constructor (or its variants below) is used in essentially all
* tutorial programs that deal with vector valued problems. See step-8,
*
* @dealiiVideoLecture{19,20}
*
- * @param[in] fe The finite element that will be used to represent
- * the components of this composed element.
- * @param[in] n_elements An integer denoting how many copies of
- * @p fe this element should consist of.
+ * @param[in] fe The finite element that will be used to represent the
+ * components of this composed element.
+ * @param[in] n_elements An integer denoting how many copies of @p fe this
+ * element should consist of.
*/
FESystem (const FiniteElement<dim,spacedim> &fe,
const unsigned int n_elements);
/**
* Constructor for mixed discretizations with two base elements.
*
- * See the other constructor above for an explanation of the
- * general idea of composing elements.
+ * See the other constructor above for an explanation of the general idea of
+ * composing elements.
*/
FESystem (const FiniteElement<dim,spacedim> &fe1, const unsigned int n1,
const FiniteElement<dim,spacedim> &fe2, const unsigned int n2);
/**
* Constructor for mixed discretizations with three base elements.
*
- * See the other constructor above for an explanation of the
- * general idea of composing elements.
+ * See the other constructor above for an explanation of the general idea of
+ * composing elements.
*/
FESystem (const FiniteElement<dim,spacedim> &fe1, const unsigned int n1,
const FiniteElement<dim,spacedim> &fe2, const unsigned int n2,
* @endcode
*
* If your compiler supports the C++11 language standard (or later) and
- * deal.II has been configured to use it, then you could do something
- * like this to create an element with four base elements and
- * multiplicities 1, 2, 3 and 4:
+ * deal.II has been configured to use it, then you could do something like
+ * this to create an element with four base elements and multiplicities 1,
+ * 2, 3 and 4:
* @code
* template <int dim>
* MySimulator<dim>::MySimulator (const unsigned int polynomial_degree)
* initializer list enclosed in braces <code>{ ... }</code>.
*
* This code has a problem: it creates four memory leaks because the first
- * vector above is created with pointers to elements that are allocated
- * with <code>new</code> but never destroyed. Without C++11, you have another
+ * vector above is created with pointers to elements that are allocated with
+ * <code>new</code> but never destroyed. Without C++11, you have another
* problem: brace-initializer don't exist in earlier C++ standards.
*
* The solution to the second of these problems is to create two static
* in 2D, etc) consisting of exactly one cell. The hypercube volume is the
* tensor product interval $[left,right]^{\text{dim}}$ in the present number
* of dimensions, where the limits are given as arguments. They default to
- * zero and unity, then producing the unit hypercube. If the argument
- * @p colorize is false, all boundary indicators are set to zero ("not
+ * zero and unity, then producing the unit hypercube. If the argument @p
+ * colorize is false, all boundary indicators are set to zero ("not
* colorized") for 2d and 3d. If it is true, the boundary is colorized as in
* hyper_rectangle(). In 1d the indicators are always colorized, see
* hyper_rectangle().
* vectors. Colorizing is done according to hyper_rectangle().
*
* @note This function silently reorders the vertices on the cells to
- * lexicographic ordering (see <code>GridReordering::reorder_grid</code>). In
- * other words, if reodering of the vertices does occur, the ordering of
+ * lexicographic ordering (see <code>GridReordering::reorder_grid</code>).
+ * In other words, if reodering of the vertices does occur, the ordering of
* vertices in the array of <code>corners</code> will no longer refer to the
* same triangulation.
*
const bool colorize = false);
/**
- * A subdivided parallelepiped, i.e., the same as above, but where the number
- * of subdivisions in each of the @p dim directions may vary. Colorizing is
- * done according to hyper_rectangle().
+ * A subdivided parallelepiped, i.e., the same as above, but where the
+ * number of subdivisions in each of the @p dim directions may vary.
+ * Colorizing is done according to hyper_rectangle().
*
* @note The triangulation needs to be void upon calling this function.
*/
* give the lower and upper bound of the inner hypercube in all coordinate
* directions. @p thickness marks the size of the layer cells.
*
- * If the flag @p colorize is set, the outer cells get material id's according
- * to the following scheme: extending over the inner cube in (+/-)
+ * If the flag @p colorize is set, the outer cells get material id's
+ * according to the following scheme: extending over the inner cube in (+/-)
* x-direction: 1/2. In y-direction 4/8, in z-direction 16/32. The cells at
* corners and edges (3d) get these values bitwise or'd.
*
* of cells of the resulting triangulation, i.e., how many cells form the
* ring (in 2d) or the shell (in 3d).
*
- * If the flag @p colorize is @p true, then the outer boundary will
- * have the indicator 1, while the inner boundary has id zero. In
- * 3d, this applies to both the faces and the edges of these
- * boundaries. If the flag is @p false, both have indicator zero.
+ * If the flag @p colorize is @p true, then the outer boundary will have the
+ * indicator 1, while the inner boundary has id zero. In 3d, this applies to
+ * both the faces and the edges of these boundaries. If the flag is @p
+ * false, both have indicator zero.
*
* In 2d, the number <tt>n_cells</tt> of elements for this initial
* triangulation can be chosen arbitrarily. If the number of initial cells
* The neighbor of a cell has at most the same level as this cell. For
* example, consider the following situation:
* @image html limit_level_difference_at_vertices.png ""
- * Here, if you are on the top right cell and you ask for its left
- * neighbor (which is, according to the conventions spelled out in the
- * GeometryInfo class, its <i>zeroth</i> neighbor), then you will get
- * the mother cell of the four small cells at the top left. In other
- * words, the cell you get as neighbor has the same refinement level
- * as the one you're on right now (the top right one) and it may have
- * children.
- *
- * On the other hand, if you were at the top right cell of the four
- * small cells at the top left, and you asked for the right neighbor
- * (which is associated with index <code>i=1</code>), then you would
- * get the large cell at the top right which in this case has
- * a lower refinement level and no children of its own.
+ * Here, if you are on the top right cell and you ask for its left neighbor
+ * (which is, according to the conventions spelled out in the GeometryInfo
+ * class, its <i>zeroth</i> neighbor), then you will get the mother cell of
+ * the four small cells at the top left. In other words, the cell you get as
+ * neighbor has the same refinement level as the one you're on right now
+ * (the top right one) and it may have children.
+ *
+ * On the other hand, if you were at the top right cell of the four small
+ * cells at the top left, and you asked for the right neighbor (which is
+ * associated with index <code>i=1</code>), then you would get the large
+ * cell at the top right which in this case has a lower refinement level and
+ * no children of its own.
*/
TriaIterator<CellAccessor<dim, spacedim> >
neighbor (const unsigned int i) const;
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or from a stream for the
- * purpose of serialization
- */
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
+ */
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or from a stream for the
- * purpose of serialization
- */
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
+ */
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or from a stream for the
- * purpose of serialization
- */
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
+ */
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or from a stream for the
- * purpose of serialization
- */
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
+ */
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
virtual std::size_t memory_consumption () const;
/**
- * Write the data of this object to a stream for the purpose of
- * serialization.
- */
+ * Write the data of this object to a stream for the purpose of
+ * serialization.
+ */
template <class Archive>
void save(Archive &ar, const unsigned int version) const;
/**
- * Read the data of this object from a stream for the purpose of
- * serialization.
- */
+ * Read the data of this object from a stream for the purpose of
+ * serialization.
+ */
template <class Archive>
void load(Archive &ar, const unsigned int version);
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or from a stream for the
- * purpose of serialization
- */
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
+ */
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
* @line Growing
*
* Now, we are ready to build a <i>2x2</i> BlockMatrixArray.
- * @line Block
- * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left
- * block
- * @line enter
- * Now -1 times <tt>B1</tt> in the upper right block.
- * @line enter
- * We add the transpose of <tt>B2</tt> to the upper right block and
- * continue in a similar fashion. In the end, the block matrix structure is
- * printed into an LaTeX table.
+ * @line Block First, we enter the matrix <tt>A</tt> multiplied by 2 in the
+ * upper left block
+ * @line enter Now -1 times <tt>B1</tt> in the upper right block.
+ * @line enter We add the transpose of <tt>B2</tt> to the upper right block
+ * and continue in a similar fashion. In the end, the block matrix structure
+ * is printed into an LaTeX table.
* @until latex
*
* Now, we set up vectors to be multiplied with this matrix and do a
/**
- * Condense a sparsity pattern. The name of the function mimics the
- * name of the function we use to condense linear systems, but it is
- * a bit of a misnomer for the current context. This is because in
- * the context of linear systems, we eliminate certain rows and
- * columns of the linear system, i.e., we "reduce" or "condense" the
- * linear system. On the other hand, in the current context, the
- * functions does not remove nonzero entries from the sparsity
- * pattern. Rather, it adds those nonzero entry locations to the
- * sparsity pattern that will later be needed for the process of
- * condensation of constrained degrees of freedom from a linear
+ * Condense a sparsity pattern. The name of the function mimics the name of
+ * the function we use to condense linear systems, but it is a bit of a
+ * misnomer for the current context. This is because in the context of
+ * linear systems, we eliminate certain rows and columns of the linear
+ * system, i.e., we "reduce" or "condense" the linear system. On the other
+ * hand, in the current context, the functions does not remove nonzero
+ * entries from the sparsity pattern. Rather, it adds those nonzero entry
+ * locations to the sparsity pattern that will later be needed for the
+ * process of condensation of constrained degrees of freedom from a linear
* system.
*
- * Since this function adds new nonzero entries to the sparsity
- * pattern, the given sparsity pattern must not be compressed. The
- * constraint matrix (i.e., the current object) must be closed. The
- * sparsity pattern is compressed at the end of the function.
+ * Since this function adds new nonzero entries to the sparsity pattern, the
+ * given sparsity pattern must not be compressed. The constraint matrix
+ * (i.e., the current object) must be closed. The sparsity pattern is
+ * compressed at the end of the function.
*/
void condense (SparsityPattern &sparsity) const;
void condense (BlockCompressedSimpleSparsityPattern &sparsity) const;
/**
- * Condense a given matrix, i.e., eliminate the rows and columns of
- * the matrix that correspond to constrained degrees of freedom.
+ * Condense a given matrix, i.e., eliminate the rows and columns of the
+ * matrix that correspond to constrained degrees of freedom.
*
- * See the general documentation of this
- * class for more detailed information.
+ * See the general documentation of this class for more detailed
+ * information.
*/
template<typename number>
void condense (SparseMatrix<number> &matrix) const;
VectorType &output) const;
/**
- * Condense a given matrix and a given vector by eliminating rows
- * and columns of the linear system that correspond to constrained
- * degrees of freedom. The sparsity pattern associated with the
- * matrix needs to be condensed and compressed. This function is
- * the appropriate choice for applying inhomogeneous constraints.
+ * Condense a given matrix and a given vector by eliminating rows and
+ * columns of the linear system that correspond to constrained degrees of
+ * freedom. The sparsity pattern associated with the matrix needs to be
+ * condensed and compressed. This function is the appropriate choice for
+ * applying inhomogeneous constraints.
*
* The constraint matrix object must be closed to call this function.
*
- * See the general documentation of this
- * class for more detailed information.
+ * See the general documentation of this class for more detailed
+ * information.
*/
template<typename number, class VectorType>
void condense (SparseMatrix<number> &matrix,
* Apply the constraints to a right hand side vector. This needs to be done
* before starting to solve with the filtered matrix. If the matrix is
* symmetric (i.e. the matrix itself, not only its sparsity pattern), set
- * the second parameter to @p true to use a faster algorithm.
- * Note: This method is deprecated as matrix_is_symmetric parameter is no longer used.
+ * the second parameter to @p true to use a faster algorithm. Note: This
+ * method is deprecated as matrix_is_symmetric parameter is no longer used.
*/
void apply_constraints (VECTOR &v,
const bool matrix_is_symmetric) const DEAL_II_DEPRECATED;
/**
* Assignment operator from a regular FullMatrix.
*
- * @note Since LAPACK expects
- * matrices in transposed order, this transposition is included here.
+ * @note Since LAPACK expects matrices in transposed order, this
+ * transposition is included here.
*/
template <typename number2>
LAPACKFullMatrix<number> &
/**
* Assignment operator from a regular SparseMatrix.
*
- * @note Since LAPACK
- * expects matrices in transposed order, this transposition is included
- * here.
+ * @note Since LAPACK expects matrices in transposed order, this
+ * transposition is included here.
*/
template <typename number2>
LAPACKFullMatrix<number> &
/**
* Return the dimension of the range space.
*
- * @note The matrix is of dimension
- * $m \times n$.
+ * @note The matrix is of dimension $m \times n$.
*/
unsigned int m () const;
/**
* Return the number of the range space.
*
- * @note The matrix is of dimension $m
- * \times n$.
+ * @note The matrix is of dimension $m \times n$.
*/
unsigned int n () const;
* eigenvalues and the corresponding eigenvectors will be stored in the
* columns of eigenvectors, whose dimension is set accordingly.
*
- * @note Calls the LAPACK function Xsyevx. For this to work, deal.II must
- * be configured to use LAPACK.
+ * @note Calls the LAPACK function Xsyevx. For this to work, deal.II must be
+ * configured to use LAPACK.
*/
void compute_eigenvalues_symmetric (const number lower_bound,
const number upper_bound,
* eigenvalues and the corresponding eigenvectors will be stored in
* eigenvectors, whose dimension is set accordingly.
*
- * @note Calls the LAPACK function Xsygvx. For this to work, deal.II must
- * be configured to use LAPACK.
+ * @note Calls the LAPACK function Xsygvx. For this to work, deal.II must be
+ * configured to use LAPACK.
*/
void compute_generalized_eigenvalues_symmetric (LAPACKFullMatrix<number> &B,
const number lower_bound,
* be retrieved using the eigenvalue() function. The number of computed
* eigenvectors is equal to eigenvectors.size()
*
- * @note Calls the LAPACK function Xsygv. For this to work, deal.II must
- * be configured to use LAPACK.
+ * @note Calls the LAPACK function Xsygv. For this to work, deal.II must be
+ * configured to use LAPACK.
*/
void compute_generalized_eigenvalues_symmetric (LAPACKFullMatrix<number> &B,
std::vector<Vector<number> > &eigenvectors,
* value (@p NaN). Note, however, that this check is only performed if the
* @p isnan function is provided by the operating system, which is not
* always true. CMake checks this with the 'check_01_cxx_features.cmake'
- * test and sets the flag
- * @p DEAL_II_HAVE_ISNAN in the include file <tt>deal.II/base/config.h</tt>
- * if this function was found.
+ * test and sets the flag @p DEAL_II_HAVE_ISNAN in the include file
+ * <tt>deal.II/base/config.h</tt> if this function was found.
*
* <tt>check()</tt> additionally preserves @p step and @p check_value. These
* values are accessible by <tt>last_value()</tt> and <tt>last_step()</tt>.
* preconditioner.
*
* FGMRES needs two vectors in each iteration steps yielding a total of
- * <tt>2*SolverFGMRES::AdditionalData::max_basis_size+1</tt> auxiliary vectors.
+ * <tt>2*SolverFGMRES::AdditionalData::max_basis_size+1</tt> auxiliary
+ * vectors.
*
* Caveat: Documentation of this class is not up to date. There are also a few
* parameters of GMRES we would like to introduce here.
void sort_arrays (const BlockSparseMatrix<number> &);
/**
- * The arrays in which we store the data for the solver.
- * SuiteSparse_long has to be used here for Windows 64 build,
- * if we used only long int, compilation would fail.
+ * The arrays in which we store the data for the solver. SuiteSparse_long
+ * has to be used here for Windows 64 build, if we used only long int,
+ * compilation would fail.
*/
std::vector<SuiteSparse_long> Ap;
std::vector<SuiteSparse_long> Ai;
* Let a symmetric, positive-definite, sparse matrix $A$ be in the form $A = D
* - L - L^T$, where $D$ is the diagonal part of $A$ and $-L$ is a strictly
* lower triangular matrix. The MIC(0) decomposition of the matrix $A$ is
- * defined by $B = (X-L)X^{-1}(X-L^T)$, where $X$ is a diagonal matrix
- * defined by the condition $\text{rowsum}(A) = \text{rowsum}(B)$.
+ * defined by $B = (X-L)X^{-1}(X-L^T)$, where $X$ is a diagonal matrix defined
+ * by the condition $\text{rowsum}(A) = \text{rowsum}(B)$.
*
* @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf Hartmann
* 2003.
/**
- * A wrapper class for an incomplete LU factorization (ILU(k)) preconditioner
- * for Trilinos matrices. This preconditioner works both in serial and in
- * parallel, depending on the matrix it is based on. In general, an
- * incomplete factorization does not take all fill-in elements that would
- * appear in a full factorization (that is the basis for a direct solve).
- * Trilinos allows to set the amount of fill-in elements, governed by the
- * additional data argument <tt>ilu_fill</tt>, so one can gradually choose
- * between a factorization on the sparse matrix structure only
+ * A wrapper class for an incomplete LU factorization (ILU(k))
+ * preconditioner for Trilinos matrices. This preconditioner works both in
+ * serial and in parallel, depending on the matrix it is based on. In
+ * general, an incomplete factorization does not take all fill-in elements
+ * that would appear in a full factorization (that is the basis for a direct
+ * solve). Trilinos allows to set the amount of fill-in elements, governed
+ * by the additional data argument <tt>ilu_fill</tt>, so one can gradually
+ * choose between a factorization on the sparse matrix structure only
* (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in the
* range of 10 to 50, depending on the spatial dimension of the PDE problem
* and the degree of the finite element basis functions; generally, more
* required fill-in elements require this parameter to be set to a higher
* integer value).
*
- * The AdditionalData data structure allows to set preconditioner
- * options. See the documentation of the AdditionalData structure for
- * details.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * See the documentation of the AdditionalData structure for details.
*
* Note that a parallel application of the ILU preconditioner is actually a
* block-Jacobi preconditioner with block size equal to the local matrix
*
* <li> @p ilu_fill: This specifies the amount of additional fill-in
* elements besides the original sparse matrix structure. If $k$ is @p
- * fill, the sparsity pattern of $A^{k+1}$ is used for the storage of
- * the result of the Gaussian elemination. This is known as ILU($k$) in
- * the literature. When @p fill is large, the preconditioner comes
- * closer to a (direct) sparse LU decomposition. Note, however, that this
- * will drastically increase the memory requirement, especially when the
+ * fill, the sparsity pattern of $A^{k+1}$ is used for the storage of the
+ * result of the Gaussian elemination. This is known as ILU($k$) in the
+ * literature. When @p fill is large, the preconditioner comes closer to
+ * a (direct) sparse LU decomposition. Note, however, that this will
+ * drastically increase the memory requirement, especially when the
* preconditioner is used in 3D.
*
* <li> @p ilu_atol and @p ilu_rtol: These two parameters allow
* perturbation of the diagonal of the matrix, which sometimes can help to
- * get better preconditioners especially in the case of bad
- * conditioning. Before factorization, the diagonal entry $a_{ii}$ is
- * replaced by $\alpha sign(a_{ii}) + \beta a_{ii}$, where $\alpha\geq 0$
- * is the absolute threshold @p ilu_atol and $\beta\geq 1$ is the relative
+ * get better preconditioners especially in the case of bad conditioning.
+ * Before factorization, the diagonal entry $a_{ii}$ is replaced by
+ * $\alpha sign(a_{ii}) + \beta a_{ii}$, where $\alpha\geq 0$ is the
+ * absolute threshold @p ilu_atol and $\beta\geq 1$ is the relative
* threshold @p ilu_rtol. The default values ($\alpha = 0$, $\beta = 1$)
* therefore use the original, unmodified diagonal entry. Suggested values
* are in the order of $10^{-5}$ to $10^{-2}$ for @p ilu_atol and 1.01 for
* @p ilu_rtol.
*
* <li> @p overlap: This determines how large the overlap of the local
- * matrix portions on each processor in a parallel application should
- * be. An overlap of 0 corresponds to a block diagonal decomposition on
- * each processor, an overlap of 1 will additionally include a row j if
- * there is a nonzero entry in column j in one of the own rows. Higher
- * overlap numbers work accordingly in a recursive fashion. Increasing @p
- * overlap will increase communication and storage cost. According to the
- * IFPACK documentation, an overlap of 1 is often effective and values of
- * more than 3 are rarely needed.
+ * matrix portions on each processor in a parallel application should be.
+ * An overlap of 0 corresponds to a block diagonal decomposition on each
+ * processor, an overlap of 1 will additionally include a row j if there
+ * is a nonzero entry in column j in one of the own rows. Higher overlap
+ * numbers work accordingly in a recursive fashion. Increasing @p overlap
+ * will increase communication and storage cost. According to the IFPACK
+ * documentation, an overlap of 1 is often effective and values of more
+ * than 3 are rarely needed.
*/
struct AdditionalData
{
* range in @p cell_loop runs from zero to n_macro_cells() (exclusive), so
* this is the appropriate size if you want to store arrays of data for all
* cells to be worked on. This number is approximately
- * n_physical_cells()/VectorizedArray::n_array_elements (depending
- * on how many cell chunks that do not get filled up completely).
+ * n_physical_cells()/VectorizedArray::n_array_elements (depending on how
+ * many cell chunks that do not get filled up completely).
*/
unsigned int n_macro_cells () const;
/**
* The degrees of freedom on the refinement edges. For each level the index
- * set denotes which level
- * degrees of freedom are on the refinement edge towards the lower level,
- * excluding boundary dofs.
+ * set denotes which level degrees of freedom are on the refinement edge
+ * towards the lower level, excluding boundary dofs.
*/
std::vector<IndexSet> interface_dofs;
* This is the central function of this class since it builds the list of
* patches to be written by the low-level functions of the base class. A
* patch is, in essence, some intermediate representation of the data on
- * each cell of a triangulation and DoFHandler object that can then be
- * used to write files in some format that is readable by visualization
- * programs.
+ * each cell of a triangulation and DoFHandler object that can then be used
+ * to write files in some format that is readable by visualization programs.
*
- * You can find an overview of the use of this function in
- * the general documentation of this class. An example is also provided in
- * the documentation of this class's base class DataOut_DoFData.
+ * You can find an overview of the use of this function in the general
+ * documentation of this class. An example is also provided in the
+ * documentation of this class's base class DataOut_DoFData.
*
* @param n_subdivisions A parameter that determines how many "patches" this
- * function will build out of every cell. If you do not specify this
- * value in calling, or provide the default value zero, then this is
- * interpreted as DataOutInterface::default_subdivisions which most of
- * the time will be equal to one (unless you have set it to something else).
- * The purpose of this parameter is to subdivide each cell of the mesh
- * into $2\times 2, 3\times 3, \ldots$ "patches" in 2d, and
- * $2\times 2\times 2, 3\times 3\times 3, \ldots$ (if passed the value
- * 2, 3, etc) where each patch represents the data from a regular subdivision
- * of the cell into equal parts. Most of the times, this is not necessary
- * and outputting one patch per cell is exactly what you want to plot
- * the solution. That said, the data we write into files for visualization
- * can only represent (bi-, tri)linear data on each cell, and most
- * visualization programs can in fact only visualize this kind of data.
- * That's good enough if you work with (bi-, tri)linear finite elements,
- * in which case what you get to see is exactly what has been computed.
- * On the other hand, if you work with (bi-, tri)quadratic elements, then
- * what is written into the output file is just a (bi-, tri)linear
- * interpolation onto the current mesh, i.e., only the values at the
- * vertices. If this is not good enough, you can, for example, specify
- * @p n_subdivisions equal to 2 to plot the solution on a once-refined
- * mesh, or if set to 3, on a mesh where each cell is represented by
- * 3-by-3 patches. On each of these smaller patches, given the limitations
- * of output formats, the data is still linearly interpolated, but a
- * linear interpolation of quadratic data on a finer mesh is still a
- * better representation of the actual quadratic surface than on the
- * original mesh. In other words, using this parameter can not help
- * you plot the solution exactly, but it can get you closer if you
- * use finite elements of higher polynomial degree.
+ * function will build out of every cell. If you do not specify this value
+ * in calling, or provide the default value zero, then this is interpreted
+ * as DataOutInterface::default_subdivisions which most of the time will be
+ * equal to one (unless you have set it to something else). The purpose of
+ * this parameter is to subdivide each cell of the mesh into $2\times 2,
+ * 3\times 3, \ldots$ "patches" in 2d, and $2\times 2\times 2, 3\times
+ * 3\times 3, \ldots$ (if passed the value 2, 3, etc) where each patch
+ * represents the data from a regular subdivision of the cell into equal
+ * parts. Most of the times, this is not necessary and outputting one patch
+ * per cell is exactly what you want to plot the solution. That said, the
+ * data we write into files for visualization can only represent (bi-,
+ * tri)linear data on each cell, and most visualization programs can in fact
+ * only visualize this kind of data. That's good enough if you work with
+ * (bi-, tri)linear finite elements, in which case what you get to see is
+ * exactly what has been computed. On the other hand, if you work with (bi-,
+ * tri)quadratic elements, then what is written into the output file is just
+ * a (bi-, tri)linear interpolation onto the current mesh, i.e., only the
+ * values at the vertices. If this is not good enough, you can, for example,
+ * specify @p n_subdivisions equal to 2 to plot the solution on a once-
+ * refined mesh, or if set to 3, on a mesh where each cell is represented by
+ * 3-by-3 patches. On each of these smaller patches, given the limitations
+ * of output formats, the data is still linearly interpolated, but a linear
+ * interpolation of quadratic data on a finer mesh is still a better
+ * representation of the actual quadratic surface than on the original mesh.
+ * In other words, using this parameter can not help you plot the solution
+ * exactly, but it can get you closer if you use finite elements of higher
+ * polynomial degree.
*/
virtual void build_patches (const unsigned int n_subdivisions = 0);
* @ref step_22 "step-22"
* tutorial program).
*
- * This class does not copy the vector given to it
- * through the add_data_vector() functions, for memory consumption reasons. It
- * only stores a reference to it, so it is in your responsibility to make sure
- * that the data vectors exist long enough.
+ * This class does not copy the vector given to it through the
+ * add_data_vector() functions, for memory consumption reasons. It only stores
+ * a reference to it, so it is in your responsibility to make sure that the
+ * data vectors exist long enough.
*
* After adding all data vectors, you need to call a function which generates
* the patches (i.e., some intermediate data representation) for output from
- * the stored data. Derived classes name this
- * function build_patches(). Finally, you write() the data in one format or
- * other, to a file.
+ * the stored data. Derived classes name this function build_patches().
+ * Finally, you write() the data in one format or other, to a file.
*
- * In the example above, an object of type DataOut was used,
- * i.e. an object of a derived class. This is necessary since the current class does
- * not provide means to actually generate the patches, only aids to store and
- * access data. Any real functionality is implemented in derived classes such
- * as DataOut.
+ * In the example above, an object of type DataOut was used, i.e. an object of
+ * a derived class. This is necessary since the current class does not provide
+ * means to actually generate the patches, only aids to store and access data.
+ * Any real functionality is implemented in derived classes such as DataOut.
*
* Note that the base class of this class, DataOutInterface offers several
* functions to ease programming with run-time determinable output formats
*
* <h3>Information for derived classes</h3>
*
- * What this class lacks is a way to produce the patches for
- * output itself, from the stored data and degree of freedom information.
- * Since this task is often application dependent it is left to derived
- * classes. For example, in many applications, it might be wanted to limit the
- * depth of output to a certain number of refinement levels and write data
- * from finer cells only in a way interpolated to coarser cells, to reduce the
- * amount of output. Also, it might be wanted to use different numbers of
- * subdivisions on different cells when forming a patch, for example to
- * accomplish for different polynomial degrees of the trial space on different
- * cells. Also, the output need not necessarily consist of a patch for each
- * cell, but might be made up of patches for faces, of other things. Take a
- * look at derived classes to what is possible in this respect.
+ * What this class lacks is a way to produce the patches for output itself,
+ * from the stored data and degree of freedom information. Since this task is
+ * often application dependent it is left to derived classes. For example, in
+ * many applications, it might be wanted to limit the depth of output to a
+ * certain number of refinement levels and write data from finer cells only in
+ * a way interpolated to coarser cells, to reduce the amount of output. Also,
+ * it might be wanted to use different numbers of subdivisions on different
+ * cells when forming a patch, for example to accomplish for different
+ * polynomial degrees of the trial space on different cells. Also, the output
+ * need not necessarily consist of a patch for each cell, but might be made up
+ * of patches for faces, of other things. Take a look at derived classes to
+ * what is possible in this respect.
*
* For this reason, it is left to a derived class to provide a function, named
* usually build_patches() or the like, which fills the #patches array of this
* This is the central function of this class since it builds the list of
* patches to be written by the low-level functions of the base class. A
* patch is, in essence, some intermediate representation of the data on
- * each face of a triangulation and DoFHandler object that can then be
- * used to write files in some format that is readable by visualization
- * programs.
+ * each face of a triangulation and DoFHandler object that can then be used
+ * to write files in some format that is readable by visualization programs.
*
- * You can find an overview of the use of this function in
- * the general documentation of this class. An example is also provided in
- * the documentation of this class's base class DataOut_DoFData.
+ * You can find an overview of the use of this function in the general
+ * documentation of this class. An example is also provided in the
+ * documentation of this class's base class DataOut_DoFData.
*
* @param n_subdivisions See DataOut::build_patches() for an extensive
- * description of this parameter.
+ * description of this parameter.
*/
virtual void
build_patches (const unsigned int n_subdivisions = 0);
* This is the central function of this class since it builds the list of
* patches to be written by the low-level functions of the base class. A
* patch is, in essence, some intermediate representation of the data on
- * each cell of a triangulation and DoFHandler object that can then be
- * used to write files in some format that is readable by visualization
- * programs.
+ * each cell of a triangulation and DoFHandler object that can then be used
+ * to write files in some format that is readable by visualization programs.
*
- * You can find an overview of the use of this function in
- * the general documentation of this class. An example is also provided in
- * the documentation of this class's base class DataOut_DoFData.
+ * You can find an overview of the use of this function in the general
+ * documentation of this class. An example is also provided in the
+ * documentation of this class's base class DataOut_DoFData.
*
- * @param n_patches_per_circle Denotes into how many intervals
- * the angular (rotation) variable is to be subdivided.
+ * @param n_patches_per_circle Denotes into how many intervals the angular
+ * (rotation) variable is to be subdivided.
*
* @param n_subdivisions See DataOut::build_patches() for an extensive
- * description of this parameter.
+ * description of this parameter.
*/
virtual void build_patches (const unsigned int n_patches_per_circle,
const unsigned int n_subdivisions = 0);
* This is the central function of this class since it builds the list of
* patches to be written by the low-level functions of the base class. A
* patch is, in essence, some intermediate representation of the data on
- * each cell of a triangulation and DoFHandler object that can then be
- * used to write files in some format that is readable by visualization
- * programs.
+ * each cell of a triangulation and DoFHandler object that can then be used
+ * to write files in some format that is readable by visualization programs.
*
- * You can find an overview of the use of this function in
- * the general documentation of this class. An example is also provided in
- * the documentation of this class's base class DataOut_DoFData.
+ * You can find an overview of the use of this function in the general
+ * documentation of this class. An example is also provided in the
+ * documentation of this class's base class DataOut_DoFData.
*
* @param n_subdivisions See DataOut::build_patches() for an extensive
- * description of this parameter. The number of subdivisions is always
- * one in the direction of the time-like parameter used by this class.
+ * description of this parameter. The number of subdivisions is always one
+ * in the direction of the time-like parameter used by this class.
*/
void build_patches (const unsigned int n_subdivisions = 0);
*
* @note To C++,
* <code>Functions::FEFieldFunction<dim>::ExcPointNotAvailableHere</code>
- * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>, TrilinosWrappers::MPI::Vector>::ExcPointNotAvailableHere</code>
- * are distinct types. You
- * need to make sure that the type of the exception you catch matches the
- * type of the object that throws it, as shown in the example above.
+ * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>,
+ * TrilinosWrappers::MPI::Vector>::ExcPointNotAvailableHere</code> are
+ * distinct types. You need to make sure that the type of the exception you
+ * catch matches the type of the object that throws it, as shown in the
+ * example above.
*
* @ingroup functions
* @author Luca Heltai, 2006, Markus Buerg, 2012, Wolfgang Bangerth, 2013
* @param[in] weight The additional argument @p weight allows to evaluate
* weighted norms. The weight function may be scalar, establishing a
* spatially variable weight in the domain for all components equally. This
- * may be used, for instance, to only integrate over parts of the
- * domain. The weight function may also be vector-valued, with as many
- * components as the finite element: Then, different components get
- * different weights. A typical application is when the error with respect
- * to only one or a subset of the solution variables is to be computed, in
- * which case the other components would have weight values equal to
- * zero. The ComponentSelectFunction class is particularly useful for this
- * purpose as it provides such a "mask" weight. The weight function is
- * expected to be positive, but negative values are not filtered. The
- * default value of this function, a null pointer, is interpreted as "no
- * weighting function", i.e., weight=1 in the whole domain for all vector
- * components uniformly.
+ * may be used, for instance, to only integrate over parts of the domain.
+ * The weight function may also be vector-valued, with as many components as
+ * the finite element: Then, different components get different weights. A
+ * typical application is when the error with respect to only one or a
+ * subset of the solution variables is to be computed, in which case the
+ * other components would have weight values equal to zero. The
+ * ComponentSelectFunction class is particularly useful for this purpose as
+ * it provides such a "mask" weight. The weight function is expected to be
+ * positive, but negative values are not filtered. The default value of this
+ * function, a null pointer, is interpreted as "no weighting function",
+ * i.e., weight=1 in the whole domain for all vector components uniformly.
* @param[in] exponent This value denotes the $p$ used in computing
* $L^p$-norms and $W^{1,p}$-norms. The value is ignores if a @p norm other
* than NormType::Lp_norm or NormType::W1p_norm is chosen.