Augment documentation of the PETSc block sparse matrix.

diff --git a/include/deal.II/lac/petsc_block_sparse_matrix.h b/include/deal.II/lac/petsc_block_sparse_matrix.h
index f62d718b2ab17fbfc64f05be287785c1dc188c56..eb52c6207222b6c12d0fe7f376ebcc3e5e664c72 100644 (file)
--- a/include/deal.II/lac/petsc_block_sparse_matrix.h
+++ b/include/deal.II/lac/petsc_block_sparse_matrix.h
@@ -285,11 +285,22 @@ namespace PETScWrappers
        * Return a reference to the underlying PETSc type. It can be used to
        * modify the underlying data, so use it only when you know what you
        * are doing.
+       *
+       * The PETSc Mat object returned here describes the *entire* matrix,
+       * not just one of its blocks. Internally, this is done by creating
+       * a "nested" matrix using Petsc's MatCreateNest object whose individual
+       * blocks are the blocks of this matrix.
        */
       Mat &
       petsc_matrix();
 
     private:
+      /**
+       * A PETSc Mat object that describes the entire block matrix.
+       * Internally, this is done by creating
+       * a "nested" matrix using Petsc's MatCreateNest object whose individual
+       * blocks are the blocks of this matrix.
+       */
       Mat petsc_nest_matrix = nullptr;
     };
 

diff --git a/source/lac/petsc_parallel_block_sparse_matrix.cc b/source/lac/petsc_parallel_block_sparse_matrix.cc
index a290cfb602bc1cc7b9032b2aba699e769a384440..b70918a984cbc35a0a5ba945a224881ab290dd45 100644 (file)
--- a/source/lac/petsc_parallel_block_sparse_matrix.cc
+++ b/source/lac/petsc_parallel_block_sparse_matrix.cc
@@ -32,6 +32,8 @@ namespace PETScWrappers
       return *this;
     }
 
+
+
     BlockSparseMatrix::~BlockSparseMatrix()
     {
       PetscErrorCode ierr = destroy_matrix(petsc_nest_matrix);
@@ -39,6 +41,8 @@ namespace PETScWrappers
       AssertNothrow(ierr == 0, ExcPETScError(ierr));
     }
 
+
+
 #  ifndef DOXYGEN
     void
     BlockSparseMatrix::reinit(const size_type n_block_rows,
@@ -65,6 +69,8 @@ namespace PETScWrappers
     }
 #  endif
 
+
+
     void
     BlockSparseMatrix::reinit(const std::vector<IndexSet> &      rows,
                               const std::vector<IndexSet> &      cols,
@@ -138,6 +144,8 @@ namespace PETScWrappers
       AssertThrow(ierr == 0, ExcPETScError(ierr));
     }
 
+
+
     std::vector<IndexSet>
     BlockSparseMatrix::locally_owned_domain_indices() const
     {
@@ -149,6 +157,8 @@ namespace PETScWrappers
       return index_sets;
     }
 
+
+
     std::vector<IndexSet>
     BlockSparseMatrix::locally_owned_range_indices() const
     {
@@ -160,6 +170,8 @@ namespace PETScWrappers
       return index_sets;
     }
 
+
+
     std::uint64_t
     BlockSparseMatrix::n_nonzero_elements() const
     {
@@ -171,6 +183,8 @@ namespace PETScWrappers
       return n_nonzero;
     }
 
+
+
     const MPI_Comm &
     BlockSparseMatrix::get_mpi_communicator() const
     {
@@ -182,6 +196,8 @@ namespace PETScWrappers
       return petsc_nest_matrix;
     }
 
+
+
     Mat &
     BlockSparseMatrix::petsc_matrix()
     {