From 16b2096c8234d8ccd2784cfd7379aec5ed9bffb5 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sun, 23 Aug 2015 19:12:39 -0500 Subject: [PATCH] improve documentation on rotation matrix for periodic boundary descriptions --- include/deal.II/dofs/dof_tools.h | 25 +++--------- include/deal.II/grid/grid_tools.h | 64 +++++++++++++------------------ 2 files changed, 31 insertions(+), 58 deletions(-) diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h index 178f471022..f4922d3b79 100644 --- a/include/deal.II/dofs/dof_tools.h +++ b/include/deal.II/dofs/dof_tools.h @@ -931,14 +931,15 @@ namespace DoFTools * into a ConstraintMatrix @p constraint_matrix. * * This is the main high level interface for above low level variant of - * make_periodicity_constraints(). It takes an std::vector @p periodic_faces - * as argument and applies above make_periodicity_constraints on each entry. - * @p periodic_faces can be created by GridTools::collect_periodic_faces. + * make_periodicity_constraints(). It takes a std::vector @p periodic_faces + * as argument and applies above make_periodicity_constraints() on each + * entry. @p periodic_faces can be created by + * GridTools::collect_periodic_faces. * * @note For DoFHandler objects that are built on a * parallel::distributed::Triangulation object * parallel::distributed::Triangulation::add_periodicity has to be called - * before. + * before calling this function.. * * @see * @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions" @@ -976,22 +977,6 @@ namespace DoFTools * 'first' boundary to the respective DoFs of the 'second' boundary * respecting the relative orientation of the two faces. * - * This routine only constrains DoFs that are not already constrained. If - * this routine encounters a DoF that already is constrained (for instance - * by Dirichlet boundary conditions), the old setting of the constraint - * (dofs the entry is constrained to, inhomogeneities) is kept and nothing - * happens. - * - * The flags in the last parameter, @p component_mask (see - * @ref GlossComponentMask) - * denote which components of the finite element space shall be constrained - * with periodic boundary conditions. If it is left as specified by the - * default value all components are constrained. If it is different from the - * default value, it is assumed that the number of entries equals the number - * of components in the boundary functions and the finite element, and those - * components in the given boundary function will be used for which the - * respective flag was set in the component mask. - * * @note: This function is a convenience wrapper. It internally calls * GridTools::collect_periodic_faces() with the supplied paramaters and * feeds the output to above make_periodicity_constraints() variant. If you diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index 19434191a6..daf233effd 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -936,17 +936,16 @@ namespace GridTools std::bitset<3> orientation; /** - * A matrix that describes how vector valued DoFs of the first face - * should be modified prior to constraining to the DoFs of the second - * face. If the std::vector first_vector_components (supplied as a - * parameter to DofTools::make_periodicity_constraints()) is non empty - * the matrix is interpreted as a @p dim $\times$ @p dim rotation - * matrix that is applied to all vector valued blocks listed in @p - * first_vector_components of the finite element space. Alternatively, - * if @p first_vector_components is empty the matrix is interpreted as - * an interpolation matrix with size no_face_dofs $\times$ - * no_face_dofs. For more details see - * DoFTools::make_periodicity_constraints() and the glossary + * A @p dim $\times$ @p dim rotation matrix that describes how vector + * valued DoFs of the first face should be modified prior to + * constraining to the DoFs of the second face. + * + * The rotation matrix is used in + * DoFTools::make_periodicity_constriants() by applying the rotation to + * all vector valued blocks listed in the parameter + * @p first_vector_components of the finite element space. + * For more details see DoFTools::make_periodicity_constraints() and + * the glossary * @ref GlossPeriodicConstraints "glossary entry on periodic conditions". */ FullMatrix matrix; @@ -959,11 +958,11 @@ namespace GridTools * @p face1 and @p face2 are considered equal, if a one to one matching * between its vertices can be achieved via an orthogonal equality relation. * - * Hereby, two vertices v_1 and v_2 are considered equal, + * Here, two vertices v_1 and v_2 are considered equal, * if $M\cdot v_1 + offset - v_2$ is parallel to the unit vector in unit * direction @p direction. If the parameter @p matrix is a reference to a - * spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is the - * identity matrix. + * spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is + * the identity matrix. * * If the matching was successful, the _relative_ orientation of @p face1 * with respect to @p face2 is returned in the bitset @p orientation, where @@ -1069,17 +1068,19 @@ namespace GridTools * them to the corresponding vertices of the 'second' boundary. This can * be used to implement conditions such as $u(0,y)=u(1,y+1)$. * - * Optionally, a @p matrix can be specified that describes how vector - * valued DoFs of the first face should be modified prior to constraining - * to the DoFs of the second face. If the matrix has size - * $n\_face\_dofs\times n\_face\_dofs$, the periodicity constraints are - * applied as $dofs\_2 = matrix\cdot dofs\_1$. If the matrix has size - * $dim\times dim$, the matrix is interpreted as a rotation matrix for - * vector valued components. - * For more details see DoFTools::make_periodicity_constraints(), the + * Optionally, a $dim\times dim$ rotation @p matrix can be specified that + * describes how vector valued DoFs of the first face should be modified + * prior to constraining to the DoFs of the second face. + * The @p matrix is used in two places. First, @p matrix will be supplied + * to orthogonal_equality() and used for matching faces: Two vertices + * $v_1$ and $v_2$ match if + * $\text{matrix}\cdot v_1 + \text{offset} - v_2$ + * is parallel to the unit vector in unit direction @p direction. + * (For more details see DoFTools::make_periodicity_constraints(), the * glossary * @ref GlossPeriodicConstraints "glossary entry on periodic conditions" - * and @ref step_45 "step-45". + * and @ref step_45 "step-45"). Second, @p matrix will be stored in the + * PeriodicFacePair collection @p matched_pairs for further use. * * @tparam Container A type that satisfies the requirements of a mesh * container (see @@ -1123,26 +1124,13 @@ namespace GridTools * This function will collect periodic face pairs on the coarsest mesh level * and add them to @p matched_pairs leaving the original contents intact. * - * Optionally, a @p matrix can be specified that describes how vector - * valued DoFs of the first face should be modified prior to constraining - * to the DoFs of the second face. If the matrix has size - * $n\_face\_dofs\times n\_face\_dofs$, the periodicity constraints are - * applied as $dofs\_2 = matrix\cdot dofs\_1$. If the matrix has size - * $dim\times dim$, the matrix is interpreted as a rotation matrix for - * vector valued components. For more details see - * DoFTools::make_periodicity_constraints(), the glossary - * @ref GlossPeriodicConstraints "glossary entry on periodic conditions" - * and @ref step_45 "step-45". - * - * @tparam Container A type that satisfies the requirements of a mesh - * container (see - * @ref GlossMeshAsAContainer). + * See above function for further details. * * @note This version of collect_periodic_face_pairs() will not work on * meshes with cells not in * @ref GlossFaceOrientation "standard orientation". * - * @author Daniel Arndt, Matthias Maier, 2013, 2014 + * @author Daniel Arndt, Matthias Maier, 2013 - 2015 */ template void -- 2.39.5