From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 11 Jan 2023 21:18:32 +0000 (-0700)
Subject: Augment documentation of the PETSc block sparse matrix.
X-Git-Tag: v9.5.0-rc1~655^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=62bc86752c77a21a965f080afafe6db61cc3c51a;p=dealii.git

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 f62d718b2a..eb52c62072 100644
--- 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 a290cfb602..b70918a984 100644
--- 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()
     {