Creates a sparse parallel matrix in
MATBAIJ format (block compressed row). For good matrix assembly performance the user should preallocate the matrix storage by setting the parameters d_nz (or d_nnz) and o_nz (or o_nnz). By setting these parameters accurately, performance can be increased by more than a factor of 50.
comm - MPI communicator
bs - size of block, the blocks are ALWAYS square. One can use
MatSetBlockSizes()to set a different row and column blocksize but the row blocksize always defines the size of the blocks. The column blocksize sets the blocksize of the vectors obtained with
m - number of local rows (or
PETSC_DECIDEto have calculated if M is given) This value should be the same as the local size used in creating the y vector for the matrix-vector product y = Ax.
n - number of local columns (or
PETSC_DECIDEto have calculated if N is given) This value should be the same as the local size used in creating the x vector for the matrix-vector product y = Ax.
M - number of global rows (or
PETSC_DETERMINEto have calculated if m is given)
N - number of global columns (or
PETSC_DETERMINEto have calculated if n is given)
d_nz - number of nonzero blocks per block row in diagonal portion of local submatrix (same for all local rows)
d_nnz - array containing the number of nonzero blocks in the various block rows of the in diagonal portion of the local (possibly different for each block row) or NULL. If you plan to factor the matrix you must leave room for the diagonal entry and set it even if it is zero.
o_nz - number of nonzero blocks per block row in the off-diagonal portion of local submatrix (same for all local rows).
o_nnz - array containing the number of nonzero blocks in the various block rows of the off-diagonal portion of the local submatrix (possibly different for each block row) or NULL.
A - the matrix
Options Database Keys#
-mat_block_size - size of the blocks to use
-set hash table factor
It is recommended that one use the
MatXXXXSetPreallocation() paradigm instead of this routine directly.
[MatXXXXSetPreallocation() is, for example,
If the *_nnz parameter is given then the *_nz parameter is ignored
A nonzero block is any block that as 1 or more nonzeros in it
The user MUST specify either the local or global matrix dimensions (possibly both).
For a square global matrix we define each processor’s diagonal portion to be its local rows and the corresponding columns (a square submatrix); each processor’s off-diagonal portion encompasses the remainder of the local matrix (a rectangular submatrix).
The user can specify preallocated storage for the diagonal part of the local submatrix with either d_nz or d_nnz (not both). Set d_nz=PETSC_DEFAULT and d_nnz=NULL for PETSc to control dynamic memory allocation. Likewise, specify preallocated storage for the off-diagonal part of the local submatrix with o_nz or o_nnz (not both).
Consider a processor that owns rows 3, 4 and 5 of a parallel matrix. In the figure below we depict these three local rows and all columns (0-11).
0 1 2 3 4 5 6 7 8 9 10 11 -------------------------- row 3 |o o o d d d o o o o o o row 4 |o o o d d d o o o o o o row 5 |o o o d d d o o o o o o --------------------------
Thus, any entries in the d locations are stored in the d (diagonal)
submatrix, and any entries in the o locations are stored in the
o (off-diagonal) submatrix. Note that the d and the o submatrices are
stored simply in the
MATSEQBAIJ format for compressed row storage.
Now d_nz should indicate the number of block nonzeros per row in the d matrix, and o_nz should indicate the number of block nonzeros per row in the o matrix. In general, for PDE problems in which most nonzeros are near the diagonal, one expects d_nz >> o_nz. For large problems you MUST preallocate memory or you will get TERRIBLE performance; see the users’ manual chapter on matrices.