]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Improve the matrix free doxygen module formatting. 7167/head
authorDavid Wells <drwells@email.unc.edu>
Mon, 27 Aug 2018 18:36:05 +0000 (14:36 -0400)
committerDavid Wells <drwells@email.unc.edu>
Thu, 13 Sep 2018 18:08:50 +0000 (14:08 -0400)
doc/doxygen/headers/matrixfree.h
include/deal.II/matrix_free/fe_evaluation.h
include/deal.II/matrix_free/mapping_info.h
include/deal.II/matrix_free/shape_info.h

index 9b29f9298ba442c9d826f66cba3cd18c928cfda8..3016828c9a6245c67d22d0c3427ae66159466dc6 100644 (file)
@@ -96,8 +96,8 @@
  * number type (e.g. double or float), but also on the polynomial degree and
  * on the number of quadrature points per spatial direction. This information
  * is used to pass the loop lengths in sum factorization to the respective
- * kernels (see `include/deal.II/matrix_free/tensor_product_kernels.h` and
- * `include/deal.II/matrix_free/evaluation_kernels.h`) and ensure optimal
+ * kernels (see `tensor_product_kernels.h` and
+ * `evaluation_kernels.h`) and ensure optimal
  * efficiency. All methods that access the vectors or provide access into the
  * data fields on an individual quadrature point are inherited from
  * FEEvaluationAccess.
  * first derivative of a selected number of basis functions evaluate to
  * nonzero on a face. The associated element type is FE_DGQHermite and the
  * decision is stored on the property
- * internal::MatrixFreeFunctions::ElementType::tensor_symmetric_hermite. The
+ * internal::MatrixFreeFunctions::tensor_symmetric_hermite. The
  * decision on whether such an optimized kernel can be used is made
  * automatically inside FEFaceEvaluation::gather_evaluate() and
  * FEFaceEvaluation::integrate_scatter(). It might seem inefficient to do this
  * <h3>The data storage through the MatrixFree class</h3>
  *
  * The tasks performed by FEEvaluation and FEFaceEvaluation can be split into
- * the three categories <i>index access into vectors</i>, <i>evaluation and
+ * the three categories: <i>index access into vectors</i>, <i>evaluation and
  * integration on the unit cell</i>, and <i>operation on quadrature points
  * including the geometry evaluation</i>. This split is reflected by the major
  * data fields contained by MatrixFree, using
  * for interleaving cell and face integrals such that the access to vector
  * entries for cell and face integrals re-uses data already in caches.
  *
- * <h4>Index storage: the MatrixFreeFunctions::DoFInfo struct</h4>
+ * <h4>Index storage: the internal::MatrixFreeFunctions::DoFInfo struct</h4>
  *
  * The main purpose of the DoFInfo class is to provide the indices consumed by
  * the vector access functions FEEvaluationBase::read_dof_values() and
  * <ol>
  * <li>Indices are stored in MPI-local index space to enable direct array
  * access, rather than translating a global index into a local one. The latter
- * would be absolutely detrimental to performance.
+ * would be absolutely detrimental to performance.</li>
  * <li>The indices are stored in a field called
  * internal::MatrixFreeFunctions::DoFInfo::dof_indices, which is a long index
  * array. The access granularity in terms of a <i>cell index</i> is controlled
  * systems becomes transparent if we provide a <i>start index</i> to every
  * single component separately. Thus, the `row_starts` field is of length
  * `n_cell_batches()*VectorizedArray<Number>::n_array_elements*n_components`.
+ * </li>
  * <li> The translation between components within a system of multiple base
- * elements is controlled by the four variables `std::vector<unsigned int>
- * n_components` (components per base element), `std::vector<unsigned int>
- * start_components` (translation from the base element to the unique
- * component number), `std::vector<unsigned int> component_to_base_index`
- * (translation from unique component number to base index), and
- * `std::vector<std::vector<unsigned int> > component_dof_indices_offset`
- * (offset of the particular component's range of degrees of freedom within
- * the full list of degrees of freedom on a cell).
- * <li>Information to extract the FE index in hp adaptive computations.
+ * elements is controlled by the four variables
+ * <ol>
+ *   <li>`std::vector<unsigned int> n_components` (components per base element),
+ *     </li>
+ *   <li>`std::vector<unsigned int> start_components` (translation from the base
+ *     element to the unique component number),</li>
+ *   <li>`std::vector<unsigned int> component_to_base_index` (translation from
+ *     unique component number to base index), and </li>
+ *   <li>`std::vector<std::vector<unsigned int>> component_dof_indices_offset`
+ *    (offset of the particular component's range of degrees of freedom within
+ *    the full list of degrees of freedom on a cell).</li>
+ * </ol>
+ * </li>
+ *
+ * <li>Information to extract the FE index in hp adaptive computations.</li>
  * <li>Information about the 'first access' into a particular vector entry
  * that is used to zero out the entries in a destination vectors within the
  * MatrixFree::loop shortly before accessing them the first time. This is used
- * to avoid writing zeros to the whole vector which destroys data locality.
+ * to avoid writing zeros to the whole vector which destroys data locality.</li>
  * </ol>
  *
- * The setup of the data structures in DoFInfo is done in a function called
- * `read_dof_indices`, where we first assume a very general finite element
- * layout, be it continuous or discontinuous elements, and where we resolve
- * the constraints due to hanging nodes. This initial step is done in the
- * original ordering of cells. In a later stage, these cells will in general
- * be rearranged to reflect the order by which we go through the cells in the
- * final loop, and we also look for patterns in the DoFIndices that can be
- * utilized, such as contiguous index ranges within a cell. This reordering is
- * done to enable overlap of communication and computation with MPI (if
- * enabled) and to form better group of batches with vectorization over
- * cells. The data storage of indices is linear in this final order, and
- * arranged in DoFInfo::reorder_cells.
+ * The setup of the data structures in internal::MatrixFreeFunctions::DoFInfo
+ * is done in internal::MatrixFreeFunctions::DoFInfo::read_dof_indices, where we
+ * first assume a very general finite element layout, be it continuous or
+ * discontinuous elements, and where we resolve the constraints due to hanging
+ * nodes. This initial step is done in the original ordering of cells. In a
+ * later stage, these cells will in general be rearranged to reflect the order
+ * by which we go through the cells in the final loop, and we also look for
+ * patterns in the DoF indices that can be utilized, such as contiguous index
+ * ranges within a cell. This reordering is done to enable overlap of
+ * communication and computation with MPI (if enabled) and to form better group
+ * of batches with vectorization over cells. The data storage of indices is
+ * linear in this final order, and arranged in
+ * internal::MatrixFreeFunctions::DoFInfo::reorder_cells.
  *
  * Since the amount of data to store indices is not negligible, it is
- * interesting to reduce the amount of data for special configuration that
+ * worthwhile to reduce the amount of data for special configurations that
  * carry more structure. One example is the case of FE_DGQ where a single
  * index per cell is enough to describe all its degrees of freedom, with the
- * others coming in consecutive order. The class DoFInfo contains a special
- * field `std::vector<unsigned int> dof_indices_contiguous` that contains a
- * single number per cell. Since both cell and face integrals use different
- * access patterns and the data in this special case is small, we are better
- * off storing 3 such vectors, one for the faces decorated as `interior`
- * (index 0), one for the faces decorated as `exterior` (index 1), and one for
- * the cells (index 2), rather than using the indirection through
- * FaceInfo. There is a series of additional special storage formats available
- * in DoFInfo. We refer to the documentation of the struct
- * internal::MatrixFreeFunctions::DoFInfo::IndexStorageVariants for the
- * options implemented in deal.II and their motivation.
+ * others coming in consecutive order. The class
+ * internal::MatrixFreeFunctions::DoFInfo contains a special array of vectors
+ * internal::MatrixFreeFunctions::DoFInfo::dof_indices_contiguous that
+ * contains a single number per cell. Since both cell and face integrals use
+ * different access patterns and the data in this special case is small, we
+ * are better off storing 3 such vectors, one for the faces decorated as
+ * `interior` (index 0), one for the faces decorated as `exterior` (index 1),
+ * and one for the cells (index 2), rather than using the indirection through
+ * internal::MatrixFreeFunctions::FaceInfo. There is a series of additional
+ * special storage formats available in DoFInfo. We refer to the documentation
+ * of the struct internal::MatrixFreeFunctions::DoFInfo::IndexStorageVariants
+ * for the options implemented in deal.II and their motivation.
  *
  * Finally, the DoFInfo class also holds a shared pointer describing the
  * parallel partitioning of the vectors. Due to the restriction of
  *
  * The MatrixFree class supports multiple DoFHandler objects to be passed to
  * the MatrixFree::reinit() function. For each of these DoFHandler objects, a
- * separate DoFInfo object is created. In MatrixFree, we store an
- * `std::vector` of DoFInfo objects to account for this fact.
+ * separate internal::MatrixFreeFunctions::DoFInfo object is created. In
+ * MatrixFree, we store a `std::vector` of
+ * internal::MatrixFreeFunctions::DoFInfo objects to account for this fact.
  *
  * <h4>The internal::MatrixFreeFunctions::ShapeInfo structure</h4>
  *
  * The evaluation of one-dimensional shape functions on one-dimensional
- * quadrature points is stored in the class ShapeInfo. More precisely, we hold
- * all function values, gradients, and hessians. Furthermore, the values and
+ * quadrature points is stored in the class
+ * internal::MatrixFreeFunctions::ShapeInfo. More precisely, we hold all
+ * function values, gradients, and hessians. Furthermore, the values and
  * derivatives of shape functions on the faces, i.e., the points 0 and 1 of
  * the unit interval, are also stored. For face integrals on hanging nodes,
  * the coarser of the two adjacent cells must interpolate the values not to
  * <h4>The internal::MatrixFreeFunctions::MappingInfo structure</h4>
  *
  * The evaluated geometry information is stored in the class
- * MappingInfo. Similarly to the DoFInfo class, multiple variants are possible
- * within a single MatrixFree instance, in this case based on multiple
- * quadrature formulas. Furthermore, separate data for both cells and faces is
- * stored.  Since there is more logic involved and there are synergies between
- * the fields, the `std::vector` of fields is kept within MappingInfo. The
- * individual field is of type
+ * internal::MatrixFreeFunctions::MappingInfo. Similarly to the
+ * internal::MatrixFreeFunctions::DoFInfo class, multiple variants are
+ * possible within a single MatrixFree instance, in this case based on
+ * multiple quadrature formulas. Furthermore, separate data for both cells and
+ * faces is stored. Since there is more logic involved and there are
+ * synergies between the fields, the `std::vector` of fields is kept within
+ * internal::MatrixFreeFunctions::MappingInfo. The individual field is of type
  * internal::MatrixFreeFunctions::MappingInfoStorage and holds arrays with the
  * inverse Jacobians, the JxW values, normal vectors, normal vectors times
  * inverse Jacobians (for FEEvaluationAccess::get_normal_derivative()),
  * lengths of fields similar to what is done for DoFInfo, but it also enables
  * something we call <i>geometry compression</i>. In order to reduce the data
  * access, we detect simple geometries of cells where Jacobians are constant
- * within a cell or also across cells, using a data field
- * internal::MatrixFreeFunctions::GeometryType:
+ * within a cell or also across cells, using
+ * internal::MatrixFreeFunctions::MappingInfo::cell_type:
  *
  * <ol>
  * <li> Cartesian cells are cells where the Jacobian is diagonal and the same
  * <li> On faces, we can have the special case that the normal vector is the
  * same in all quadrature points also when the JxW values are different. This
  * is the case for faces which are flat. To reduce the data access, we keep
- * this as a third option of compressed indices in `GeometryType`. As opposed
+ * this as a third option of compressed indices in
+ * internal::MatrixFreeFunctions::GeometryType. As opposed
  * to the Cartesian and affine case where only a single field is reserved in
  * the arrays, flat faces keep a separate entry for all quadrature points (to
  * keep a single index field `data_index_offsets`), but only access the first
  * points of all cells (with many different cases).
  * </ol>
  *
- * The implementation of MappingInfo is split into cell and face parts, so the
+ * The implementation of internal::MatrixFreeFunctions::MappingInfo is split
+ * into cell and face parts, so the
  * two components can be easily held apart. What makes the code a bit awkward
  * to read is the fact that we need to batch several objects together from the
  * original scalar evaluation done in an FEValues object, that we need to
  * compression over several cells with a `std::map` for the Cartesian and
  * affine cases.
  *
- * The data computation part of MappingInfo is parallelized by tasks besides
+ * The data computation part of internal::MatrixFreeFunctions::MappingInfo is
+ * parallelized by tasks besides
  * the obvious MPI parallelization. Each processor computes the information
  * on a subrange, before the data is eventually copied into a single combined
  * data field.
  * batch of cells gets intertwined when seen from a batch of faces (where we
  * only keep faces together that have the same face index within a cell and so
  * on). The setup of the face loop, which is done in the file
- * `include/deal.II/matrix_free/face_setup_internal.h`, tries to provide face
+ * `face_setup_internal.h`, tries to provide face
  * batches that at least partly resemble the cell patches, to increase the
  * data locality. Along these lines, the face work is also interleaved with
  * cell work in the typical MatrixFree::loop context, i.e., the `cell_range`
index eee84f020120c6ad62025879992784dd8f691b6d..fa22e3f4da619329e4912dd217d615a7650e599f 100644 (file)
@@ -2129,7 +2129,7 @@ protected:
  * way cells are looped by MatrixFree::cell_loop() can be different for
  * different DoFHandler or AffineConstraints arguments. More precisely, even
  * though the layout is going to be the same in serial, there is no guarantee
- * about the ordering for different DoFHandler/Constraints in the MPI
+ * about the ordering for different DoFHandler/AffineConstraints in the MPI
  * case. The reason is that the algorithm detects cells that need data
  * exchange with MPI and those can change for different elements &mdash; FE_Q
  * with hanging node constraints connects to more neighbors than a FE_DGQ
index de34fb84ade77395e88eda8788dee1a2e371e994..d9eb4ce39eddef0a4df0cb85ad2491dcdee2b3eb 100644 (file)
@@ -53,15 +53,18 @@ namespace internal
        * The cell or face is Cartesian.
        */
       cartesian = 0,
+
       /**
        * The cell or face can be described with an affine mapping.
        */
       affine = 1,
+
       /**
        * The face is flat, i.e., the normal factor on a face is the same on
        * all quadrature points. This type is not assigned for cells.
        */
       flat_faces = 2,
+
       /**
        * There is no special information available for compressing the
        * representation of the object under consideration.
index 54f8dfa52f06712f8cbe5f35eb5b826307a774ad..9533c9c94d4cc3e9d8a5cdc3c1ea8f25803fb846 100644 (file)
@@ -35,6 +35,8 @@ namespace internal
      * An enum that encodes the type of element detected during
      * initialization. FEEvaluation will select the most efficient algorithm
      * based on the given element type.
+     *
+     * @ingroup matrixfree
      */
     enum ElementType
     {
@@ -47,27 +49,32 @@ namespace internal
        * integration in the Gauss-Lobatto quadrature points of the same order.
        */
       tensor_symmetric_collocation = 0,
+
       /**
        * Symmetric tensor product shape functions fulfilling a Hermite
        * identity with values and first derivatives zero at the element end
        * points in 1D.
        */
       tensor_symmetric_hermite = 1,
+
       /**
        * Usual tensor product shape functions whose shape values and
        * quadrature points are symmetric about the midpoint of the unit
        * interval 0.5
        */
       tensor_symmetric = 2,
+
       /**
        * Tensor product shape functions without further particular properties
        */
       tensor_general = 3,
+
       /**
        * Polynomials of complete degree rather than tensor degree which can be
        * described by a truncated tensor product
        */
       truncated_tensor = 4,
+
       /**
        * Tensor product shape functions that are symmetric about the midpoint
        * of the unit interval 0.5 that additionally add a constant shape

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.