Debian Codegraph @

include/deal.II/meshworker/local_results.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 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
16 #ifndef dealii_mesh_worker_local_results_h
17 #define dealii_mesh_worker_local_results_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/geometry_info.h>
22
23 #include <deal.II/lac/block_vector.h>
24 #include <deal.II/lac/matrix_block.h>
25
26 #include <deal.II/meshworker/vector_selector.h>
27
28 #include <functional>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declaration
33 #ifndef DOXYGEN
34 class BlockIndices;
35 #endif
36
37 namespace MeshWorker
38 {
39 /**
40 * The class providing the scrapbook to fill with results of local
41 * integration. Depending on the task the mesh worker loop is performing,
42 * local results can be of different types: They can be scalars, vectors
43 * of size equal to the number of degrees of freedom used in the integrals,
44 * or square matrices of that same size. All of these have in common that they
45 * are the result of local integration over a cell or face. Which kind of
46 * object is the result of an operation is determined by the Assembler using
47 * them. It is also the assembler that determines <i>how many</i> of each
48 * kind of object are produced (for example, an assembler may create
49 * both the local contributions to a mass and a @ref GlossStiffnessMatrix "stiffness matrix"), and for
50 * setting the arrays of local results to the sizes needed.
51 *
52 * The interface of this class allows accessing all of this information
53 * via the following functions:
54 *
55 * <ol>
56 * <li> Scalars: n_values() returns the number of scalars stored by
57 * an object of this class, and they are accessed via the value() function.
58 *
59 * <li> Vectors: n_vectors() returns the number of vectors stored by
60 * an object of this class (each vector has length equal to the number of
61 * degrees of freedom on this cell on which the integration happens).
62 * The vectors are accessed by the vector() function.
63 *
64 * <li> Matrices: n_matrices() returns the number of matrices stored,
65 * each of which is a square matrix of dimension equal to the number of
66 * degrees of freedom per cell. The matrices are
67 * accessed by matrix() with second argument <tt>false</tt>. These are
68 * matrices coupling degrees of freedom in
69 * the same cell. For fluxes across faces, there is an additional set of
70 * matrices of the same size, with the dimension of these matrices being
71 * according to the degrees of freedom on both cells. These are accessed
72 * with matrix(), using the second argument <tt>true</tt>.
73 * </ol>
74 *
75 * The local matrices are initialized by reinit() of the @p info object and then
76 * assembled into the global system by Assembler classes.
77 *
78 * @ingroup MeshWorker
79 */
80 template <typename number>
81 class LocalResults
82 {
83 public:
84 /**
85 * The number of scalar values stored by the current object.
86 *
87 * This number is set to a nonzero value by Assembler::CellsAndFaces
88 */
89 unsigned int
90 n_values() const;
91
92 /**
93 * The number of vectors stored by the current object.
94 *
95 * This number is set to a nonzero value by Assembler::ResidualSimple and
96 * Assembler::ResidualLocalBlocksToGlobalBlocks.
97 */
98 unsigned int
99 n_vectors() const;
100
101 /**
102 * The number of matrices stored by the current object.
103 */
104 unsigned int
105 n_matrices() const;
106
107 /**
108 * The number of quadrature points in quadrature_values().
109 */
110 unsigned int
111 n_quadrature_points() const;
112
113 /**
114 * The number of values in each quadrature point in quadrature_values().
115 */
116 unsigned int
117 n_quadrature_values() const;
118
119 /**
120 * Read-write access to the `i`th scalar stored by this class.
121 */
122 number &
123 value(const unsigned int i);
124
125 /**
126 * Read access to the `i`th scalar stored by this class.
127 */
128 number
129 value(const unsigned int i) const;
130
131 /**
132 * Read-write access to the `i`th vector stored by this class
133 */
134 BlockVector<number> &
135 vector(const unsigned int i);
136
137 /**
138 * Read-write access to the `i`th vector stored by this class
139 */
140 const BlockVector<number> &
141 vector(const unsigned int i) const;
142
143 /**
144 * Read-write access to the `i`th matrix stored by this class.
145 *
146 * For an explanation of the second argument, see the documentation
147 * of the current class itself.
148 */
149 MatrixBlock<FullMatrix<number>> &
150 matrix(const unsigned int i, const bool external = false);
151
152 /**
153 * Read access to the `i`th matrix stored by this class.
154 *
155 * For an explanation of the second argument, see the documentation
156 * of the current class itself.
157 */
158 const MatrixBlock<FullMatrix<number>> &
159 matrix(const unsigned int i, const bool external = false) const;
160
161 /**
162 * Access to the vector #quadrature_data of data in quadrature points,
163 * organized such that there is a vector for each point, containing one
164 * entry for each component.
165 */
166 Table<2, number> &
167 quadrature_values();
168
169 /**
170 * Access the <i>i</i>th value at quadrature point <i>k</i>
171 */
172 number &
173 quadrature_value(const unsigned int k, const unsigned int i);
174
175 /**
176 * Read the <i>i</i>th value at quadrature point <i>k</i>
177 */
178 number
179 quadrature_value(const unsigned int k, const unsigned int i) const;
180
181 /**
182 * Initialize the vector with scalar values.
183 *
184 * @note This function is usually only called by the assembler.
185 */
186 void
187 initialize_numbers(const unsigned int n);
188
189 /**
190 * Initialize the vector with vector values.
191 *
192 * @note This function is usually only called by the assembler.
193 */
194 void
195 initialize_vectors(const unsigned int n);
196
197 /**
198 * Allocate @p n local matrices. Additionally, set their block row and
199 * column coordinates to zero. The matrices themselves are resized by
200 * reinit().
201 *
202 * @note This function is usually only called by the assembler.
203 */
204 void
205 initialize_matrices(const unsigned int n, bool both);
206
207 /**
208 * Allocate a local matrix for each of the global ones in @p matrices.
209 * Additionally, set their block row and column coordinates. The matrices
210 * themselves are resized by reinit().
211 *
212 * @note This function is usually only called by the assembler.
213 */
214 template <typename MatrixType>
215 void
216 initialize_matrices(const MatrixBlockVector<MatrixType> &matrices,
217 bool both);
218
219 /**
220 * Allocate a local matrix for each of the global level objects in @p
221 * matrices. Additionally, set their block row and column coordinates. The
222 * matrices themselves are resized by reinit().
223 *
224 * @note This function is usually only called by the assembler.
225 */
226 template <typename MatrixType>
227 void
228 initialize_matrices(const MGMatrixBlockVector<MatrixType> &matrices,
229 bool both);
230
231 /**
232 * Initialize quadrature values to <tt>nv</tt> values in <tt>np</tt>
233 * quadrature points.
234 */
235 void
236 initialize_quadrature(const unsigned int np, const unsigned int nv);
237
238 /**
239 * Reinitialize matrices for new cell. Does not resize any of the data
240 * vectors stored in this object, but resizes the vectors in #R and the
241 * matrices in #M1 and #M2 for hp and sets them to zero.
242 */
243 void
244 reinit(const BlockIndices &local_sizes);
245
246 template <typename StreamType>
247 void
248 print_debug(StreamType &os) const;
249
250 /**
251 * The memory used by this object.
252 */
253 std::size_t
254 memory_consumption() const;
255
256 private:
257 /**
258 * The local numbers, computed on a cell or on a face.
259 */
260 std::vector<number> J;
261
262 /**
263 * The local vectors. This field is public, so that local integrators can
264 * write to it.
265 */
266 std::vector<BlockVector<number>> R;
267
268 /**
269 * The local matrices coupling degrees of freedom in the cell itself or
270 * within the first cell on a face.
271 */
272 std::vector<MatrixBlock<FullMatrix<number>>> M1;
273
274 /**
275 * The local matrices coupling test functions on the cell with trial
276 * functions on the other cell.
277 *
278 * Only used on interior faces.
279 */
280 std::vector<MatrixBlock<FullMatrix<number>>> M2;
281
282 /**
283 * Values in quadrature points for writing into patch data.
284 */
285 Table<2, number> quadrature_data;
286 };
287
288 //----------------------------------------------------------------------//
289
290 template <typename number>
291 inline void
292 LocalResults<number>::initialize_numbers(const unsigned int n)
293 {
294 J.resize(n);
295 }
296
297
298 template <typename number>
299 inline void
300 LocalResults<number>::initialize_vectors(const unsigned int n)
301 {
302 R.resize(n);
303 }
304
305
306 template <typename number>
307 template <typename MatrixType>
308 inline void
309 LocalResults<number>::initialize_matrices(
310 const MatrixBlockVector<MatrixType> &matrices,
311 bool both)
312 {
313 M1.resize(matrices.size());
314 if (both)
315 M2.resize(matrices.size());
316 for (unsigned int i = 0; i < matrices.size(); ++i)
317 {
318 const unsigned int row = matrices.block(i).row;
319 const unsigned int col = matrices.block(i).column;
320
321 M1[i].row = row;
322 M1[i].column = col;
323 if (both)
324 {
325 M2[i].row = row;
326 M2[i].column = col;
327 }
328 }
329 }
330
331
332 template <typename number>
333 template <typename MatrixType>
334 inline void
335 LocalResults<number>::initialize_matrices(
336 const MGMatrixBlockVector<MatrixType> &matrices,
337 bool both)
338 {
339 M1.resize(matrices.size());
340 if (both)
341 M2.resize(matrices.size());
342 for (unsigned int i = 0; i < matrices.size(); ++i)
343 {
344 const MGLevelObject<MatrixBlock<MatrixType>> &o = matrices.block(i);
345 const unsigned int row = o[o.min_level()].row;
346 const unsigned int col = o[o.min_level()].column;
347
348 M1[i].row = row;
349 M1[i].column = col;
350 if (both)
351 {
352 M2[i].row = row;
353 M2[i].column = col;
354 }
355 }
356 }
357
358
359 template <typename number>
360 inline void
361 LocalResults<number>::initialize_matrices(const unsigned int n,
362 const bool both)
363 {
364 M1.resize(n);
365 if (both)
366 M2.resize(n);
367 for (unsigned int i = 0; i < n; ++i)
368 {
369 M1[i].row = 0;
370 M1[i].column = 0;
371 if (both)
372 {
373 M2[i].row = 0;
374 M2[i].column = 0;
375 }
376 }
377 }
378
379
380 template <typename number>
381 inline void
382 LocalResults<number>::initialize_quadrature(const unsigned int np,
383 const unsigned int nv)
384 {
385 quadrature_data.reinit(np, nv);
386 }
387
388
389 template <typename number>
390 inline unsigned int
391 LocalResults<number>::n_values() const
392 {
393 return J.size();
394 }
395
396
397 template <typename number>
398 inline unsigned int
399 LocalResults<number>::n_vectors() const
400 {
401 return R.size();
402 }
403
404
405 template <typename number>
406 inline unsigned int
407 LocalResults<number>::n_matrices() const
408 {
409 return M1.size();
410 }
411
412
413 template <typename number>
414 inline unsigned int
415 LocalResults<number>::n_quadrature_points() const
416 {
417 return quadrature_data.n_rows();
418 }
419
420
421 template <typename number>
422 inline unsigned int
423 LocalResults<number>::n_quadrature_values() const
424 {
425 return quadrature_data.n_cols();
426 }
427
428
429 template <typename number>
430 inline number &
431 LocalResults<number>::value(const unsigned int i)
432 {
433 AssertIndexRange(i, J.size());
434 return J[i];
435 }
436
437
438 template <typename number>
439 inline BlockVector<number> &
440 LocalResults<number>::vector(const unsigned int i)
441 {
442 AssertIndexRange(i, R.size());
443 return R[i];
444 }
445
446
447 template <typename number>
448 inline MatrixBlock<FullMatrix<number>> &
449 LocalResults<number>::matrix(const unsigned int i, const bool external)
450 {
451 if (external)
452 {
453 AssertIndexRange(i, M2.size());
454 return M2[i];
455 }
456 AssertIndexRange(i, M1.size());
457 return M1[i];
458 }
459
460
461 template <typename number>
462 inline number &
463 LocalResults<number>::quadrature_value(const unsigned int k,
464 const unsigned int i)
465 {
466 return quadrature_data(k, i);
467 }
468
469
470 template <typename number>
471 inline Table<2, number> &
472 LocalResults<number>::quadrature_values()
473 {
474 return quadrature_data;
475 }
476
477
478 template <typename number>
479 inline number
480 LocalResults<number>::value(const unsigned int i) const
481 {
482 AssertIndexRange(i, J.size());
483 return J[i];
484 }
485
486
487 template <typename number>
488 inline const BlockVector<number> &
489 LocalResults<number>::vector(const unsigned int i) const
490 {
491 AssertIndexRange(i, R.size());
492 return R[i];
493 }
494
495
496 template <typename number>
497 inline const MatrixBlock<FullMatrix<number>> &
498 LocalResults<number>::matrix(const unsigned int i, const bool external) const
499 {
500 if (external)
501 {
502 AssertIndexRange(i, M2.size());
503 return M2[i];
504 }
505 AssertIndexRange(i, M1.size());
506 return M1[i];
507 }
508
509
510 template <typename number>
511 inline number
512 LocalResults<number>::quadrature_value(const unsigned int k,
513 const unsigned int i) const
514 {
515 return quadrature_data(k, i);
516 }
517
518
519 template <typename number>
520 template <typename StreamType>
521 void
522 LocalResults<number>::print_debug(StreamType &os) const
523 {
524 os << "J: " << J.size() << std::endl;
525 os << "R: " << R.size() << std::endl;
526 for (unsigned int i = 0; i < R.size(); ++i)
527 {
528 os << " " << R[i].n_blocks() << " -";
529 for (unsigned int j = 0; j < R[i].n_blocks(); ++j)
530 os << ' ' << R[i].block(j).size();
531 os << std::endl;
532 }
533 os << "M: " << M1.size() << " face " << M2.size() << std::endl;
534 for (unsigned int i = 0; i < M1.size(); ++i)
535 {
536 os << " " << M1[i].row << ',' << M1[i].column << ' '
537 << M1[i].matrix.m() << 'x' << M1[i].matrix.n();
538 if (i < M2.size())
539 os << " face " << M2[i].row << ',' << M2[i].column << ' '
540 << M2[i].matrix.m() << 'x' << M2[i].matrix.n();
541 os << std::endl;
542 }
543 }
544
545 } // namespace MeshWorker
546
547
548 DEAL_II_NAMESPACE_CLOSE
549
550 #endif