petsc-3.7.1 2016-05-15
Report Typos and Errors

MatCreateSBAIJ

Creates a sparse parallel matrix in symmetric block AIJ 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.

Synopsis

#include "petscmat.h" 
PetscErrorCode  MatCreateSBAIJ(MPI_Comm comm,PetscInt bs,PetscInt m,PetscInt n,PetscInt M,PetscInt N,PetscInt d_nz,const PetscInt d_nnz[],PetscInt o_nz,const PetscInt o_nnz[],Mat *A)
Collective on MPI_Comm Many br

Input Parameters

comm - MPI communicator Many br
bs - size of block, the blocks are ALWAYS square. One can use MatSetBlockSizes() to set a different row and column blocksize but the row Many brblocksize always defines the size of the blocks. The column blocksize sets the blocksize of the vectors obtained with MatCreateVecs() Many br
m - number of local rows (or PETSC_DECIDE to have calculated if M is given) Many brThis value should be the same as the local size used in creating the Many bry vector for the matrix-vector product y = Ax. Many br
n - number of local columns (or PETSC_DECIDE to have calculated if N is given) Many brThis value should be the same as the local size used in creating the Many brx vector for the matrix-vector product y = Ax. Many br
M - number of global rows (or PETSC_DETERMINE to have calculated if m is given) Many br
N - number of global columns (or PETSC_DETERMINE to have calculated if n is given) Many br
d_nz - number of block nonzeros per block row in diagonal portion of local Many brsubmatrix (same for all local rows) Many br
d_nnz - array containing the number of block nonzeros in the various block rows Many brin the upper triangular portion of the in diagonal portion of the local Many br(possibly different for each block block row) or NULL. Many brIf you plan to factor the matrix you must leave room for the diagonal entry and Many brset its value even if it is zero. Many br
o_nz - number of block nonzeros per block row in the off-diagonal portion of local Many brsubmatrix (same for all local rows). Many br
o_nnz - array containing the number of nonzeros in the various block rows of the Many broff-diagonal portion of the local submatrix (possibly different for Many breach block row) or NULL. Many br

Output Parameter

A -the matrix Many br

Options Database Keys

-mat_no_unroll -uses code that does not unroll the loops in the Many brblock calculations (much slower) Many br
-mat_block_size -size of the blocks to use Many br
-mat_mpi -use the parallel matrix data structures even on one processor Many br(defaults to using SeqBAIJ format on one processor) Many br

It is recommended that one use the MatCreate(), MatSetType() and/or MatSetFromOptions(), Many brMatXXXXSetPreallocation() paradgm instead of this routine directly. Many br[MatXXXXSetPreallocation() is, for example, MatSeqAIJSetPreallocation] Many br

Notes

The number of rows and columns must be divisible by blocksize. Many brThis matrix type does not support complex Hermitian operation. Many br

The user MUST specify either the local or global matrix dimensions Many br(possibly both). Many br

If PETSC_DECIDE or PETSC_DETERMINE is used for a particular argument on one processor Many brthan it must be used on all processors that share the object for that argument. Many br

If the *_nnz parameter is given then the *_nz parameter is ignored Many br

Storage Information

For a square global matrix we define each processor's diagonal portion Many brto be its local rows and the corresponding columns (a square submatrix); Many breach processor's off-diagonal portion encompasses the remainder of the Many brlocal matrix (a rectangular submatrix). Many br

The user can specify preallocated storage for the diagonal part of Many brthe local submatrix with either d_nz or d_nnz (not both). Set Many brd_nz=PETSC_DEFAULT and d_nnz=NULL for PETSc to control dynamic Many brmemory allocation. Likewise, specify preallocated storage for the Many broff-diagonal part of the local submatrix with o_nz or o_nnz (not both). Many br

Consider a processor that owns rows 3, 4 and 5 of a parallel matrix. In Many brthe figure below we depict these three local rows and all columns (0-11). Many br

           0 1 2 3 4 5 6 7 8 9 10 11
          --------------------------
   row 3  |. . . d d d o o o o  o  o
   row 4  |. . . d d d o o o o  o  o
   row 5  |. . . d d d o o o o  o  o
          --------------------------
Many br

Thus, any entries in the d locations are stored in the d (diagonal) Many brsubmatrix, and any entries in the o locations are stored in the Many bro (off-diagonal) submatrix. Note that the d matrix is stored in Many brMatSeqSBAIJ format and the o submatrix in MATSEQBAIJ format. Many br

Now d_nz should indicate the number of block nonzeros per row in the upper triangular Many brplus the diagonal part of the d matrix, Many brand o_nz should indicate the number of block nonzeros per row in the o matrix. Many brIn general, for PDE problems in which most nonzeros are near the diagonal, Many brone expects d_nz >> o_nz. For large problems you MUST preallocate memory Many bror you will get TERRIBLE performance; see the users' manual chapter on Many brmatrices. Many br

Many br

Keywords

matrix, block, aij, compressed row, sparse, parallel

See Also

MatCreate(), MatCreateSeqSBAIJ(), MatSetValues(), MatCreateBAIJ()

Level:intermediate
Location:
src/mat/impls/sbaij/mpi/mpisbaij.c
Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages