Debian Codegraph @

include/deal.II/lac/constrained_linear_operator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 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_constrained_linear_operator_h
16 #define dealii_constrained_linear_operator_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/lac/affine_constraints.h>
21 #include <deal.II/lac/linear_operator.h>
22 #include <deal.II/lac/packaged_operation.h>
23
24
25 DEAL_II_NAMESPACE_OPEN
26
27
28 /**
29 * @name Indirectly applying constraints to LinearOperator
30 */
31 /** @{ */
32
33
34 /**
35 * This function takes an AffineConstraints object @p constraints and
36 * an operator exemplar @p exemplar (this exemplar is usually a linear
37 * operator that describes the system matrix - it is only used to create
38 * domain and range vectors of appropriate sizes, its action <tt>vmult</tt>
39 * is never used). A LinearOperator object associated with the "homogeneous
40 * action" of the underlying AffineConstraints object is returned:
41 *
42 * Applying the LinearOperator object on a vector <code>u</code> results in a
43 * vector <code>v</code> that stores the result of calling
44 * AffineConstraints::distribute() on <code>u</code> - with one important
45 * difference: inhomogeneities are not applied, but always treated as 0
46 * instead.
47 *
48 * The LinearOperator object created by this function is primarily used
49 * internally in constrained_linear_operator() to build up a modified system
50 * of linear equations. How to solve a linear system of equations with this
51 * approach is explained in detail in the
52 * @ref constraints
53 * topic.
54 *
55 *
56 * @note Currently, this function may not work correctly for distributed data
57 * structures.
58 *
59 * @relatesalso LinearOperator
60 * @ingroup constraints
61 */
62 template <typename Range, typename Domain, typename Payload>
63 LinearOperator<Range, Domain, Payload>
64 distribute_constraints_linear_operator(
65 const AffineConstraints<typename Range::value_type> &constraints,
66 const LinearOperator<Range, Domain, Payload> &exemplar)
67 {
68 LinearOperator<Range, Domain, Payload> return_op = exemplar;
69
70 return_op.vmult_add = [&constraints](Range &v, const Domain &u) {
71 Assert(!dealii::PointerComparison::equal(&v, &u),
72 dealii::ExcMessage("The domain and range vectors must be different "
73 "storage locations"));
74
75 // First, add vector u to v unconditionally and clean up constrained
76 // degrees of freedom later.
77 v += u;
78
79 const auto &locally_owned_elements = v.locally_owned_elements();
80 for (const auto &line : constraints.get_lines())
81 {
82 const auto i = line.index;
83 if (locally_owned_elements.is_element(i))
84 {
85 v(i) -= u(i);
86 const auto &entries = line.entries;
87 for (types::global_dof_index j = 0; j < entries.size(); ++j)
88 {
89 const auto pos = entries[j].first;
90 v(i) += u(pos) * entries[j].second;
91 }
92 }
93 }
94
95 v.compress(VectorOperation::add);
96 };
97
98 return_op.Tvmult_add = [&constraints](Domain &v, const Range &u) {
99 Assert(!dealii::PointerComparison::equal(&v, &u),
100 dealii::ExcMessage("The domain and range vectors must be different "
101 "storage locations"));
102
103 // First, add vector u to v unconditionally and clean up constrained
104 // degrees of freedom later.
105 v += u;
106
107 const auto &locally_owned_elements = v.locally_owned_elements();
108 for (const auto &line : constraints.get_lines())
109 {
110 const auto i = line.index;
111
112 if (locally_owned_elements.is_element(i))
113 {
114 v(i) -= u(i);
115 }
116
117 const auto &entries = line.entries;
118 for (types::global_dof_index j = 0; j < entries.size(); ++j)
119 {
120 const auto pos = entries[j].first;
121 if (locally_owned_elements.is_element(pos))
122 v(pos) += u(i) * entries[j].second;
123 }
124 }
125
126 v.compress(VectorOperation::add);
127 };
128
129 return_op.vmult = [vmult_add = return_op.vmult_add](Range &v,
130 const Domain &u) {
131 v = 0.;
132 vmult_add(v, u);
133 };
134
135 return_op.Tvmult = [Tvmult_add = return_op.Tvmult_add](Domain &v,
136 const Range &u) {
137 v = 0.;
138 Tvmult_add(v, u);
139 };
140
141 return return_op;
142 }
143
144
145 /**
146 * Given a AffineConstraints @p constraints and an operator exemplar @p
147 * exemplar, return a LinearOperator that is the projection to the subspace of
148 * constrained degrees of freedom, i.e. all entries of the result vector that
149 * correspond to unconstrained degrees of freedom are set to zero.
150 *
151 *
152 * @relatesalso LinearOperator
153 * @ingroup constraints
154 */
155 template <typename Range, typename Domain, typename Payload>
156 LinearOperator<Range, Domain, Payload>
157 project_to_constrained_linear_operator(
158 const AffineConstraints<typename Range::value_type> &constraints,
159 const LinearOperator<Range, Domain, Payload> &exemplar)
160 {
161 LinearOperator<Range, Domain, Payload> return_op = exemplar;
162
163 return_op.vmult_add = [&constraints](Range &v, const Domain &u) {
164 const auto &locally_owned_elements = v.locally_owned_elements();
165 for (const auto &line : constraints.get_lines())
166 {
167 const auto i = line.index;
168 if (locally_owned_elements.is_element(i))
169 {
170 v(i) += u(i);
171 }
172 }
173
174 v.compress(VectorOperation::add);
175 };
176
177 return_op.Tvmult_add = [&constraints](Domain &v, const Range &u) {
178 const auto &locally_owned_elements = v.locally_owned_elements();
179 for (const auto &line : constraints.get_lines())
180 {
181 const auto i = line.index;
182 if (locally_owned_elements.is_element(i))
183 {
184 v(i) += u(i);
185 }
186 }
187
188 v.compress(VectorOperation::add);
189 };
190
191 return_op.vmult = [vmult_add = return_op.vmult_add](Range &v,
192 const Domain &u) {
193 v = 0.;
194 vmult_add(v, u);
195 };
196
197 return_op.Tvmult = [Tvmult_add = return_op.Tvmult_add](Domain &v,
198 const Range &u) {
199 v = 0.;
200 Tvmult_add(v, u);
201 };
202
203 return return_op;
204 }
205
206
207 /**
208 * Given a AffineConstraints object @p constraints and a LinearOperator
209 * @p linop, this function creates a LinearOperator object consisting of the
210 * composition of three operations and a regularization:
211 * @code
212 * Ct * linop * C + Id_c;
213 * @endcode
214 * with
215 * @code
216 * C = distribute_constraints_linear_operator(constraints, linop);
217 * Ct = transpose_operator(C);
218 * Id_c = project_to_constrained_linear_operator(constraints, linop);
219 * @endcode
220 * and <code>Id_c</code> is the projection to the subspace consisting of all
221 * vector entries associated with constrained degrees of freedom.
222 *
223 * This LinearOperator object is used together with
224 * constrained_right_hand_side() to build up the following modified system of
225 * linear equations:
226 * @f[
227 * (C^T A C + Id_c) x = C^T (b - A\,k)
228 * @f]
229 * with a given (unconstrained) system matrix $A$, right hand side $b$, and
230 * linear constraints $C$ with inhomogeneities $k$.
231 *
232 * A detailed explanation of this approach is given in the
233 * @ref constraints
234 * topic.
235 *
236 *
237 * @note Currently, this function may not work correctly for distributed data
238 * structures.
239 *
240 * @relatesalso LinearOperator
241 * @ingroup constraints
242 */
243 template <typename Range, typename Domain, typename Payload>
244 LinearOperator<Range, Domain, Payload>
245 constrained_linear_operator(
246 const AffineConstraints<typename Range::value_type> &constraints,
247 const LinearOperator<Range, Domain, Payload> &linop)
248 {
249 const auto C = distribute_constraints_linear_operator(constraints, linop);
250 const auto Ct = transpose_operator(C);
251 const auto Id_c = project_to_constrained_linear_operator(constraints, linop);
252 return Ct * linop * C + Id_c;
253 }
254
255
256 /**
257 * Given a AffineConstraints object @p constraints, a LinearOperator @p
258 * linop and a right-hand side @p right_hand_side, this function creates a
259 * PackagedOperation that stores the following computation:
260 * @code
261 * Ct * (right_hand_side - linop * k)
262 * @endcode
263 * with
264 * @code
265 * C = distribute_constraints_linear_operator(constraints, linop);
266 * Ct = transpose_operator(C);
267 * @endcode
268 *
269 * This LinearOperator object is used together with
270 * constrained_right_hand_side() to build up the following modified system of
271 * linear equations:
272 * @f[
273 * (C^T A C + Id_c) x = C^T (b - A\,k)
274 * @f]
275 * with a given (unconstrained) system matrix $A$, right hand side $b$, and
276 * linear constraints $C$ with inhomogeneities $k$.
277 *
278 * A detailed explanation of this approach is given in the
279 * @ref constraints
280 * topic.
281 *
282 *
283 * @note Currently, this function may not work correctly for distributed data
284 * structures.
285 *
286 * @relatesalso LinearOperator
287 * @ingroup constraints
288 */
289 template <typename Range, typename Domain, typename Payload>
290 PackagedOperation<Range>
291 constrained_right_hand_side(
292 const AffineConstraints<typename Range::value_type> &constraints,
293 const LinearOperator<Range, Domain, Payload> &linop,
294 const Range &right_hand_side)
295 {
296 PackagedOperation<Range> return_comp;
297
298 return_comp.reinit_vector = linop.reinit_range_vector;
299
300 return_comp.apply_add = [&constraints, &linop, &right_hand_side](Range &v) {
301 const auto C = distribute_constraints_linear_operator(constraints, linop);
302 const auto Ct = transpose_operator(C);
303
304 GrowingVectorMemory<Domain> vector_memory;
305 typename VectorMemory<Domain>::Pointer k(vector_memory);
306 linop.reinit_domain_vector(*k, /*bool fast=*/false);
307 constraints.distribute(*k);
308
309 v += Ct * (right_hand_side - linop * *k);
310 };
311
312 return_comp.apply = [apply_add = return_comp.apply_add](Range &v) {
313 v = 0.;
314 apply_add(v);
315 };
316
317 return return_comp;
318 }
319
320 /** @} */
321
322 DEAL_II_NAMESPACE_CLOSE
323
324 #endif