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,int *,int,int *,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,MatLUInfo*),
 31:             (*choleskyfactor)(Mat,IS,PetscReal),
 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,PetscScalar *),
 45:             (*lufactorsymbolic)(Mat,IS,IS,MatLUInfo*,Mat *),
 46:             (*lufactornumeric)(Mat,Mat *),
 47:             (*choleskyfactorsymbolic)(Mat,IS,PetscReal,Mat *),
 48:             (*choleskyfactornumeric)(Mat,Mat *),
 49: /*30*/      (*setuppreallocation)(Mat),
 50:             (*ilufactorsymbolic)(Mat,IS,IS,MatILUInfo*,Mat *),
 51:             (*iccfactorsymbolic)(Mat,IS,PetscReal,int,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,MatILUInfo*),
 58:             (*iccfactor)(Mat,IS,PetscReal,int),
 59: /*40*/      (*axpy)(PetscScalar *,Mat,Mat,MatStructure),
 60:             (*getsubmatrices)(Mat,int,IS *,IS *,MatReuse,Mat **),
 61:             (*increaseoverlap)(Mat,int,IS *,int),
 62:             (*getvalues)(Mat,int,int *,int,int *,PetscScalar *),
 63:             (*copy)(Mat,Mat,MatStructure),
 64: /*45*/      (*printhelp)(Mat),
 65:             (*scale)(PetscScalar *,Mat),
 66:             (*shift)(PetscScalar *,Mat),
 67:             (*diagonalset)(Mat,Vec,InsertMode),
 68:             (*iludtfactor)(Mat,MatILUInfo*,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,int *,ISColoring*),
 76:             (*setunfactored)(Mat),
 77:             (*permute)(Mat,IS,IS,Mat*),
 78:             (*setvaluesblocked)(Mat,int,int *,int,int *,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,int *,int,int *,PetscScalar *,InsertMode),
 88:             (*zerorowslocal)(Mat,IS,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:             (*serialize)(MPI_Comm, Mat *, PetscViewer, PetscTruth),
100: /*80*/      (*permutesparsify)(Mat, int, double, double, IS, IS, Mat *),
101:             (*multmultiple)(Mat, Mat, Mat),
102:             (*solvemultiple)(Mat, Mat, Mat);
103: };

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

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

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

144: EXTERN int MatStashCreate_Private(MPI_Comm,int,MatStash*);
145: EXTERN int MatStashDestroy_Private(MatStash*);
146: EXTERN int MatStashScatterEnd_Private(MatStash*);
147: EXTERN int MatStashSetInitialSize_Private(MatStash*,int);
148: EXTERN int MatStashGetInfo_Private(MatStash*,int*,int*);
149: EXTERN int MatStashValuesRow_Private(MatStash*,int,int,int*,MatScalar*);
150: EXTERN int MatStashValuesCol_Private(MatStash*,int,int,int*,MatScalar*,int);
151: EXTERN int MatStashValuesRowBlocked_Private(MatStash*,int,int,int*,MatScalar*,int,int,int);
152: EXTERN int MatStashValuesColBlocked_Private(MatStash*,int,int,int*,MatScalar*,int,int,int);
153: EXTERN int MatStashScatterBegin_Private(MatStash*,int*);
154: EXTERN int MatStashScatterGetMesg_Private(MatStash*,int*,int**,int**,MatScalar**,int*);

156: #define FACTOR_LU       1
157: #define FACTOR_CHOLESKY 2

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

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

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

194: /*
195:     Object for partitioning graphs
196: */

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

206: struct _p_MatPartitioning {
207:   PETSCHEADER(struct _MatPartitioningOps)
208:   Mat         adj;
209:   int         *vertex_weights;
210:   int         n;                                 /* number of partitions */
211:   void        *data;
212:   int         setupcalled;
213: };

215: /*
216:     MatFDColoring is used to compute Jacobian matrices efficiently
217:   via coloring. The data structure is explained below in an example.

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

231:     ncolors = 4;

233:     ncolumns      = {2,1,1,0}
234:     columns       = {{0,2},{1},{3},{}}
235:     nrows         = {4,2,3,3}
236:     rows          = {{0,1,2,3},{0,1},{1,2,3},{0,1,2}}
237:     columnsforrow = {{0,0,2,2},{1,1},{4,3,3},{5,5,5}}
238:     vscaleforrow  = {{,,,},{,},{,,},{,,}}
239:     vwscale       = {dx(0),dx(1),dx(2),dx(3)}               MPI Vec
240:     vscale        = {dx(0),dx(1),dx(2),dx(3),dx(4),dx(5)}   Seq Vec

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

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

254: */

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

279: /*
280:    Null space context for preconditioner/operators
281: */
282: struct _p_MatNullSpace {
283:   PETSCHEADER(int)
284:   int         has_cnst;
285:   int         n;
286:   Vec*        vecs;
287:   Vec         vec;      /* for out of place removals */
288: };


291: #endif