Skip to main content
`Ctrl`+`K`

# MatCreateSBAIJ

Creates a sparse parallel matrix in symmetric block AIJ format, `MATSBAIJ`, (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`).

## 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

## Input Parameters

- 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 `MatCreateVecs()`

- m - number of local rows (or `PETSC_DECIDE` to 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_DECIDE` to 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_DETERMINE` to have calculated if `m` is given)

- N - number of global columns (or `PETSC_DETERMINE` to have calculated if `n` is given)

- d_nz - number of block nonzeros per block row in diagonal portion of local submatrix (same for all local rows)

- d_nnz - array containing the number of block nonzeros in the various block rows in the upper triangular portion of the in diagonal portion of the local (possibly different for each block block row) or `NULL`. If you plan to factor the matrix you must leave room for the diagonal entry and set its value even if it is zero.

- o_nz - number of block nonzeros per block row in the off-diagonal portion of local submatrix (same for all local rows).

- o_nnz - array containing the number of nonzeros in the various block rows of the off-diagonal portion of the local submatrix (possibly different for each block row) or `NULL`.

## Output Parameter

- A - the matrix

## Options Database Keys

- -mat_no_unroll - uses code that does not unroll the loops in the block calculations (much slower)

- -mat_block_size - size of the blocks to use

- -mat_mpi - use the parallel matrix data structures even on one processor (defaults to using SeqBAIJ format on one processor)

## Notes

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

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

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

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

If `m` and `n` are not `PETSC_DECIDE`, then the values determines the `PetscLayout` of the matrix and the ranges returned by `MatGetOwnershipRange()`, `MatGetOwnershipRanges()`, `MatGetOwnershipRangeColumn()`, and `MatGetOwnershipRangesColumn()`.

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

## Storage Information

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  |. . . 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
              --------------------------

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 matrix is stored in `MATSEQSBAIJ` format and the o submatrix in `MATSEQBAIJ` format.

Now `d_nz` should indicate the number of block nonzeros per row in the upper triangular plus the diagonal part of 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`.

## See Also

Matrices, `Mat`, `MATSBAIJ`, `MatCreate()`, `MatCreateSeqSBAIJ()`, `MatSetValues()`, `MatCreateBAIJ()`, `MatGetOwnershipRange()`, `MatGetOwnershipRanges()`, `MatGetOwnershipRangeColumn()`, `MatGetOwnershipRangesColumn()`, `PetscLayout`

## Level

intermediate

## Location

src/mat/impls/sbaij/mpi/mpisbaij.c

## Examples

src/ksp/ksp/tutorials/ex81.c
src/ksp/ksp/tutorials/ex81a.c

Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages