Debian Codegraph @

include/deal.II/integrators/local_integrators.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_integrators_local_integrators_h
16 #define dealii_integrators_local_integrators_h
17
18 // This file only provides definition and documentation of the
19 // namespace LocalIntegrators. There is no necessity to include it
20 // anywhere in a C++ code. Only doxygen will make use of it.
21
22 #include <deal.II/base/config.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26
27 /**
28 * @brief Library of integrals over cells and faces
29 *
30 * @note The contents of this namespace are deprecated and will be removed in
31 * one of the next releases.
32 *
33 * This namespace contains application specific local integrals for bilinear
34 * forms, forms and error estimates. It is a collection of functions organized
35 * into namespaces devoted to certain applications. For instance, the
36 * namespace Laplace contains functions for computing cell matrices and cell
37 * residuals for the Laplacian operator, as well as functions for the weak
38 * boundary conditions by Nitsche or the interior penalty discontinuous
39 * Galerkin method. The namespace Maxwell does the same for curl-curl type
40 * problems.
41 *
42 * The namespace L2 contains functions for mass matrices and
43 * <i>L<sup>2</sup></i>-inner products.
44 *
45 * <h3>Notational conventions</h3>
46 *
47 * In most cases, the action of a function in this namespace can be described
48 * by a single integral. We distinguish between integrals over cells <i>Z</i>
49 * and over faces <i>F</i>. If an integral is denoted as
50 * @f[
51 * \int_Z u \otimes v \,dx,
52 * @f]
53 * it will yield the following results, depending on the type of operation
54 * <ul>
55 * <li> If the function returns a matrix, the entry at position <i>(i,j)</i>
56 * will be the integrated product of test function <i>v<sub>i</sub></i> and
57 * trial function <i>u<sub>j</sub></i> (note the reversion of indices)</li>
58 * <li> If the function returns a vector, then the vector entry at position
59 * <i>i</i> will be the integrated product of the given function <i>u</i> with
60 * the test function <i>v<sub>i</sub></i>.</li>
61 * <li> If the function returns a number, then this number is the integral of
62 * the two given functions <i>u</i> and <i>v</i>.
63 * </ul>
64 *
65 * We will use regular cursive symbols $u$ for scalars and bold symbols
66 * $\mathbf u$ for vectors. Test functions are always <i>v</i> and trial
67 * functions are always <i>u</i>. Parameters are Greek and the face normal
68 * vectors are $\mathbf n = \mathbf n_1 = -\mathbf n_2$.
69 *
70 * <h3>Signature of functions</h3>
71 *
72 * Functions in this namespace follow a generic signature. In the simplest
73 * case, you have two related functions
74 * @code
75 * template <int dim>
76 * void
77 * cell_matrix (
78 * FullMatrix<double>& M,
79 * const FEValuesBase<dim>& fe,
80 * const double factor = 1.);
81 *
82 * template <int dim>
83 * void
84 * cell_residual (
85 * BlockVector<double>* v,
86 * const FEValuesBase<dim>& fe,
87 * const std::vector<Tensor<1,dim> >& input,
88 * const double factor = 1.);
89 * @endcode
90 *
91 * There is typically a pair of functions for the same operator, the function
92 * <tt>cell_residual</tt> implementing the mapping of the operator from the
93 * finite element space into its dual, and the function <tt>cell_matrix</tt>
94 * generating the bilinear form corresponding to the Frechet derivative of
95 * <tt>cell_residual</tt>.
96 *
97 * The first argument of these functions is the return type, which is
98 * <ul>
99 * <li> FullMatrix&lt;double&gt; for matrices
100 * <li> BlockVector&ltdouble&gt; for vectors
101 * </ul>
102 *
103 * The next argument is the FEValuesBase object representing the finite
104 * element for integration. If the integrated operator maps from one finite
105 * element space into the dual of another (for instance an off-diagonal matrix
106 * in a block system), then first the FEValuesBase for the trial space and
107 * after this the one for the test space are specified.
108 *
109 * This list is followed by the set of required data in the order
110 * <ol>
111 * <li> Data vectors from finite element functions
112 * <li> Data vectors from other objects
113 * <li> Additional data
114 * <li> A factor which is multiplied with the whole result
115 * </ol>
116 *
117 * <h3>Usage</h3>
118 *
119 * The local integrators can be used wherever a local integration loop would
120 * have been implemented instead. The following example is from the
121 * implementation of a Stokes solver, using
122 * MeshWorker::Assembler::LocalBlocksToGlobalBlocks. The matrices are
123 * <ul>
124 * <li> 0: The vector Laplacian for the velocity (here with a vector valued
125 * element)
126 * <li> 1: The divergence matrix
127 * <li> 2: The pressure @ref GlossMassMatrix "mass matrix" used in the preconditioner
128 * </ul>
129 *
130 * With these matrices, the function called by MeshWorker::loop() could be
131 * written like
132 * @code
133 * using namespace dealii::LocalIntegrators;
134 *
135 * template <int dim>
136 * void MatrixIntegrator<dim>::cell(MeshWorker::DoFInfo<dim> &dinfo,
137 * MeshWorker::IntegrationInfo<dim> &info)
138 * {
139 * Laplace::cell_matrix (dinfo.matrix(0,false).matrix,
140 * info.fe_values(0));
141 * Divergence::cell_matrix (dinfo.matrix(1,false).matrix,
142 * info.fe_values(0),
143 * info.fe_values(1));
144 * L2::cell_matrix (dinfo.matrix(2,false).matrix,
145 * info.fe_values(1));
146 * }
147 * @endcode
148 * See step-39 for a worked out example of this code.
149 *
150 * @ingroup Integrators
151 */
152 namespace LocalIntegrators
153 {}
154
155 DEAL_II_NAMESPACE_CLOSE
156
157 #endif