MatCreateMPIAIJ

Creates a sparse parallel matrix in AIJ format (the default parallel PETSc format). 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

int MatCreateMPIAIJ(MPI_Comm comm,int m,int n,int M,int N,int d_nz,int *d_nnz,int o_nz,int *o_nnz,Mat *A)
Collective on MPI_Comm

Input Parameters

comm - MPI communicator
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 - This value should be the same as the local size used in creating the x vector for the matrix-vector product y = Ax. (or PETSC_DECIDE to have calculated if N is given) For square matrices n is almost always m.
M - number of global rows (or PETSC_DECIDE to have calculated if m is given)
N - number of global columns (or PETSC_DECIDE to have calculated if n is given)
d_nz - number of nonzeros per row in diagonal portion of local submatrix (same for all local rows)
d_nzz - array containing the number of nonzeros in the various rows of the diagonal portion of the local submatrix (possibly different for each row) or PETSC_NULL. You must leave room for the diagonal entry even if it is zero.
o_nz - number of nonzeros per row in the off-diagonal portion of local submatrix (same for all local rows).
o_nzz - array containing the number of nonzeros in the various rows of the off-diagonal portion of the local submatrix (possibly different for each row) or PETSC_NULL.

Output Parameter

A -the matrix

Notes

The AIJ format (also called the Yale sparse matrix format orcompressed row storage), is fully compatible with standard Fortran 77storage. That is, the stored row and column indices can begin ateither one (as in Fortran) or zero. See the users manual for details.

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

By default, this format uses inodes (identical nodes) when possible. We search for consecutive rows with the same nonzero structure, therebyreusing matrix information to achieve increased efficiency.

Options Database Keys

-mat_aij_no_inode - Do not use inodes
-mat_aij_inode_limit <limit> - Sets inode limit (max limit=5)
-mat_aij_oneindex - Internally use indexing starting at 1 rather than 0. Note that when calling MatSetValues(), the user still MUST index entries starting at 0!

Storage Information

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

The user can specify preallocated storage for the diagonal part ofthe local submatrix with either d_nz or d_nnz (not both). Setd_nz=PETSC_DEFAULT and d_nnz=PETSC_NULL for PETSc to control dynamicmemory allocation. Likewise, specify preallocated storage for theoff-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. Inthe 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 theo (off-diagonal) submatrix. Note that the d and the o submatrices arestored simply in the MATSEQAIJ format for compressed row storage.

Now d_nz should indicate the number of nonzeros per row in the d matrix, and o_nz should indicate the number of 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 memoryor you will get TERRIBLE performance; see the users' manual chapter onmatrices.

Keywords

matrix, aij, compressed row, sparse, parallel

See Also

MatCreate(), MatCreateSeqAIJ(), MatSetValues()

Location: src/mat/impls/aij/mpi/mpiaij.c
Matrix Index
Table of Contents