Fixup documentation for Periodicity constraints

diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index c623dfe1e37754b99329a4e5dd5475646aac8e95..02a10aef32ae7261cb7c28498d67210be1996309 100644 (file)
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------
 //
-// Copyright (C) 2005 - 2014 by the deal.II authors
+// Copyright (C) 2005 - 2015 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -1215,6 +1215,26 @@ Article{JK10,
  *     <td>Gauss points on edges(faces) and anisotropic Gauss points in the interior</td></tr>
  * </table>
  *
+ *
+ * <dt class="glossary">@anchor GlossPeriodicConstraints <b>Periodic boundary
+ * conditions</b></dt>
+ * <dd>Periodic boundary condition are often used when only part of the physical
+ * relevant domain is modeled. One assumes that the solution simply continues
+ * periodically with respect to the boundaries that are condiered periodic.
+ * In deal.II, support for this is through DoFTools::make_periodicity_constraints()
+ * and GridTools::collect_periodic_faces(). As soon as a
+ * parallel::distributed::Triangulation is used also
+ * parallel::distributed::Triangulation::add_periodicity() has to be called to make
+ * sure that all the processes know about relevant parts of the triangulation on both
+ * sides of the periodic boundary. A typical process for disctributed triangulations would be:
+ * -# Create a mesh
+ * -# Gather the periodic faces using GridTools::collect_periodic_faces() (Triangulation)
+ * -# Add the periodicity information to the mesh
+ * using parallel::distributed::Triangulation::add_periodicity()
+ * -# Gather the periodic faces using GridTools::collect_periodic_faces() (DoFHandler)
+ * -# Add periodicity constraints using DoFTools::make_periodicity_constraints()
+ *
+ *
  * <dt class="glossary">@anchor GlossPrimitive <b>Primitive finite
  * elements</b></dt>
  * <dd>A finite element (described by its shape functions) is primitive if

diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h
index b1ae1229679c65e11d06e40cc96564e03228975a..d33f8a1211c8e721e5212eb32cd60e7bdec197af 100644 (file)
--- a/include/deal.II/dofs/dof_tools.h
+++ b/include/deal.II/dofs/dof_tools.h
@@ -933,8 +933,7 @@ namespace DoFTools
    * 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.
-   * The std::vector @p periodic_faces can be created by
-   * GridTools::collect_periodic_faces.
+   * @p periodic_faces can be created by GridTools::collect_periodic_faces.
    *
    * @note For DoFHandler objects that are built on a
    * parallel::distributed::Triangulation object

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 3239513e252c7971702879601fcce69b3899fffd..ebd00565736085c2c0c40251029786ddadb16dac 100644 (file)
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -931,7 +931,7 @@ namespace GridTools
     /**
      * The relative orientation of the first face with respect to the second
      * face as described in orthogonal_equality() and
-     * make_periodicity_constraints() (and stored as a bitset).
+     * DoFTools::make_periodicity_constraints() (and stored as a bitset).
      */
     std::bitset<3> orientation;
 
@@ -945,7 +945,9 @@ namespace GridTools
      * first_vector_components of the FESystem. 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().
+     * For more details see DoFTools::make_periodicity_constraints() and
+     * the glossary
+     * @ref GlossPeriodicConstraints "glossary entry on periodic conditions".
      */
     FullMatrix<double> matrix;
   };
@@ -1060,14 +1062,14 @@ namespace GridTools
    * details.
    *
    * The @p direction refers to the space direction in which periodicity is
-   * enforced.
+   * enforced. When maching periodic faces this vector component is ignored.
    *
    * The @p offset is a vector tangential to the faces that is added to the
    * location of vertices of the 'first' boundary when attempting to match
    * them to the corresponding vertices of the 'second' boundary. This can
    * be used to implement conditions such as $u(0,y)=u(1,y+1)$.
    *
-   * Optionally a @p matrix can be specified that describes how vector
+   * 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
@@ -1075,8 +1077,9 @@ namespace GridTools
    * $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".
+   * 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
@@ -1124,9 +1127,11 @@ namespace GridTools
    * first_vector_components 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 @p first_vector_components is non empty the
-   * matrix is interpreted as a rotation matrix that is applied to all vector
-   * valued blocks listed in @p first_vector_components of the FESystem. For
-   * more details see make_periodicity_constraints() and the glossary
+   * matrix is interpreted as a rotation matrix that is applied to all
+   * vector valued blocks listed in @p first_vector_components of the
+   * FESystem. For more details see
+   * DoFTools::make_periodicity_constraints() and the glossary
+   *
    * @ref GlossPeriodicConstraints "glossary entry on periodic conditions".
    *
    * @tparam Container A type that satisfies the requirements of a mesh