From 453b8ffac2aa3239f572fb32cee769e12e51e33e Mon Sep 17 00:00:00 2001 From: Timo Heister Date: Thu, 23 Mar 2017 11:57:07 -0400 Subject: [PATCH] doxygen formatting fixes - wrong indentation - code blocks not marked correctly - some @ref fixes --- doc/doxygen/headers/fe.h | 22 +- include/deal.II/base/data_out_base.h | 6 +- include/deal.II/base/geometric_utilities.h | 4 +- include/deal.II/distributed/p4est_wrappers.h | 21 +- include/deal.II/dofs/dof_accessor.h | 7 +- include/deal.II/fe/fe.h | 7 +- include/deal.II/fe/fe_bernstein.h | 3 +- include/deal.II/fe/fe_dgp.h | 3 +- include/deal.II/fe/fe_dgp_monomial.h | 3 +- include/deal.II/fe/fe_dgp_nonparametric.h | 3 +- include/deal.II/fe/fe_dgq.h | 3 +- include/deal.II/fe/fe_enriched.h | 54 +- include/deal.II/fe/fe_face.h | 9 +- include/deal.II/fe/fe_nothing.h | 3 +- include/deal.II/fe/fe_poly_tensor.h | 2 +- include/deal.II/fe/fe_q_base.h | 3 +- include/deal.II/fe/fe_q_hierarchical.h | 3 +- include/deal.II/fe/fe_q_iso_q1.h | 3 +- include/deal.II/fe/fe_system.h | 3 +- include/deal.II/fe/fe_tools.h | 10 +- include/deal.II/fe/fe_trace.h | 3 +- include/deal.II/grid/grid_in.h | 7 +- .../deal.II/grid/tensor_product_manifold.h | 63 +- include/deal.II/grid/tria.h | 42 +- include/deal.II/grid/tria_accessor.h | 3 +- include/deal.II/lac/block_linear_operator.h | 41 +- include/deal.II/lac/full_matrix.h | 4 +- include/deal.II/lac/linear_operator.h | 62 +- include/deal.II/lac/precondition.h | 16 +- include/deal.II/lac/read_write_vector.h | 4 +- .../lac/trilinos_block_sparse_matrix.h | 48 +- include/deal.II/lac/trilinos_solver.h | 4 +- include/deal.II/lac/trilinos_vector_base.h | 8 +- include/deal.II/lac/vector.h | 3 +- include/deal.II/lac/vector_view.h | 3 +- include/deal.II/matrix_free/matrix_free.h | 20 +- include/deal.II/matrix_free/operators.h | 5 +- include/deal.II/meshworker/simple.h | 14 +- include/deal.II/multigrid/mg_tools.h | 13 +- .../deal.II/numerics/vector_tools.templates.h | 10 +- .../deal.II/physics/elasticity/kinematics.h | 2 +- .../physics/elasticity/standard_tensors.h | 2 +- include/deal.II/physics/transformations.h | 857 +++++++++--------- 43 files changed, 747 insertions(+), 659 deletions(-) diff --git a/doc/doxygen/headers/fe.h b/doc/doxygen/headers/fe.h index 59b827e834..376c210c63 100644 --- a/doc/doxygen/headers/fe.h +++ b/doc/doxygen/headers/fe.h @@ -19,7 +19,8 @@ * * All classes related to shape functions and to access to shape * functions. This concerns the actual values of finite elements. For - * the numbering of degrees of freedom refer to the module on @ref dofs. + * the numbering of degrees of freedom refer to the module on + * @ref dofs. * * The classes and functions of this module fall into several sub-groups that * are discussed in their respective sub-modules listed above. In addition, @@ -86,7 +87,8 @@ * of its face with the neighboring cell. If vector-valued elements are used, * the FEValues and related classes allow access to all vector components; if * one wants to pick individual components, there are extractor classes that - * make this task simpler, as described in the @ref vector_valued module. + * make this task simpler, as described in the + * @ref vector_valued module. * * The last member of this group, the UpdateFlags enumeration, is used as an * optimization: instead of letting the FEValues class compute every possible @@ -95,13 +97,14 @@ * UpdateFlags enumeration is used to offer symbolic names denoting what you * want the FEValues class to compute. * - * All these classes are used in all @ref Tutorial "tutorial programs" from - * step-3 onward, and are described there in significant detail. + * All these classes are used in all + * @ref Tutorial "tutorial programs" + * from step-3 onward, and are described there in significant detail. * * The actual workings of the FEValues class and friends is * complicated because it has to be general yet efficient. The page on - * @ref UpdateFlags attempts to give an overview of how this - * works. + * @ref UpdateFlags + * attempts to give an overview of how this works. * * @ingroup feall */ @@ -120,8 +123,11 @@ * point on the unit cell. To be useful in integrating matrix and right hand * side entries, one has to have the ability to map these shape functions and * gradients to the real cell. This is done using classes derived from the - * Mapping base class (see the @ref mapping module) in conjunction with the - * FEValues class (see the @ref feaccess module). + * Mapping base class (see + * @ref mapping) + * in conjunction with the + * FEValues class (see + * @ref feaccess). * *

Vector-valued finite elements

* diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h index 9e4d8b543d..04b6eb5463 100644 --- a/include/deal.II/base/data_out_base.h +++ b/include/deal.II/base/data_out_base.h @@ -541,9 +541,9 @@ namespace DataOutBase * surrounded by angle brackets: For example, if the space dimension is 2 * and the labels are "x" and "t", then the relevant * line will start with - @verbatim - # - @endverbatim + * @verbatim + * # + * @endverbatim * Any extra labels will be ignored. * * If you specify these labels yourself then there should be at least diff --git a/include/deal.II/base/geometric_utilities.h b/include/deal.II/base/geometric_utilities.h index 2bf0cb8e24..2478a80499 100644 --- a/include/deal.II/base/geometric_utilities.h +++ b/include/deal.II/base/geometric_utilities.h @@ -47,7 +47,7 @@ namespace GeometricUtilities * and polar/inclination angle $ \in [0,\pi]$ (ommited in 2D). * * In 3D the transformation is given by - * @f{align*} + * @f{align*}{ * r &= \sqrt{x^2+y^2+z^2} \\ * \theta &= {\rm atan}(y/x) \\ * \phi &= {\rm acos} (z/r) @@ -64,7 +64,7 @@ namespace GeometricUtilities * (ommited in 2D). * * In 3D the transformation is given by - * @f{align*} + * @f{align*}{ * x &= r\, \cos(\theta) \, \sin(\phi) \\ * y &= r\, \sin(\theta) \, \sin(\phi) \\ * z &= r\, \cos(\phi) diff --git a/include/deal.II/distributed/p4est_wrappers.h b/include/deal.II/distributed/p4est_wrappers.h index 795a561947..01c8749a7d 100644 --- a/include/deal.II/distributed/p4est_wrappers.h +++ b/include/deal.II/distributed/p4est_wrappers.h @@ -53,12 +53,12 @@ namespace internal namespace p4est { /** - * A structure whose explicit specializations contain typedefs to the - * relevant p4est_* and p8est_* types. Using this structure, for example - * by saying types::connectivity we can write code in a - * dimension independent way, either referring to p4est_connectivity_t or - * p8est_connectivity_t, depending on template argument. - */ + * A structure whose explicit specializations contain typedefs to the + * relevant p4est_* and p8est_* types. Using this structure, for example + * by saying types::connectivity we can write code in a + * dimension independent way, either referring to p4est_connectivity_t or + * p8est_connectivity_t, depending on template argument. + */ template struct types; template <> @@ -486,7 +486,8 @@ namespace internal * This struct templatizes the p4est iterate structs and function * prototypes, which are used to execute callback functions for faces, * edges, and corners that require local neighborhood information, i.e. - * the neighboring cells */ + * the neighboring cells + */ template struct iter; template <> struct iter<2> @@ -515,9 +516,9 @@ namespace internal /** - * Initialize the GeometryInfo::max_children_per_cell children of the - * cell p4est_cell. - */ + * Initialize the GeometryInfo::max_children_per_cell children of the + * cell p4est_cell. + */ template void init_quadrant_children diff --git a/include/deal.II/dofs/dof_accessor.h b/include/deal.II/dofs/dof_accessor.h index 85e3a68c2c..45876c8752 100644 --- a/include/deal.II/dofs/dof_accessor.h +++ b/include/deal.II/dofs/dof_accessor.h @@ -180,7 +180,8 @@ namespace internal * edges have @p structdim equal to one, etc. * @tparam DoFHandlerType The type of the DoF handler into which accessor * of this type point. This is either the DoFHandler or hp::DoFHandler - * class. See also the @ref ConceptDoFHandlerType "DoFHandlerType concept". + * class. See also the + * @ref ConceptDoFHandlerType "DoFHandlerType concept". * @tparam level_dof_access If @p false, then the accessor simply represents * a cell, face, or edge in a DoFHandler for which degrees of freedom only * exist on the finest level. Some operations are not allowed in this case, @@ -875,8 +876,8 @@ public: /** * Return the global indices of the degrees of freedom located on * this object in the standard ordering defined by the finite element. This - * function is only available on active objects (see @ref GlossActive - * "this glossary entry"). + * function is only available on active objects (see + * @ref GlossActive "this glossary entry"). * * The present vertex must belong to an active cell (and not artificial in a * parallel distributed computation). diff --git a/include/deal.II/fe/fe.h b/include/deal.II/fe/fe.h index 4d9fa3763b..1d7c58cbe0 100644 --- a/include/deal.II/fe/fe.h +++ b/include/deal.II/fe/fe.h @@ -1231,7 +1231,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination @@ -1947,7 +1948,9 @@ public: * FETools::compute_node_matrix() function. * * In more detail, let us assume that the generalized support points - * (see @ref GlossGeneralizedSupport "this glossary entry") of the current + * (see + * @ref GlossGeneralizedSupport "this glossary entry" + * ) of the current * element are $\hat{\mathbf x}_i$ and that the node functionals associated * with the current element are $\Psi_i[\cdot]$. Then, the fact that the * element is based on generalized support points, implies that if we diff --git a/include/deal.II/fe/fe_bernstein.h b/include/deal.II/fe/fe_bernstein.h index 98c3df663c..798eaa645e 100644 --- a/include/deal.II/fe/fe_bernstein.h +++ b/include/deal.II/fe/fe_bernstein.h @@ -177,7 +177,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_dgp.h b/include/deal.II/fe/fe_dgp.h index 799cb846be..ef22bfabad 100644 --- a/include/deal.II/fe/fe_dgp.h +++ b/include/deal.II/fe/fe_dgp.h @@ -386,7 +386,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_dgp_monomial.h b/include/deal.II/fe/fe_dgp_monomial.h index e17f02ce2e..ce393da029 100644 --- a/include/deal.II/fe/fe_dgp_monomial.h +++ b/include/deal.II/fe/fe_dgp_monomial.h @@ -361,7 +361,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_dgp_nonparametric.h b/include/deal.II/fe/fe_dgp_nonparametric.h index 6c7e535bcb..9b054dc0a1 100644 --- a/include/deal.II/fe/fe_dgp_nonparametric.h +++ b/include/deal.II/fe/fe_dgp_nonparametric.h @@ -469,7 +469,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_dgq.h b/include/deal.II/fe/fe_dgq.h index 9758d3f902..1c04563d41 100644 --- a/include/deal.II/fe/fe_dgq.h +++ b/include/deal.II/fe/fe_dgq.h @@ -275,7 +275,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_enriched.h b/include/deal.II/fe/fe_enriched.h index d983feda8f..ded5e7f0f4 100644 --- a/include/deal.II/fe/fe_enriched.h +++ b/include/deal.II/fe/fe_enriched.h @@ -97,7 +97,7 @@ DEAL_II_NAMESPACE_OPEN * Note that evaluation of gradients (hessians) of the enriched shape functions * or the finite element field requires evaluation of gradients (gradients and hessians) * of the enrichment functions: - * @f{align*} + * @f{align*}{ * U(\mathbf x) * &= \sum_i N_i(\mathbf x) U_i * + \sum_{j,k} N_j(\mathbf x) F_k(\mathbf x) U_{jk} \\ @@ -145,35 +145,35 @@ DEAL_II_NAMESPACE_OPEN * * When using this class, please cite * @code{.bib} - @Article{Davydov2016, - Title = {On the h-adaptive PUM and hp-adaptive FEM approaches applied to PDEs in quantum mechanics.}, - Author = {Davydov, D and Gerasimov, T and Pelteret, J.-P. and Steinmann, P.}, - eprinttype = {arXiv}, - eprint = {1612.02305}, - eprintclass = {physics.comp-ph}, - Year = {2016}, - } + * @Article{Davydov2016, + * Title = {On the h-adaptive PUM and hp-adaptive FEM approaches applied to PDEs in quantum mechanics.}, + * Author = {Davydov, D and Gerasimov, T and Pelteret, J.-P. and Steinmann, P.}, + * eprinttype = {arXiv}, + * eprint = {1612.02305}, + * eprintclass = {physics.comp-ph}, + * Year = {2016}, + * } * @endcode * The PUM was introduced in * @code{.bib} - @Article{Melenk1996, - Title = {The partition of unity finite element method: Basic theory and applications }, - Author = {Melenk, J.M. and Babu\v{s}ka, I.}, - Journal = {Computer Methods in Applied Mechanics and Engineering}, - Year = {1996}, - Number = {1--4}, - Pages = {289 -- 314}, - Volume = {139}, -} -@Article{Babuska1997, - Title = {The partition of unity method}, - Author = {Babu\v{s}ka, I. and Melenk, J. M.}, - Journal = {International Journal for Numerical Methods in Engineering}, - Year = {1997}, - Number = {4}, - Pages = {727--758}, - Volume = {40}, -} + * @Article{Melenk1996, + * Title = {The partition of unity finite element method: Basic theory and applications }, + * Author = {Melenk, J.M. and Babu\v{s}ka, I.}, + * Journal = {Computer Methods in Applied Mechanics and Engineering}, + * Year = {1996}, + * Number = {1--4}, + * Pages = {289 -- 314}, + * Volume = {139}, + * } + * @Article{Babuska1997, + * Title = {The partition of unity method}, + * Author = {Babu\v{s}ka, I. and Melenk, J. M.}, + * Journal = {International Journal for Numerical Methods in Engineering}, + * Year = {1997}, + * Number = {4}, + * Pages = {727--758}, + * Volume = {40}, + * } * @endcode * *

Implementation

diff --git a/include/deal.II/fe/fe_face.h b/include/deal.II/fe/fe_face.h index 7b59245c86..4246522f40 100644 --- a/include/deal.II/fe/fe_face.h +++ b/include/deal.II/fe/fe_face.h @@ -112,7 +112,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination @@ -216,7 +217,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination @@ -412,7 +414,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_nothing.h b/include/deal.II/fe/fe_nothing.h index 02dc8a5fe7..34351ef5fe 100644 --- a/include/deal.II/fe/fe_nothing.h +++ b/include/deal.II/fe/fe_nothing.h @@ -185,7 +185,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". * * In the current case, this element is assumed to dominate if the second * argument in the constructor @p dominate is true. When this argument is diff --git a/include/deal.II/fe/fe_poly_tensor.h b/include/deal.II/fe/fe_poly_tensor.h index 7e8e10c196..912d31bbe7 100644 --- a/include/deal.II/fe/fe_poly_tensor.h +++ b/include/deal.II/fe/fe_poly_tensor.h @@ -79,7 +79,7 @@ DEAL_II_NAMESPACE_OPEN * $\{\varphi_j(\hat{\mathbf x})\}$. Rather, we need to express the finite * element shape functions as a linear combination of the basis provided * by the polynomial space: - * @f{align*} + * @f{align*}{ * \varphi_j = \sum_k c_{jk} \tilde\varphi_j. * @f} * These expansion coefficients $c_{jk}$ are typically computed in the diff --git a/include/deal.II/fe/fe_q_base.h b/include/deal.II/fe/fe_q_base.h index 021c3c40e0..2a39e81e90 100644 --- a/include/deal.II/fe/fe_q_base.h +++ b/include/deal.II/fe/fe_q_base.h @@ -259,7 +259,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_q_hierarchical.h b/include/deal.II/fe/fe_q_hierarchical.h index 1d7f5b130a..b11550778d 100644 --- a/include/deal.II/fe/fe_q_hierarchical.h +++ b/include/deal.II/fe/fe_q_hierarchical.h @@ -656,7 +656,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_q_iso_q1.h b/include/deal.II/fe/fe_q_iso_q1.h index 7180b11c50..d163801c97 100644 --- a/include/deal.II/fe/fe_q_iso_q1.h +++ b/include/deal.II/fe/fe_q_iso_q1.h @@ -132,7 +132,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_system.h b/include/deal.II/fe/fe_system.h index 024bf4cfde..2b8f9b515f 100644 --- a/include/deal.II/fe/fe_system.h +++ b/include/deal.II/fe/fe_system.h @@ -832,7 +832,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/fe/fe_tools.h b/include/deal.II/fe/fe_tools.h index b4f8a0270b..64551e4440 100644 --- a/include/deal.II/fe/fe_tools.h +++ b/include/deal.II/fe/fe_tools.h @@ -253,14 +253,14 @@ namespace FETools * $\varphi_j(\mathbf x) = \sum_{k=1}^N c_{jk} \tilde\varphi_k(\mathbf x)$ * where we need to determine the expansion coefficients $c_{jk}$. We do this * by applying $\Psi_i$ to both sides of the equation, to obtain - * @f{align*} + * @f{align*}{ * \Psi_i [\varphi_j] = \sum_{k=1}^N c_{jk} \Psi_i[\tilde\varphi_k], * @f} * and we know that the left hand side equals $\delta_{ij}$. * If you think of this as a system of $N\times N$ equations for the * elements of a matrix on the left and on the right, then this can be * written as - * @f{align*} + * @f{align*}{ * I = C X^T * @f} * where $C$ is the matrix of coefficients $c_{jk}$ and @@ -912,7 +912,7 @@ namespace FETools * two vector components, where the first should have linear shape * functions and the second quadratic shape functions. In 1d, the * shape functions (on the reference cell) of the base elements are then - * @f{align*} + * @f{align*}{ * Q_1 &= \{ 1-x, x \}, * \\ Q_2 &= \{ 2(\frac 12 - x)(1-x), 2(x - \frac 12)x, 4x(1-x) \}, * @f} @@ -920,7 +920,7 @@ namespace FETools * first vertex, then on the second vertex, then in the interior of * the cell). The tensor product construction will create an element with * the following shape functions: - * @f{align*} + * @f{align*}{ * Q_1 \times Q_2 &= * \left\{ * \begin{pmatrix} 1-x \\ 0 \end{pmatrix}, @@ -942,7 +942,7 @@ namespace FETools * previous strategy, combining shape functions simply takes * all of the shape functions together. In the case above, * this would yield the following element: - * @f{align*} + * @f{align*}{ * Q_1 + Q_2 &= \{ 1-x, 2(\frac 12 - x)(1-x), * x, 2(x - \frac 12)x, 4x(1-x) \}. * @f} diff --git a/include/deal.II/fe/fe_trace.h b/include/deal.II/fe/fe_trace.h index 03a7586d35..9c4fa55406 100644 --- a/include/deal.II/fe/fe_trace.h +++ b/include/deal.II/fe/fe_trace.h @@ -116,7 +116,8 @@ public: * neither dominates, or if either could dominate. * * For a definition of domination, see FiniteElementDomination::Domination - * and in particular the @ref hp_paper "hp paper". + * and in particular the + * @ref hp_paper "hp paper". */ virtual FiniteElementDomination::Domination diff --git a/include/deal.II/grid/grid_in.h b/include/deal.II/grid/grid_in.h index eef8c36655..dec5aea9d0 100644 --- a/include/deal.II/grid/grid_in.h +++ b/include/deal.II/grid/grid_in.h @@ -38,8 +38,11 @@ template struct CellData; * geometric (vertex locations) and topological (how vertices form cells, * faces, and edges) information is ignored, but the readers for the various * formats generally do read information that associates material ids or - * boundary ids to cells or faces (see @ref GlossMaterialId "this" and - * @ref GlossBoundaryIndicator "this" glossary entry for more information). + * boundary ids to cells or faces (see + * @ref GlossMaterialId "this" + * and + * @ref GlossBoundaryIndicator "this" + * glossary entry for more information). * * @note Since deal.II only supports line, quadrilateral and hexahedral * meshes, the functions in this class can only read meshes that consist diff --git a/include/deal.II/grid/tensor_product_manifold.h b/include/deal.II/grid/tensor_product_manifold.h index 152c0929fe..75bc3b8c6d 100644 --- a/include/deal.II/grid/tensor_product_manifold.h +++ b/include/deal.II/grid/tensor_product_manifold.h @@ -26,38 +26,37 @@ DEAL_II_NAMESPACE_OPEN /** - * @brief Tensor product manifold of two ChartManifolds. - * - * This manifold will combine the ChartManifolds @p A and @p B given in the - * constructor to form a new ChartManifold by building the tensor product - * $A\cross B$. The first @p spacedim_A - * dimensions in the real space and the first @p chartdim_A dimensions - * of the chart will be given by manifold @p A, while the remaining - * coordinates are given by @p B. The manifold is to be used by a - * Triangulation@. - * - * An example usage would be the combination of a SphericalManifold with - * space dimension 2 and a FlatManifold with space dimension 1 to form - * a cylindrical manifold. - * - * pull_back(), push_forward(), and push_forward_gradient() are implemented - * by splitting the input argument into inputs for @p A and @p B according - * to the given dimensions and applying the corresponding operations before - * concatenating the result. - * - * @note The dimension arguments @p dim_A and @p dim_B are not used. - * - * @tparam dim Dimension of cells (needs to match first template argument of - * the Triangulation to be attached to. - * @tparam dim_A Dimension of ChartManifold A. - * @tparam spacedim_A Spacial dimension of ChartManifold A. - * @tparam chartdim_A Chart dimension of ChartManifold A. - * @tparam dim_B Dimension of ChartManifold B. - * @tparam spacedim_B Spacial dimension of ChartManifold B. - * @tparam chartdim_B Chart dimension of ChartManifold B. - * - * @author Luca Heltai, Timo Heister, 2016 - */ + * @brief Tensor product manifold of two ChartManifolds. + * + * This manifold will combine the ChartManifolds @p A and @p B given in the + * constructor to form a new ChartManifold by building the tensor product + * $A\cross B$. The first @p spacedim_A dimensions in the real space and the + * first @p chartdim_A dimensions of the chart will be given by manifold @p A, + * while the remaining coordinates are given by @p B. The manifold is to be + * used by a Triangulation@. + * + * An example usage would be the combination of a SphericalManifold with space + * dimension 2 and a FlatManifold with space dimension 1 to form a cylindrical + * manifold. + * + * pull_back(), push_forward(), and push_forward_gradient() are implemented by + * splitting the input argument into inputs for @p A and @p B according to the + * given dimensions and applying the corresponding operations before + * concatenating the result. + * + * @note The dimension arguments @p dim_A and @p dim_B are not used. + * + * @tparam dim Dimension of cells (needs to match first template argument of + * the Triangulation to be attached to. + * @tparam dim_A Dimension of ChartManifold A. + * @tparam spacedim_A Spacial dimension of ChartManifold A. + * @tparam chartdim_A Chart dimension of ChartManifold A. + * @tparam dim_B Dimension of ChartManifold B. + * @tparam spacedim_B Spacial dimension of ChartManifold B. + * @tparam chartdim_B Chart dimension of ChartManifold B. + * + * @author Luca Heltai, Timo Heister, 2016 + */ template diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index 13e5fd6fc6..74ef9ca223 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -3081,27 +3081,27 @@ public: /** - * Declare the (coarse) face pairs given in the argument of this function - * as periodic. This way it it possible to obtain neighbors across periodic - * boundaries. - * - * The vector can be filled by the function - * GridTools::collect_periodic_faces. - * - * For more information on periodic boundary conditions see - * GridTools::collect_periodic_faces, - * DoFTools::make_periodicity_constraints and step-45. - * - * @note Before this function can be used the Triangulation has to be - * initialized and must not be refined. - */ + * Declare the (coarse) face pairs given in the argument of this function as + * periodic. This way it it possible to obtain neighbors across periodic + * boundaries. + * + * The vector can be filled by the function + * GridTools::collect_periodic_faces. + * + * For more information on periodic boundary conditions see + * GridTools::collect_periodic_faces, DoFTools::make_periodicity_constraints + * and step-45. + * + * @note Before this function can be used the Triangulation has to be + * initialized and must not be refined. + */ virtual void add_periodicity (const std::vector > &); /** - * Return the periodic_face_map. - */ + * Return the periodic_face_map. + */ const std::map,std::pair, std::bitset<3> > > & get_periodic_face_map() const; @@ -3219,11 +3219,11 @@ protected: private: /** - * If add_periodicity() is called, this variable stores the given - * periodic face pairs on level 0 for later access during the - * identification of ghost cells for the multigrid hierarchy and for - * setting up the periodic_face_map. - */ + * If add_periodicity() is called, this variable stores the given periodic + * face pairs on level 0 for later access during the identification of ghost + * cells for the multigrid hierarchy and for setting up the + * periodic_face_map. + */ std::vector > periodic_face_pairs_level_0; /** diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h index 5f2f0a9e63..5266f721e9 100644 --- a/include/deal.II/grid/tria_accessor.h +++ b/include/deal.II/grid/tria_accessor.h @@ -2524,7 +2524,8 @@ public: /** * For a cell with its @c ith face at a periodic boundary, - * (see @ref GlossPeriodicConstraints "the entry for periodic boundaries") + * see + * @ref GlossPeriodicConstraints "the entry for periodic boundaries", * this function returns an iterator to the cell on the other side * of the periodic boundary. If there is no periodic boundary at the @c ith * face, an exception will be thrown. diff --git a/include/deal.II/lac/block_linear_operator.h b/include/deal.II/lac/block_linear_operator.h index 74d3aa19c5..176afd707c 100644 --- a/include/deal.II/lac/block_linear_operator.h +++ b/include/deal.II/lac/block_linear_operator.h @@ -378,34 +378,35 @@ namespace internal /** - * A dummy class for BlockLinearOperators that do not require any extensions - * to facilitate the operations of the block matrix or its subblocks. - * - * This is the Payload class typically associated with deal.II's native - * BlockSparseMatrix. To use Trilinos and PETSc BlockSparseMatrices it is - * necessary to initialize a BlockLinearOperator with their associated - * BlockPayload. - * - * @author Jean-Paul Pelteret, Matthias Maier, 2016 - * - * @ingroup LAOperators - */ + * A dummy class for BlockLinearOperators that do not require any + * extensions to facilitate the operations of the block matrix or its + * subblocks. + * + * This is the Payload class typically associated with deal.II's native + * BlockSparseMatrix. To use Trilinos and PETSc BlockSparseMatrices it is + * necessary to initialize a BlockLinearOperator with their associated + * BlockPayload. + * + * @author Jean-Paul Pelteret, Matthias Maier, 2016 + * + * @ingroup LAOperators + */ template class EmptyBlockPayload { public: /** - * Type of payload held by each subblock - */ + * Type of payload held by each subblock + */ typedef PayloadBlockType BlockType; /** - * Default constructor - * - * Since this class does not do anything in particular and needs no special - * configuration, we have only one generic constructor that can be called - * under any conditions. - */ + * Default constructor + * + * Since this class does not do anything in particular and needs no + * special configuration, we have only one generic constructor that can + * be called under any conditions. + */ template EmptyBlockPayload (const Args &...) { } diff --git a/include/deal.II/lac/full_matrix.h b/include/deal.II/lac/full_matrix.h index 0a0d639892..dec7308bd5 100644 --- a/include/deal.II/lac/full_matrix.h +++ b/include/deal.II/lac/full_matrix.h @@ -54,7 +54,9 @@ template class LAPACKFullMatrix; * @note Instantiations for this template are provided for @, * @, @@>, * @@>. Others can be generated in application - * programs (see the section on @ref Instantiations in the manual). + * programs, see + * @ref Instantiations + * for details. * * @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth, 1993-2004 */ diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index 1403d17d7a..59a39340f2 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -921,36 +921,36 @@ namespace internal /** - * A dummy class for LinearOperators that do not require any extensions - * to facilitate the operations of the matrix. - * - * This is the Payload class typically associated with deal.II's native - * SparseMatrix. To use Trilinos and PETSc SparseMatrices it is necessary - * to initialize a LinearOperator with their associated Payload. - * - * @author Jean-Paul Pelteret, Matthias Maier, 2016 - * - * @ingroup LAOperators - */ + * A dummy class for LinearOperators that do not require any extensions to + * facilitate the operations of the matrix. + * + * This is the Payload class typically associated with deal.II's native + * SparseMatrix. To use Trilinos and PETSc SparseMatrices it is necessary + * to initialize a LinearOperator with their associated Payload. + * + * @author Jean-Paul Pelteret, Matthias Maier, 2016 + * + * @ingroup LAOperators + */ class EmptyPayload { public: /** - * Default constructor - * - * Since this class does not do anything in particular and needs no special - * configuration, we have only one generic constructor that can be called - * under any conditions. - */ + * Default constructor + * + * Since this class does not do anything in particular and needs no + * special configuration, we have only one generic constructor that can + * be called under any conditions. + */ template EmptyPayload (const Args &...) { } /** - * Returns a payload configured for identity operations - */ + * Returns a payload configured for identity operations + */ EmptyPayload identity_payload () const { @@ -959,8 +959,8 @@ namespace internal /** - * Returns a payload configured for null operations - */ + * Returns a payload configured for null operations + */ EmptyPayload null_payload () const { @@ -969,8 +969,8 @@ namespace internal /** - * Returns a payload configured for transpose operations - */ + * Returns a payload configured for transpose operations + */ EmptyPayload transpose_payload () const { @@ -979,8 +979,8 @@ namespace internal /** - * Returns a payload configured for inverse operations - */ + * Returns a payload configured for inverse operations + */ template EmptyPayload inverse_payload (Solver &, const Preconditioner &) const @@ -990,9 +990,9 @@ namespace internal }; /** - * Operator that returns a payload configured to support the - * addition of two LinearOperators - */ + * Operator that returns a payload configured to support the addition of + * two LinearOperators + */ inline EmptyPayload operator+(const EmptyPayload &, const EmptyPayload &) @@ -1001,9 +1001,9 @@ namespace internal } /** - * Operator that returns a payload configured to support the - * multiplication of two LinearOperators - */ + * Operator that returns a payload configured to support the + * multiplication of two LinearOperators + */ inline EmptyPayload operator*(const EmptyPayload &, const EmptyPayload &) diff --git a/include/deal.II/lac/precondition.h b/include/deal.II/lac/precondition.h index 20fe5e1a25..d2e80e2515 100644 --- a/include/deal.II/lac/precondition.h +++ b/include/deal.II/lac/precondition.h @@ -864,14 +864,14 @@ private: * * For details on the algorithm, see section 5.1 of * @code{.bib} - @Book{Varga2009, - Title = {Matrix iterative analysis}, - Author = {Varga, R. S.}, - Publisher = {Springer}, - Address = {Berlin}, - Edition = {2nd}, - Year = {2009}, - } + * @Book{Varga2009, + * Title = {Matrix iterative analysis}, + * Author = {Varga, R. S.}, + * Publisher = {Springer}, + * Address = {Berlin}, + * Edition = {2nd}, + * Year = {2009}, + * } * @endcode * *

Requirements on the templated classes

diff --git a/include/deal.II/lac/read_write_vector.h b/include/deal.II/lac/read_write_vector.h index 631ecec5c1..520dc4a198 100644 --- a/include/deal.II/lac/read_write_vector.h +++ b/include/deal.II/lac/read_write_vector.h @@ -213,12 +213,12 @@ namespace LinearAlgebra /** * Apply the functor @p func to each element of the vector. The functor * should look like - * + * @code * struct Functor * { * void operator() (Number &value); * }; - * + * @endcode * * @note This function requires C++11 and read_write_vector.templates.h * needs to be included. diff --git a/include/deal.II/lac/trilinos_block_sparse_matrix.h b/include/deal.II/lac/trilinos_block_sparse_matrix.h index 8015170f97..4864876808 100644 --- a/include/deal.II/lac/trilinos_block_sparse_matrix.h +++ b/include/deal.II/lac/trilinos_block_sparse_matrix.h @@ -573,38 +573,38 @@ namespace TrilinosWrappers { /** - * This is an extension class to BlockLinearOperators for Trilinos - * block sparse matrices. - * - * @note This class does very little at the moment other than to check - * that the correct Payload type for each subblock has been chosen - * correctly. Further extensions to the class may be necessary in the - * future in order to add further functionality to BlockLinearOperators - * while retaining compatability with the Trilinos sparse matrix and - * preconditioner classes. - * - * @author Jean-Paul Pelteret, 2016 - * - * @ingroup TrilinosWrappers - */ + * This is an extension class to BlockLinearOperators for Trilinos block + * sparse matrices. + * + * @note This class does very little at the moment other than to check + * that the correct Payload type for each subblock has been chosen + * correctly. Further extensions to the class may be necessary in the + * future in order to add further functionality to BlockLinearOperators + * while retaining compatability with the Trilinos sparse matrix and + * preconditioner classes. + * + * @author Jean-Paul Pelteret, 2016 + * + * @ingroup TrilinosWrappers + */ template class TrilinosBlockPayload { public: /** - * Type of payload held by each subblock - */ + * Type of payload held by each subblock + */ typedef PayloadBlockType BlockType; /** - * Default constructor - * - * This simply checks that the payload for each block has been chosen - * correctly (i.e. is of type TrilinosPayload). Apart from this, this - * class does not do anything in particular and needs no special - * configuration, we have only one generic constructor that can be - * called under any conditions. - */ + * Default constructor + * + * This simply checks that the payload for each block has been chosen + * correctly (i.e. is of type TrilinosPayload). Apart from this, this + * class does not do anything in particular and needs no special + * configuration, we have only one generic constructor that can be + * called under any conditions. + */ template TrilinosBlockPayload (const Args &...) { diff --git a/include/deal.II/lac/trilinos_solver.h b/include/deal.II/lac/trilinos_solver.h index 7f89c783b8..b846247506 100644 --- a/include/deal.II/lac/trilinos_solver.h +++ b/include/deal.II/lac/trilinos_solver.h @@ -310,8 +310,8 @@ namespace TrilinosWrappers void do_solve(const Preconditioner &preconditioner); /** - * A function that sets the preconditioner that the solver will apply - */ + * A function that sets the preconditioner that the solver will apply + */ template void set_preconditioner (AztecOO &solver, const Preconditioner &preconditioner); diff --git a/include/deal.II/lac/trilinos_vector_base.h b/include/deal.II/lac/trilinos_vector_base.h index a97e48f8a0..9009682b2b 100644 --- a/include/deal.II/lac/trilinos_vector_base.h +++ b/include/deal.II/lac/trilinos_vector_base.h @@ -55,10 +55,10 @@ template class Vector; */ /** -* A namespace in which wrapper classes for Trilinos objects reside. -* -* @ingroup TrilinosWrappers -*/ + * A namespace in which wrapper classes for Trilinos objects reside. + * + * @ingroup TrilinosWrappers + */ namespace TrilinosWrappers { // forward declaration diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h index 6aa7a25da6..4c63d2aa68 100644 --- a/include/deal.II/lac/vector.h +++ b/include/deal.II/lac/vector.h @@ -121,7 +121,8 @@ struct VectorOperation * @note Instantiations for this template are provided for @, * @, @@>, @@>; * others can be generated in application programs (see the section on - * @ref Instantiations in the manual). + * @ref Instantiations + * in the manual). * * @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth */ diff --git a/include/deal.II/lac/vector_view.h b/include/deal.II/lac/vector_view.h index 298ead3026..485e130fc3 100644 --- a/include/deal.II/lac/vector_view.h +++ b/include/deal.II/lac/vector_view.h @@ -122,7 +122,8 @@ DEAL_II_NAMESPACE_OPEN * @note Instantiations for this template are provided for @, * @, @@>, @@>; * others can be generated in application programs (see the section on - * @ref Instantiations in the manual). + * @ref Instantiations + * in the manual). * * @author Luca Heltai, 2009 */ diff --git a/include/deal.II/matrix_free/matrix_free.h b/include/deal.II/matrix_free/matrix_free.h index 3e9c6b8db5..c03216c089 100644 --- a/include/deal.II/matrix_free/matrix_free.h +++ b/include/deal.II/matrix_free/matrix_free.h @@ -568,9 +568,11 @@ public: * component is to be used. * * For the vectors used with MatrixFree and in FEEvaluation, a vector needs - * to hold all @ref GlossLocallyActiveDof "locally active DoFs" and also - * some of the @ref GlossLocallyRelevantDof "locally relevant DoFs". The - * selection of DoFs is such that one can read all degrees of freedom on all + * to hold all + * @ref GlossLocallyActiveDof "locally active DoFs" + * and also some of the + * @ref GlossLocallyRelevantDof "locally relevant DoFs". + * The selection of DoFs is such that one can read all degrees of freedom on all * locally relevant elements (locally active) plus the degrees of freedom * that contraints expand into from the locally owned cells. However, not * all locally relevant DoFs are stored because most of them would never be @@ -590,9 +592,11 @@ public: * component is to be used. * * For the vectors used with MatrixFree and in FEEvaluation, a vector needs - * to hold all @ref GlossLocallyActiveDof "locally active DoFs" and also - * some of the @ref GlossLocallyRelevantDof "locally relevant DoFs". The - * selection of DoFs is such that one can read all degrees of freedom on all + * to hold all + * @ref GlossLocallyActiveDof "locally active DoFs" + * and also some of the + * @ref GlossLocallyRelevantDof "locally relevant DoFs". + * The selection of DoFs is such that one can read all degrees of freedom on all * locally relevant elements (locally active) plus the degrees of freedom * that contraints expand into from the locally owned cells. However, not * all locally relevant DoFs are stored because most of them would never be @@ -894,7 +898,9 @@ public: * of a list of vectors. Multiple threads will each get a separate storage * field and separate vectors, ensuring thread safety. The mechanism to * acquire and release objects is similar to the mechanisms used for the - * local contributions of WorkStream, see @ref workstream_paper. + * local contributions of WorkStream, see + * @ref workstream_paper "the WorkStream paper" + * . */ AlignedVector > *acquire_scratch_data() const; diff --git a/include/deal.II/matrix_free/operators.h b/include/deal.II/matrix_free/operators.h index a561ce1530..f14bc021ba 100644 --- a/include/deal.II/matrix_free/operators.h +++ b/include/deal.II/matrix_free/operators.h @@ -444,8 +444,9 @@ namespace MatrixFreeOperators * coupling over the multigrid interface needs to be taken into account. * This is done by the so-called interface (or edge) matrices that compute * the part of the residual that is missed by the level matrix with - * homogeneous Dirichlet conditions. We refer to the @ref mg_paper - * "Multigrid paper by Janssen and Kanschat" for more details. + * homogeneous Dirichlet conditions. We refer to the + * @ref mg_paper "Multigrid paper by Janssen and Kanschat" + * for more details. * * For the implementation of those interface matrices, most infrastructure * is already in place and provided by MatrixFreeOperators::Base through the diff --git a/include/deal.II/meshworker/simple.h b/include/deal.II/meshworker/simple.h index 732e9472a2..5282f4ee63 100644 --- a/include/deal.II/meshworker/simple.h +++ b/include/deal.II/meshworker/simple.h @@ -211,10 +211,10 @@ namespace MeshWorker std::vector > > matrix; /** - * The smallest positive number that will be entered into the global - * matrix. All smaller absolute values will be treated as zero and will - * not be assembled. - */ + * The smallest positive number that will be entered into the global + * matrix. All smaller absolute values will be treated as zero and will + * not be assembled. + */ const double threshold; private: @@ -462,9 +462,9 @@ namespace MeshWorker private: /** - * Assemble a single matrix M into the element at - * index in the vector #matrix. - */ + * Assemble a single matrix M into the element at + * index in the vector #matrix. + */ void assemble(const FullMatrix &M, const Vector &vector, const unsigned int index, diff --git a/include/deal.II/multigrid/mg_tools.h b/include/deal.II/multigrid/mg_tools.h index 1d89b1bfe2..2796a95db8 100644 --- a/include/deal.II/multigrid/mg_tools.h +++ b/include/deal.II/multigrid/mg_tools.h @@ -204,13 +204,12 @@ namespace MGTools const ComponentMask &component_mask = ComponentMask()); /** - * The same function as above, but return an IndexSet rather than a - * std::set on each level and use a std::set of - * boundary_ids as input. - * - * Previous content in @p boundary_indices is not overwritten, - * but added to. - */ + * The same function as above, but return an IndexSet rather than a + * std::set on each level and use a std::set of boundary_ids + * as input. + * + * Previous content in @p boundary_indices is not overwritten, but added to. + */ template void make_boundary_list (const DoFHandler &mg_dof, diff --git a/include/deal.II/numerics/vector_tools.templates.h b/include/deal.II/numerics/vector_tools.templates.h index 50a7db5a86..30e751f574 100644 --- a/include/deal.II/numerics/vector_tools.templates.h +++ b/include/deal.II/numerics/vector_tools.templates.h @@ -968,11 +968,11 @@ namespace VectorTools /** - * Helper interface. After figuring out the number of components - * in project_matrix_free_component, we determine the degree of the - * FiniteElement and call project_matrix_free with the appropriate - * template arguments. - */ + * Helper interface. After figuring out the number of components in + * project_matrix_free_component, we determine the degree of the + * FiniteElement and call project_matrix_free with the appropriate + * template arguments. + */ template void project_matrix_free_degree (const Mapping &mapping, diff --git a/include/deal.II/physics/elasticity/kinematics.h b/include/deal.II/physics/elasticity/kinematics.h index 9c80108f8c..75a7a4e0e4 100644 --- a/include/deal.II/physics/elasticity/kinematics.h +++ b/include/deal.II/physics/elasticity/kinematics.h @@ -42,7 +42,7 @@ namespace Physics * 0 case, where the metric tensor is the identity tensor. * * @author Jean-Paul Pelteret, Andrew McBride, 2016 - */ + */ namespace Kinematics { diff --git a/include/deal.II/physics/elasticity/standard_tensors.h b/include/deal.II/physics/elasticity/standard_tensors.h index 91c4ec3734..e34f1784a1 100644 --- a/include/deal.II/physics/elasticity/standard_tensors.h +++ b/include/deal.II/physics/elasticity/standard_tensors.h @@ -41,7 +41,7 @@ namespace Physics * @relates Tensor * @relates SymmetricTensor * @author Jean-Paul Pelteret, Andrew McBride, 2016 - */ + */ template class StandardTensors { diff --git a/include/deal.II/physics/transformations.h b/include/deal.II/physics/transformations.h index e7e6ebff06..a8a377b083 100644 --- a/include/deal.II/physics/transformations.h +++ b/include/deal.II/physics/transformations.h @@ -34,7 +34,7 @@ namespace Physics * rotation angles and axes of rotation. * * @author Jean-Paul Pelteret, 2017 - */ + */ namespace Rotations { /** @@ -43,52 +43,53 @@ namespace Physics //@{ /** - * Returns the rotation matrix for 2-d Euclidean space, namely - * @f[ - * \mathbf{R} := \left[ \begin{array}{cc} - * cos(\theta) & sin(\theta) \\ - * -sin(\theta) & cos(\theta) - * \end{array}\right] - * @f] - * where $\theta$ is the rotation angle given in radians. - * In particular, this describes the counter-clockwise rotation of a vector - * relative to a - * fixed set of right-handed axes. - * - * @param[in] angle The rotation angle (about the z-axis) in radians - */ + * Returns the rotation matrix for 2-d Euclidean space, namely + * @f[ + * \mathbf{R} := \left[ \begin{array}{cc} + * cos(\theta) & sin(\theta) \\ + * -sin(\theta) & cos(\theta) + * \end{array}\right] + * @f] + * where $\theta$ is the rotation angle given in radians. In particular, + * this describes the counter-clockwise rotation of a vector relative to + * a fixed + * set of right-handed axes. + * + * @param[in] angle The rotation angle (about the z-axis) in radians + */ template Tensor<2,2,Number> rotation_matrix_2d (const Number &angle); /** - * Returns the rotation matrix for 3-d Euclidean space. - * Most concisely stated using the Rodrigues' rotation formula, this - * function returns the equivalent of - * @f[ - * \mathbf{R} := cos(\theta)\mathbf{I} + sin(\theta)\mathbf{W} - * + (1-cos(\theta))\mathbf{u}\otimes\mathbf{u} - * @f] - * where $\mathbf{u}$ is the axial vector (an axial vector) and $\theta$ - * is the rotation angle given in radians, $\mathbf{I}$ is the identity - * tensor and $\mathbf{W}$ is the skew symmetric tensor of $\mathbf{u}$. - * - * @dealiiWriggersA{374,9.194} - * This presents Rodrigues' rotation formula, but the implementation used - * in this function is described in this - * wikipedia link. - * In particular, this describes the counter-clockwise rotation of a vector - * in a plane with its normal. - * defined by the @p axis of rotation. - * An alternative implementation is discussed at - * this link, - * but is inconsistent (sign-wise) with the Rodrigues' rotation formula as - * it describes the rotation of a coordinate system. - * - * @param[in] axis A unit vector that defines the axis of rotation - * @param[in] angle The rotation angle in radians - */ + * Returns the rotation matrix for 3-d Euclidean space. Most concisely + * stated using the Rodrigues' rotation formula, this function returns + * the equivalent of + * @f[ + * \mathbf{R} := cos(\theta)\mathbf{I} + sin(\theta)\mathbf{W} + * + (1-cos(\theta))\mathbf{u}\otimes\mathbf{u} + * @f] + * where $\mathbf{u}$ is the axial vector (an axial vector) and $\theta$ + * is the rotation angle given in radians, $\mathbf{I}$ is the identity + * tensor and $\mathbf{W}$ is the skew symmetric tensor of $\mathbf{u}$. + * + * @dealiiWriggersA{374,9.194} This presents Rodrigues' rotation + * formula, but the implementation used in this function is described in + * this wikipedia + * link. In particular, this describes the counter-clockwise + * rotation of a vector in a plane + * with its normal. defined by the @p axis of rotation. An + * alternative implementation is discussed at this + * link, but is inconsistent (sign-wise) with the Rodrigues' + * rotation formula as it describes the rotation of a coordinate system. + * + * @param[in] axis A unit vector that defines the axis of rotation + * @param[in] angle The rotation angle in radians + */ template Tensor<2,3,Number> rotation_matrix_3d (const Point<3,Number> &axis, @@ -101,8 +102,8 @@ namespace Physics /** * Transformation of tensors that are defined in terms of a set of * contravariant bases. Rank-1 and rank-2 contravariant tensors - * $\left(\bullet\right)^{\sharp} = \mathbf{T}$ (and its spatial counterpart - * $\mathbf{t}$) typically satisfy the relation + * $\left(\bullet\right)^{\sharp} = \mathbf{T}$ (and its spatial + * counterpart $\mathbf{t}$) typically satisfy the relation * @f[ * \int_{V_{0}} \nabla_{0} \cdot \mathbf{T} \; dV * = \int_{\partial V_{0}} \mathbf{T} \cdot \mathbf{N} \; dA @@ -110,12 +111,12 @@ namespace Physics * = \int_{V_{t}} \nabla \cdot \mathbf{t} \; dv * @f] * where $V_{0}$ and $V_{t}$ are respectively control volumes in the - * reference and spatial configurations, and their surfaces $\partial V_{0}$ - * and $\partial V_{t}$ have the outwards facing normals $\mathbf{N}$ and - * $\mathbf{n}$. + * reference and spatial configurations, and their surfaces $\partial + * V_{0}$ and $\partial V_{t}$ have the outwards facing normals + * $\mathbf{N}$ and $\mathbf{n}$. * * @author Jean-Paul Pelteret, Andrew McBride, 2016 - */ + */ namespace Contravariant { @@ -125,85 +126,92 @@ namespace Physics //@{ /** - * Returns the result of the push forward transformation on a - * contravariant vector, i.e. - * @f[ - * \chi\left(\bullet\right)^{\sharp} - * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} - * @f] - * - * @param[in] V The (referential) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{V} \right)$ - */ + * Returns the result of the push forward transformation on a + * contravariant vector, i.e. + * @f[ + * \chi\left(\bullet\right)^{\sharp} + * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} + * @f] + * + * @param[in] V The (referential) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{V} \right)$ + */ template Tensor<1,dim,Number> push_forward (const Tensor<1,dim,Number> &V, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * contravariant tensor, i.e. - * @f[ - * \chi\left(\bullet\right)^{\sharp} - * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} - * @f] - * - * @param[in] T The (referential) rank-2 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * contravariant tensor, i.e. + * @f[ + * \chi\left(\bullet\right)^{\sharp} + * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} + * @f] + * + * @param[in] T The (referential) rank-2 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{T} \right)$ + */ template Tensor<2,dim,Number> push_forward (const Tensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * contravariant symmetric tensor, i.e. - * @f[ - * \chi\left(\bullet\right)^{\sharp} - * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} - * @f] - * - * @param[in] T The (referential) rank-2 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * contravariant symmetric tensor, i.e. + * @f[ + * \chi\left(\bullet\right)^{\sharp} + * := \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} + * @f] + * + * @param[in] T The (referential) rank-2 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{T} \right)$ + */ template SymmetricTensor<2,dim,Number> push_forward (const SymmetricTensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * contravariant tensor, i.e. (in index notation) - * @f[ - * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} - * := F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * contravariant tensor, i.e. (in index notation) + * @f[ + * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} + * := F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{H} \right)$ + */ template Tensor<4,dim,Number> push_forward (const Tensor<4,dim,Number> &H, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * contravariant symmetric tensor, i.e. (in index notation) - * @f[ - * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} - * := F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * contravariant symmetric tensor, i.e. (in index notation) + * @f[ + * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} + * := F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{H} \right)$ + */ template SymmetricTensor<4,dim,Number> push_forward (const SymmetricTensor<4,dim,Number> &H, @@ -217,85 +225,90 @@ namespace Physics //@{ /** - * Returns the result of the pull back transformation on a - * contravariant vector, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\sharp} - * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} - * @f] - * - * @param[in] v The (spatial) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{v} \right)$ - */ + * Returns the result of the pull back transformation on a contravariant + * vector, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\sharp} + * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} + * @f] + * + * @param[in] v The (spatial) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{v} \right)$ + */ template Tensor<1,dim,Number> pull_back (const Tensor<1,dim,Number> &v, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * contravariant tensor, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\sharp} - * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} - * @f] - * - * @param[in] t The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * contravariant tensor, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\sharp} + * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} + * @f] + * + * @param[in] t The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{t} \right)$ + */ template Tensor<2,dim,Number> pull_back (const Tensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * contravariant symmetric tensor, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\sharp} - * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} - * @f] - * - * @param[in] t The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * contravariant symmetric tensor, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\sharp} + * := \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} + * @f] + * + * @param[in] t The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{t} \right)$ + */ template SymmetricTensor<2,dim,Number> pull_back (const SymmetricTensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant tensor, i.e. (in index notation) - * @f[ - * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} - * := F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} - * @f] - * - * @param[in] h The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant tensor, i.e. (in index notation) + * @f[ + * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} + * := F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} + * @f] + * + * @param[in] h The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{h} \right)$ + */ template Tensor<4,dim,Number> pull_back (const Tensor<4,dim,Number> &h, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant symmetric tensor, i.e. (in index notation) - * @f[ - * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} - * := F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} - * @f] - * - * @param[in] h The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant symmetric tensor, i.e. (in index notation) + * @f[ + * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} + * := F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} + * @f] + * + * @param[in] h The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{h} \right)$ + */ template SymmetricTensor<4,dim,Number> pull_back (const SymmetricTensor<4,dim,Number> &h, @@ -307,8 +320,8 @@ namespace Physics /** * Transformation of tensors that are defined in terms of a set of * covariant basis vectors. Rank-1 and rank-2 covariant tensors - * $\left(\bullet\right)^{\flat} = \mathbf{T}$ (and its spatial counterpart - * $\mathbf{t}$) typically satisfy the relation + * $\left(\bullet\right)^{\flat} = \mathbf{T}$ (and its spatial + * counterpart $\mathbf{t}$) typically satisfy the relation * @f[ * \int_{\partial V_{0}} \left[ \nabla_{0} \times \mathbf{T} \right] \cdot \mathbf{N} \; dA * = \oint_{\partial A_{0}} \mathbf{T} \cdot \mathbf{L} \; dL @@ -316,12 +329,13 @@ namespace Physics * = \int_{\partial V_{t}} \left[ \nabla \times \mathbf{t} \right] \cdot \mathbf{n} \; da * @f] * where the control surfaces $\partial V_{0}$ and $\partial V_{t}$ with - * outwards facing normals $\mathbf{N}$ and $\mathbf{n}$ are bounded by the - * curves $\partial A_{0}$ and $\partial A_{0}$ that are, respectively, - * associated with the line directors $\mathbf{L}$ and $\mathbf{l}$. + * outwards facing normals $\mathbf{N}$ and $\mathbf{n}$ are bounded by + * the curves $\partial A_{0}$ and $\partial A_{0}$ that are, + * respectively, associated with the line directors $\mathbf{L}$ and + * $\mathbf{l}$. * * @author Jean-Paul Pelteret, Andrew McBride, 2016 - */ + */ namespace Covariant { @@ -331,85 +345,92 @@ namespace Physics //@{ /** - * Returns the result of the push forward transformation on a covariant - * vector, i.e. - * @f[ - * \chi\left(\bullet\right)^{\flat} - * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} - * @f] - * - * @param[in] V The (referential) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{V} \right)$ - */ + * Returns the result of the push forward transformation on a covariant + * vector, i.e. + * @f[ + * \chi\left(\bullet\right)^{\flat} + * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} + * @f] + * + * @param[in] V The (referential) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{V} \right)$ + */ template Tensor<1,dim,Number> push_forward (const Tensor<1,dim,Number> &V, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * covariant tensor, i.e. - * @f[ - * \chi\left(\bullet\right)^{\flat} - * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F}^{-1} - * @f] - * - * @param[in] T The (referential) rank-2 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * covariant tensor, i.e. + * @f[ + * \chi\left(\bullet\right)^{\flat} + * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F}^{-1} + * @f] + * + * @param[in] T The (referential) rank-2 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{T} \right)$ + */ template Tensor<2,dim,Number> push_forward (const Tensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * covariant symmetric tensor, i.e. - * @f[ - * \chi\left(\bullet\right)^{\flat} - * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F}^{-1} - * @f] - * - * @param[in] T The (referential) rank-2 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * covariant symmetric tensor, i.e. + * @f[ + * \chi\left(\bullet\right)^{\flat} + * := \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F}^{-1} + * @f] + * + * @param[in] T The (referential) rank-2 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{T} \right)$ + */ template SymmetricTensor<2,dim,Number> push_forward (const SymmetricTensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * covariant tensor, i.e. (in index notation) - * @f[ - * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl} - * := F^{-T}_{iI} F^{-T}_{jJ} \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * covariant tensor, i.e. (in index notation) + * @f[ + * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl} + * := F^{-T}_{iI} F^{-T}_{jJ} \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{H} \right)$ + */ template Tensor<4,dim,Number> push_forward (const Tensor<4,dim,Number> &H, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * covariant symmetric tensor, i.e. (in index notation) - * @f[ - * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl} - * := F^{-T}_{iI} F^{-T}_{jJ} \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * covariant symmetric tensor, i.e. (in index notation) + * @f[ + * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl} + * := F^{-T}_{iI} F^{-T}_{jJ} \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi\left( \mathbf{H} \right)$ + */ template SymmetricTensor<4,dim,Number> push_forward (const SymmetricTensor<4,dim,Number> &H, @@ -423,85 +444,90 @@ namespace Physics //@{ /** - * Returns the result of the pull back transformation on a - * covariant vector, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\flat} - * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} - * @f] - * - * @param[in] v The (spatial) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{v} \right)$ - */ + * Returns the result of the pull back transformation on a covariant + * vector, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\flat} + * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} + * @f] + * + * @param[in] v The (spatial) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{v} \right)$ + */ template Tensor<1,dim,Number> pull_back (const Tensor<1,dim,Number> &v, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * covariant tensor, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\flat} - * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F} - * @f] - * - * @param[in] t The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * covariant tensor, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\flat} + * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F} + * @f] + * + * @param[in] t The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{t} \right)$ + */ template Tensor<2,dim,Number> pull_back (const Tensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * covariant symmetric tensor, i.e. - * @f[ - * \chi^{-1}\left(\bullet\right)^{\flat} - * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F} - * @f] - * - * @param[in] t The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * covariant symmetric tensor, i.e. + * @f[ + * \chi^{-1}\left(\bullet\right)^{\flat} + * := \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} \cdot \mathbf{F} + * @f] + * + * @param[in] t The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{t} \right)$ + */ template SymmetricTensor<2,dim,Number> pull_back (const SymmetricTensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant tensor, i.e. (in index notation) - * @f[ - * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL} - * := F^{T}_{Ii} F^{T}_{Jj} \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll} - * @f] - * - * @param[in] h The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant tensor, i.e. (in index notation) + * @f[ + * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL} + * := F^{T}_{Ii} F^{T}_{Jj} \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll} + * @f] + * + * @param[in] h The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{h} \right)$ + */ template Tensor<4,dim,Number> pull_back (const Tensor<4,dim,Number> &h, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant symmetric tensor, i.e. (in index notation) - * @f[ - * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL} - * := F^{T}_{Ii} F^{T}_{Jj} \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll} - * @f] - * - * @param[in] h The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant symmetric tensor, i.e. (in index notation) + * @f[ + * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL} + * := F^{T}_{Ii} F^{T}_{Jj} \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll} + * @f] + * + * @param[in] h The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\chi^{-1}\left( \mathbf{h} \right)$ + */ template SymmetricTensor<4,dim,Number> pull_back (const SymmetricTensor<4,dim,Number> &h, @@ -516,7 +542,7 @@ namespace Physics * change associated with the mapping. * * @author Jean-Paul Pelteret, Andrew McBride, 2016 - */ + */ namespace Piola { @@ -526,85 +552,97 @@ namespace Physics //@{ /** - * Returns the result of the push forward transformation on a - * contravariant vector, i.e. - * @f[ - * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} - * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} - * @f] - * - * @param[in] V The (referential) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( \mathbf{V} \right)$ - */ + * Returns the result of the push forward transformation on a + * contravariant vector, i.e. + * @f[ + * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} + * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} + * @f] + * + * @param[in] V The (referential) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( + * \mathbf{V} \right)$ + */ template Tensor<1,dim,Number> push_forward (const Tensor<1,dim,Number> &V, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * contravariant tensor, i.e. - * @f[ - * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} - * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} - * @f] - * - * @param[in] T The (referential) rank-2 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * contravariant tensor, i.e. + * @f[ + * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} + * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} + * @f] + * + * @param[in] T The (referential) rank-2 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( + * \mathbf{T} \right)$ + */ template Tensor<2,dim,Number> push_forward (const Tensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-2 - * contravariant symmetric tensor, i.e. - * @f[ - * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} - * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} - * @f] - * - * @param[in] T The (referential) rank-2 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( \mathbf{T} \right)$ - */ + * Returns the result of the push forward transformation on a rank-2 + * contravariant symmetric tensor, i.e. + * @f[ + * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp} + * := \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T} + * @f] + * + * @param[in] T The (referential) rank-2 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( + * \mathbf{T} \right)$ + */ template SymmetricTensor<2,dim,Number> push_forward (const SymmetricTensor<2,dim,Number> &T, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * contravariant tensor, i.e. (in index notation) - * @f[ - * \textrm{det} \mathbf{F}^{-1} \; \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} - * := \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * contravariant tensor, i.e. (in index notation) + * @f[ + * \textrm{det} \mathbf{F}^{-1} \; \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} + * := \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( + * \mathbf{H} \right)$ + */ template Tensor<4,dim,Number> push_forward (const Tensor<4,dim,Number> &H, const Tensor<2,dim,Number> &F); /** - * Returns the result of the push forward transformation on a rank-4 - * contravariant symmetric tensor, i.e. (in index notation) - * @f[ - * \textrm{det} \mathbf{F}^{-1} \; \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} - * := \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} - * @f] - * - * @param[in] H The (referential) rank-4 symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( \mathbf{H} \right)$ - */ + * Returns the result of the push forward transformation on a rank-4 + * contravariant symmetric tensor, i.e. (in index notation) + * @f[ + * \textrm{det} \mathbf{F}^{-1} \; \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl} + * := \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ} \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL} + * @f] + * + * @param[in] H The (referential) rank-4 symmetric tensor to be operated + * on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left( + * \mathbf{H} \right)$ + */ template SymmetricTensor<4,dim,Number> push_forward (const SymmetricTensor<4,dim,Number> &H, @@ -618,85 +656,95 @@ namespace Physics //@{ /** - * Returns the result of the pull back transformation on a - * contravariant vector, i.e. - * @f[ - * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} - * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} - * @f] - * - * @param[in] v The (spatial) vector to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{v} \right)$ - */ + * Returns the result of the pull back transformation on a contravariant + * vector, i.e. + * @f[ + * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} + * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} + * @f] + * + * @param[in] v The (spatial) vector to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{v} + * \right)$ + */ template Tensor<1,dim,Number> pull_back (const Tensor<1,dim,Number> &v, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * contravariant tensor, i.e. - * @f[ - * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} - * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} - * @f] - * - * @param[in] t The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * contravariant tensor, i.e. + * @f[ + * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} + * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} + * @f] + * + * @param[in] t The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t} + * \right)$ + */ template Tensor<2,dim,Number> pull_back (const Tensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-2 - * contravariant symmetric tensor, i.e. - * @f[ - * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} - * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} - * @f] - * - * @param[in] t The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t} \right)$ - */ + * Returns the result of the pull back transformation on a rank-2 + * contravariant symmetric tensor, i.e. + * @f[ + * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp} + * := \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T} + * @f] + * + * @param[in] t The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t} + * \right)$ + */ template SymmetricTensor<2,dim,Number> pull_back (const SymmetricTensor<2,dim,Number> &t, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant tensor, i.e. (in index notation) - * @f[ - * \textrm{det} \mathbf{F} \; \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} - * := \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} - * @f] - * - * @param[in] h The (spatial) tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant tensor, i.e. (in index notation) + * @f[ + * \textrm{det} \mathbf{F} \; \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} + * := \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} + * @f] + * + * @param[in] h The (spatial) tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h} + * \right)$ + */ template Tensor<4,dim,Number> pull_back (const Tensor<4,dim,Number> &h, const Tensor<2,dim,Number> &F); /** - * Returns the result of the pull back transformation on a rank-4 - * contravariant symmetric tensor, i.e. (in index notation) - * @f[ - * \textrm{det} \mathbf{F} \; \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} - * := \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} - * @f] - * - * @param[in] h The (spatial) symmetric tensor to be operated on - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h} \right)$ - */ + * Returns the result of the pull back transformation on a rank-4 + * contravariant symmetric tensor, i.e. (in index notation) + * @f[ + * \textrm{det} \mathbf{F} \; \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL} + * := \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj} \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll} + * @f] + * + * @param[in] h The (spatial) symmetric tensor to be operated on + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h} + * \right)$ + */ template SymmetricTensor<4,dim,Number> pull_back (const SymmetricTensor<4,dim,Number> &h, @@ -711,26 +759,27 @@ namespace Physics //@{ /** - * Returns the result of applying Nanson's formula for the transformation of - * the material surface area element $d\mathbf{A}$ to the current surfaces - * area element $d\mathbf{a}$ under the nonlinear transformation map - * $\mathbf{x} = \boldsymbol{\varphi} \left( \mathbf{X} \right)$. - * - * The returned result is the spatial normal scaled by the ratio of areas - * between the reference and spatial surface elements, i.e. - * @f[ - * \mathbf{n} \frac{da}{dA} - * := \textrm{det} \mathbf{F} \, \mathbf{F}^{-T} \cdot \mathbf{N} - * = \textrm{cof} \mathbf{F} \cdot \mathbf{N} \, . - * @f] - * - * @param[in] N The referential normal unit vector $\mathbf{N}$ - * @param[in] F The deformation gradient tensor $\mathbf{F} \left( \mathbf{X} \right)$ - * @return The scaled spatial normal vector $\mathbf{n} \frac{da}{dA}$ - * - * @dealiiHolzapfelA{75,2.55} - * @dealiiWriggersA{23,3.11} - */ + * Returns the result of applying Nanson's formula for the transformation + * of the material surface area element $d\mathbf{A}$ to the current + * surfaces area element $d\mathbf{a}$ under the nonlinear transformation + * map $\mathbf{x} = \boldsymbol{\varphi} \left( \mathbf{X} \right)$. + * + * The returned result is the spatial normal scaled by the ratio of areas + * between the reference and spatial surface elements, i.e. + * @f[ + * \mathbf{n} \frac{da}{dA} + * := \textrm{det} \mathbf{F} \, \mathbf{F}^{-T} \cdot \mathbf{N} + * = \textrm{cof} \mathbf{F} \cdot \mathbf{N} \, . + * @f] + * + * @param[in] N The referential normal unit vector $\mathbf{N}$ + * @param[in] F The deformation gradient tensor $\mathbf{F} \left( + * \mathbf{X} \right)$ + * @return The scaled spatial normal vector $\mathbf{n} + * \frac{da}{dA}$ + * + * @dealiiHolzapfelA{75,2.55} @dealiiWriggersA{23,3.11} + */ template Tensor<1,dim,Number> nansons_formula (const Tensor<1,dim,Number> &N, -- 2.39.5