| 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<double> for matrices |
| 100 |
* <li> BlockVector<double> 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 |