Debian Codegraph @

include/deal.II/lac/matrix_out.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 2025 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_matrix_out_h
16 # define dealii_matrix_out_h
17
18 # include <deal.II/base/config.h>
19
20 # include <deal.II/base/data_out_base.h>
21
22 # include <deal.II/lac/block_sparse_matrix.h>
23 # include <deal.II/lac/sparse_matrix.h>
24
25 # ifdef DEAL_II_WITH_TRILINOS
26 # include <deal.II/lac/trilinos_block_sparse_matrix.h>
27 # include <deal.II/lac/trilinos_sparse_matrix.h>
28 # endif
29
30
31 DEAL_II_NAMESPACE_OPEN
32
33 /**
34 * Output a matrix in graphical form using the generic format independent
35 * output routines of the base class. The matrix is converted into a list of
36 * patches on a 2d domain where the height is given by the elements of the
37 * matrix. The functions of the base class can then write this "mountain
38 * representation" of the matrix in a variety of graphical output formats. The
39 * coordinates of the matrix output are that the columns run with increasing
40 * x-axis, as usual, starting from zero, while the rows run into the negative
41 * y-axis, also starting from zero. Note that due to some internal
42 * restrictions, this class can only output one matrix at a time, i.e. it can
43 * not take advantage of the multiple dataset capabilities of the base class.
44 *
45 * A typical usage of this class would be as follows:
46 * @code
47 * FullMatrix<double> M;
48 * // fill matrix M with some values
49 * ...
50 *
51 * // now write out M:
52 * MatrixOut matrix_out;
53 * std::ofstream out ("M.vtu");
54 * matrix_out.build_patches (M, "M");
55 * matrix_out.write_vtu (out);
56 * @endcode
57 * Of course, you can as well choose a different graphical output format:
58 * all of the formats implemented by the DataOutInterface functions are also
59 * supported by this class.
60 *
61 * This class supports any matrix, not only of type FullMatrix, as long
62 * as it satisfies a number of requirements, stated with the member functions
63 * of this class.
64 *
65 * The generation of patches through the build_patches() function can be
66 * modified by giving it an object holding certain flags. See the
67 * documentation of the members of the Options class for a description of
68 * these flags.
69 *
70 *
71 * @ingroup output
72 */
73 class MatrixOut : public DataOutInterface<2, 2>
74 {
75 public:
76 /**
77 * Declare type for container size.
78 */
79 using size_type = types::global_dof_index;
80
81 /**
82 * Class holding various variables which are used to modify the output of
83 * the MatrixOut class.
84 */
85 struct Options
86 {
87 /**
88 * If @p true, only show the absolute values of the matrix entries, rather
89 * than their true values including the sign. This is useful if you have
90 * matrix entries that span a large range and want to display their
91 * magnitude using a logarithmic scale.
92 *
93 * The default value is @p false.
94 */
95 bool show_absolute_values;
96
97 /**
98 * If larger than one, do not show each element of the matrix, but rather
99 * an average over a number of entries. The number of output patches is
100 * accordingly smaller. This flag determines how large each shown block
101 * shall be (in rows/columns). For example, if it is two, then always four
102 * entries are collated into one.
103 *
104 * The default value is one.
105 */
106 unsigned int block_size;
107
108 /**
109 * By default, this class shows each matrix entry as one value,
110 * and then produces a bilinear display of all of these
111 * values. This results in a continuous plot on a mesh with
112 * $N\times N$ vertices for a matrix of size $N$. If, on the other
113 * hand, the current variable is set to `true`, then this class
114 * instead creates a plot in which each matrix entry corresponds
115 * to a single patch on which the value of the matrix entry is
116 * shown as a constant function. This creates a discontinuous plot
117 * with $N\times N$ cells on a mesh of size $(N+1)\times(N+1)$.
118 *
119 * The default value is false.
120 */
121 bool discontinuous;
122
123 /**
124 * If this flag is set to `false`, the MatrixOut class creates
125 * a plot in which each matrix
126 * entry is actually shown, even if it is zero. For large
127 * matrices, this results in very large output files, or indeed
128 * exhausts the available memory. On the other hand, if the
129 * current flags is set to `true`, then the class only outputs
130 * patches whenever there are non-zero matrix entries to be
131 * shown. For sparse matrices, this leads to an output size that
132 * is proportional to the number of nonzero entries, rather than
133 * proportional to $N^2$.
134 *
135 * The default is `true`.
136 *
137 * @note Internally, the current implementation continues to loop
138 * over all matrix entries, whether they are zero or not. As a
139 * consequence, the *run time* of outputting sparse matrices
140 * continues to be proportional to $N^2$, rather than proportional
141 * to the number of nonzero entries. For large matrices, this means
142 * that you still have to have patience -- but at least it is possible
143 * to output information about matrices of size $10,000\times 10,000$
144 * or $50,000\times 50,000$ with a few million nonzero entries.
145 */
146 bool create_sparse_plot;
147
148 /**
149 * Default constructor. Set all elements of this structure to their
150 * default values.
151 */
152 Options(const bool show_absolute_values = false,
153 const unsigned int block_size = 1,
154 const bool discontinuous = false,
155 const bool create_sparse_plot = true);
156 };
157
158 /**
159 * Destructor. Declared in order to make it virtual.
160 */
161 virtual ~MatrixOut() override = default;
162
163 /**
164 * Generate a list of patches from the given matrix and use the given string
165 * as the name of the data set upon writing to a file. Once patches have
166 * been built, you can use the functions of the base class to write the data
167 * into a files, using one of the supported output formats.
168 *
169 * The last argument provides customization choices for how output
170 * is to be produced. See the description of the fields of the
171 * Options structure for more information.
172 *
173 * Note that this function requires that we can extract elements of the
174 * matrix, which is done using the get_element() function declared in an
175 * internal namespace. By adding specializations, you can extend this class
176 * to other matrix classes which are not presently supported. Furthermore,
177 * we need to be able to extract the size of the matrix, for which we assume
178 * that the matrix type offers member functions <tt>m()</tt> and
179 * <tt>n()</tt>, which return the number of rows and columns, respectively.
180 */
181 template <class Matrix>
182 void
183 build_patches(const Matrix &matrix,
184 const std::string &name,
185 const Options options = Options());
186
187 private:
188 /**
189 * Abbreviate the somewhat lengthy name for the dealii::DataOutBase::Patch
190 * class.
191 */
192 using Patch = DataOutBase::Patch<2, 2>;
193
194 /**
195 * This is a list of patches that is created each time build_patches() is
196 * called. These patches are used in the output routines of the base
197 * classes.
198 */
199 std::vector<Patch> patches;
200
201 /**
202 * Name of the matrix to be written.
203 */
204 std::string name;
205
206 /**
207 * %Function by which the base class's functions get to know what patches
208 * they shall write to a file.
209 */
210 virtual const std::vector<Patch> &
211 get_patches() const override;
212
213 /**
214 * Virtual function through which the names of data sets are obtained by the
215 * output functions of the base class.
216 */
217 virtual std::vector<std::string>
218 get_dataset_names() const override;
219
220 /**
221 * Get the value of the matrix at gridpoint <tt>(i,j)</tt>. Depending on the
222 * given flags, this can mean different things, for example if only absolute
223 * values shall be shown then the absolute value of the matrix entry is
224 * taken. If the block size is larger than one, then an average of several
225 * matrix entries is taken.
226 */
227 template <class Matrix>
228 static double
229 get_gridpoint_value(const Matrix &matrix,
230 const size_type i,
231 const size_type j,
232 const Options &options);
233 };
234
235
236 /* ---------------------- Template and inline functions ------------- */
237
238
239 namespace internal
240 {
241 namespace MatrixOutImplementation
242 {
243 /**
244 * Return the element with given indices of a sparse matrix.
245 */
246 template <typename number>
247 double
248 get_element(const dealii::SparseMatrix<number> &matrix,
249 const types::global_dof_index i,
250 const types::global_dof_index j)
251 {
252 return matrix.el(i, j);
253 }
254
255
256
257 /**
258 * Return the element with given indices of a block sparse matrix.
259 */
260 template <typename number>
261 double
262 get_element(const dealii::BlockSparseMatrix<number> &matrix,
263 const types::global_dof_index i,
264 const types::global_dof_index j)
265 {
266 return matrix.el(i, j);
267 }
268
269
270 # ifdef DEAL_II_WITH_TRILINOS
271 /**
272 * Return the element with given indices of a Trilinos sparse matrix.
273 */
274 inline double
275 get_element(const TrilinosWrappers::SparseMatrix &matrix,
276 const types::global_dof_index i,
277 const types::global_dof_index j)
278 {
279 return matrix.el(i, j);
280 }
281
282
283
284 /**
285 * Return the element with given indices of a Trilinos block sparse
286 * matrix.
287 */
288 inline double
289 get_element(const TrilinosWrappers::BlockSparseMatrix &matrix,
290 const types::global_dof_index i,
291 const types::global_dof_index j)
292 {
293 return matrix.el(i, j);
294 }
295 # endif
296
297
298 # ifdef DEAL_II_WITH_PETSC
299 // no need to do anything: PETSc matrix objects do not distinguish
300 // between operator() and el(i,j), so we can safely access elements
301 // through the generic function below
302 # endif
303
304
305 /**
306 * Return the element with given indices from any matrix type for which
307 * no specialization of this function was declared above. This will call
308 * <tt>operator()</tt> on the matrix.
309 */
310 template <class Matrix>
311 double
312 get_element(const Matrix &matrix,
313 const types::global_dof_index i,
314 const types::global_dof_index j)
315 {
316 return matrix(i, j);
317 }
318 } // namespace MatrixOutImplementation
319 } // namespace internal
320
321
322
323 template <class Matrix>
324 inline double
325 MatrixOut::get_gridpoint_value(const Matrix &matrix,
326 const size_type i,
327 const size_type j,
328 const Options &options)
329 {
330 // special case if block size is
331 // one since we then don't need all
332 // that loop overhead
333 if (options.block_size == 1)
334 {
335 if (options.show_absolute_values == true)
336 return std::fabs(
337 internal::MatrixOutImplementation::get_element(matrix, i, j));
338 else
339 return internal::MatrixOutImplementation::get_element(matrix, i, j);
340 }
341
342 // if blocksize greater than one,
343 // then compute average of elements
344 double average = 0;
345 size_type n_elements = 0;
346 for (size_type row = i * options.block_size;
347 row <
348 std::min(size_type(matrix.m()), size_type((i + 1) * options.block_size));
349 ++row)
350 for (size_type col = j * options.block_size;
351 col < std::min(size_type(matrix.m()),
352 size_type((j + 1) * options.block_size));
353 ++col, ++n_elements)
354 if (options.show_absolute_values == true)
355 average += std::fabs(
356 internal::MatrixOutImplementation::get_element(matrix, row, col));
357 else
358 average +=
359 internal::MatrixOutImplementation::get_element(matrix, row, col);
360 average /= n_elements;
361 return average;
362 }
363
364
365
366 template <class Matrix>
367 void
368 MatrixOut::build_patches(const Matrix &matrix,
369 const std::string &name,
370 const Options options)
371 {
372 size_type n_patches_x = (matrix.n() / options.block_size +
373 (matrix.n() % options.block_size != 0 ? 1 : 0)),
374 n_patches_y = (matrix.m() / options.block_size +
375 (matrix.m() % options.block_size != 0 ? 1 : 0));
376
377 // If continuous, the number of
378 // plotted patches is matrix size-1
379 if (!options.discontinuous)
380 {
381 --n_patches_x;
382 --n_patches_y;
383 }
384
385 const size_type n_patches =
386 (options.create_sparse_plot ?
387 [&]() {
388 size_type count = 0;
389 for (size_type i = 0; i < n_patches_y; ++i)
390 {
391 for (size_type j = 0; j < n_patches_x; ++j)
392 // Use the same logic as below to determine whether we
393 // need to output a patch, and count if we do:
394 if ((((options.discontinuous == true) &&
395 (get_gridpoint_value(matrix, i, j, options) != 0)) ||
396 ((options.discontinuous == false) &&
397 ((get_gridpoint_value(matrix, i, j, options) != 0) ||
398 (get_gridpoint_value(matrix, i + 1, j, options) != 0) ||
399 (get_gridpoint_value(matrix, i, j + 1, options) != 0) ||
400 (get_gridpoint_value(matrix, i + 1, j + 1, options) !=
401 0)))))
402 ++count;
403 }
404 return count;
405 }() :
406 n_patches_x * n_patches_y);
407
408 // first clear old data and re-set the object to a correctly sized state:
409 patches.clear();
410 try
411 {
412 patches.resize(n_patches);
413 }
414 catch (const std::bad_alloc &)
415 {
416 AssertThrow(false,
417 ExcMessage("You are trying to create a graphical "
418 "representation of a matrix that would "
419 "requiring outputting " +
420 (options.create_sparse_plot ?
421 std::to_string(n_patches) :
422 std::to_string(n_patches_x) + "x" +
423 std::to_string(n_patches_y)) +
424 " patches. There is not enough memory to output " +
425 "this many patches."));
426 }
427
428 // now build the patches
429 size_type index = 0;
430 for (size_type i = 0; i < n_patches_y; ++i)
431 for (size_type j = 0; j < n_patches_x; ++j)
432 {
433 // If we are creating a sparse plot, check whether this patch
434 // would have any nonzero values. If not, we can skip the
435 // patch:
436 if (options.create_sparse_plot &&
437 (((options.discontinuous == true) &&
438 (get_gridpoint_value(matrix, i, j, options) == 0)) ||
439 ((options.discontinuous == false) &&
440 (get_gridpoint_value(matrix, i, j, options) == 0) &&
441 (get_gridpoint_value(matrix, i + 1, j, options) == 0) &&
442 (get_gridpoint_value(matrix, i, j + 1, options) == 0) &&
443 (get_gridpoint_value(matrix, i + 1, j + 1, options) == 0))))
444 continue;
445
446 patches[index].n_subdivisions = 1;
447 patches[index].reference_cell = ReferenceCells::Quadrilateral;
448
449 // within each patch, order the points in such a way that if some
450 // graphical output program (such as gnuplot) plots the quadrilaterals
451 // as two triangles, then the diagonal of the quadrilateral which cuts
452 // it into the two printed triangles is parallel to the diagonal of the
453 // matrix, rather than perpendicular to it. this has the advantage that,
454 // for example, the unit matrix is plotted as a straight ridge, rather
455 // than as a series of bumps and valleys along the diagonal
456 patches[index].vertices[0][0] = j;
457 patches[index].vertices[0][1] = -static_cast<signed int>(i);
458 patches[index].vertices[1][0] = j;
459 patches[index].vertices[1][1] = -static_cast<signed int>(i + 1);
460 patches[index].vertices[2][0] = j + 1;
461 patches[index].vertices[2][1] = -static_cast<signed int>(i);
462 patches[index].vertices[3][0] = j + 1;
463 patches[index].vertices[3][1] = -static_cast<signed int>(i + 1);
464 // next scale all the patch
465 // coordinates by the block
466 // size, to get original
467 // coordinates
468 for (auto &vertex : patches[index].vertices)
469 vertex *= options.block_size;
470
471 patches[index].n_subdivisions = 1;
472
473 patches[index].data.reinit(1, 4);
474 if (options.discontinuous)
475 {
476 patches[index].data(0, 0) =
477 get_gridpoint_value(matrix, i, j, options);
478 patches[index].data(0, 1) =
479 get_gridpoint_value(matrix, i, j, options);
480 patches[index].data(0, 2) =
481 get_gridpoint_value(matrix, i, j, options);
482 patches[index].data(0, 3) =
483 get_gridpoint_value(matrix, i, j, options);
484 }
485 else
486 {
487 patches[index].data(0, 0) =
488 get_gridpoint_value(matrix, i, j, options);
489 patches[index].data(0, 1) =
490 get_gridpoint_value(matrix, i + 1, j, options);
491 patches[index].data(0, 2) =
492 get_gridpoint_value(matrix, i, j + 1, options);
493 patches[index].data(0, 3) =
494 get_gridpoint_value(matrix, i + 1, j + 1, options);
495 }
496
497 ++index;
498 }
499
500 // finally set the name
501 this->name = name;
502 }
503
504
505
506 /*---------------------------- matrix_out.h ---------------------------*/
507
508 DEAL_II_NAMESPACE_CLOSE
509
510 #endif
511 /*---------------------------- matrix_out.h ---------------------------*/