Line data Source code
1 : // The libMesh Finite Element Library.
2 : // Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
3 :
4 : // This library is free software; you can redistribute it and/or
5 : // modify it under the terms of the GNU Lesser General Public
6 : // License as published by the Free Software Foundation; either
7 : // version 2.1 of the License, or (at your option) any later version.
8 :
9 : // This library is distributed in the hope that it will be useful,
10 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 : // Lesser General Public License for more details.
13 :
14 : // You should have received a copy of the GNU Lesser General Public
15 : // License along with this library; if not, write to the Free Software
16 : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 :
18 :
19 :
20 : #ifndef LIBMESH_SPARSE_MATRIX_H
21 : #define LIBMESH_SPARSE_MATRIX_H
22 :
23 :
24 : // Local includes
25 : #include "libmesh/libmesh.h"
26 : #include "libmesh/libmesh_common.h"
27 : #include "libmesh/reference_counted_object.h"
28 : #include "libmesh/id_types.h"
29 : #include "libmesh/parallel_object.h"
30 : #include "libmesh/enum_parallel_type.h" // PARALLEL
31 : #include "libmesh/enum_matrix_build_type.h" // AUTOMATIC
32 : #include "libmesh/enum_solver_package.h"
33 :
34 : // C++ includes
35 : #include <cstddef>
36 : #include <iomanip>
37 : #include <vector>
38 : #include <memory>
39 : #include <string>
40 :
41 : namespace libMesh
42 : {
43 :
44 : // forward declarations
45 : template <typename T> class SparseMatrix;
46 : template <typename T> class DenseMatrix;
47 : class DofMap;
48 : namespace SparsityPattern {
49 : class Build;
50 : class Graph;
51 : }
52 : template <typename T> class NumericVector;
53 :
54 : // This template helper function must be declared before it
55 : // can be defined below.
56 : template <typename T>
57 : std::ostream & operator << (std::ostream & os, const SparseMatrix<T> & m);
58 :
59 :
60 : /**
61 : * Generic sparse matrix. This class contains pure virtual members
62 : * that must be overridden in derived classes. Using a common base
63 : * class allows for uniform access to sparse matrices from various
64 : * different solver packages in different formats.
65 : *
66 : * \author Benjamin S. Kirk
67 : * \date 2003
68 : */
69 : template <typename T>
70 : class SparseMatrix : public ReferenceCountedObject<SparseMatrix<T>>,
71 : public ParallelObject
72 : {
73 : public:
74 : /**
75 : * Constructor; initializes the matrix to be empty, without any
76 : * structure, i.e. the matrix is not usable at all. This
77 : * constructor is therefore only useful for matrices which are
78 : * members of a class. All other matrices should be created at a
79 : * point in the data flow where all necessary information is
80 : * available.
81 : *
82 : * You have to initialize the matrix before usage with
83 : * \p init(...).
84 : */
85 : explicit
86 : SparseMatrix (const Parallel::Communicator & comm);
87 :
88 : /**
89 : * This _looks_ like a copy assignment operator, but note that,
90 : * unlike normal copy assignment operators, it is pure virtual. This
91 : * function should be overridden in derived classes so that they can
92 : * be copied correctly via references to the base class. This design
93 : * usually isn't a good idea in general, but in this context it
94 : * works because we usually don't have a mix of different kinds of
95 : * SparseMatrix active in the library at a single time.
96 : *
97 : * \returns A reference to *this as the base type.
98 : */
99 0 : virtual SparseMatrix<T> & operator= (const SparseMatrix<T> &)
100 : {
101 0 : libmesh_not_implemented();
102 : return *this;
103 : }
104 :
105 : /**
106 : * These 3 special functions can be defaulted for this class, as it
107 : * does not manage any memory itself.
108 : */
109 : SparseMatrix (SparseMatrix &&) = default;
110 292 : SparseMatrix (const SparseMatrix &) = default;
111 : SparseMatrix & operator= (SparseMatrix &&) = default;
112 :
113 : /**
114 : * While this class doesn't manage any memory, the derived class might and
115 : * users may be deleting through a pointer to this base class
116 : */
117 113535 : virtual ~SparseMatrix() = default;
118 :
119 : /**
120 : * Builds a \p SparseMatrix<T> using the linear solver package specified by
121 : * \p solver_package
122 : */
123 : static std::unique_ptr<SparseMatrix<T>>
124 : build(const Parallel::Communicator & comm,
125 : const SolverPackage solver_package = libMesh::default_solver_package(),
126 : const MatrixBuildType matrix_build_type = MatrixBuildType::AUTOMATIC);
127 :
128 : virtual SolverPackage solver_package() = 0;
129 :
130 : /**
131 : * \returns \p true if the matrix has been initialized,
132 : * \p false otherwise.
133 : */
134 3935844 : virtual bool initialized() const { return _is_initialized; }
135 :
136 : /**
137 : * Set a pointer to the \p DofMap to use. If a separate sparsity
138 : * pattern is not being used, use the one from the DofMap.
139 : *
140 : * The lifetime of \p dof_map must exceed the lifetime of \p this.
141 : */
142 : void attach_dof_map (const DofMap & dof_map);
143 :
144 : /**
145 : * Set a pointer to a sparsity pattern to use. Useful in cases
146 : * where a matrix requires a wider (or for efficiency narrower)
147 : * pattern than most matrices in the system, or in cases where no
148 : * system sparsity pattern is being calculated by the DofMap.
149 : *
150 : * The lifetime of \p sp must exceed the lifetime of \p this.
151 : */
152 : void attach_sparsity_pattern (const SparsityPattern::Build & sp);
153 :
154 : /**
155 : * \returns \p true if this sparse matrix format needs to be fed the
156 : * graph of the sparse matrix.
157 : *
158 : * This is true for \p LaspackMatrix, but not \p PetscMatrixBase subclasses. In
159 : * the case where the full graph is not required, we can efficiently
160 : * approximate it to provide a good estimate of the required size of
161 : * the sparse matrix.
162 : */
163 43597 : virtual bool need_full_sparsity_pattern() const
164 43597 : { return false; }
165 :
166 : /**
167 : * @returns Whether this matrix needs the sparsity pattern computed by the \p DofMap
168 : */
169 14781 : virtual bool require_sparsity_pattern() const { return !this->use_hash_table(); }
170 :
171 : /**
172 : * Updates the matrix sparsity pattern. When your \p SparseMatrix<T>
173 : * implementation does not need this data, simply do not override
174 : * this method.
175 : */
176 0 : virtual void update_sparsity_pattern (const SparsityPattern::Graph &) {}
177 :
178 : /**
179 : * Initialize SparseMatrix with the specified sizes.
180 : *
181 : * \param m The global number of rows.
182 : * \param n The global number of columns.
183 : * \param m_l The local number of rows.
184 : * \param n_l The local number of columns.
185 : * \param nnz The number of on-diagonal nonzeros per row (defaults to 30).
186 : * \param noz The number of off-diagonal nonzeros per row (defaults to 10).
187 : * \param blocksize Optional value indicating dense coupled blocks
188 : * for systems with multiple variables all of the same type.
189 : */
190 : virtual void init (const numeric_index_type m,
191 : const numeric_index_type n,
192 : const numeric_index_type m_l,
193 : const numeric_index_type n_l,
194 : const numeric_index_type nnz=30,
195 : const numeric_index_type noz=10,
196 : const numeric_index_type blocksize=1) = 0;
197 :
198 : /**
199 : * Initialize this matrix using the sparsity structure computed by \p dof_map.
200 : * @param type The serial/parallel/ghosted type of the matrix
201 : */
202 : virtual void init (ParallelType type = PARALLEL) = 0;
203 :
204 : /**
205 : * Restores the \p SparseMatrix<T> to a pristine state.
206 : */
207 : virtual void clear () = 0;
208 :
209 : /**
210 : * Set all entries to 0.
211 : */
212 : virtual void zero () = 0;
213 :
214 : /**
215 : * \returns A smart pointer to a copy of this matrix with the same
216 : * type, size, and partitioning, but with all zero entries.
217 : *
218 : * \note This must be overridden in the derived classes.
219 : */
220 : virtual std::unique_ptr<SparseMatrix<T>> zero_clone () const = 0;
221 :
222 : /**
223 : * \returns A smart pointer to a copy of this matrix.
224 : *
225 : * \note This must be overridden in the derived classes.
226 : */
227 : virtual std::unique_ptr<SparseMatrix<T>> clone () const = 0;
228 :
229 : /**
230 : * Sets all row entries to 0 then puts \p diag_value in the diagonal entry.
231 : */
232 : virtual void zero_rows (std::vector<numeric_index_type> & rows, T diag_value = 0.0);
233 :
234 : /**
235 : * Calls the SparseMatrix's internal assembly routines, ensuring
236 : * that the values are consistent across processors.
237 : */
238 : virtual void close () = 0;
239 :
240 : /**
241 : * For PETSc matrix , this function is similar to close but without shrinking memory.
242 : * This is useful when we want to switch between ADD_VALUES and INSERT_VALUES.
243 : * close should be called before using the matrix.
244 : */
245 0 : virtual void flush () { close(); }
246 :
247 : /**
248 : * \returns The row-dimension of the matrix.
249 : */
250 : virtual numeric_index_type m () const = 0;
251 :
252 : /**
253 : * Get the number of rows owned by this process
254 : */
255 8 : virtual numeric_index_type local_m () const { return row_stop() - row_start(); }
256 :
257 : /**
258 : * Get the number of columns owned by this process
259 : */
260 16 : virtual numeric_index_type local_n () const { return col_stop() - col_start(); }
261 :
262 : /**
263 : * \returns The column-dimension of the matrix.
264 : */
265 : virtual numeric_index_type n () const = 0;
266 :
267 : /**
268 : * \returns The index of the first matrix row stored on this
269 : * processor.
270 : */
271 : virtual numeric_index_type row_start () const = 0;
272 :
273 : /**
274 : * \returns The index of the last matrix row (+1) stored on this
275 : * processor.
276 : */
277 : virtual numeric_index_type row_stop () const = 0;
278 :
279 : /**
280 : * \returns The index of the first matrix column owned by this
281 : * processor.
282 : */
283 : virtual numeric_index_type col_start () const = 0;
284 :
285 : /**
286 : * \returns The index of the last matrix column (+1) owned by this
287 : * processor.
288 : */
289 : virtual numeric_index_type col_stop () const = 0;
290 :
291 : /**
292 : * Set the element \p (i,j) to \p value. Throws an error if the
293 : * entry does not exist. Zero values can be "stored" in non-existent
294 : * fields.
295 : */
296 : virtual void set (const numeric_index_type i,
297 : const numeric_index_type j,
298 : const T value) = 0;
299 :
300 : /**
301 : * Add \p value to the element \p (i,j). Throws an error if the
302 : * entry does not exist. Zero values can be "added" to non-existent
303 : * entries.
304 : */
305 : virtual void add (const numeric_index_type i,
306 : const numeric_index_type j,
307 : const T value) = 0;
308 :
309 : /**
310 : * Add the full matrix \p dm to the SparseMatrix. This is useful
311 : * for adding an element matrix at assembly time.
312 : */
313 : virtual void add_matrix (const DenseMatrix<T> & dm,
314 : const std::vector<numeric_index_type> & rows,
315 : const std::vector<numeric_index_type> & cols) = 0;
316 :
317 : /**
318 : * Same as \p add_matrix, but assumes the row and column maps are the same.
319 : * Thus the matrix \p dm must be square.
320 : */
321 : virtual void add_matrix (const DenseMatrix<T> & dm,
322 : const std::vector<numeric_index_type> & dof_indices) = 0;
323 :
324 : /**
325 : * Add the full matrix \p dm to the SparseMatrix. This is useful
326 : * for adding an element matrix at assembly time. The matrix is
327 : * assumed blocked, and \p brow, \p bcol correspond to the *block*
328 : * row and column indices.
329 : */
330 : virtual void add_block_matrix (const DenseMatrix<T> & dm,
331 : const std::vector<numeric_index_type> & brows,
332 : const std::vector<numeric_index_type> & bcols);
333 :
334 : /**
335 : * Same as \p add_block_matrix(), but assumes the row and column
336 : * maps are the same. Thus the matrix \p dm must be square.
337 : */
338 0 : virtual void add_block_matrix (const DenseMatrix<T> & dm,
339 : const std::vector<numeric_index_type> & dof_indices)
340 0 : { this->add_block_matrix (dm, dof_indices, dof_indices); }
341 :
342 : /**
343 : * Compute \f$ A \leftarrow A + a*X \f$ for scalar \p a, matrix \p X.
344 : */
345 : virtual void add (const T a, const SparseMatrix<T> & X) = 0;
346 :
347 : /**
348 : * Compute Y = A*X for matrix \p X.
349 : */
350 0 : virtual void matrix_matrix_mult (SparseMatrix<T> & /*X*/, SparseMatrix<T> & /*Y*/, bool /*reuse*/)
351 0 : { libmesh_not_implemented(); }
352 :
353 : /**
354 : * Add \p scalar* \p spm to the rows and cols of this matrix (A):
355 : * A(rows[i], cols[j]) += scalar * spm(i,j)
356 : */
357 0 : virtual void add_sparse_matrix (const SparseMatrix<T> & /*spm*/,
358 : const std::map<numeric_index_type, numeric_index_type> & /*rows*/,
359 : const std::map<numeric_index_type, numeric_index_type> & /*cols*/,
360 : const T /*scalar*/)
361 0 : { libmesh_not_implemented(); }
362 :
363 : /**
364 : * \returns A copy of matrix entry \p (i,j).
365 : *
366 : * \note This may be an expensive operation, and you should always
367 : * be careful where you call this function.
368 : */
369 : virtual T operator () (const numeric_index_type i,
370 : const numeric_index_type j) const = 0;
371 :
372 : /**
373 : * \returns The \f$ \ell_1 \f$-norm of the matrix, that is the max column sum:
374 : * \f$ |M|_1 = \max_{j} \sum_{i} |M_{ij}| \f$
375 : *
376 : * This is the natural matrix norm that is compatible with the
377 : * \f$ \ell_1 \f$-norm for vectors, i.e. \f$ |Mv|_1 \leq |M|_1 |v|_1 \f$.
378 : * (cf. Haemmerlin-Hoffmann : Numerische Mathematik)
379 : */
380 : virtual Real l1_norm () const = 0;
381 :
382 : /**
383 : * \returns The \f$ \ell_{\infty} \f$-norm of the matrix, that is the max row sum:
384 : *
385 : * \f$ |M|_{\infty} = \max_{i} \sum_{j} |M_{ij}| \f$
386 : *
387 : * This is the natural matrix norm that is compatible to the
388 : * \f$ \ell_{\infty} \f$-norm of vectors, i.e.
389 : * \f$ |Mv|_{\infty} \leq |M|_{\infty} |v|_{\infty} \f$.
390 : * (cf. Haemmerlin-Hoffmann : Numerische Mathematik)
391 : */
392 : virtual Real linfty_norm () const = 0;
393 :
394 : /**
395 : * \returns The l1_norm() of the difference of \p this and \p other_mat
396 : */
397 : Real l1_norm_diff (const SparseMatrix<T> & other_mat) const;
398 :
399 : /**
400 : * \returns \p true if the matrix has been assembled.
401 : */
402 : virtual bool closed() const = 0;
403 :
404 : /**
405 : * \returns the global number of non-zero entries in the matrix
406 : * sparsity pattern
407 : */
408 : virtual std::size_t n_nonzeros() const;
409 :
410 : /**
411 : * Print the contents of the matrix to the screen in a uniform
412 : * style, regardless of matrix/solver package being used.
413 : */
414 : void print(std::ostream & os=libMesh::out, const bool sparse=false) const;
415 :
416 : /**
417 : * Same as the print method above, but allows you to print to a
418 : * stream in the standard syntax.
419 : *
420 : * \code
421 : * template <typename U>
422 : * friend std::ostream & operator << (std::ostream & os, const SparseMatrix<U> & m);
423 : * \endcode
424 : *
425 : * \note The above syntax, which does not require any
426 : * prior declaration of operator<<, declares *any* instantiation of
427 : * SparseMatrix<X> is friend to *any* instantiation of
428 : * operator<<(ostream &, SparseMatrix<Y> &). It would not happen in
429 : * practice, but in principle it means that SparseMatrix<Complex>
430 : * would be friend to operator<<(ostream &, SparseMatrix<Real>).
431 : *
432 : * \note The form below, which requires a previous
433 : * declaration of the operator<<(stream &, SparseMatrix<T> &) function
434 : * (see top of this file), means that any instantiation of
435 : * SparseMatrix<T> is friend to the specialization
436 : * operator<<(ostream &, SparseMatrix<T> &), but e.g. SparseMatrix<U>
437 : * is *not* friend to the same function. So this is slightly
438 : * different to the form above...
439 : *
440 : * This method seems to be the "preferred" technique, see
441 : * http://www.parashift.com/c++-faq-lite/template-friends.html
442 : */
443 : friend std::ostream & operator << <>(std::ostream & os, const SparseMatrix<T> & m);
444 :
445 : /**
446 : * Print the contents of the matrix to the screen in a
447 : * package-personalized style, if available.
448 : */
449 : virtual void print_personal(std::ostream & os=libMesh::out) const = 0;
450 :
451 : /**
452 : * Print the contents of the matrix to a file, with a file format
453 : * depending on the extension of \p filename
454 : */
455 : void print(const std::string & filename) const;
456 :
457 : /**
458 : * Print the contents of the matrix to a file, with the HDF5 sparse
459 : * matrix format used by CoreForm, putting CSR sparse matrix data in
460 : * the group given by \p groupname.
461 : */
462 : virtual void print_coreform_hdf5(const std::string & filename,
463 : const std::string & groupname = "extraction") const;
464 :
465 : /**
466 : * Print the contents of the matrix in Matlab's sparse matrix
467 : * format. Optionally prints the matrix to the file named \p name.
468 : * If \p name is not specified it is dumped to the screen.
469 : */
470 : virtual void print_matlab(const std::string & /*name*/ = "") const;
471 :
472 : /**
473 : * Write the contents of the matrix to a file in PETSc's binary
474 : * sparse matrix format.
475 : */
476 : virtual void print_petsc_binary(const std::string & filename) const;
477 :
478 : /**
479 : * Write the contents of the matrix to a file in PETSc's HDF5
480 : * sparse matrix format.
481 : */
482 : virtual void print_petsc_hdf5(const std::string & filename) const;
483 :
484 : /**
485 : * Read the contents of the matrix from a file, with the file format
486 : * inferred from the extension of \p filename.
487 : */
488 : virtual void read(const std::string & filename);
489 :
490 : /**
491 : * Read the contents of the matrix from a file, with the HDF5 sparse
492 : * matrix format used by CoreForm, expecing sparse matrix data in
493 : * the group given by \p groupname.
494 : *
495 : * This will be initialized with the sparsity from the file,
496 : * linearly partitioned onto the number of processors available
497 : * unless \p this matrix is pre-sized and pre-partitionsed.
498 : */
499 : virtual void read_coreform_hdf5(const std::string & filename,
500 : const std::string & groupname = "extraction");
501 :
502 : /**
503 : * Read the contents of the matrix from the Matlab-script sparse
504 : * matrix format used by PETSc.
505 : *
506 : * If the size and sparsity of the matrix in \p filename appears
507 : * consistent with the existing sparsity of \p this then the
508 : * existing parallel decomposition and sparsity will be retained.
509 : * If not, then \p this will be initialized with the sparsity from
510 : * the file, linearly partitioned onto the number of processors
511 : * available.
512 : */
513 : virtual void read_matlab(const std::string & filename);
514 :
515 : /**
516 : * Read the contents of the matrix from a file in PETSc's binary
517 : * sparse matrix format.
518 : */
519 : virtual void read_petsc_binary(const std::string & filename);
520 :
521 : /**
522 : * Read the contents of the matrix from a file in PETSc's HDF5
523 : * sparse matrix format.
524 : */
525 : virtual void read_petsc_hdf5(const std::string & filename);
526 :
527 : /**
528 : * This function creates a matrix called "submatrix" which is defined
529 : * by the row and column indices given in the "rows" and "cols" entries.
530 : * Currently this operation is only defined for the PetscMatrixBase subclasses.
531 : * Note: The \p rows and \p cols vectors need to be sorted;
532 : * Use the nosort version below if \p rows and \p cols vectors are not sorted;
533 : * The \p rows and \p cols only contain indices that are owned by this processor.
534 : */
535 594 : virtual void create_submatrix(SparseMatrix<T> & submatrix,
536 : const std::vector<numeric_index_type> & rows,
537 : const std::vector<numeric_index_type> & cols) const
538 : {
539 594 : this->_get_submatrix(submatrix,
540 : rows,
541 : cols,
542 : false); // false means DO NOT REUSE submatrix
543 594 : }
544 :
545 : /**
546 : * Similar to the above function, this function creates a \p
547 : * submatrix which is defined by the indices given in the \p rows
548 : * and \p cols vectors.
549 : * Note: Both \p rows and \p cols can be unsorted;
550 : * Use the above function for better efficiency if your indices are sorted;
551 : * \p rows and \p cols can contain indices that are owned by other processors.
552 : */
553 0 : virtual void create_submatrix_nosort(SparseMatrix<T> & /*submatrix*/,
554 : const std::vector<numeric_index_type> & /*rows*/,
555 : const std::vector<numeric_index_type> & /*cols*/) const
556 : {
557 0 : libmesh_not_implemented();
558 : }
559 :
560 : /**
561 : * This function is similar to the one above, but it allows you to reuse
562 : * the existing sparsity pattern of "submatrix" instead of reallocating
563 : * it again. This should hopefully be more efficient if you are frequently
564 : * extracting submatrices of the same size.
565 : */
566 0 : virtual void reinit_submatrix(SparseMatrix<T> & submatrix,
567 : const std::vector<numeric_index_type> & rows,
568 : const std::vector<numeric_index_type> & cols) const
569 : {
570 0 : this->_get_submatrix(submatrix,
571 : rows,
572 : cols,
573 : true); // true means REUSE submatrix
574 0 : }
575 :
576 : /**
577 : * Multiplies the matrix by the NumericVector \p arg and stores the
578 : * result in NumericVector \p dest.
579 : */
580 : void vector_mult (NumericVector<T> & dest,
581 : const NumericVector<T> & arg) const;
582 :
583 : /**
584 : * Multiplies the matrix by the NumericVector \p arg and adds the
585 : * result to the NumericVector \p dest.
586 : */
587 : void vector_mult_add (NumericVector<T> & dest,
588 : const NumericVector<T> & arg) const;
589 :
590 : /**
591 : * Copies the diagonal part of the matrix into \p dest.
592 : */
593 : virtual void get_diagonal (NumericVector<T> & dest) const = 0;
594 :
595 : /**
596 : * Copies the transpose of the matrix into \p dest, which may be
597 : * *this.
598 : */
599 : virtual void get_transpose (SparseMatrix<T> & dest) const = 0;
600 :
601 : /**
602 : * Get a row from the matrix
603 : * @param i The matrix row to get
604 : * @param indices A container that will be filled with the column indices
605 : * corresponding to (possibly) non-zero values
606 : * @param values A container holding the column values
607 : */
608 : virtual void get_row(numeric_index_type i,
609 : std::vector<numeric_index_type> & indices,
610 : std::vector<T> & values) const = 0;
611 :
612 : /**
613 : * Scales all elements of this matrix by \p scale
614 : */
615 : virtual void scale(const T scale);
616 :
617 : /**
618 : * @returns Whether the matrix supports hash table assembly
619 : */
620 0 : virtual bool supports_hash_table() const { return false; }
621 :
622 : /**
623 : * Sets whether to use hash table assembly. This will error if the passed-in value is true and the
624 : * matrix type does not support hash tables. Hash table or hash map assembly means storing maps
625 : * from i-j locations in the matrix to values. Because it is a hash map as opposed to a contiguous
626 : * array of data, no preallocation is required to use it
627 : */
628 : void use_hash_table(bool use_hash);
629 :
630 : /**
631 : * @returns Whether this matrix is using hash table assembly. Hash table or hash map assembly
632 : * means storing maps from i-j locations in the matrix to values. Because it is a hash map as
633 : * opposed to a contiguous array of data, no preallocation is required to use it
634 : */
635 35133 : bool use_hash_table() const { return _use_hash_table; }
636 :
637 : /**
638 : * Sets the prefix that solver packages prepend to option names when
639 : * they configure this matrix, e.g. a PETSc options prefix. The
640 : * prefix takes effect at the next init() of the matrix.
641 : */
642 21921 : void set_options_prefix(std::string prefix) { _options_prefix = std::move(prefix); }
643 :
644 : /**
645 : * \returns The options prefix of this matrix. See set_options_prefix().
646 : */
647 1578 : const std::string & options_prefix() const { return _options_prefix; }
648 :
649 : /**
650 : * Reset the memory storage of the matrix. Unlike \p clear(), this does not destroy the matrix but
651 : * rather will reset the matrix to use the original preallocation or when using hash table matrix
652 : * assembly (see \p use_hash_table()) will reset (clear) the hash table used for assembly. In the
653 : * words of the \p MatResetPreallocation documentation in PETSc, 'current values in the matrix are
654 : * lost in this call', so a user can expect to have back their original sparsity pattern in a
655 : * zeroed state
656 : */
657 0 : virtual void restore_original_nonzero_pattern() { libmesh_not_implemented(); }
658 :
659 : protected:
660 : /**
661 : * Protected implementation of the create_submatrix and reinit_submatrix
662 : * routines.
663 : *
664 : * \note This function must be overridden in derived classes for it
665 : * to work properly!
666 : */
667 0 : virtual void _get_submatrix(SparseMatrix<T> & /*submatrix*/,
668 : const std::vector<numeric_index_type> & /*rows*/,
669 : const std::vector<numeric_index_type> & /*cols*/,
670 : const bool /*reuse_submatrix*/) const
671 : {
672 0 : libmesh_not_implemented();
673 : }
674 :
675 : /**
676 : * The \p DofMap object associated with this object. May be queried
677 : * for degree-of-freedom counts on processors.
678 : */
679 : DofMap const * _dof_map;
680 :
681 : /**
682 : * The \p sparsity pattern associated with this object. Should be
683 : * queried for entry counts (or with need_full_sparsity_pattern,
684 : * patterns) when needed.
685 : */
686 : SparsityPattern::Build const * _sp;
687 :
688 : /**
689 : * Flag indicating whether or not the matrix has been initialized.
690 : */
691 : bool _is_initialized;
692 :
693 : /**
694 : * Flag indicating whether the matrix is assembled using a hash table
695 : */
696 : bool _use_hash_table;
697 :
698 : /**
699 : * Prefix for solver-package options. See set_options_prefix().
700 : */
701 : std::string _options_prefix;
702 : };
703 :
704 :
705 :
706 : //-----------------------------------------------------------------------
707 : // SparseMatrix inline members
708 : template <typename T>
709 : void
710 21649 : SparseMatrix<T>::use_hash_table(const bool use_hash)
711 : {
712 21649 : libmesh_error_msg_if(use_hash && !this->supports_hash_table(),
713 : "This matrix class does not support hash table assembly");
714 21649 : this->_use_hash_table = use_hash;
715 21649 : }
716 :
717 : // For SGI MIPSpro this implementation must occur after
718 : // the full specialization of the print() member.
719 : //
720 : // It's generally easier to define these friend functions in the header
721 : // file.
722 : template <typename T>
723 0 : std::ostream & operator << (std::ostream & os, const SparseMatrix<T> & m)
724 : {
725 0 : m.print(os);
726 0 : return os;
727 : }
728 :
729 : template <typename T>
730 : auto
731 : l1_norm(const SparseMatrix<T> & mat)
732 : {
733 : return mat.l1_norm();
734 : }
735 :
736 : template <typename T>
737 : auto
738 : l1_norm_diff(const SparseMatrix<T> & mat1, const SparseMatrix<T> & mat2)
739 : {
740 : return mat1.l1_norm_diff(mat2);
741 : }
742 :
743 : } // namespace libMesh
744 :
745 :
746 : #endif // LIBMESH_SPARSE_MATRIX_H
|