Actual source code: matimpl.h


 5:  #include petscmat.h

  7: /*
  8:   This file defines the parts of the matrix data structure that are 
  9:   shared by all matrix types.
 10: */

 12: /*
 13:     If you add entries here also add them to the MATOP enum
 14:     in include/petscmat.h and include/finclude/petscmat.h
 15: */
 16: typedef struct _MatOps *MatOps;
 17: struct _MatOps {
 18:   PetscErrorCode (*setvalues)(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
 19:   PetscErrorCode (*getrow)(Mat,PetscInt,PetscInt *,PetscInt*[],PetscScalar*[]);
 20:   PetscErrorCode (*restorerow)(Mat,PetscInt,PetscInt *,PetscInt *[],PetscScalar *[]);
 21:   PetscErrorCode (*mult)(Mat,Vec,Vec);
 22:   /*4*/
 23:   PetscErrorCode (*multadd)(Mat,Vec,Vec,Vec);
 24:   PetscErrorCode (*multtranspose)(Mat,Vec,Vec);
 25:   PetscErrorCode (*multtransposeadd)(Mat,Vec,Vec,Vec);
 26:   PetscErrorCode (*solve)(Mat,Vec,Vec);
 27:   PetscErrorCode (*solveadd)(Mat,Vec,Vec,Vec);
 28:   PetscErrorCode (*solvetranspose)(Mat,Vec,Vec);
 29:   /*10*/
 30:   PetscErrorCode (*solvetransposeadd)(Mat,Vec,Vec,Vec);
 31:   PetscErrorCode (*lufactor)(Mat,IS,IS,MatFactorInfo*);
 32:   PetscErrorCode (*choleskyfactor)(Mat,IS,MatFactorInfo*);
 33:   PetscErrorCode (*relax)(Mat,Vec,PetscReal,MatSORType,PetscReal,PetscInt,PetscInt,Vec);
 34:   PetscErrorCode (*transpose)(Mat,Mat *);
 35:   /*15*/
 36:   PetscErrorCode (*getinfo)(Mat,MatInfoType,MatInfo*);
 37:   PetscErrorCode (*equal)(Mat,Mat,PetscTruth *);
 38:   PetscErrorCode (*getdiagonal)(Mat,Vec);
 39:   PetscErrorCode (*diagonalscale)(Mat,Vec,Vec);
 40:   PetscErrorCode (*norm)(Mat,NormType,PetscReal *);
 41:   /*20*/
 42:   PetscErrorCode (*assemblybegin)(Mat,MatAssemblyType);
 43:   PetscErrorCode (*assemblyend)(Mat,MatAssemblyType);
 44:   PetscErrorCode (*compress)(Mat);
 45:   PetscErrorCode (*setoption)(Mat,MatOption);
 46:   PetscErrorCode (*zeroentries)(Mat);
 47:   /*25*/
 48:   PetscErrorCode (*zerorows)(Mat,IS,const PetscScalar *);
 49:   PetscErrorCode (*lufactorsymbolic)(Mat,IS,IS,MatFactorInfo*,Mat *);
 50:   PetscErrorCode (*lufactornumeric)(Mat,Mat *);
 51:   PetscErrorCode (*choleskyfactorsymbolic)(Mat,IS,MatFactorInfo*,Mat *);
 52:   PetscErrorCode (*choleskyfactornumeric)(Mat,Mat *);
 53:   /*30*/
 54:   PetscErrorCode (*setuppreallocation)(Mat);
 55:   PetscErrorCode (*ilufactorsymbolic)(Mat,IS,IS,MatFactorInfo*,Mat *);
 56:   PetscErrorCode (*iccfactorsymbolic)(Mat,IS,MatFactorInfo*,Mat *);
 57:   PetscErrorCode (*getarray)(Mat,PetscScalar **);
 58:   PetscErrorCode (*restorearray)(Mat,PetscScalar **);
 59:   /*35*/
 60:   PetscErrorCode (*duplicate)(Mat,MatDuplicateOption,Mat *);
 61:   PetscErrorCode (*forwardsolve)(Mat,Vec,Vec);
 62:   PetscErrorCode (*backwardsolve)(Mat,Vec,Vec);
 63:   PetscErrorCode (*ilufactor)(Mat,IS,IS,MatFactorInfo*);
 64:   PetscErrorCode (*iccfactor)(Mat,IS,MatFactorInfo*);
 65:   /*40*/
 66:   PetscErrorCode (*axpy)(const PetscScalar *,Mat,Mat,MatStructure);
 67:   PetscErrorCode (*getsubmatrices)(Mat,PetscInt,const IS[],const IS[],MatReuse,Mat *[]);
 68:   PetscErrorCode (*increaseoverlap)(Mat,PetscInt,IS[],PetscInt);
 69:   PetscErrorCode (*getvalues)(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],PetscScalar []);
 70:   PetscErrorCode (*copy)(Mat,Mat,MatStructure);
 71:   /*45*/
 72:   PetscErrorCode (*printhelp)(Mat);
 73:   PetscErrorCode (*scale)(const PetscScalar *,Mat);
 74:   PetscErrorCode (*shift)(const PetscScalar *,Mat);
 75:   PetscErrorCode (*diagonalset)(Mat,Vec,InsertMode);
 76:   PetscErrorCode (*iludtfactor)(Mat,MatFactorInfo*,IS,IS,Mat *);
 77:   /*50*/
 78:   PetscErrorCode (*setblocksize)(Mat,PetscInt);
 79:   PetscErrorCode (*getrowij)(Mat,PetscInt,PetscTruth,PetscInt*,PetscInt *[],PetscInt *[],PetscTruth *);
 80:   PetscErrorCode (*restorerowij)(Mat,PetscInt,PetscTruth,PetscInt *,PetscInt *[],PetscInt *[],PetscTruth *);
 81:   PetscErrorCode (*getcolumnij)(Mat,PetscInt,PetscTruth,PetscInt*,PetscInt *[],PetscInt *[],PetscTruth *);
 82:   PetscErrorCode (*restorecolumnij)(Mat,PetscInt,PetscTruth,PetscInt*,PetscInt *[],PetscInt *[],PetscTruth *);
 83:   /*55*/
 84:   PetscErrorCode (*fdcoloringcreate)(Mat,ISColoring,MatFDColoring);
 85:   PetscErrorCode (*coloringpatch)(Mat,PetscInt,PetscInt,ISColoringValue[],ISColoring*);
 86:   PetscErrorCode (*setunfactored)(Mat);
 87:   PetscErrorCode (*permute)(Mat,IS,IS,Mat*);
 88:   PetscErrorCode (*setvaluesblocked)(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
 89:   /*60*/
 90:   PetscErrorCode (*getsubmatrix)(Mat,IS,IS,PetscInt,MatReuse,Mat*);
 91:   PetscErrorCode (*destroy)(Mat);
 92:   PetscErrorCode (*view)(Mat,PetscViewer);
 93:   PetscErrorCode (*getmaps)(Mat,PetscMap*,PetscMap*);
 94:   PetscErrorCode (*usescaledform)(Mat,PetscTruth);
 95:   /*65*/
 96:   PetscErrorCode (*scalesystem)(Mat,Vec,Vec);
 97:   PetscErrorCode (*unscalesystem)(Mat,Vec,Vec);
 98:   PetscErrorCode (*setlocaltoglobalmapping)(Mat,ISLocalToGlobalMapping);
 99:   PetscErrorCode (*setvalueslocal)(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
100:   PetscErrorCode (*zerorowslocal)(Mat,IS,const PetscScalar *);
101:   /*70*/
102:   PetscErrorCode (*getrowmax)(Mat,Vec);
103:   PetscErrorCode (*convert)(Mat,const MatType,Mat*);
104:   PetscErrorCode (*setcoloring)(Mat,ISColoring);
105:   PetscErrorCode (*setvaluesadic)(Mat,void*);
106:   PetscErrorCode (*setvaluesadifor)(Mat,PetscInt,void*);
107:   /*75*/
108:   PetscErrorCode (*fdcoloringapply)(Mat,MatFDColoring,Vec,MatStructure*,void*);
109:   PetscErrorCode (*setfromoptions)(Mat);
110:   PetscErrorCode (*multconstrained)(Mat,Vec,Vec);
111:   PetscErrorCode (*multtransposeconstrained)(Mat,Vec,Vec);
112:   PetscErrorCode (*ilufactorsymbolicconstrained)(Mat,IS,IS,double,PetscInt,PetscInt,Mat *);
113:   /*80*/
114:   PetscErrorCode (*permutesparsify)(Mat, PetscInt, double, double, IS, IS, Mat *);
115:   PetscErrorCode (*mults)(Mat, Vecs, Vecs);
116:   PetscErrorCode (*solves)(Mat, Vecs, Vecs);
117:   PetscErrorCode (*getinertia)(Mat,PetscInt*,PetscInt*,PetscInt*);
118:   PetscErrorCode (*load)(PetscViewer,const MatType,Mat*);
119:   /*85*/
120:   PetscErrorCode (*issymmetric)(Mat,PetscReal,PetscTruth*);
121:   PetscErrorCode (*ishermitian)(Mat,PetscTruth*);
122:   PetscErrorCode (*isstructurallysymmetric)(Mat,PetscTruth*);
123:   PetscErrorCode (*pbrelax)(Mat,Vec,PetscReal,MatSORType,PetscReal,PetscInt,PetscInt,Vec);
124:   PetscErrorCode (*getvecs)(Mat,Vec*,Vec*);
125:   /*90*/
126:   PetscErrorCode (*matmult)(Mat,Mat,MatReuse,PetscReal,Mat*);
127:   PetscErrorCode (*matmultsymbolic)(Mat,Mat,PetscReal,Mat*);
128:   PetscErrorCode (*matmultnumeric)(Mat,Mat,Mat);
129:   PetscErrorCode (*ptap)(Mat,Mat,MatReuse,PetscReal,Mat*);
130:   PetscErrorCode (*ptapsymbolic)(Mat,Mat,PetscReal,Mat*);
131:   /*95*/
132:   PetscErrorCode (*ptapnumeric)(Mat,Mat,Mat);
133:   PetscErrorCode (*matmulttranspose)(Mat,Mat,MatReuse,PetscReal,Mat*);
134:   PetscErrorCode (*matmulttransposesymbolic)(Mat,Mat,PetscReal,Mat*);
135:   PetscErrorCode (*matmulttransposenumeric)(Mat,Mat,Mat);
136: };

138: /*
139:    Utility private matrix routines
140: */
141: EXTERN PetscErrorCode MatConvert_Basic(Mat,const MatType,Mat*);
142: EXTERN PetscErrorCode MatCopy_Basic(Mat,Mat,MatStructure);
143: EXTERN PetscErrorCode MatView_Private(Mat);
144: EXTERN PetscErrorCode MatGetPetscMaps_Petsc(Mat,PetscMap *,PetscMap *);
145: EXTERN PetscErrorCode MatHeaderCopy(Mat,Mat);
146: EXTERN PetscErrorCode MatAXPYGetxtoy_Private(PetscInt,PetscInt*,PetscInt*,PetscInt*, PetscInt*,PetscInt*,PetscInt*, PetscInt**);

148: /* 
149:   The stash is used to temporarily store inserted matrix values that 
150:   belong to another processor. During the assembly phase the stashed 
151:   values are moved to the correct processor and 
152: */

154: typedef struct {
155:   PetscInt      nmax;                   /* maximum stash size */
156:   PetscInt      umax;                   /* user specified max-size */
157:   PetscInt      oldnmax;                /* the nmax value used previously */
158:   PetscInt      n;                      /* stash size */
159:   PetscInt      bs;                     /* block size of the stash */
160:   PetscInt      reallocs;               /* preserve the no of mallocs invoked */
161:   PetscInt      *idx;                   /* global row numbers in stash */
162:   PetscInt      *idy;                   /* global column numbers in stash */
163:   MatScalar     *array;                 /* array to hold stashed values */
164:   /* The following variables are used for communication */
165:   MPI_Comm      comm;
166:   PetscMPIInt   size,rank;
167:   PetscMPIInt   tag1,tag2;
168:   MPI_Request   *send_waits;            /* array of send requests */
169:   MPI_Request   *recv_waits;            /* array of receive requests */
170:   MPI_Status    *send_status;           /* array of send status */
171:   PetscInt      nsends,nrecvs;         /* numbers of sends and receives */
172:   MatScalar     *svalues,*rvalues;     /* sending and receiving data */
173:   PetscInt      rmax;                   /* maximum message length */
174:   PetscInt      *nprocs;                /* tmp data used both duiring scatterbegin and end */
175:   PetscInt      nprocessed;             /* number of messages already processed */
176: } MatStash;

178: EXTERN PetscErrorCode MatStashCreate_Private(MPI_Comm,PetscInt,MatStash*);
179: EXTERN PetscErrorCode MatStashDestroy_Private(MatStash*);
180: EXTERN PetscErrorCode MatStashScatterEnd_Private(MatStash*);
181: EXTERN PetscErrorCode MatStashSetInitialSize_Private(MatStash*,PetscInt);
182: EXTERN PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*);
183: EXTERN PetscErrorCode MatStashValuesRow_Private(MatStash*,PetscInt,PetscInt,const PetscInt[],const MatScalar[]);
184: EXTERN PetscErrorCode MatStashValuesCol_Private(MatStash*,PetscInt,PetscInt,const PetscInt[],const MatScalar[],PetscInt);
185: EXTERN PetscErrorCode MatStashValuesRowBlocked_Private(MatStash*,PetscInt,PetscInt,const PetscInt[],const MatScalar[],PetscInt,PetscInt,PetscInt);
186: EXTERN PetscErrorCode MatStashValuesColBlocked_Private(MatStash*,PetscInt,PetscInt,const PetscInt[],const MatScalar[],PetscInt,PetscInt,PetscInt);
187: EXTERN PetscErrorCode MatStashScatterBegin_Private(MatStash*,PetscInt*);
188: EXTERN PetscErrorCode MatStashScatterGetMesg_Private(MatStash*,PetscMPIInt*,PetscInt**,PetscInt**,MatScalar**,PetscInt*);

190: #define FACTOR_LU       1
191: #define FACTOR_CHOLESKY 2

193: typedef struct {
194:   PetscInt   dim;
195:   PetscInt   dims[4];
196:   PetscInt   starts[4];
197:   PetscTruth noc;        /* this is a single component problem, hence user will not set MatStencil.c */
198: } MatStencilInfo;

200: struct _p_Mat {
201:   PETSCHEADER(struct _MatOps)
202:   PetscMap               rmap,cmap;
203:   void                   *data;            /* implementation-specific data */
204:   PetscInt               factor;           /* 0, FACTOR_LU, or FACTOR_CHOLESKY */
205:   PetscReal              lupivotthreshold; /* threshold for pivoting */
206:   PetscTruth             assembled;        /* is the matrix assembled? */
207:   PetscTruth             was_assembled;    /* new values inserted into assembled mat */
208:   PetscInt               num_ass;          /* number of times matrix has been assembled */
209:   PetscTruth             same_nonzero;     /* matrix has same nonzero pattern as previous */
210:   PetscInt               M,N;             /* global numbers of rows, columns */
211:   PetscInt               m,n;             /* local numbers of rows, columns */
212:   MatInfo                info;             /* matrix information */
213:   ISLocalToGlobalMapping mapping;          /* mapping used in MatSetValuesLocal() */
214:   ISLocalToGlobalMapping bmapping;         /* mapping used in MatSetValuesBlockedLocal() */
215:   InsertMode             insertmode;       /* have values been inserted in matrix or added? */
216:   MatStash               stash,bstash;     /* used for assembling off-proc mat emements */
217:   MatNullSpace           nullsp;
218:   PetscTruth             preallocated;
219:   MatStencilInfo         stencil;          /* information for structured grid */
220:   PetscTruth             symmetric,hermitian,structurally_symmetric;
221:   PetscTruth             symmetric_set,hermitian_set,structurally_symmetric_set; /* if true, then corresponding flag is correct*/
222:   PetscTruth             symmetric_eternal;
223:   PetscInt               bs;
224:   void                   *spptr;          /* pointer for special library like SuperLU */
225: };

227: #define MatPreallocated(A) {PetscInt _e;if (!(A)->preallocated) {_e = MatSetUpPreallocation(A);CHKERRQ(_e);}}

230: /*
231:     Object for partitioning graphs
232: */

234: typedef struct _MatPartitioningOps *MatPartitioningOps;
235: struct _MatPartitioningOps {
236:   PetscErrorCode (*apply)(MatPartitioning,IS*);
237:   PetscErrorCode (*setfromoptions)(MatPartitioning);
238:   PetscErrorCode (*destroy)(MatPartitioning);
239:   PetscErrorCode (*view)(MatPartitioning,PetscViewer);
240: };

242: struct _p_MatPartitioning {
243:   PETSCHEADER(struct _MatPartitioningOps)
244:   Mat         adj;
245:   PetscInt    *vertex_weights;
246:   PetscReal   *part_weights;
247:   PetscInt    n;                                 /* number of partitions */
248:   void        *data;
249:   PetscInt    setupcalled;
250: };

252: /*
253:     MatFDColoring is used to compute Jacobian matrices efficiently
254:   via coloring. The data structure is explained below in an example.

256:    Color =   0    1     0    2   |   2      3       0 
257:    ---------------------------------------------------
258:             00   01              |          05
259:             10   11              |   14     15               Processor  0
260:                        22    23  |          25
261:                        32    33  | 
262:    ===================================================
263:                                  |   44     45     46
264:             50                   |          55               Processor 1
265:                                  |   64            66
266:    ---------------------------------------------------

268:     ncolors = 4;

270:     ncolumns      = {2,1,1,0}
271:     columns       = {{0,2},{1},{3},{}}
272:     nrows         = {4,2,3,3}
273:     rows          = {{0,1,2,3},{0,1},{1,2,3},{0,1,2}}
274:     columnsforrow = {{0,0,2,2},{1,1},{4,3,3},{5,5,5}}
275:     vscaleforrow  = {{,,,},{,},{,,},{,,}}
276:     vwscale       = {dx(0),dx(1),dx(2),dx(3)}               MPI Vec
277:     vscale        = {dx(0),dx(1),dx(2),dx(3),dx(4),dx(5)}   Seq Vec

279:     ncolumns      = {1,0,1,1}
280:     columns       = {{6},{},{4},{5}}
281:     nrows         = {3,0,2,2}
282:     rows          = {{0,1,2},{},{1,2},{1,2}}
283:     columnsforrow = {{6,0,6},{},{4,4},{5,5}}
284:     vscaleforrow =  {{,,},{},{,},{,}}
285:     vwscale       = {dx(4),dx(5),dx(6)}              MPI Vec
286:     vscale        = {dx(0),dx(4),dx(5),dx(6)}        Seq Vec

288:     See the routine MatFDColoringApply() for how this data is used
289:     to compute the Jacobian.

291: */

293: struct  _p_MatFDColoring{
294:   PETSCHEADER(int)
295:   PetscInt   M,N,m;            /* total rows, columns; local rows */
296:   PetscInt   rstart;           /* first row owned by local processor */
297:   PetscInt   ncolors;          /* number of colors */
298:   PetscInt   *ncolumns;        /* number of local columns for a color */
299:   PetscInt   **columns;        /* lists the local columns of each color (using global column numbering) */
300:   PetscInt   *nrows;           /* number of local rows for each color */
301:   PetscInt   **rows;           /* lists the local rows for each color (using the local row numbering) */
302:   PetscInt   **columnsforrow;  /* lists the corresponding columns for those rows (using the global column) */
303:   PetscReal  error_rel;        /* square root of relative error in computing function */
304:   PetscReal  umin;             /* minimum allowable u'dx value */
305:   PetscInt   freq;             /* frequency at which new Jacobian is computed */
306:   Vec        w1,w2,w3;         /* work vectors used in computing Jacobian */
307:   PetscErrorCode (*f)(void);       /* function that defines Jacobian */
308:   void       *fctx;            /* optional user-defined context for use by the function f */
309:   PetscInt   **vscaleforrow;   /* location in vscale for each columnsforrow[] entry */
310:   Vec        vscale;           /* holds FD scaling, i.e. 1/dx for each perturbed column */
311:   PetscTruth usersetsrecompute;/* user determines when Jacobian is recomputed, via MatFDColoringSetRecompute() */
312:   PetscTruth recompute;        /* used with usersetrecompute to determine if Jacobian should be recomputed */
313:   Vec        F;                /* current value of user provided function; can set with MatFDColoringSetF() */
314:   PetscInt   currentcolor;     /* color for which function evaluation is being done now */
315: };

317: /*
318:    Null space context for preconditioner/operators
319: */
320: struct _p_MatNullSpace {
321:   PETSCHEADER(int)
322:   PetscTruth  has_cnst;
323:   PetscInt    n;
324:   Vec*        vecs;
325:   Vec         vec;      /* for out of place removals */
326: };

328: #endif