Actual source code: matimpl.h

  1: /* $Id: matimpl.h,v 1.121 2001/04/10 22:35:01 balay Exp $ */

  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:   int       (*setvalues)(Mat,int,int *,int,int *,Scalar *,InsertMode),
 19:             (*getrow)(Mat,int,int *,int **,Scalar **),
 20:             (*restorerow)(Mat,int,int *,int **,Scalar **),
 21:             (*mult)(Mat,Vec,Vec),
 22: /* 4*/      (*multadd)(Mat,Vec,Vec,Vec),
 23:             (*multtranspose)(Mat,Vec,Vec),
 24:             (*multtransposeadd)(Mat,Vec,Vec,Vec),
 25:             (*solve)(Mat,Vec,Vec),
 26:             (*solveadd)(Mat,Vec,Vec,Vec),
 27:             (*solvetranspose)(Mat,Vec,Vec),
 28: /*10*/      (*solvetransposeadd)(Mat,Vec,Vec,Vec),
 29:             (*lufactor)(Mat,IS,IS,MatLUInfo*),
 30:             (*choleskyfactor)(Mat,IS,double),
 31:             (*relax)(Mat,Vec,double,MatSORType,double,int,Vec),
 32:             (*transpose)(Mat,Mat *),
 33: /*15*/      (*getinfo)(Mat,MatInfoType,MatInfo*),
 34:             (*equal)(Mat,Mat,PetscTruth *),
 35:             (*getdiagonal)(Mat,Vec),
 36:             (*diagonalscale)(Mat,Vec,Vec),
 37:             (*norm)(Mat,NormType,double *),
 38: /*20*/      (*assemblybegin)(Mat,MatAssemblyType),
 39:             (*assemblyend)(Mat,MatAssemblyType),
 40:             (*compress)(Mat),
 41:             (*setoption)(Mat,MatOption),
 42:             (*zeroentries)(Mat),
 43: /*25*/      (*zerorows)(Mat,IS,Scalar *),
 44:             (*lufactorsymbolic)(Mat,IS,IS,MatLUInfo*,Mat *),
 45:             (*lufactornumeric)(Mat,Mat *),
 46:             (*choleskyfactorsymbolic)(Mat,IS,double,Mat *),
 47:             (*choleskyfactornumeric)(Mat,Mat *),
 48: /*30*/      (*setuppreallocation)(Mat),
 49:             (*dummy2)(Mat,int *,int *),
 50:             (*getownershiprange)(Mat,int *,int *),
 51:             (*ilufactorsymbolic)(Mat,IS,IS,MatILUInfo*,Mat *),
 52:             (*iccfactorsymbolic)(Mat,IS,double,int,Mat *),
 53: /*35*/      (*getarray)(Mat,Scalar **),
 54:             (*restorearray)(Mat,Scalar **),
 55:             (*duplicate)(Mat,MatDuplicateOption,Mat *),
 56:             (*forwardsolve)(Mat,Vec,Vec),
 57:             (*backwardsolve)(Mat,Vec,Vec),
 58: /*40*/      (*ilufactor)(Mat,IS,IS,MatILUInfo*),
 59:             (*iccfactor)(Mat,IS,double,int),
 60:             (*axpy)(Scalar *,Mat,Mat),
 61:             (*getsubmatrices)(Mat,int,IS *,IS *,MatReuse,Mat **),
 62:             (*increaseoverlap)(Mat,int,IS *,int),
 63: /*45*/      (*getvalues)(Mat,int,int *,int,int *,Scalar *),
 64:             (*copy)(Mat,Mat,MatStructure),
 65:             (*printhelp)(Mat),
 66:             (*scale)(Scalar *,Mat),
 67:             (*shift)(Scalar *,Mat),
 68: /*50*/      (*diagonalset)(Mat,Vec,InsertMode),
 69:             (*iludtfactor)(Mat,MatILUInfo*,IS,IS,Mat *),
 70:             (*getblocksize)(Mat,int *),
 71:             (*getrowij)(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *),
 72:             (*restorerowij)(Mat,int,PetscTruth,int *,int **,int **,PetscTruth *),
 73: /*55*/      (*getcolumnij)(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *),
 74:             (*restorecolumnij)(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *),
 75:             (*fdcoloringcreate)(Mat,ISColoring,MatFDColoring),
 76:             (*coloringpatch)(Mat,int,int,int *,ISColoring*),
 77:             (*setunfactored)(Mat),
 78: /*60*/      (*permute)(Mat,IS,IS,Mat*),
 79:             (*setvaluesblocked)(Mat,int,int *,int,int *,Scalar *,InsertMode),
 80:             (*getsubmatrix)(Mat,IS,IS,int,MatReuse,Mat*),
 81:             (*destroy)(Mat),
 82:             (*view)(Mat,PetscViewer),
 83:             (*getmaps)(Mat,Map*,Map*),
 84:             (*usescaledform)(Mat,PetscTruth),
 85:             (*scalesystem)(Mat,Vec,Vec),
 86:             (*unscalesystem)(Mat,Vec,Vec),
 87:             (*setlocaltoglobalmapping)(Mat,ISLocalToGlobalMapping),
 88:             (*setvalueslocal)(Mat,int,int *,int,int *,Scalar *,InsertMode),
 89:             (*zerorowslocal)(Mat,IS,Scalar *),
 90:             (*getrowmax)(Mat,Vec),
 91:             (*convert)(Mat,MatType,Mat*);
 92: };

 94: /*
 95:    Utility private matrix routines
 96: */
 97: EXTERN int MatConvert_Basic(Mat,MatType,Mat*);
 98: EXTERN int MatCopy_Basic(Mat,Mat,MatStructure);
 99: EXTERN int MatView_Private(Mat);
100: EXTERN int MatGetMaps_Petsc(Mat,Map *,Map *);
101: EXTERN int MatHeaderCopy(Mat,Mat);

103: /* 
104:   The stash is used to temporarily store inserted matrix values that 
105:   belong to another processor. During the assembly phase the stashed 
106:   values are moved to the correct processor and 
107: */

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

133: EXTERN int MatStashCreate_Private(MPI_Comm,int,MatStash*);
134: EXTERN int MatStashDestroy_Private(MatStash*);
135: EXTERN int MatStashScatterEnd_Private(MatStash*);
136: EXTERN int MatStashSetInitialSize_Private(MatStash*,int);
137: EXTERN int MatStashGetInfo_Private(MatStash*,int*,int*);
138: EXTERN int MatStashValuesRow_Private(MatStash*,int,int,int*,MatScalar*);
139: EXTERN int MatStashValuesCol_Private(MatStash*,int,int,int*,MatScalar*,int);
140: EXTERN int MatStashValuesRowBlocked_Private(MatStash*,int,int,int*,MatScalar*,int,int,int);
141: EXTERN int MatStashValuesColBlocked_Private(MatStash*,int,int,int*,MatScalar*,int,int,int);
142: EXTERN int MatStashScatterBegin_Private(MatStash*,int*);
143: EXTERN int MatStashScatterGetMesg_Private(MatStash*,int*,int**,int**,MatScalar**,int*);

145: #define FACTOR_LU       1
146: #define FACTOR_CHOLESKY 2

148: typedef struct {
149:   int        dim;
150:   int        dims[4];
151:   int        starts[4];
152:   PetscTruth noc;        /* this is a single component problem, hence user will not set MatStencil.c */
153: } MatStencilInfo;

155: struct _p_Mat {
156:   PETSCHEADER(struct _MatOps)
157:   Map                    rmap,cmap;
158:   void                   *data;            /* implementation-specific data */
159:   int                    factor;           /* 0, FACTOR_LU, or FACTOR_CHOLESKY */
160:   double                 lupivotthreshold; /* threshold for pivoting */
161:   PetscTruth             assembled;        /* is the matrix assembled? */
162:   PetscTruth             was_assembled;    /* new values inserted into assembled mat */
163:   int                    num_ass;          /* number of times matrix has been assembled */
164:   PetscTruth             same_nonzero;     /* matrix has same nonzero pattern as previous */
165:   int                    M,N;             /* global numbers of rows, columns */
166:   int                    m,n;             /* local numbers of rows, columns */
167:   MatInfo                info;             /* matrix information */
168:   ISLocalToGlobalMapping mapping;          /* mapping used in MatSetValuesLocal() */
169:   ISLocalToGlobalMapping bmapping;         /* mapping used in MatSetValuesBlockedLocal() */
170:   InsertMode             insertmode;       /* have values been inserted in matrix or added? */
171:   MatStash               stash,bstash;     /* used for assembling off-proc mat emements */
172:   MatNullSpace           nullsp;
173:   PetscTruth             preallocated;
174:   MatStencilInfo         stencil;          /* information for structured grid */
175:   PetscTruth             symmetric,structurally_symmetric;
176: };

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

180: /*
181:     Object for partitioning graphs
182: */

184: typedef struct _MatPartitioningOps *MatPartitioningOps;
185: struct _MatPartitioningOps {
186:   int         (*apply)(MatPartitioning,IS*);
187:   int         (*setfromoptions)(MatPartitioning);
188:   int         (*destroy)(MatPartitioning);
189:   int         (*view)(MatPartitioning,PetscViewer);
190: };

192: struct _p_MatPartitioning {
193:   PETSCHEADER(struct _MatPartitioningOps)
194:   Mat         adj;
195:   int         *vertex_weights;
196:   int         n;                                 /* number of partitions */
197:   void        *data;
198:   int         setupcalled;
199: };

201: /*
202:     MatFDColoring is used to compute Jacobian matrices efficiently
203:   via coloring. The data structure is explained below in an example.

205:    Color =   0    1     0    2   |   2      3       0 
206:    ---------------------------------------------------
207:             00   01              |          05
208:             10   11              |   14     15               Processor  0
209:                        22    23  |          25
210:                        32    33  | 
211:    ===================================================
212:                                  |   44     45     46
213:             50                   |          55               Processor 1
214:                                  |   64            66
215:    ---------------------------------------------------

217:     ncolors = 4;

219:     ncolumns      = {2,1,1,0}
220:     columns       = {{0,2},{1},{3},{}}
221:     nrows         = {4,2,3,3}
222:     rows          = {{0,1,2,3},{0,1},{1,2,3},{0,1,2}}
223:     columnsforrow = {{0,0,2,2},{1,1},{4,3,3},{5,5,5}}
224:     vscaleforrow  = {{,,,},{,},{,,},{,,}}
225:     vwscale       = {dx(0),dx(1),dx(2),dx(3)}               MPI Vec
226:     vscale        = {dx(0),dx(1),dx(2),dx(3),dx(4),dx(5)}   Seq Vec

228:     ncolumns      = {1,0,1,1}
229:     columns       = {{6},{},{4},{5}}
230:     nrows         = {3,0,2,2}
231:     rows          = {{0,1,2},{},{1,2},{1,2}}
232:     columnsforrow = {{6,0,6},{},{4,4},{5,5}}
233:     vscaleforrow =  {{,,},{},{,},{,}}
234:     vwscale       = {dx(4),dx(5),dx(6)}              MPI Vec
235:     vscale        = {dx(0),dx(4),dx(5),dx(6)}        Seq Vec

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

240: */

242: struct  _p_MatFDColoring{
243:   PETSCHEADER(int)
244:   int        M,N,m;            /* total rows, columns; local rows */
245:   int        rstart;           /* first row owned by local processor */
246:   int        ncolors;          /* number of colors */
247:   int        *ncolumns;        /* number of local columns for a color */
248:   int        **columns;        /* lists the local columns of each color (using global column numbering) */
249:   int        *nrows;           /* number of local rows for each color */
250:   int        **rows;           /* lists the local rows for each color (using the local row numbering) */
251:   int        **columnsforrow;  /* lists the corresponding columns for those rows (using the global column) */
252:   double     error_rel;        /* square root of relative error in computing function */
253:   double     umin;             /* minimum allowable u'dx value */
254:   int        freq;             /* frequency at which new Jacobian is computed */
255:   Vec        w1,w2,w3;         /* work vectors used in computing Jacobian */
256:   int        (*f)(void);       /* function that defines Jacobian */
257:   void       *fctx;            /* optional user-defined context for use by the function f */
258:   int        **vscaleforrow;   /* location in vscale for each columnsforrow[] entry */
259:   Vec        vscale;           /* holds FD scaling, i.e. 1/dx for each perturbed column */
260:   PetscTruth usersetsrecompute;/* user determines when Jacobian is recomputed, via MatFDColoringSetRecompute() */
261:   PetscTruth recompute;        /* used with usersetrecompute to determine if Jacobian should be recomputed */
262: };

264: /*
265:    Null space context for preconditioner/operators
266: */
267: struct _p_MatNullSpace {
268:   PETSCHEADER(int)
269:   int         has_cnst;
270:   int         n;
271:   Vec*        vecs;
272:   Vec         vec;      /* for out of place removals */
273: };


276: #endif