LCOV - code coverage report
Current view: top level - include/numerics - sparse_matrix.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4573 (924896) with base 3f0912 Lines: 18 40 45.0 %
Date: 2026-11-18 21:52:26 Functions: 19 55 34.5 %
Legend: Lines: hit not hit

          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          36 :   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       10404 :   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     3690262 :   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        3957 :   virtual bool need_full_sparsity_pattern() const
     164        3957 :   { return false; }
     165             : 
     166             :   /**
     167             :    * @returns Whether this matrix needs the sparsity pattern computed by the \p DofMap
     168             :    */
     169        1461 :   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          56 :   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          56 :     this->_get_submatrix(submatrix,
     540             :                          rows,
     541             :                          cols,
     542             :                          false); // false means DO NOT REUSE submatrix
     543          56 :   }
     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        2093 :   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        2073 :   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        2057 : SparseMatrix<T>::use_hash_table(const bool use_hash)
     711             : {
     712        2057 :   libmesh_error_msg_if(use_hash && !this->supports_hash_table(),
     713             :                        "This matrix class does not support hash table assembly");
     714        2057 :   this->_use_hash_table = use_hash;
     715        2057 : }
     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

Generated by: LCOV version 1.14