From 31c9db954965938190688f751114f0da3a7146b9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 11 Nov 2013 01:03:17 +0000 Subject: [PATCH] Provide documentation. git-svn-id: https://svn.dealii.org/trunk@31615 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/base/graph_coloring.h | 8 ++-- deal.II/include/deal.II/base/work_stream.h | 46 +++++++++++++++++-- 2 files changed, 46 insertions(+), 8 deletions(-) diff --git a/deal.II/include/deal.II/base/graph_coloring.h b/deal.II/include/deal.II/base/graph_coloring.h index d83fc85139..963716dca3 100644 --- a/deal.II/include/deal.II/base/graph_coloring.h +++ b/deal.II/include/deal.II/base/graph_coloring.h @@ -443,9 +443,11 @@ namespace GraphColoring * cells adjacent to the faces of the current cell (in the case of * discontinuous Galerkin methods, because there one computes face integrals * coupling the degrees of freedom connected by a common face -- see step-12). - * More generally, however, the conflict set needs to contain all degrees of - * freedom for which anything is written into the matrix or right hand side; - * in other words, if the writing happens through a function like + * + * @note The conflict set returned by the user defined function passed as + * third argument needs to accurately describe all degrees of + * freedom for which anything is written into the matrix or right hand side. + * In other words, if the writing happens through a function like * ConstraintMatrix::copy_local_to_global(), then the set of conflict indices * must actually contain not only the degrees of freedom on the current * cell, but also those they are linked to by constraints such as hanging diff --git a/deal.II/include/deal.II/base/work_stream.h b/deal.II/include/deal.II/base/work_stream.h index 4feb5bb0f3..61731df318 100644 --- a/deal.II/include/deal.II/base/work_stream.h +++ b/deal.II/include/deal.II/base/work_stream.h @@ -1128,10 +1128,11 @@ namespace WorkStream /** - * This is the main function of the WorkStream concept, doing work as - * described in the introduction to this namespace. + * This is one of two main functions of the WorkStream concept, doing work as + * described in the introduction to this namespace. It corresponds to + * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth. * - * This is the function that can be used for worker and copier objects that + * This function that can be used for worker and copier objects that * are either pointers to non-member functions or objects that allow to be * called with an operator(), for example objects created by std::bind. * @@ -1239,6 +1240,39 @@ namespace WorkStream } + /** + * This is one of two main functions of the WorkStream concept, doing work as + * described in the introduction to this namespace. It corresponds to + * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth. + * As such, it takes not a range of iterators described by a begin + * and end iterator, but a "colored" graph of iterators where each + * color represents cells for which writing the cell contributions into + * the global object does not conflict (in other words, these cells + * are not neighbors). Each "color" is represented by std::vectors of cells. + * The first argument to this function, a set of sets of cells (which are + * represent as a vector of vectors, for efficiency), is typically + * constructed by calling GraphColoring::make_graph_coloring(). + * + * This function that can be used for worker and copier objects that + * are either pointers to non-member functions or objects that allow to be + * called with an operator(), for example objects created by std::bind. + * + * The two data types ScratchData and CopyData need to + * have a working copy constructor. ScratchData is only used in the + * worker function, while CopyData is the object passed + * from the worker to the copier. + * + * The @p queue_length argument indicates the number of items that can be + * live at any given time. Each item consists of @p chunk_size elements of + * the input stream that will be worked on by the worker and copier + * functions one after the other on the same thread. + * + * @note If your data objects are large, or their constructors are + * expensive, it is helpful to keep in mind that queue_length + * copies of the ScratchData object and + * queue_length*chunk_size copies of the CopyData object + * are generated. + */ template