| 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 ---------------------------*/ |