Actual source code: matimpl.h

  1: /* $Id: matimpl.h,v 1.126 2001/08/21 21:02:01 bsmith Exp $ */


 6:  #include petscmat.h

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

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

110: /*
111:    Utility private matrix routines
112: */
113: EXTERN int MatConvert_Basic(Mat,const MatType,Mat*);
114: EXTERN int MatCopy_Basic(Mat,Mat,MatStructure);
115: EXTERN int MatView_Private(Mat);
116: EXTERN int MatGetPetscMaps_Petsc(Mat,PetscMap *,PetscMap *);
117: EXTERN int MatHeaderCopy(Mat,Mat);
118: EXTERN int MatAXPYGetxtoy_Private(int,int*,int*,int*, int*,int*,int*, int**);

120: /* 
121:   The stash is used to temporarily store inserted matrix values that 
122:   belong to another processor. During the assembly phase the stashed 
123:   values are moved to the correct processor and 
124: */

126: typedef struct {
127:   int           nmax;                   /* maximum stash size */
128:   int           umax;                   /* user specified max-size */
129:   int           oldnmax;                /* the nmax value used previously */
130:   int           n;                      /* stash size */
131:   int           bs;                     /* block size of the stash */
132:   int           reallocs;               /* preserve the no of mallocs invoked */
133:   int           *idx;                   /* global row numbers in stash */
134:   int           *idy;                   /* global column numbers in stash */
135:   MatScalar     *array;                 /* array to hold stashed values */
136:   /* The following variables are used for communication */
137:   MPI_Comm      comm;
138:   int           size,rank;
139:   int           tag1,tag2;
140:   MPI_Request   *send_waits;            /* array of send requests */
141:   MPI_Request   *recv_waits;            /* array of receive requests */
142:   MPI_Status    *send_status;           /* array of send status */
143:   int           nsends,nrecvs;         /* numbers of sends and receives */
144:   MatScalar     *svalues,*rvalues;     /* sending and receiving data */
145:   int           rmax;                   /* maximum message length */
146:   int           *nprocs;                /* tmp data used both duiring scatterbegin and end */
147:   int           nprocessed;             /* number of messages already processed */
148: } MatStash;

150: EXTERN int MatStashCreate_Private(MPI_Comm,int,MatStash*);
151: EXTERN int MatStashDestroy_Private(MatStash*);
152: EXTERN int MatStashScatterEnd_Private(MatStash*);
153: EXTERN int MatStashSetInitialSize_Private(MatStash*,int);
154: EXTERN int MatStashGetInfo_Private(MatStash*,int*,int*);
155: EXTERN int MatStashValuesRow_Private(MatStash*,int,int,const int[],const MatScalar[]);
156: EXTERN int MatStashValuesCol_Private(MatStash*,int,int,const int[],const MatScalar[],int);
157: EXTERN int MatStashValuesRowBlocked_Private(MatStash*,int,int,const int[],const MatScalar[],int,int,int);
158: EXTERN int MatStashValuesColBlocked_Private(MatStash*,int,int,const int[],const MatScalar[],int,int,int);
159: EXTERN int MatStashScatterBegin_Private(MatStash*,int*);
160: EXTERN int MatStashScatterGetMesg_Private(MatStash*,int*,int**,int**,MatScalar**,int*);

162: #define FACTOR_LU       1
163: #define FACTOR_CHOLESKY 2

165: typedef struct {
166:   int        dim;
167:   int        dims[4];
168:   int        starts[4];
169:   PetscTruth noc;        /* this is a single component problem, hence user will not set MatStencil.c */
170: } MatStencilInfo;

172: struct _p_Mat {
173:   PETSCHEADER(struct _MatOps)
174:   PetscMap               rmap,cmap;
175:   void                   *data;            /* implementation-specific data */
176:   int                    factor;           /* 0, FACTOR_LU, or FACTOR_CHOLESKY */
177:   PetscReal              lupivotthreshold; /* threshold for pivoting */
178:   PetscTruth             assembled;        /* is the matrix assembled? */
179:   PetscTruth             was_assembled;    /* new values inserted into assembled mat */
180:   int                    num_ass;          /* number of times matrix has been assembled */
181:   PetscTruth             same_nonzero;     /* matrix has same nonzero pattern as previous */
182:   int                    M,N;             /* global numbers of rows, columns */
183:   int                    m,n;             /* local numbers of rows, columns */
184:   MatInfo                info;             /* matrix information */
185:   ISLocalToGlobalMapping mapping;          /* mapping used in MatSetValuesLocal() */
186:   ISLocalToGlobalMapping bmapping;         /* mapping used in MatSetValuesBlockedLocal() */
187:   InsertMode             insertmode;       /* have values been inserted in matrix or added? */
188:   MatStash               stash,bstash;     /* used for assembling off-proc mat emements */
189:   MatNullSpace           nullsp;
190:   PetscTruth             preallocated;
191:   MatStencilInfo         stencil;          /* information for structured grid */
192:   PetscTruth             symmetric,hermitian,structurally_symmetric;
193:   PetscTruth             symmetric_set,hermitian_set,structurally_symmetric_set; /* if true, then corresponding flag is correct*/
194:   PetscTruth             symmetric_eternal;
195:   void                   *spptr;          /* pointer for special library like SuperLU */
196:   void                   *esimat;
197: };

199: #define MatPreallocated(A) {int _e;if (!(A)->preallocated) {_e = MatSetUpPreallocation(A);CHKERRQ(_e);}}
200: extern int MatAXPY_Basic(const PetscScalar*,Mat,Mat,MatStructure);

202: /*
203:     Object for partitioning graphs
204: */

206: typedef struct _MatPartitioningOps *MatPartitioningOps;
207: struct _MatPartitioningOps {
208:   int         (*apply)(MatPartitioning,IS*);
209:   int         (*setfromoptions)(MatPartitioning);
210:   int         (*destroy)(MatPartitioning);
211:   int         (*view)(MatPartitioning,PetscViewer);
212: };

214: struct _p_MatPartitioning {
215:   PETSCHEADER(struct _MatPartitioningOps)
216:   Mat         adj;
217:   int         *vertex_weights;
218:   PetscReal   *part_weights;
219:   int         n;                                 /* number of partitions */
220:   void        *data;
221:   int         setupcalled;
222: };

224: /*
225:     MatFDColoring is used to compute Jacobian matrices efficiently
226:   via coloring. The data structure is explained below in an example.

228:    Color =   0    1     0    2   |   2      3       0 
229:    ---------------------------------------------------
230:             00   01              |          05
231:             10   11              |   14     15               Processor  0
232:                        22    23  |          25
233:                        32    33  | 
234:    ===================================================
235:                                  |   44     45     46
236:             50                   |          55               Processor 1
237:                                  |   64            66
238:    ---------------------------------------------------

240:     ncolors = 4;

242:     ncolumns      = {2,1,1,0}
243:     columns       = {{0,2},{1},{3},{}}
244:     nrows         = {4,2,3,3}
245:     rows          = {{0,1,2,3},{0,1},{1,2,3},{0,1,2}}
246:     columnsforrow = {{0,0,2,2},{1,1},{4,3,3},{5,5,5}}
247:     vscaleforrow  = {{,,,},{,},{,,},{,,}}
248:     vwscale       = {dx(0),dx(1),dx(2),dx(3)}               MPI Vec
249:     vscale        = {dx(0),dx(1),dx(2),dx(3),dx(4),dx(5)}   Seq Vec

251:     ncolumns      = {1,0,1,1}
252:     columns       = {{6},{},{4},{5}}
253:     nrows         = {3,0,2,2}
254:     rows          = {{0,1,2},{},{1,2},{1,2}}
255:     columnsforrow = {{6,0,6},{},{4,4},{5,5}}
256:     vscaleforrow =  {{,,},{},{,},{,}}
257:     vwscale       = {dx(4),dx(5),dx(6)}              MPI Vec
258:     vscale        = {dx(0),dx(4),dx(5),dx(6)}        Seq Vec

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

263: */

265: struct  _p_MatFDColoring{
266:   PETSCHEADER(int)
267:   int        M,N,m;            /* total rows, columns; local rows */
268:   int        rstart;           /* first row owned by local processor */
269:   int        ncolors;          /* number of colors */
270:   int        *ncolumns;        /* number of local columns for a color */
271:   int        **columns;        /* lists the local columns of each color (using global column numbering) */
272:   int        *nrows;           /* number of local rows for each color */
273:   int        **rows;           /* lists the local rows for each color (using the local row numbering) */
274:   int        **columnsforrow;  /* lists the corresponding columns for those rows (using the global column) */
275:   PetscReal  error_rel;        /* square root of relative error in computing function */
276:   PetscReal  umin;             /* minimum allowable u'dx value */
277:   int        freq;             /* frequency at which new Jacobian is computed */
278:   Vec        w1,w2,w3;         /* work vectors used in computing Jacobian */
279:   int        (*f)(void);       /* function that defines Jacobian */
280:   void       *fctx;            /* optional user-defined context for use by the function f */
281:   int        **vscaleforrow;   /* location in vscale for each columnsforrow[] entry */
282:   Vec        vscale;           /* holds FD scaling, i.e. 1/dx for each perturbed column */
283:   PetscTruth usersetsrecompute;/* user determines when Jacobian is recomputed, via MatFDColoringSetRecompute() */
284:   PetscTruth recompute;        /* used with usersetrecompute to determine if Jacobian should be recomputed */
285:   Vec        F;                /* current value of user provided function; can set with MatFDColoringSetF() */
286:   int        currentcolor;     /* color for which function evaluation is being done now */
287: };

289: /*
290:    Null space context for preconditioner/operators
291: */
292: struct _p_MatNullSpace {
293:   PETSCHEADER(int)
294:   int         has_cnst;
295:   int         n;
296:   Vec*        vecs;
297:   Vec         vec;      /* for out of place removals */
298: };

300: #endif