From: kanschat Date: Mon, 20 Dec 2010 19:06:31 +0000 (+0000) Subject: update documentation X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4809228f43a90737e4292c04497895efb9063e5d;p=dealii-svn.git update documentation git-svn-id: https://svn.dealii.org/trunk@23030 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/doxygen/headers/matrices.h b/deal.II/doc/doxygen/headers/matrices.h index 794881e1c1..351b28180c 100644 --- a/deal.II/doc/doxygen/headers/matrices.h +++ b/deal.II/doc/doxygen/headers/matrices.h @@ -37,6 +37,62 @@ * @ingroup LAC */ +/** + * Template for matrix classes. + * + * @note This is a description of the expectations on the MATRIX + * template argument. It is not a class by itself. + * + * Depending on where the MATRIX is used, its interface is expected to + * conform to one of the following groups, which can also be found in + * the overview. + * + *

Solver interface

+ * + * Functions in this group are the minimal interface to use the MATRIX + * in a linear Solver. Solvers use a matrix only as a linear operator, + * that is, they map a vector to another. To this end, we either + * multiply with the matrix itself or its transpose. + * + * The function vmult() is the bare necessity in this group. Some + * solvers use Tvmult() as well, in which case it needs to be + * implemented. Some derived matrices like PointerMatrix require its + * existence, in which case it can be implemented empty with an + * assertion Assert(false, ExcNotImplemented()). + * + * If vmult_add() and Tvmult_add() are missing, PointerMatrixAux can + * be used to provide the missing functionality without implementing + * it by hand. + * + * @ingroup LAC + */ +template +class MATRIX +{ + public: + /** + * @name Solver interface + */ + /*@{*/ + /** + * The matrix vector product $u = Av$. + */ + void vmult(VECTOR& u, const VECTOR& v) const; + /** + * The matrix vector product $u = A^Tv$. + */ + void Tvmult(VECTOR& u, const VECTOR& v) const; + /** + * The matrix vector product $u += Av$. + */ + void vmult_add(VECTOR& u, const VECTOR& v) const; + /** + * The matrix vector product $u += A^Tv$. + */ + void Tvmult_add(VECTOR& u, const VECTOR& v) const; + /*@}*/ +}; + /** * @defgroup Matrix1 Basic matrices * diff --git a/deal.II/include/deal.II/fe/mapping.h b/deal.II/include/deal.II/fe/mapping.h index b6237a6a67..05bb02b1d7 100644 --- a/deal.II/include/deal.II/fe/mapping.h +++ b/deal.II/include/deal.II/fe/mapping.h @@ -124,6 +124,77 @@ enum MappingType * fill_fe_*_values with the result of @p update_each to compute * values for a special cell. * + *

Mathematics of the mapping

+ * + * The mapping is a transformation $\mathbf x = \Phi(\mathbf{\hat x})$ + * which maps the reference cell [0,1]dim to the actual + * grid cell. In order to describe the application of the mapping to + * different objects, we introduce the notation for the Jacobian + * $J(\mathbf{\hat x}) = \nabla\Phi(\mathbf{\hat x})$. For instance, + * in two dimensions, we have + * @f[ + * J(\mathbf{\hat x}) = \begin{matrix} + * \frac{\partial x}{\partial \hat x} & \frac{\partial x}{\partial \hat y} + * \\ + * \frac{\partial y}{\partial \hat x} & \frac{\partial y}{\partial \hat y} + * \end{matrix} + * @f] + * + *

Mapping of functions

+ * + * Functions are simply mapped such that + * @f[ + * u(\mathbf x) = u\bigl(\Phi(\mathbf{\hat x})\bigr) + * = \hat u(\mathbf{\hat x}). + * @f] + * Since finite element shape functions are usually defined on the + * reference cell, nothing needs to be done for them. For a function + * defined on the computational domain, the quadrature points need to + * be mapped, which is done in fill_fe_values() if + * #update_quadrature_points is set in the update flags. The mapped + * quadrature points are then accessed through FEValuesBase::quadrature_point(). + * + * @todo Add a function transform_quadrature_points for this. + * + *

Mapping of integrals

+ * + * The volume form $d\hat x$ is mapped such that for a grid cell Z + * @f[ + * \int_Z u(\mathbf x)\,d\mathbf x = \int_{\hat Z} \hat + * u(\mathbf{\hat x}) \left|\text{det}J(\mathbf{\hat x})\right| + * \,d\mathbf{\hat x}. + * @f] + * + * The transformed quadrature weights $\left|\text{det}J(\mathbf{\hat + * x})\right|$ are accessed through FEValuesBase::JxW() and + * computed in fill_fe_values(), if #update_JxW_values is set in the + * update flags. + * + * @todo Add a function transform_quadrature_weights for + * this. + * + * @todo Add documentation on the codimension-one case + * + *

Mapping of vector fields and tensor fields

+ * + * Mappings of a vector field v and a tensor field T + * follows the general form + * + * @f[ + * \mathbf v(\mathbf x) = \mathbf A(\mathbf{\hat x}) + * \mathbf{\hat v}(\mathbf{\hat x}), + * \qquad + * \mathbf v(\mathbf x) = \mathbf A(\mathbf{\hat x}) + * \mathbf{\hat T}(\mathbf{\hat x}) \mathbf B(\mathbf{\hat x}), + * @f] + * respectively, where the tensors A and B are + * determined by the MappingType enumerator. + * These transformations are performed through the two functions + * transform(). See the documentation there for possible + * choices. + * + *

Technical notes

+ * * A hint to implementators: no function except the two functions * @p update_once and @p update_each may add any flags. * @@ -131,6 +202,20 @@ enum MappingType * check the documentation of FiniteElement or the one of * Triangulation. * + *

References

+ * + * A general publication on differential geometry and finite elements + * is the survey + * + * The description of the Piola transform has been taken from the lecture + * notes by Ronald H. W. Hoppe, University of Houston, Chapter 7. + * * @ingroup mapping * @author Guido Kanschat, Ralf Hartmann 2000, 2001 */ @@ -336,11 +421,49 @@ class Mapping : public Subscriptor bool first_cell; }; - /** - * Transform a field of - * vectors accorsing to - * the selected MappingType. - */ +/** + * Transform a field of vectors or forms according to the selected + * MappingType. + * + * @note Normally, this function is called by a finite element, + * filling FEValues objects. For this finite element, there should be + * an alias MappingType like #mapping_bdm, #mapping_nedelec, etc. This + * alias should be preferred to using the types below. + * + * The mapping types currently implemented by derived classes are: + * + * + */ virtual void transform (const VectorSlice > > input, @@ -349,11 +472,54 @@ class Mapping : public Subscriptor const MappingType type) const = 0; - /** - * Transform a field of - * rank two tensors accorsing to - * the selected MappingType. - */ +/** + * Transform a field of rank two tensors according to the selected + * MappingType. + * + * @note Normally, this function is called by a finite element, + * filling FEValues objects. For this finite element, there should be + * an alias MappingType like #mapping_bdm, #mapping_nedelec, etc. This + * alias should be preferred to using the types below. + * + * This function is most of the time applied to gradients of a + * Tensor<1,dim> object, thus in the formulas below, it is useful to + * think of $\mathbf{T} = \nabla \mathbf u$ and $\mathbf{\hat T} = + * \hat\nabla \mathbf{\hat u}$. + * + * @todo The formulas for #mapping_covariant_gradient and + * #mapping_contravariant_gradient have been reverse engineered from + * MappingQ1. They should be verified for consistency with + * mathematics. The description of the Piola transform is from Hoppe's + * lecture notes and the implementation should be verified. + * + * The mapping types currently implemented by derived classes are: + *
    + *
  • #mapping_contravariant_gradient, which is the consistent gradient + * for a vector field mapped with #mapping_contravariant, namely + * @f[ + * \mathbf T(\mathbf x) = + * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x}) + * J^{-T}(\mathbf{\hat x}). + * @f] + * + *
  • Correspondingly, #mapping_covariant_gradient is the consistent + * gradient of a one-form, namely, + * @f[ + * \mathbf T(\mathbf x) = + * J^{-T}(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x}) + * J^{-T}(\mathbf{\hat x}). + * @f] + * + *
  • The gradients of n-1-forms mapped by the Piola + * transform are mapped by #mapping_piola, and the formul is + * @f[ + * \mathbf T(\mathbf x) = + * \frac{1}{\text{det}J(\mathbf x)} + * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x}) + * J^{-1}(\mathbf{\hat x}). + * @f] + *
+ */ virtual void transform (const VectorSlice > > input,