1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>MatMPIBAIJSetPreallocation</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<A NAME="MatMPIBAIJSetPreallocation"><H1>MatMPIBAIJSetPreallocation</H1></A>
Allocates memory for a sparse parallel matrix in 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.
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscmat.h"
PetscErrorCode MatMPIBAIJSetPreallocation(Mat B,PetscInt bs,PetscInt d_nz,const PetscInt d_nnz[],PetscInt o_nz,const PetscInt o_nnz[])
</PRE>
Collective on <A HREF="../Mat/Mat.html#Mat">Mat</A>
<P>
<H3><FONT COLOR="#CC3333">Input Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>A </B></TD><TD>- the matrix
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>bs </B></TD><TD>- size of blockk
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>d_nz </B></TD><TD>- number of block nonzeros per block row in diagonal portion of local
submatrix (same for all local rows)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>d_nnz </B></TD><TD>- array containing the number of block nonzeros in the various block rows
of the in diagonal portion of the local (possibly different for each block
row) or <A HREF="../Sys/PETSC_NULL.html#PETSC_NULL">PETSC_NULL</A>. You must leave room for the diagonal entry even if it is zero.
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>o_nz </B></TD><TD>- number of block nonzeros per block row in the off-diagonal portion of local
submatrix (same for all local rows).
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>o_nnz </B></TD><TD>- 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 <A HREF="../Sys/PETSC_NULL.html#PETSC_NULL">PETSC_NULL</A>.
</TD></TR></TABLE>
<P>
If the *_nnz parameter is given then the *_nz parameter is ignored
<P>
<H3><FONT COLOR="#CC3333">Options Database Keys</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-mat_block_size </B></TD><TD>- size of the blocks to use
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-mat_use_hash_table <fact></B></TD><TD>-
Notes:
If <A HREF="../Sys/PETSC_DECIDE.html#PETSC_DECIDE">PETSC_DECIDE</A> or <A HREF="../Sys/PETSC_DETERMINE.html#PETSC_DETERMINE">PETSC_DETERMINE</A> is used for a particular argument on one processor
than it must be used on all processors that share the object for that argument.
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Storage Information</FONT></H3>
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).
<P>
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=<A HREF="../Sys/PETSC_DEFAULT.html#PETSC_DEFAULT">PETSC_DEFAULT</A> and d_nnz=<A HREF="../Sys/PETSC_NULL.html#PETSC_NULL">PETSC_NULL</A> 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).
<P>
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).
<P>
<PRE>
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
-------------------
</PRE>
<P>
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 <A HREF="../Mat/MATSEQBAIJ.html#MATSEQBAIJ">MATSEQBAIJ</A> format for compressed row storage.
<P>
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.
<P>
You can call <A HREF="../Mat/MatGetInfo.html#MatGetInfo">MatGetInfo</A>() to get information on how effective the preallocation was;
for example the fields mallocs,nz_allocated,nz_used,nz_unneeded;
You can also run with the option -info and look for messages with the string
malloc in them to see if additional memory allocation was needed.
<P>
<P>
<H3><FONT COLOR="#CC3333">Keywords</FONT></H3>
matrix, block, aij, compressed row, sparse, parallel
<BR>
<P>
<H3><FONT COLOR="#CC3333">C++ variants</FONT></H3><TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD>  MatMPIBAIJSetPreallocation(Mat A,PetscInt bs,const PetscInt nnz[],const PetscInt onz[])<TD WIDTH=20></TD><TD>-></TD><TD WIDTH=20></TD><TD>MatMPIBAIJSetPreallocation(A,bs,0,nnz,0,onz)</TR></TD>
</TABLE>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(), <A HREF="../Mat/MatCreateSeqBAIJ.html#MatCreateSeqBAIJ">MatCreateSeqBAIJ</A>(), <A HREF="../Mat/MatSetValues.html#MatSetValues">MatSetValues</A>(), <A HREF="../Mat/MatCreateMPIBAIJ.html#MatCreateMPIBAIJ">MatCreateMPIBAIJ</A>(), <A HREF="../Mat/MatMPIBAIJSetPreallocationCSR.html#MatMPIBAIJSetPreallocationCSR">MatMPIBAIJSetPreallocationCSR</A>()
<BR><P><B><P><B><FONT COLOR="#CC3333">Level:</FONT></B>intermediate
<BR><FONT COLOR="#CC3333">Location:</FONT></B><A HREF="../../../src/mat/impls/baij/mpi/mpibaij.c.html#MatMPIBAIJSetPreallocation">src/mat/impls/baij/mpi/mpibaij.c</A>
<BR><A HREF="./index.html">Index of all Mat routines</A>
<BR><A HREF="../../index.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/snes/examples/tutorials/ex48.c.html">src/snes/examples/tutorials/ex48.c.html</A><BR>
</BODY></HTML>
|
