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,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*/      (*serialize)(MPI_Comm, Mat *, PetscViewer, PetscTruth),
100:             (*permutesparsify)(Mat, int, double, double, IS, IS, Mat *),
101:             (*mults)(Mat, Vecs, Vecs),
102:             (*solves)(Mat, Vecs, Vecs),
103:             (*getinertia)(Mat,int*,int*,int*),
104: /*85*/      (*load)(PetscViewer,MatType,Mat*);
105: };

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

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

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

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

159: #define FACTOR_LU       1
160: #define FACTOR_CHOLESKY 2

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

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

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

197: /*
198:     Object for partitioning graphs
199: */

201: typedef struct _MatPartitioningOps *MatPartitioningOps;
202: struct _MatPartitioningOps {
203:   int         (*apply)(MatPartitioning,IS*);
204:   int         (*setfromoptions)(MatPartitioning);
205:   int         (*destroy)(MatPartitioning);
206:   int         (*view)(MatPartitioning,PetscViewer);
207: };

209: struct _p_MatPartitioning {
210:   PETSCHEADER(struct _MatPartitioningOps)
211:   Mat         adj;
212:   int         *vertex_weights;
213:   PetscReal   *part_weights;
214:   int         n;                                 /* number of partitions */
215:   void        *data;
216:   int         setupcalled;
217: };

219: /*
220:     MatFDColoring is used to compute Jacobian matrices efficiently
221:   via coloring. The data structure is explained below in an example.

223:    Color =   0    1     0    2   |   2      3       0 
224:    ---------------------------------------------------
225:             00   01              |          05
226:             10   11              |   14     15               Processor  0
227:                        22    23  |          25
228:                        32    33  | 
229:    ===================================================
230:                                  |   44     45     46
231:             50                   |          55               Processor 1
232:                                  |   64            66
233:    ---------------------------------------------------

235:     ncolors = 4;

237:     ncolumns      = {2,1,1,0}
238:     columns       = {{0,2},{1},{3},{}}
239:     nrows         = {4,2,3,3}
240:     rows          = {{0,1,2,3},{0,1},{1,2,3},{0,1,2}}
241:     columnsforrow = {{0,0,2,2},{1,1},{4,3,3},{5,5,5}}
242:     vscaleforrow  = {{,,,},{,},{,,},{,,}}
243:     vwscale       = {dx(0),dx(1),dx(2),dx(3)}               MPI Vec
244:     vscale        = {dx(0),dx(1),dx(2),dx(3),dx(4),dx(5)}   Seq Vec

246:     ncolumns      = {1,0,1,1}
247:     columns       = {{6},{},{4},{5}}
248:     nrows         = {3,0,2,2}
249:     rows          = {{0,1,2},{},{1,2},{1,2}}
250:     columnsforrow = {{6,0,6},{},{4,4},{5,5}}
251:     vscaleforrow =  {{,,},{},{,},{,}}
252:     vwscale       = {dx(4),dx(5),dx(6)}              MPI Vec
253:     vscale        = {dx(0),dx(4),dx(5),dx(6)}        Seq Vec

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

258: */

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

284: /*
285:    Null space context for preconditioner/operators
286: */
287: struct _p_MatNullSpace {
288:   PETSCHEADER(int)
289:   int         has_cnst;
290:   int         n;
291:   Vec*        vecs;
292:   Vec         vec;      /* for out of place removals */
293: };


296: #endif