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

MatCreateAIJ

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

#include "petscmat.h" 
PetscErrorCode  MatCreateAIJ(MPI_Comm comm,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
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 - This value should be the same as the local size used in creating the Many brx vector for the matrix-vector product y = Ax. (or PETSC_DECIDE to have Many brcalculated if N is given) For square matrices n is almost always m. 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 nonzeros per row in DIAGONAL portion of local submatrix Many br(same value is used for all local rows) Many br
d_nnz - array containing the number of nonzeros in the various rows of the Many brDIAGONAL portion of the local submatrix (possibly different for each row) Many bror NULL, if d_nz is used to specify the nonzero structure. Many brThe size of this array is equal to the number of local rows, i.e 'm'. Many br
o_nz - number of nonzeros per row in the OFF-DIAGONAL portion of local Many brsubmatrix (same value is used for all local rows). Many br
o_nnz - array containing the number of nonzeros in the various rows of the Many brOFF-DIAGONAL portion of the local submatrix (possibly different for Many breach row) or NULL, if o_nz is used to specify the nonzero Many brstructure. The size of this array is equal to the number Many brof local rows, i.e 'm'. Many br

Output Parameter

A -the matrix 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

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

m,n,M,N parameters specify the size of the matrix, and its partitioning across Many brprocessors, while d_nz,d_nnz,o_nz,o_nnz parameters specify the approximate Many brstorage requirements for this matrix. Many br

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

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

The parallel matrix is partitioned across processors such that the Many brfirst m0 rows belong to process 0, the next m1 rows belong to Many brprocess 1, the next m2 rows belong to process 2 etc.. where Many brm0,m1,m2,.. are the input parameter 'm'. i.e each processor stores Many brvalues corresponding to [m x N] submatrix. Many br

The columns are logically partitioned with the n0 columns belonging Many brto 0th partition, the next n1 columns belonging to the next Many brpartition etc.. where n0,n1,n2... are the input parameter 'n'. Many br

The DIAGONAL portion of the local submatrix on any given processor Many bris the submatrix corresponding to the rows and columns m,n Many brcorresponding to the given processor. i.e diagonal matrix on Many brprocess 0 is [m0 x n0], diagonal matrix on process 1 is [m1 x n1] Many bretc. The remaining portion of the local submatrix [m x (N-n)] Many brconstitute the OFF-DIAGONAL portion. The example below better Many brillustrates this concept. Many br

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

If o_nnz, d_nnz are specified, then o_nz, and d_nz are ignored. Many br

When calling this routine with a single process communicator, a matrix of Many brtype SEQAIJ is returned. If a matrix of type MPIAIJ is desired for this Many br

type of communicator, use the construction mechanism

MatCreate(...,&A); MatSetType(A,MATMPIAIJ); MatSetSizes(A, m,n,M,N); MatMPIAIJSetPreallocation(A,...); Many br

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

Options Database Keys

-mat_no_inode - Do not use inodes Many br
-mat_inode_limit <limit> - Sets inode limit (max limit=5) Many br
-mat_aij_oneindex - Internally use indexing starting at 1 Many brrather than 0. Note that when calling MatSetValues(), Many brthe user still MUST index entries starting at 0! Many br

Example usage

Consider the following 8x8 matrix with 34 non-zero values, that is Many brassembled across 3 processors. Lets assume that proc0 owns 3 rows, Many brproc1 owns 3 rows, proc2 owns 2 rows. This division can be shown Many br

as follows

            1  2  0  |  0  3  0  |  0  4
    Proc0   0  5  6  |  7  0  0  |  8  0
            9  0 10  | 11  0  0  | 12  0
    -------------------------------------
           13  0 14  | 15 16 17  |  0  0
    Proc1   0 18  0  | 19 20 21  |  0  0
            0  0  0  | 22 23  0  | 24  0
    -------------------------------------
    Proc2  25 26 27  |  0  0 28  | 29  0
           30  0  0  | 31 32 33  |  0 34
Many br

This can be represented as a collection of submatrices as

      A B C
      D E F
      G H I
Many br

Where the submatrices A,B,C are owned by proc0, D,E,F are Many browned by proc1, G,H,I are owned by proc2. Many br

The 'm' parameters for proc0,proc1,proc2 are 3,3,2 respectively. Many brThe 'n' parameters for proc0,proc1,proc2 are 3,3,2 respectively. Many brThe 'M','N' parameters are 8,8, and have the same values on all procs. Many br

The DIAGONAL submatrices corresponding to proc0,proc1,proc2 are Many brsubmatrices [A], [E], [I] respectively. The OFF-DIAGONAL submatrices Many brcorresponding to proc0,proc1,proc2 are [BC], [DF], [GH] respectively. Many brInternally, each processor stores the DIAGONAL part, and the OFF-DIAGONAL Many brpart as SeqAIJ matrices. for eg: proc1 will store [E] as a SeqAIJ Many brmatrix, ans [DF] as another SeqAIJ matrix. Many br

When d_nz, o_nz parameters are specified, d_nz storage elements are Many brallocated for every row of the local diagonal submatrix, and o_nz Many brstorage locations are allocated for every row of the OFF-DIAGONAL submat. Many brOne way to choose d_nz and o_nz is to use the max nonzerors per local Many brrows for each of the local DIAGONAL, and the OFF-DIAGONAL submatrices. Many br

In this case, the values of d_nz,o_nz are

     proc0 : dnz = 2, o_nz = 2
     proc1 : dnz = 3, o_nz = 2
     proc2 : dnz = 1, o_nz = 4
Many brWe are allocating m*(d_nz+o_nz) storage locations for every proc. This Many brtranslates to 3*(2+2)=12 for proc0, 3*(3+2)=15 for proc1, 2*(1+4)=10 Many brfor proc3. i.e we are using 12+15+10=37 storage locations to store Many br34 values. Many br

When d_nnz, o_nnz parameters are specified, the storage is specified Many brfor every row, coresponding to both DIAGONAL and OFF-DIAGONAL submatrices. Many br

In the above case the values for d_nnz,o_nnz are

     proc0: d_nnz = [2,2,2] and o_nnz = [2,2,2]
     proc1: d_nnz = [3,3,2] and o_nnz = [2,1,1]
     proc2: d_nnz = [1,1]   and o_nnz = [4,4]
Many brHere the space allocated is sum of all the above values i.e 34, and Many brhence pre-allocation is perfect. Many br

Many br

Keywords

matrix, aij, compressed row, sparse, parallel

See Also

MatCreate(), MatCreateSeqAIJ(), MatSetValues(), MatMPIAIJSetPreallocation(), MatMPIAIJSetPreallocationCSR(),
MPIAIJ, MatCreateMPIAIJWithArrays() Many br

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

Examples

src/ksp/ksp/examples/tutorials/ex54.c.html
src/ksp/ksp/examples/tutorials/ex14f.F.html
src/snes/examples/tutorials/ex5s.c.html
src/tao/bound/examples/tutorials/plate2.c.html
src/tao/bound/examples/tutorials/plate2f.F.html