From a4e655b59f7159dddaf888dbed0cb532ef1e867a Mon Sep 17 00:00:00 2001 From: kanschat Date: Mon, 5 Oct 2009 15:48:09 +0000 Subject: [PATCH] remove doxygen complaints and improve documentation of step 38 git-svn-id: https://svn.dealii.org/trunk@19707 0785d39b-7218-0410-832d-ea1e28bc413d --- .../deal.II/include/numerics/mesh_worker.h | 44 +++++++++++ .../include/numerics/mesh_worker_info.h | 7 -- .../numerics/mesh_worker_vector_selector.h | 10 ++- deal.II/examples/step-38/doc/intro.dox | 19 +++-- deal.II/examples/step-38/step-38.cc | 79 +++++++++---------- deal.II/lac/include/lac/constraint_matrix.h | 5 +- deal.II/lac/include/lac/petsc_block_vector.h | 1 - .../include/lac/petsc_parallel_block_vector.h | 3 +- .../lac/include/lac/petsc_parallel_vector.h | 3 +- deal.II/lac/include/lac/petsc_vector.h | 1 - deal.II/lac/include/lac/petsc_vector_base.h | 1 - .../lac/include/lac/trilinos_block_vector.h | 2 - deal.II/lac/include/lac/trilinos_vector.h | 2 - .../lac/include/lac/trilinos_vector_base.h | 1 - 14 files changed, 107 insertions(+), 71 deletions(-) diff --git a/deal.II/deal.II/include/numerics/mesh_worker.h b/deal.II/deal.II/include/numerics/mesh_worker.h index b4bef51b70..4f34fa7573 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker.h +++ b/deal.II/deal.II/include/numerics/mesh_worker.h @@ -60,6 +60,50 @@ template class MGDoFHandler; * class responsible for the local integration: * * @code + * template + * class LocalIntegrator : public Subscriptor + * { + * void cell(typename MeshWorker::IntegrationWorker::CellInfo& info) const; + * void bdry(typename MeshWorker::IntegrationWorker::FaceInfo& info) const; + * void face(typename MeshWorker::IntegrationWorker::FaceInfo& info1, + * typename MeshWorker::IntegrationWorker::FaceInfo& info2) const; + * }; + * @endcode + * The three functions in there must have exactly this signature and + * should do the integration on cells, boundary and interior faces, + * respectively. + * + * Then, create the AssemblingIntegrator object, where the second + * template argument decides on what kind of global data is + * assembled. In the following, we decide to assemble a simple + * SparseMatrix with no block structure: + * + * @code + * LocalIntegrator loc; + * MeshWorker::AssemblingIntegrator >, LocalIntegrator > + * integrator(loc); + * @endcode + * + * Before we can run the integration loop, we have to initialize + * several data structures in our AssemblingIntegrator. For instance, + * we have to decide on the quadrature rule or we may need more than + * the default update flags. + * + * @code + * integrator.initialize_gauss_quadrature(2,2,2); + * integrator.add_update_flags(update_values | update_gradients, true, true, true, true); + * integrator.initialize(system_matrix); + * @endcode + * + * Finally, we set up the structures needed by the integration_loop() + * and run it. + * + * @code + * MeshWorker::IntegrationInfoBox info_box(dof_handler); + * info_box.initialize(integrator, fe, mapping); + * + * MeshWorker::integration_loop(dof_handler.begin_active(), dof_handler.end(), + * info_box, integrator); * @endcode * * @author Guido Kanschat, 2009 diff --git a/deal.II/deal.II/include/numerics/mesh_worker_info.h b/deal.II/deal.II/include/numerics/mesh_worker_info.h index c0e8e5213c..1c0a1f0bea 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker_info.h +++ b/deal.II/deal.II/include/numerics/mesh_worker_info.h @@ -346,13 +346,6 @@ namespace MeshWorker * and allocate space for * data vectors. * - * @param fe is only used - * to determine the type of - * the element and can be a - * null pointer to FEValues, - * FEVaceValues or - * FESubfaceValues. - * * @param el is the finite * element of the DoFHandler. * diff --git a/deal.II/deal.II/include/numerics/mesh_worker_vector_selector.h b/deal.II/deal.II/include/numerics/mesh_worker_vector_selector.h index 73f5f81092..c4fadab0cd 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker_vector_selector.h +++ b/deal.II/deal.II/include/numerics/mesh_worker_vector_selector.h @@ -209,9 +209,13 @@ namespace MeshWorker * the subset of @p indices * used. * - * @param block is the block - * number processed, or zero if - * no base elements are used. + * @param component is the first + * index in @p values, @p + * gradients and @p hessians + * entered in this function. + * + * @param n_comp is the number + * of components to be filled. * * @param start is the first * index of this block in @p diff --git a/deal.II/examples/step-38/doc/intro.dox b/deal.II/examples/step-38/doc/intro.dox index 2f9248cc02..edbf0491e6 100644 --- a/deal.II/examples/step-38/doc/intro.dox +++ b/deal.II/examples/step-38/doc/intro.dox @@ -1,13 +1,20 @@ -

This will be an example of the new MeshWorker framework and will be available soon

+

Example of the MeshWorker framework with an advection problem

Overview

-This example is devoted to the discontinuous Galerkin method, -or in short: DG method. It solves the same problem as step-12 (see -there for a description of the problem and discretization), but here -we use the MeshWorker framework in order to save reprogramming the -cell/face loops. +This example is devoted to the MeshWorker framework and the +discontinuous Galerkin method, or in short: DG method. It +solves the same problem as @ref step_12 "step-12" (see there for a description of the +problem and discretization), but here we use the MeshWorker framework +in order to save reprogramming the cell/face loops. + +In particular the loops of DG methods turn out to be complex, because +for the face terms, we have to distinguish the cases of boundary, +regular interior faces and interior faces with hanging nodes, +respectively. The MeshWorker framework implements the standard loop +over all cells and faces in MeshWorker::loop() and takes care of +distinguishing between all the different faces.

Implementation

diff --git a/deal.II/examples/step-38/step-38.cc b/deal.II/examples/step-38/step-38.cc index ab36d414dc..8aa23c35af 100644 --- a/deal.II/examples/step-38/step-38.cc +++ b/deal.II/examples/step-38/step-38.cc @@ -181,39 +181,20 @@ void BoundaryValues::value_list(const std::vector > &points, // @sect3{Integrating cell and face matrices} // - // In order to use the MeshWorker - // framework, we need to define a - // worker object, which serves three - // purposes. First, it performs the - // local integration on each mesh - // cell. Second, it controls the loop - // over cells and faces and the data - // being generated. This part is - // easily implemented here, since the - // default structure can be - // used. Finally, through its base - // class from the - // MeshWorker::Assembler namespace, - // this object determines, how locally - // produced data is assembled into - // the global system. - // - // The fist base class is - // MeshWorker::IntegrationWorker. It - // has all the control structures the - // generic loop needs. Fortunately, - // most of them have reasonable - // default values. The others will be - // set below. - // - // The second base class is - // MeshWorker::Assembler::SystemSimple, - // which will assemble the matrices - // and residuals on cells and faces, - // respectively, into the global - // system. The "simple" indicates - // that we do not want to use - // sophisticated block structures. + // We define a class that fits into + // the MeshWorker framework. Since it + // will be used by + // MeshWorker::AssemblingIntegrator, + // it needs the functions for cell, + // boundary and interior face + // integration specified exactly as + // below. + + // The base class Subscriptor is + // needed so that + // MeshWorker::AssemblingIntegrator + // can store a SmartPointer to an + // object of this class. template class DGIntegrator : public Subscriptor { @@ -236,7 +217,8 @@ class DGIntegrator : public Subscriptor void bdry(FaceInfo& info) const; void face(FaceInfo& info1, FaceInfo& info2) const; - // Additionally, like in step 12, + // Additionally, like in @ref + // step_12 "step-12", // we have objects of the // functions used in this class. private: @@ -246,6 +228,7 @@ class DGIntegrator : public Subscriptor }; // @sect4{The local integrators} + // These functions are analogous to // step 12 and differ only in the // data structures. Instead of @@ -573,18 +556,32 @@ void DGMethod::assemble_system () // This is the magic object, which // knows everything about the data - // structures and local - // integration (the latter through - // our object @p dg). This is the - // object doing the work in the - // function MeshWorker::loop, which - // is implicitly called - // below. After @p dg did the local + // structures and local integration + // (the latter through our object + // @p dg). This is the object doing + // the work in the function + // MeshWorker::loop(), which is + // implicitly called by + // MeshWorker::integration_loop() + // below. + // After @p dg did the local // integration, the // MeshWorker::Assembler::SystemSimple // object distributes these into // the global sparse matrix and the // right hand side vector. + // + // It turns out, + // MeshWorker::AssemblingIntegrator + // itself is not that clever at + // all, but all its capabilities + // are provided by the two later + // template arguments. By + // exchanging + // MeshWorker::Assembler::SystemSimple, + // we could for instance assemble a + // BlockMatrix or just a Vector + // instead. MeshWorker::AssemblingIntegrator, Vector >, DGIntegrator > integrator(dg); diff --git a/deal.II/lac/include/lac/constraint_matrix.h b/deal.II/lac/include/lac/constraint_matrix.h index c98ab653e3..998350e4e3 100644 --- a/deal.II/lac/include/lac/constraint_matrix.h +++ b/deal.II/lac/include/lac/constraint_matrix.h @@ -1234,8 +1234,9 @@ class ConstraintMatrix : public Subscriptor * write into a matrix but only allocate * sparsity pattern entries. * - * As explained in the @ref hp_paper "hp - * paper" and in @ref step_27 "step-27", + * As explained in the + * @ref hp_paper "hp paper" + * and in @ref step_27 "step-27", * first allocating a sparsity pattern * and later coming back and allocating * additional entries for those matrix diff --git a/deal.II/lac/include/lac/petsc_block_vector.h b/deal.II/lac/include/lac/petsc_block_vector.h index 97224dab68..6026ac6c7c 100644 --- a/deal.II/lac/include/lac/petsc_block_vector.h +++ b/deal.II/lac/include/lac/petsc_block_vector.h @@ -469,7 +469,6 @@ namespace PETScWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup PETScWrappers * @relates PETScWrappers::BlockVector * @author Wolfgang Bangerth, 2000 */ diff --git a/deal.II/lac/include/lac/petsc_parallel_block_vector.h b/deal.II/lac/include/lac/petsc_parallel_block_vector.h index a87b9b7361..393d2caebd 100644 --- a/deal.II/lac/include/lac/petsc_parallel_block_vector.h +++ b/deal.II/lac/include/lac/petsc_parallel_block_vector.h @@ -2,7 +2,7 @@ // $Id$ // Version: $Name$ // -// Copyright (C) 2004, 2005, 2006, 2007 by the deal.II authors +// Copyright (C) 2004, 2005, 2006, 2007, 2009 by the deal.II authors // // This file is subject to QPL and may not be distributed // without copyright and license information. Please refer @@ -459,7 +459,6 @@ namespace PETScWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup PETScWrappers * @relates PETScWrappers::MPI::BlockVector * @author Wolfgang Bangerth, 2000 */ diff --git a/deal.II/lac/include/lac/petsc_parallel_vector.h b/deal.II/lac/include/lac/petsc_parallel_vector.h index 004784360b..440a1b0e77 100644 --- a/deal.II/lac/include/lac/petsc_parallel_vector.h +++ b/deal.II/lac/include/lac/petsc_parallel_vector.h @@ -2,7 +2,7 @@ // $Id$ // Version: $Name$ // -// Copyright (C) 2004, 2005, 2006, 2007 by the deal.II authors +// Copyright (C) 2004, 2005, 2006, 2007, 2009 by the deal.II authors // // This file is subject to QPL and may not be distributed // without copyright and license information. Please refer @@ -382,7 +382,6 @@ namespace PETScWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup PETScWrappers * @relates PETScWrappers::MPI::Vector * @author Wolfgang Bangerth, 2004 */ diff --git a/deal.II/lac/include/lac/petsc_vector.h b/deal.II/lac/include/lac/petsc_vector.h index 16721ee341..fbe1a67390 100644 --- a/deal.II/lac/include/lac/petsc_vector.h +++ b/deal.II/lac/include/lac/petsc_vector.h @@ -204,7 +204,6 @@ namespace PETScWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup PETScWrappers * @relates PETScWrappers::Vector * @author Wolfgang Bangerth, 2004 */ diff --git a/deal.II/lac/include/lac/petsc_vector_base.h b/deal.II/lac/include/lac/petsc_vector_base.h index 8762b5f9a6..3f2e79403c 100644 --- a/deal.II/lac/include/lac/petsc_vector_base.h +++ b/deal.II/lac/include/lac/petsc_vector_base.h @@ -772,7 +772,6 @@ namespace PETScWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup PETScWrappers * @relates PETScWrappers::VectorBase * @author Wolfgang Bangerth, 2004 */ diff --git a/deal.II/lac/include/lac/trilinos_block_vector.h b/deal.II/lac/include/lac/trilinos_block_vector.h index 845399c8a0..bc65485c11 100644 --- a/deal.II/lac/include/lac/trilinos_block_vector.h +++ b/deal.II/lac/include/lac/trilinos_block_vector.h @@ -438,7 +438,6 @@ namespace TrilinosWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup TrilinosWrappers * @relates TrilinosWrappers::MPI::BlockVector * @author Martin Kronbichler, Wolfgang Bangerth, 2008 */ @@ -898,7 +897,6 @@ namespace TrilinosWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup TrilinosWrappers * @relates TrilinosWrappers::BlockVector * @author Martin Kronbichler, 2008 */ diff --git a/deal.II/lac/include/lac/trilinos_vector.h b/deal.II/lac/include/lac/trilinos_vector.h index ba27a9bf4e..7838e7691a 100644 --- a/deal.II/lac/include/lac/trilinos_vector.h +++ b/deal.II/lac/include/lac/trilinos_vector.h @@ -413,7 +413,6 @@ namespace TrilinosWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup TrilinosWrappers * @relates TrilinosWrappers::MPI::Vector * @author Martin Kronbichler, Wolfgang Bangerth, 2008 */ @@ -646,7 +645,6 @@ namespace TrilinosWrappers * of the C++ standard library which uses a temporary object. The * function simply exchanges the data of the two vectors. * - * @ingroup TrilinosWrappers * @relates TrilinosWrappers::Vector * @author Martin Kronbichler, Wolfgang Bangerth, 2008 */ diff --git a/deal.II/lac/include/lac/trilinos_vector_base.h b/deal.II/lac/include/lac/trilinos_vector_base.h index 04a35a43ff..85526044cc 100644 --- a/deal.II/lac/include/lac/trilinos_vector_base.h +++ b/deal.II/lac/include/lac/trilinos_vector_base.h @@ -963,7 +963,6 @@ namespace TrilinosWrappers * the C standard library which uses a temporary object. The function * simply exchanges the data of the two vectors. * - * @ingroup TrilinosWrappers * @relates TrilinosWrappers::VectorBase * @author Martin Kronbichler, Wolfgang Bangerth, 2008 */ -- 2.39.5