Actual source code: matrix.c

  1: /*$Id: matrix.c,v 1.414 2001/09/28 18:57:28 balay Exp $*/

  3: /*
  4:    This is where the abstract matrix operations are defined
  5: */

 7:  #include src/mat/matimpl.h
 8:  #include src/vec/vecimpl.h

 10: /* Logging support */
 11: int MAT_COOKIE;
 12: int MATSNESMFCTX_COOKIE;
 13: int MAT_Mult, MAT_MultMatrixFree, MAT_Mults, MAT_MultConstrained, MAT_MultAdd, MAT_MultTranspose;
 14: int MAT_MultTransposeConstrained, MAT_MultTransposeAdd, MAT_Solve, MAT_Solves, MAT_SolveAdd, MAT_SolveTranspose;
 15: int MAT_SolveTransposeAdd, MAT_Relax, MAT_ForwardSolve, MAT_BackwardSolve, MAT_LUFactor, MAT_LUFactorSymbolic;
 16: int MAT_LUFactorNumeric, MAT_CholeskyFactor, MAT_CholeskyFactorSymbolic, MAT_CholeskyFactorNumeric, MAT_ILUFactor;
 17: int MAT_ILUFactorSymbolic, MAT_ICCFactorSymbolic, MAT_Copy, MAT_Convert, MAT_Scale, MAT_AssemblyBegin;
 18: int MAT_AssemblyEnd, MAT_SetValues, MAT_GetValues, MAT_GetRow, MAT_GetSubMatrices, MAT_GetColoring, MAT_GetOrdering;
 19: int MAT_IncreaseOverlap, MAT_Partitioning, MAT_ZeroEntries, MAT_Load, MAT_View, MAT_AXPY, MAT_FDColoringCreate;
 20: int MAT_FDColoringApply,MAT_Transpose,MAT_FDColoringFunction;

 24: /*@C
 25:    MatGetRow - Gets a row of a matrix.  You MUST call MatRestoreRow()
 26:    for each row that you get to ensure that your application does
 27:    not bleed memory.

 29:    Not Collective

 31:    Input Parameters:
 32: +  mat - the matrix
 33: -  row - the row to get

 35:    Output Parameters:
 36: +  ncols -  if not NULL, the number of nonzeros in the row
 37: .  cols - if not NULL, the column numbers
 38: -  vals - if not NULL, the values

 40:    Notes:
 41:    This routine is provided for people who need to have direct access
 42:    to the structure of a matrix.  We hope that we provide enough
 43:    high-level matrix routines that few users will need it. 

 45:    MatGetRow() always returns 0-based column indices, regardless of
 46:    whether the internal representation is 0-based (default) or 1-based.

 48:    For better efficiency, set cols and/or vals to PETSC_NULL if you do
 49:    not wish to extract these quantities.

 51:    The user can only examine the values extracted with MatGetRow();
 52:    the values cannot be altered.  To change the matrix entries, one
 53:    must use MatSetValues().

 55:    You can only have one call to MatGetRow() outstanding for a particular
 56:    matrix at a time, per processor. MatGetRow() can only obtained rows
 57:    associated with the given processor, it cannot get rows from the 
 58:    other processors; for that we suggest using MatGetSubMatrices(), then
 59:    MatGetRow() on the submatrix. The row indix passed to MatGetRows() 
 60:    is in the global number of rows.

 62:    Fortran Notes:
 63:    The calling sequence from Fortran is 
 64: .vb
 65:    MatGetRow(matrix,row,ncols,cols,values,ierr)
 66:          Mat     matrix (input)
 67:          integer row    (input)
 68:          integer ncols  (output)
 69:          integer cols(maxcols) (output)
 70:          double precision (or double complex) values(maxcols) output
 71: .ve
 72:    where maxcols >= maximum nonzeros in any row of the matrix.

 74:    Caution:
 75:    Do not try to change the contents of the output arrays (cols and vals).
 76:    In some cases, this may corrupt the matrix.

 78:    Level: advanced

 80:    Concepts: matrices^row access

 82: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
 83: @*/
 84: int MatGetRow(Mat mat,int row,int *ncols,int *cols[],PetscScalar *vals[])
 85: {
 86:   int   incols,ierr;

 91:   MatPreallocated(mat);
 92:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
 93:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
 94:   if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
 95:   PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
 96:   (*mat->ops->getrow)(mat,row,&incols,cols,vals);
 97:   if (ncols) *ncols = incols;
 98:   PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
 99:   return(0);
100: }

104: /*@C  
105:    MatRestoreRow - Frees any temporary space allocated by MatGetRow().

107:    Not Collective

109:    Input Parameters:
110: +  mat - the matrix
111: .  row - the row to get
112: .  ncols, cols - the number of nonzeros and their columns
113: -  vals - if nonzero the column values

115:    Notes: 
116:    This routine should be called after you have finished examining the entries.

118:    Fortran Notes:
119:    The calling sequence from Fortran is 
120: .vb
121:    MatRestoreRow(matrix,row,ncols,cols,values,ierr)
122:       Mat     matrix (input)
123:       integer row    (input)
124:       integer ncols  (output)
125:       integer cols(maxcols) (output)
126:       double precision (or double complex) values(maxcols) output
127: .ve
128:    Where maxcols >= maximum nonzeros in any row of the matrix. 

130:    In Fortran MatRestoreRow() MUST be called after MatGetRow()
131:    before another call to MatGetRow() can be made.

133:    Level: advanced

135: .seealso:  MatGetRow()
136: @*/
137: int MatRestoreRow(Mat mat,int row,int *ncols,int *cols[],PetscScalar *vals[])
138: {

144:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
145:   if (!mat->ops->restorerow) return(0);
146:   (*mat->ops->restorerow)(mat,row,ncols,cols,vals);
147:   return(0);
148: }

152: /*@C
153:    MatView - Visualizes a matrix object.

155:    Collective on Mat

157:    Input Parameters:
158: +  mat - the matrix
159: -  viewer - visualization context

161:   Notes:
162:   The available visualization contexts include
163: +    PETSC_VIEWER_STDOUT_SELF - standard output (default)
164: .    PETSC_VIEWER_STDOUT_WORLD - synchronized standard
165:         output where only the first processor opens
166:         the file.  All other processors send their 
167:         data to the first processor to print. 
168: -     PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure

170:    The user can open alternative visualization contexts with
171: +    PetscViewerASCIIOpen() - Outputs matrix to a specified file
172: .    PetscViewerBinaryOpen() - Outputs matrix in binary to a
173:          specified file; corresponding input uses MatLoad()
174: .    PetscViewerDrawOpen() - Outputs nonzero matrix structure to 
175:          an X window display
176: -    PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
177:          Currently only the sequential dense and AIJ
178:          matrix types support the Socket viewer.

180:    The user can call PetscViewerSetFormat() to specify the output
181:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
182:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
183: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
184: .    PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
185: .    PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
186: .    PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 
187:          format common among all matrix types
188: .    PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 
189:          format (which is in many cases the same as the default)
190: .    PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
191:          size and structure (not the matrix entries)
192: .    PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about
193:          the matrix structure

195:    Options Database Keys:
196: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
197: .  -mat_view_info_detailed - Prints more detailed info
198: .  -mat_view - Prints matrix in ASCII format
199: .  -mat_view_matlab - Prints matrix in Matlab format
200: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
201: .  -display <name> - Sets display name (default is host)
202: .  -draw_pause <sec> - Sets number of seconds to pause after display
203: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
204: .  -viewer_socket_machine <machine>
205: .  -viewer_socket_port <port>
206: .  -mat_view_binary - save matrix to file in binary format
207: -  -viewer_binary_filename <name>
208:    Level: beginner

210:    Concepts: matrices^viewing
211:    Concepts: matrices^plotting
212:    Concepts: matrices^printing

214: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 
215:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
216: @*/
217: int MatView(Mat mat,PetscViewer viewer)
218: {
219:   int               ierr,rows,cols;
220:   PetscTruth        isascii;
221:   char              *cstr;
222:   PetscViewerFormat format;

227:   MatPreallocated(mat);
228:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm);
231:   if (!mat->assembled) SETERRQ(1,"Must call MatAssemblyBegin/End() before viewing matrix");

233:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);
234:   if (isascii) {
235:     PetscViewerGetFormat(viewer,&format);
236:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
237:       if (mat->prefix) {
238:         PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);
239:       } else {
240:         PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");
241:       }
242:       PetscViewerASCIIPushTab(viewer);
243:       MatGetType(mat,&cstr);
244:       MatGetSize(mat,&rows,&cols);
245:       PetscViewerASCIIPrintf(viewer,"type=%s, rows=%d, cols=%d\n",cstr,rows,cols);
246:       if (mat->ops->getinfo) {
247:         MatInfo info;
248:         MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
249:         PetscViewerASCIIPrintf(viewer,"total: nonzeros=%d, allocated nonzeros=%d\n",
250:                           (int)info.nz_used,(int)info.nz_allocated);
251:       }
252:     }
253:   }
254:   if (mat->ops->view) {
255:     PetscViewerASCIIPushTab(viewer);
256:     (*mat->ops->view)(mat,viewer);
257:     PetscViewerASCIIPopTab(viewer);
258:   } else if (!isascii) {
259:     SETERRQ1(1,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
260:   }
261:   if (isascii) {
262:     PetscViewerGetFormat(viewer,&format);
263:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
264:       PetscViewerASCIIPopTab(viewer);
265:     }
266:   }
267:   return(0);
268: }

272: /*@C
273:    MatScaleSystem - Scale a vector solution and right hand side to 
274:    match the scaling of a scaled matrix.
275:   
276:    Collective on Mat

278:    Input Parameter:
279: +  mat - the matrix
280: .  x - solution vector (or PETSC_NULL)
281: -  b - right hand side vector (or PETSC_NULL)


284:    Notes: 
285:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
286:    internally scaled, so this does nothing. For MPIROWBS it
287:    permutes and diagonally scales.

289:    The SLES methods automatically call this routine when required
290:    (via PCPreSolve()) so it is rarely used directly.

292:    Level: Developer            

294:    Concepts: matrices^scaling

296: .seealso: MatUseScaledForm(), MatUnScaleSystem()
297: @*/
298: int MatScaleSystem(Mat mat,Vec x,Vec b)
299: {

305:   MatPreallocated(mat);

309:   if (mat->ops->scalesystem) {
310:     (*mat->ops->scalesystem)(mat,x,b);
311:   }
312:   return(0);
313: }

317: /*@C
318:    MatUnScaleSystem - Unscales a vector solution and right hand side to 
319:    match the original scaling of a scaled matrix.
320:   
321:    Collective on Mat

323:    Input Parameter:
324: +  mat - the matrix
325: .  x - solution vector (or PETSC_NULL)
326: -  b - right hand side vector (or PETSC_NULL)


329:    Notes: 
330:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
331:    internally scaled, so this does nothing. For MPIROWBS it
332:    permutes and diagonally scales.

334:    The SLES methods automatically call this routine when required
335:    (via PCPreSolve()) so it is rarely used directly.

337:    Level: Developer            

339: .seealso: MatUseScaledForm(), MatScaleSystem()
340: @*/
341: int MatUnScaleSystem(Mat mat,Vec x,Vec b)
342: {

348:   MatPreallocated(mat);
351:   if (mat->ops->unscalesystem) {
352:     (*mat->ops->unscalesystem)(mat,x,b);
353:   }
354:   return(0);
355: }

359: /*@C
360:    MatUseScaledForm - For matrix storage formats that scale the 
361:    matrix (for example MPIRowBS matrices are diagonally scaled on
362:    assembly) indicates matrix operations (MatMult() etc) are 
363:    applied using the scaled matrix.
364:   
365:    Collective on Mat

367:    Input Parameter:
368: +  mat - the matrix
369: -  scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 
370:             applying the original matrix

372:    Notes: 
373:    For scaled matrix formats, applying the original, unscaled matrix
374:    will be slightly more expensive

376:    Level: Developer            

378: .seealso: MatScaleSystem(), MatUnScaleSystem()
379: @*/
380: int MatUseScaledForm(Mat mat,PetscTruth scaled)
381: {

387:   MatPreallocated(mat);
388:   if (mat->ops->usescaledform) {
389:     (*mat->ops->usescaledform)(mat,scaled);
390:   }
391:   return(0);
392: }

396: /*@C
397:    MatDestroy - Frees space taken by a matrix.
398:   
399:    Collective on Mat

401:    Input Parameter:
402: .  A - the matrix

404:    Level: beginner

406: @*/
407: int MatDestroy(Mat A)
408: {

414:   MatPreallocated(A);
415:   if (--A->refct > 0) return(0);

417:   /* if memory was published with AMS then destroy it */
418:   PetscObjectDepublish(A);
419:   if (A->mapping) {
420:     ISLocalToGlobalMappingDestroy(A->mapping);
421:   }
422:   if (A->bmapping) {
423:     ISLocalToGlobalMappingDestroy(A->bmapping);
424:   }
425:   if (A->rmap) {
426:     PetscMapDestroy(A->rmap);
427:   }
428:   if (A->cmap) {
429:     PetscMapDestroy(A->cmap);
430:   }

432:   (*A->ops->destroy)(A);
433:   PetscLogObjectDestroy(A);
434:   PetscHeaderDestroy(A);
435:   return(0);
436: }

440: /*@
441:    MatValid - Checks whether a matrix object is valid.

443:    Collective on Mat

445:    Input Parameter:
446: .  m - the matrix to check 

448:    Output Parameter:
449:    flg - flag indicating matrix status, either
450:    PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.

452:    Level: developer

454:    Concepts: matrices^validity
455: @*/
456: int MatValid(Mat m,PetscTruth *flg)
457: {
460:   if (!m)                           *flg = PETSC_FALSE;
461:   else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
462:   else                              *flg = PETSC_TRUE;
463:   return(0);
464: }

468: /*@ 
469:    MatSetValues - Inserts or adds a block of values into a matrix.
470:    These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 
471:    MUST be called after all calls to MatSetValues() have been completed.

473:    Not Collective

475:    Input Parameters:
476: +  mat - the matrix
477: .  v - a logically two-dimensional array of values
478: .  m, idxm - the number of rows and their global indices 
479: .  n, idxn - the number of columns and their global indices
480: -  addv - either ADD_VALUES or INSERT_VALUES, where
481:    ADD_VALUES adds values to any existing entries, and
482:    INSERT_VALUES replaces existing entries with new values

484:    Notes:
485:    By default the values, v, are row-oriented and unsorted.
486:    See MatSetOption() for other options.

488:    Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 
489:    options cannot be mixed without intervening calls to the assembly
490:    routines.

492:    MatSetValues() uses 0-based row and column numbers in Fortran 
493:    as well as in C.

495:    Negative indices may be passed in idxm and idxn, these rows and columns are 
496:    simply ignored. This allows easily inserting element stiffness matrices
497:    with homogeneous Dirchlet boundary conditions that you don't want represented
498:    in the matrix.

500:    Efficiency Alert:
501:    The routine MatSetValuesBlocked() may offer much better efficiency
502:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

504:    Level: beginner

506:    Concepts: matrices^putting entries in

508: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
509: @*/
510: int MatSetValues(Mat mat,int m,const int idxm[],int n,const int idxn[],const PetscScalar v[],InsertMode addv)
511: {

515:   if (!m || !n) return(0); /* no values to insert */
518:   MatPreallocated(mat);
522:   if (mat->insertmode == NOT_SET_VALUES) {
523:     mat->insertmode = addv;
524:   }
525: #if defined(PETSC_USE_BOPT_g)
526:   else if (mat->insertmode != addv) {
527:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
528:   }
529:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
530: #endif

532:   if (mat->assembled) {
533:     mat->was_assembled = PETSC_TRUE;
534:     mat->assembled     = PETSC_FALSE;
535:   }
536:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
537:   if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
538:   (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
539:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
540:   return(0);
541: }

545: /*@C 
546:    MatSetValuesStencil - Inserts or adds a block of values into a matrix.
547:      Using structured grid indexing

549:    Not Collective

551:    Input Parameters:
552: +  mat - the matrix
553: .  v - a logically two-dimensional array of values
554: .  m - number of rows being entered
555: .  idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
556: .  n - number of columns being entered
557: .  idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 
558: -  addv - either ADD_VALUES or INSERT_VALUES, where
559:    ADD_VALUES adds values to any existing entries, and
560:    INSERT_VALUES replaces existing entries with new values

562:    Notes:
563:    By default the values, v, are row-oriented and unsorted.
564:    See MatSetOption() for other options.

566:    Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 
567:    options cannot be mixed without intervening calls to the assembly
568:    routines.

570:    The grid coordinates are across the entire grid, not just the local portion

572:    MatSetValuesStencil() uses 0-based row and column numbers in Fortran 
573:    as well as in C.

575:    For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine

577:    In order to use this routine you must either obtain the matrix with DAGetMatrix()
578:    or call MatSetLocalToGlobalMapping() and MatSetStencil() first.

580:    The columns and rows in the stencil passed in MUST be contained within the 
581:    ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example,
582:    if you create a DA with an overlap of one grid level and on a particular process its first
583:    local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the
584:    first i index you can use in your column and row indices in MatSetStencil() is 5.

586:    In Fortran idxm and idxn should be declared as
587: $     MatStencil idxm(4,m),idxn(4,n)
588:    and the values inserted using
589: $    idxm(MatStencil_i,1) = i
590: $    idxm(MatStencil_j,1) = j
591: $    idxm(MatStencil_k,1) = k
592: $    idxm(MatStencil_c,1) = c
593:    etc

595:    Negative indices may be passed in idxm and idxn, these rows and columns are 
596:    simply ignored. This allows easily inserting element stiffness matrices
597:    with homogeneous Dirchlet boundary conditions that you don't want represented
598:    in the matrix.

600:    Inspired by the structured grid interface to the HYPRE package
601:    (http://www.llnl.gov/CASC/hypre)

603:    Efficiency Alert:
604:    The routine MatSetValuesBlockedStencil() may offer much better efficiency
605:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

607:    Level: beginner

609:    Concepts: matrices^putting entries in

611: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
612:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray()
613: @*/
614: int MatSetValuesStencil(Mat mat,int m,const MatStencil idxm[],int n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
615: {
616:   int j,i,ierr,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
617:   int *starts = mat->stencil.starts,*dxm = (int*)idxm,*dxn = (int*)idxn,sdim = dim - (1 - (int)mat->stencil.noc);

620:   if (!m || !n) return(0); /* no values to insert */

627:   if (m > 128) SETERRQ1(1,"Can only set 128 rows at a time; trying to set %d",m);
628:   if (n > 128) SETERRQ1(1,"Can only set 256 columns at a time; trying to set %d",n);

630:   for (i=0; i<m; i++) {
631:     for (j=0; j<3-sdim; j++) dxm++;
632:     tmp = *dxm++ - starts[0];
633:     for (j=0; j<dim-1; j++) {
634:       tmp = tmp*dims[j] + *dxm++ - starts[j+1];
635:     }
636:     if (mat->stencil.noc) dxm++;
637:     jdxm[i] = tmp;
638:   }
639:   for (i=0; i<n; i++) {
640:     for (j=0; j<3-sdim; j++) dxn++;
641:     tmp = *dxn++ - starts[0];
642:     for (j=0; j<dim-1; j++) {
643:       tmp = tmp*dims[j] + *dxn++ - starts[j+1];
644:     }
645:     if (mat->stencil.noc) dxn++;
646:     jdxn[i] = tmp;
647:   }
648:   MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
649:   return(0);
650: }

654: /*@ 
655:    MatSetStencil - Sets the grid information for setting values into a matrix via
656:         MatSetValuesStencil()

658:    Not Collective

660:    Input Parameters:
661: +  mat - the matrix
662: .  dim - dimension of the grid 1, 2, or 3
663: .  dims - number of grid points in x, y, and z direction, including ghost points on your processor
664: .  starts - starting point of ghost nodes on your processor in x, y, and z direction 
665: -  dof - number of degrees of freedom per node


668:    Inspired by the structured grid interface to the HYPRE package
669:    (www.llnl.gov/CASC/hyper)

671:    For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the
672:    user.
673:    
674:    Level: beginner

676:    Concepts: matrices^putting entries in

678: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
679:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
680: @*/
681: int MatSetStencil(Mat mat,int dim,const int dims[],const int starts[],int dof)
682: {
683:   int i;


690:   mat->stencil.dim = dim + (dof > 1);
691:   for (i=0; i<dim; i++) {
692:     mat->stencil.dims[i]   = dims[dim-i-1];      /* copy the values in backwards */
693:     mat->stencil.starts[i] = starts[dim-i-1];
694:   }
695:   mat->stencil.dims[dim]   = dof;
696:   mat->stencil.starts[dim] = 0;
697:   mat->stencil.noc         = (PetscTruth)(dof == 1);
698:   return(0);
699: }

703: /*@ 
704:    MatSetValuesBlocked - Inserts or adds a block of values into a matrix.

706:    Not Collective

708:    Input Parameters:
709: +  mat - the matrix
710: .  v - a logically two-dimensional array of values
711: .  m, idxm - the number of block rows and their global block indices 
712: .  n, idxn - the number of block columns and their global block indices
713: -  addv - either ADD_VALUES or INSERT_VALUES, where
714:    ADD_VALUES adds values to any existing entries, and
715:    INSERT_VALUES replaces existing entries with new values

717:    Notes:
718:    By default the values, v, are row-oriented and unsorted. So the layout of 
719:    v is the same as for MatSetValues(). See MatSetOption() for other options.

721:    Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
722:    options cannot be mixed without intervening calls to the assembly
723:    routines.

725:    MatSetValuesBlocked() uses 0-based row and column numbers in Fortran 
726:    as well as in C.

728:    Negative indices may be passed in idxm and idxn, these rows and columns are 
729:    simply ignored. This allows easily inserting element stiffness matrices
730:    with homogeneous Dirchlet boundary conditions that you don't want represented
731:    in the matrix.

733:    Each time an entry is set within a sparse matrix via MatSetValues(),
734:    internal searching must be done to determine where to place the the
735:    data in the matrix storage space.  By instead inserting blocks of 
736:    entries via MatSetValuesBlocked(), the overhead of matrix assembly is
737:    reduced.

739:    Restrictions:
740:    MatSetValuesBlocked() is currently supported only for the block AIJ
741:    matrix format (MATSEQBAIJ and MATMPIBAIJ, which are created via
742:    MatCreateSeqBAIJ() and MatCreateMPIBAIJ()).

744:    Level: intermediate

746:    Concepts: matrices^putting entries in blocked

748: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
749: @*/
750: int MatSetValuesBlocked(Mat mat,int m,const int idxm[],int n,const int idxn[],const PetscScalar v[],InsertMode addv)
751: {

755:   if (!m || !n) return(0); /* no values to insert */
758:   MatPreallocated(mat);
762:   if (mat->insertmode == NOT_SET_VALUES) {
763:     mat->insertmode = addv;
764:   }
765: #if defined(PETSC_USE_BOPT_g) 
766:   else if (mat->insertmode != addv) {
767:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
768:   }
769:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
770: #endif

772:   if (mat->assembled) {
773:     mat->was_assembled = PETSC_TRUE;
774:     mat->assembled     = PETSC_FALSE;
775:   }
776:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
777:   if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
778:   (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
779:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
780:   return(0);
781: }

785: /*@ 
786:    MatGetValues - Gets a block of values from a matrix.

788:    Not Collective; currently only returns a local block

790:    Input Parameters:
791: +  mat - the matrix
792: .  v - a logically two-dimensional array for storing the values
793: .  m, idxm - the number of rows and their global indices 
794: -  n, idxn - the number of columns and their global indices

796:    Notes:
797:    The user must allocate space (m*n PetscScalars) for the values, v.
798:    The values, v, are then returned in a row-oriented format, 
799:    analogous to that used by default in MatSetValues().

801:    MatGetValues() uses 0-based row and column numbers in
802:    Fortran as well as in C.

804:    MatGetValues() requires that the matrix has been assembled
805:    with MatAssemblyBegin()/MatAssemblyEnd().  Thus, calls to
806:    MatSetValues() and MatGetValues() CANNOT be made in succession
807:    without intermediate matrix assembly.

809:    Level: advanced

811:    Concepts: matrices^accessing values

813: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
814: @*/
815: int MatGetValues(Mat mat,int m,const int idxm[],int n,const int idxn[],PetscScalar v[])
816: {

822:   MatPreallocated(mat);
826:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
827:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
828:   if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

830:   PetscLogEventBegin(MAT_GetValues,mat,0,0,0);
831:   (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
832:   PetscLogEventEnd(MAT_GetValues,mat,0,0,0);
833:   return(0);
834: }

838: /*@
839:    MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
840:    the routine MatSetValuesLocal() to allow users to insert matrix entries
841:    using a local (per-processor) numbering.

843:    Not Collective

845:    Input Parameters:
846: +  x - the matrix
847: -  mapping - mapping created with ISLocalToGlobalMappingCreate() 
848:              or ISLocalToGlobalMappingCreateIS()

850:    Level: intermediate

852:    Concepts: matrices^local to global mapping
853:    Concepts: local to global mapping^for matrices

855: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
856: @*/
857: int MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
858: {
863:   MatPreallocated(x);
865:   if (x->mapping) {
866:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
867:   }

869:   if (x->ops->setlocaltoglobalmapping) {
870:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
871:   } else {
872:     x->mapping = mapping;
873:     PetscObjectReference((PetscObject)mapping);
874:   }
875:   return(0);
876: }

880: /*@
881:    MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
882:    by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
883:    entries using a local (per-processor) numbering.

885:    Not Collective

887:    Input Parameters:
888: +  x - the matrix
889: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or
890:              ISLocalToGlobalMappingCreateIS()

892:    Level: intermediate

894:    Concepts: matrices^local to global mapping blocked
895:    Concepts: local to global mapping^for matrices, blocked

897: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
898:            MatSetValuesBlocked(), MatSetValuesLocal()
899: @*/
900: int MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
901: {
906:   MatPreallocated(x);
908:   if (x->bmapping) {
909:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
910:   }
911: 
912:   x->bmapping = mapping;
913:   PetscObjectReference((PetscObject)mapping);
914:   return(0);
915: }

919: /*@
920:    MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
921:    using a local ordering of the nodes. 

923:    Not Collective

925:    Input Parameters:
926: +  x - the matrix
927: .  nrow, irow - number of rows and their local indices
928: .  ncol, icol - number of columns and their local indices
929: .  y -  a logically two-dimensional array of values
930: -  addv - either INSERT_VALUES or ADD_VALUES, where
931:    ADD_VALUES adds values to any existing entries, and
932:    INSERT_VALUES replaces existing entries with new values

934:    Notes:
935:    Before calling MatSetValuesLocal(), the user must first set the
936:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

938:    Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 
939:    options cannot be mixed without intervening calls to the assembly
940:    routines.

942:    These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 
943:    MUST be called after all calls to MatSetValuesLocal() have been completed.

945:    Level: intermediate

947:    Concepts: matrices^putting entries in with local numbering

949: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
950:            MatSetValueLocal()
951: @*/
952: int MatSetValuesLocal(Mat mat,int nrow,const int irow[],int ncol,const int icol[],const PetscScalar y[],InsertMode addv)
953: {
954:   int ierr,irowm[2048],icolm[2048];

959:   MatPreallocated(mat);

964:   if (mat->insertmode == NOT_SET_VALUES) {
965:     mat->insertmode = addv;
966:   }
967: #if defined(PETSC_USE_BOPT_g) 
968:   else if (mat->insertmode != addv) {
969:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
970:   }
971:   if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
972:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
973:   }
974:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
975: #endif

977:   if (mat->assembled) {
978:     mat->was_assembled = PETSC_TRUE;
979:     mat->assembled     = PETSC_FALSE;
980:   }
981:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
982:   if (!mat->ops->setvalueslocal) {
983:     ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
984:     ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
985:     (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
986:   } else {
987:     (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
988:   }
989:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
990:   return(0);
991: }

995: /*@
996:    MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix,
997:    using a local ordering of the nodes a block at a time. 

999:    Not Collective

1001:    Input Parameters:
1002: +  x - the matrix
1003: .  nrow, irow - number of rows and their local indices
1004: .  ncol, icol - number of columns and their local indices
1005: .  y -  a logically two-dimensional array of values
1006: -  addv - either INSERT_VALUES or ADD_VALUES, where
1007:    ADD_VALUES adds values to any existing entries, and
1008:    INSERT_VALUES replaces existing entries with new values

1010:    Notes:
1011:    Before calling MatSetValuesBlockedLocal(), the user must first set the
1012:    local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
1013:    where the mapping MUST be set for matrix blocks, not for matrix elements.

1015:    Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1016:    options cannot be mixed without intervening calls to the assembly
1017:    routines.

1019:    These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 
1020:    MUST be called after all calls to MatSetValuesBlockedLocal() have been completed.

1022:    Level: intermediate

1024:    Concepts: matrices^putting blocked values in with local numbering

1026: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
1027: @*/
1028: int MatSetValuesBlockedLocal(Mat mat,int nrow,const int irow[],int ncol,const int icol[],const PetscScalar y[],InsertMode addv)
1029: {
1030:   int ierr,irowm[2048],icolm[2048];

1035:   MatPreallocated(mat);
1039:   if (mat->insertmode == NOT_SET_VALUES) {
1040:     mat->insertmode = addv;
1041:   }
1042: #if defined(PETSC_USE_BOPT_g) 
1043:   else if (mat->insertmode != addv) {
1044:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1045:   }
1046:   if (!mat->bmapping) {
1047:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
1048:   }
1049:   if (nrow > 2048 || ncol > 2048) {
1050:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
1051:   }
1052:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1053: #endif

1055:   if (mat->assembled) {
1056:     mat->was_assembled = PETSC_TRUE;
1057:     mat->assembled     = PETSC_FALSE;
1058:   }
1059:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1060:   ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1061:   ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1062:   (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1063:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1064:   return(0);
1065: }

1067: /* --------------------------------------------------------*/
1070: /*@
1071:    MatMult - Computes the matrix-vector product, y = Ax.

1073:    Collective on Mat and Vec

1075:    Input Parameters:
1076: +  mat - the matrix
1077: -  x   - the vector to be multilplied

1079:    Output Parameters:
1080: .  y - the result

1082:    Notes:
1083:    The vectors x and y cannot be the same.  I.e., one cannot
1084:    call MatMult(A,y,y).

1086:    Level: beginner

1088:    Concepts: matrix-vector product

1090: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1091: @*/
1092: int MatMult(Mat mat,Vec x,Vec y)
1093: {

1099:   MatPreallocated(mat);

1103:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1104:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1105:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1106: #ifndef PETSC_HAVE_CONSTRAINTS
1107:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1108:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1109:   if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %d %d",mat->m,y->n);
1110: #endif

1112:   if (mat->nullsp) {
1113:     MatNullSpaceRemove(mat->nullsp,x,&x);
1114:   }

1116:   PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1117:   (*mat->ops->mult)(mat,x,y);
1118:   PetscLogEventEnd(MAT_Mult,mat,x,y,0);

1120:   if (mat->nullsp) {
1121:     MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1122:   }
1123:   return(0);
1124: }

1128: /*@
1129:    MatMultTranspose - Computes matrix transpose times a vector.

1131:    Collective on Mat and Vec

1133:    Input Parameters:
1134: +  mat - the matrix
1135: -  x   - the vector to be multilplied

1137:    Output Parameters:
1138: .  y - the result

1140:    Notes:
1141:    The vectors x and y cannot be the same.  I.e., one cannot
1142:    call MatMultTranspose(A,y,y).

1144:    Level: beginner

1146:    Concepts: matrix vector product^transpose

1148: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1149: @*/
1150: int MatMultTranspose(Mat mat,Vec x,Vec y)
1151: {
1153:   PetscTruth flg1, flg2;

1158:   MatPreallocated(mat);

1162:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1163:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1164:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1165: #ifndef PETSC_HAVE_CONSTRAINTS
1166:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
1167:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
1168: #endif

1170:   if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP, "Operation not supported");
1171:   PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);
1172:   if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined");
1173: 
1174:   PetscTypeCompare((PetscObject)mat,MATSEQSBAIJ,&flg1);
1175:   PetscTypeCompare((PetscObject)mat,MATMPISBAIJ,&flg2);
1176:   if (flg1 || flg2) { /* mat is in sbaij format */
1177:     (*mat->ops->mult)(mat,x,y);
1178:   } else {
1179:     (*mat->ops->multtranspose)(mat,x,y);
1180:   }
1181:   PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);
1182:   return(0);
1183: }

1187: /*@
1188:     MatMultAdd -  Computes v3 = v2 + A * v1.

1190:     Collective on Mat and Vec

1192:     Input Parameters:
1193: +   mat - the matrix
1194: -   v1, v2 - the vectors

1196:     Output Parameters:
1197: .   v3 - the result

1199:     Notes:
1200:     The vectors v1 and v3 cannot be the same.  I.e., one cannot
1201:     call MatMultAdd(A,v1,v2,v1).

1203:     Level: beginner

1205:     Concepts: matrix vector product^addition

1207: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1208: @*/
1209: int MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1210: {

1216:   MatPreallocated(mat);

1221:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1222:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1223:   if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->N,v1->N);
1224:   if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->M,v2->N);
1225:   if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->M,v3->N);
1226:   if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %d %d",mat->m,v3->n);
1227:   if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %d %d",mat->m,v2->n);
1228:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");

1230:   PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);
1231:   (*mat->ops->multadd)(mat,v1,v2,v3);
1232:   PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);
1233:   return(0);
1234: }

1238: /*@
1239:    MatMultTransposeAdd - Computes v3 = v2 + A' * v1.

1241:    Collective on Mat and Vec

1243:    Input Parameters:
1244: +  mat - the matrix
1245: -  v1, v2 - the vectors

1247:    Output Parameters:
1248: .  v3 - the result

1250:    Notes:
1251:    The vectors v1 and v3 cannot be the same.  I.e., one cannot
1252:    call MatMultTransposeAdd(A,v1,v2,v1).

1254:    Level: beginner

1256:    Concepts: matrix vector product^transpose and addition

1258: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1259: @*/
1260: int MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1261: {

1267:   MatPreallocated(mat);

1272:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1273:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1274:   if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1275:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1276:   if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->M,v1->N);
1277:   if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->N,v2->N);
1278:   if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->N,v3->N);

1280:   PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);
1281:   (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1282:   PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);
1283:   return(0);
1284: }

1288: /*@
1289:    MatMultConstrained - The inner multiplication routine for a
1290:    constrained matrix P^T A P.

1292:    Collective on Mat and Vec

1294:    Input Parameters:
1295: +  mat - the matrix
1296: -  x   - the vector to be multilplied

1298:    Output Parameters:
1299: .  y - the result

1301:    Notes:
1302:    The vectors x and y cannot be the same.  I.e., one cannot
1303:    call MatMult(A,y,y).

1305:    Level: beginner

1307: .keywords: matrix, multiply, matrix-vector product, constraint
1308: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1309: @*/
1310: int MatMultConstrained(Mat mat,Vec x,Vec y)
1311: {

1317:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1318:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1319:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1320:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1321:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1322:   if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %d %d",mat->m,y->n);

1324:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1325:   (*mat->ops->multconstrained)(mat,x,y);
1326:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);

1328:   return(0);
1329: }

1333: /*@
1334:    MatMultTransposeConstrained - The inner multiplication routine for a
1335:    constrained matrix P^T A^T P.

1337:    Collective on Mat and Vec

1339:    Input Parameters:
1340: +  mat - the matrix
1341: -  x   - the vector to be multilplied

1343:    Output Parameters:
1344: .  y - the result

1346:    Notes:
1347:    The vectors x and y cannot be the same.  I.e., one cannot
1348:    call MatMult(A,y,y).

1350:    Level: beginner

1352: .keywords: matrix, multiply, matrix-vector product, constraint
1353: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1354: @*/
1355: int MatMultTransposeConstrained(Mat mat,Vec x,Vec y)
1356: {

1362:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1363:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1364:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1365:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1366:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);

1368:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1369:   (*mat->ops->multtransposeconstrained)(mat,x,y);
1370:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);

1372:   return(0);
1373: }
1374: /* ------------------------------------------------------------*/
1377: /*@C
1378:    MatGetInfo - Returns information about matrix storage (number of
1379:    nonzeros, memory, etc.).

1381:    Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1382:    as the flag

1384:    Input Parameters:
1385: .  mat - the matrix

1387:    Output Parameters:
1388: +  flag - flag indicating the type of parameters to be returned
1389:    (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1390:    MAT_GLOBAL_SUM - sum over all processors)
1391: -  info - matrix information context

1393:    Notes:
1394:    The MatInfo context contains a variety of matrix data, including
1395:    number of nonzeros allocated and used, number of mallocs during
1396:    matrix assembly, etc.  Additional information for factored matrices
1397:    is provided (such as the fill ratio, number of mallocs during
1398:    factorization, etc.).  Much of this info is printed to STDOUT
1399:    when using the runtime options 
1400: $       -log_info -mat_view_info

1402:    Example for C/C++ Users:
1403:    See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1404:    data within the MatInfo context.  For example, 
1405: .vb
1406:       MatInfo info;
1407:       Mat     A;
1408:       double  mal, nz_a, nz_u;

1410:       MatGetInfo(A,MAT_LOCAL,&info);
1411:       mal  = info.mallocs;
1412:       nz_a = info.nz_allocated;
1413: .ve

1415:    Example for Fortran Users:
1416:    Fortran users should declare info as a double precision
1417:    array of dimension MAT_INFO_SIZE, and then extract the parameters
1418:    of interest.  See the file ${PETSC_DIR}/include/finclude/petscmat.h
1419:    a complete list of parameter names.
1420: .vb
1421:       double  precision info(MAT_INFO_SIZE)
1422:       double  precision mal, nz_a
1423:       Mat     A
1424:       integer ierr

1426:       call MatGetInfo(A,MAT_LOCAL,info,ierr)
1427:       mal = info(MAT_INFO_MALLOCS)
1428:       nz_a = info(MAT_INFO_NZ_ALLOCATED)
1429: .ve

1431:     Level: intermediate

1433:     Concepts: matrices^getting information on
1434:  
1435: @*/
1436: int MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1437: {

1443:   MatPreallocated(mat);
1445:   if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1446:   (*mat->ops->getinfo)(mat,flag,info);
1447:   return(0);
1448: }

1450: /* ----------------------------------------------------------*/
1453: /*@C  
1454:    MatILUDTFactor - Performs a drop tolerance ILU factorization.

1456:    Collective on Mat

1458:    Input Parameters:
1459: +  mat - the matrix
1460: .  info - information about the factorization to be done
1461: .  row - row permutation
1462: -  col - column permutation

1464:    Output Parameters:
1465: .  fact - the factored matrix

1467:    Level: developer

1469:    Notes:
1470:    Most users should employ the simplified SLES interface for linear solvers
1471:    instead of working directly with matrix algebra routines such as this.
1472:    See, e.g., SLESCreate().

1474:    This is currently only supported for the SeqAIJ matrix format using code
1475:    from Yousef Saad's SPARSEKIT2  package (translated to C with f2c) and/or
1476:    Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright
1477:    and thus can be distributed with PETSc.

1479:     Concepts: matrices^ILUDT factorization

1481: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1482: @*/
1483: int MatILUDTFactor(Mat mat,MatFactorInfo *info,IS row,IS col,Mat *fact)
1484: {

1490:   MatPreallocated(mat);
1492:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1493:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1494:   if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1496:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1497:   (*mat->ops->iludtfactor)(mat,info,row,col,fact);
1498:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);

1500:   return(0);
1501: }

1505: /*@  
1506:    MatLUFactor - Performs in-place LU factorization of matrix.

1508:    Collective on Mat

1510:    Input Parameters:
1511: +  mat - the matrix
1512: .  row - row permutation
1513: .  col - column permutation
1514: -  info - options for factorization, includes 
1515: $          fill - expected fill as ratio of original fill.
1516: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1517: $                   Run with the option -log_info to determine an optimal value to use

1519:    Notes:
1520:    Most users should employ the simplified SLES interface for linear solvers
1521:    instead of working directly with matrix algebra routines such as this.
1522:    See, e.g., SLESCreate().

1524:    This changes the state of the matrix to a factored matrix; it cannot be used
1525:    for example with MatSetValues() unless one first calls MatSetUnfactored().

1527:    Level: developer

1529:    Concepts: matrices^LU factorization

1531: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
1532:           MatGetOrdering(), MatSetUnfactored(), MatFactorInfo

1534: @*/
1535: int MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
1536: {

1542:   MatPreallocated(mat);
1543:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1544:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1545:   if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1547:   PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);
1548:   (*mat->ops->lufactor)(mat,row,col,info);
1549:   PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);
1550:   return(0);
1551: }

1555: /*@  
1556:    MatILUFactor - Performs in-place ILU factorization of matrix.

1558:    Collective on Mat

1560:    Input Parameters:
1561: +  mat - the matrix
1562: .  row - row permutation
1563: .  col - column permutation
1564: -  info - structure containing 
1565: $      levels - number of levels of fill.
1566: $      expected fill - as ratio of original fill.
1567: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
1568:                 missing diagonal entries)

1570:    Notes: 
1571:    Probably really in-place only when level of fill is zero, otherwise allocates
1572:    new space to store factored matrix and deletes previous memory.

1574:    Most users should employ the simplified SLES interface for linear solvers
1575:    instead of working directly with matrix algebra routines such as this.
1576:    See, e.g., SLESCreate().

1578:    Level: developer

1580:    Concepts: matrices^ILU factorization

1582: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1583: @*/
1584: int MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
1585: {

1591:   MatPreallocated(mat);
1592:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
1593:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1594:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1595:   if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1597:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1598:   (*mat->ops->ilufactor)(mat,row,col,info);
1599:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1600:   return(0);
1601: }

1605: /*@  
1606:    MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
1607:    Call this routine before calling MatLUFactorNumeric().

1609:    Collective on Mat

1611:    Input Parameters:
1612: +  mat - the matrix
1613: .  row, col - row and column permutations
1614: -  info - options for factorization, includes 
1615: $          fill - expected fill as ratio of original fill.
1616: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1617: $                   Run with the option -log_info to determine an optimal value to use

1619:    Output Parameter:
1620: .  fact - new matrix that has been symbolically factored

1622:    Notes:
1623:    See the users manual for additional information about
1624:    choosing the fill factor for better efficiency.

1626:    Most users should employ the simplified SLES interface for linear solvers
1627:    instead of working directly with matrix algebra routines such as this.
1628:    See, e.g., SLESCreate().

1630:    Level: developer

1632:    Concepts: matrices^LU symbolic factorization

1634: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1635: @*/
1636: int MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1637: {

1643:   MatPreallocated(mat);
1647:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1648:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1649:   if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic LU",mat->type_name);

1651:   PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);
1652:   (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
1653:   PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);
1654:   return(0);
1655: }

1659: /*@  
1660:    MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
1661:    Call this routine after first calling MatLUFactorSymbolic().

1663:    Collective on Mat

1665:    Input Parameters:
1666: +  mat - the matrix
1667: -  fact - the matrix generated for the factor, from MatLUFactorSymbolic()

1669:    Notes:
1670:    See MatLUFactor() for in-place factorization.  See 
1671:    MatCholeskyFactorNumeric() for the symmetric, positive definite case.  

1673:    Most users should employ the simplified SLES interface for linear solvers
1674:    instead of working directly with matrix algebra routines such as this.
1675:    See, e.g., SLESCreate().

1677:    Level: developer

1679:    Concepts: matrices^LU numeric factorization

1681: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
1682: @*/
1683: int MatLUFactorNumeric(Mat mat,Mat *fact)
1684: {
1685:   int        ierr;

1690:   MatPreallocated(mat);
1693:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1694:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1695:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %d should = %d %d should = %d",
1696:             mat->M,(*fact)->M,mat->N,(*fact)->N);
1697:   }
1698:   if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1700:   PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
1701:   (*(*fact)->ops->lufactornumeric)(mat,fact);
1702:   PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);

1704:   MatView_Private(*fact);
1705:   return(0);
1706: }

1710: /*@  
1711:    MatCholeskyFactor - Performs in-place Cholesky factorization of a
1712:    symmetric matrix. 

1714:    Collective on Mat

1716:    Input Parameters:
1717: +  mat - the matrix
1718: .  perm - row and column permutations
1719: -  f - expected fill as ratio of original fill

1721:    Notes:
1722:    See MatLUFactor() for the nonsymmetric case.  See also
1723:    MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().

1725:    Most users should employ the simplified SLES interface for linear solvers
1726:    instead of working directly with matrix algebra routines such as this.
1727:    See, e.g., SLESCreate().

1729:    Level: developer

1731:    Concepts: matrices^Cholesky factorization

1733: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
1734:           MatGetOrdering()

1736: @*/
1737: int MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info)
1738: {

1744:   MatPreallocated(mat);
1746:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1747:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1748:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1749:   if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1751:   PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);
1752:   (*mat->ops->choleskyfactor)(mat,perm,info);
1753:   PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);
1754:   return(0);
1755: }

1759: /*@  
1760:    MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
1761:    of a symmetric matrix. 

1763:    Collective on Mat

1765:    Input Parameters:
1766: +  mat - the matrix
1767: .  perm - row and column permutations
1768: -  info - options for factorization, includes 
1769: $          fill - expected fill as ratio of original fill.
1770: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1771: $                   Run with the option -log_info to determine an optimal value to use

1773:    Output Parameter:
1774: .  fact - the factored matrix

1776:    Notes:
1777:    See MatLUFactorSymbolic() for the nonsymmetric case.  See also
1778:    MatCholeskyFactor() and MatCholeskyFactorNumeric().

1780:    Most users should employ the simplified SLES interface for linear solvers
1781:    instead of working directly with matrix algebra routines such as this.
1782:    See, e.g., SLESCreate().

1784:    Level: developer

1786:    Concepts: matrices^Cholesky symbolic factorization

1788: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
1789:           MatGetOrdering()

1791: @*/
1792: int MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
1793: {

1799:   MatPreallocated(mat);
1801:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1802:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1803:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1804:   if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1806:   PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1807:   (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);
1808:   PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1809:   return(0);
1810: }

1814: /*@  
1815:    MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
1816:    of a symmetric matrix. Call this routine after first calling
1817:    MatCholeskyFactorSymbolic().

1819:    Collective on Mat

1821:    Input Parameter:
1822: .  mat - the initial matrix

1824:    Output Parameter:
1825: .  fact - the factored matrix

1827:    Notes:
1828:    Most users should employ the simplified SLES interface for linear solvers
1829:    instead of working directly with matrix algebra routines such as this.
1830:    See, e.g., SLESCreate().

1832:    Level: developer

1834:    Concepts: matrices^Cholesky numeric factorization

1836: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
1837: @*/
1838: int MatCholeskyFactorNumeric(Mat mat,Mat *fact)
1839: {

1845:   MatPreallocated(mat);
1847:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1848:   if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1849:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1850:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %d should = %d %d should = %d",
1851:             mat->M,(*fact)->M,mat->N,(*fact)->N);
1852:   }

1854:   PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1855:   (*(*fact)->ops->choleskyfactornumeric)(mat,fact);
1856:   PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1857:   return(0);
1858: }

1860: /* ----------------------------------------------------------------*/
1863: /*@
1864:    MatSolve - Solves A x = b, given a factored matrix.

1866:    Collective on Mat and Vec

1868:    Input Parameters:
1869: +  mat - the factored matrix
1870: -  b - the right-hand-side vector

1872:    Output Parameter:
1873: .  x - the result vector

1875:    Notes:
1876:    The vectors b and x cannot be the same.  I.e., one cannot
1877:    call MatSolve(A,x,x).

1879:    Notes:
1880:    Most users should employ the simplified SLES interface for linear solvers
1881:    instead of working directly with matrix algebra routines such as this.
1882:    See, e.g., SLESCreate().

1884:    Level: developer

1886:    Concepts: matrices^triangular solves

1888: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
1889: @*/
1890: int MatSolve(Mat mat,Vec b,Vec x)
1891: {

1897:   MatPreallocated(mat);
1902:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1903:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1904:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1905:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1906:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1907:   if (mat->M == 0 && mat->N == 0) return(0);

1909:   if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1910:   PetscLogEventBegin(MAT_Solve,mat,b,x,0);
1911:   (*mat->ops->solve)(mat,b,x);
1912:   PetscLogEventEnd(MAT_Solve,mat,b,x,0);
1913:   return(0);
1914: }

1918: /* @
1919:    MatForwardSolve - Solves L x = b, given a factored matrix, A = LU.

1921:    Collective on Mat and Vec

1923:    Input Parameters:
1924: +  mat - the factored matrix
1925: -  b - the right-hand-side vector

1927:    Output Parameter:
1928: .  x - the result vector

1930:    Notes:
1931:    MatSolve() should be used for most applications, as it performs
1932:    a forward solve followed by a backward solve.

1934:    The vectors b and x cannot be the same.  I.e., one cannot
1935:    call MatForwardSolve(A,x,x).

1937:    Most users should employ the simplified SLES interface for linear solvers
1938:    instead of working directly with matrix algebra routines such as this.
1939:    See, e.g., SLESCreate().

1941:    Level: developer

1943:    Concepts: matrices^forward solves

1945: .seealso: MatSolve(), MatBackwardSolve()
1946: @ */
1947: int MatForwardSolve(Mat mat,Vec b,Vec x)
1948: {

1954:   MatPreallocated(mat);
1959:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1960:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1961:   if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1962:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1963:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1964:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

1966:   PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
1967:   (*mat->ops->forwardsolve)(mat,b,x);
1968:   PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
1969:   return(0);
1970: }

1974: /* @
1975:    MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU.

1977:    Collective on Mat and Vec

1979:    Input Parameters:
1980: +  mat - the factored matrix
1981: -  b - the right-hand-side vector

1983:    Output Parameter:
1984: .  x - the result vector

1986:    Notes:
1987:    MatSolve() should be used for most applications, as it performs
1988:    a forward solve followed by a backward solve.

1990:    The vectors b and x cannot be the same.  I.e., one cannot
1991:    call MatBackwardSolve(A,x,x).

1993:    Most users should employ the simplified SLES interface for linear solvers
1994:    instead of working directly with matrix algebra routines such as this.
1995:    See, e.g., SLESCreate().

1997:    Level: developer

1999:    Concepts: matrices^backward solves

2001: .seealso: MatSolve(), MatForwardSolve()
2002: @ */
2003: int MatBackwardSolve(Mat mat,Vec b,Vec x)
2004: {

2010:   MatPreallocated(mat);
2015:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2016:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2017:   if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2018:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
2019:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
2020:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

2022:   PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);
2023:   (*mat->ops->backwardsolve)(mat,b,x);
2024:   PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);
2025:   return(0);
2026: }

2030: /*@
2031:    MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix.

2033:    Collective on Mat and Vec

2035:    Input Parameters:
2036: +  mat - the factored matrix
2037: .  b - the right-hand-side vector
2038: -  y - the vector to be added to 

2040:    Output Parameter:
2041: .  x - the result vector

2043:    Notes:
2044:    The vectors b and x cannot be the same.  I.e., one cannot
2045:    call MatSolveAdd(A,x,y,x).

2047:    Most users should employ the simplified SLES interface for linear solvers
2048:    instead of working directly with matrix algebra routines such as this.
2049:    See, e.g., SLESCreate().

2051:    Level: developer

2053:    Concepts: matrices^triangular solves

2055: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
2056: @*/
2057: int MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
2058: {
2059:   PetscScalar one = 1.0;
2060:   Vec    tmp;
2061:   int    ierr;

2066:   MatPreallocated(mat);
2073:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2074:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2075:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
2076:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
2077:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
2078:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
2079:   if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);

2081:   PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);
2082:   if (mat->ops->solveadd)  {
2083:     (*mat->ops->solveadd)(mat,b,y,x);
2084:   } else {
2085:     /* do the solve then the add manually */
2086:     if (x != y) {
2087:       MatSolve(mat,b,x);
2088:       VecAXPY(&one,y,x);
2089:     } else {
2090:       VecDuplicate(x,&tmp);
2091:       PetscLogObjectParent(mat,tmp);
2092:       VecCopy(x,tmp);
2093:       MatSolve(mat,b,x);
2094:       VecAXPY(&one,tmp,x);
2095:       VecDestroy(tmp);
2096:     }
2097:   }
2098:   PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);
2099:   return(0);
2100: }

2104: /*@
2105:    MatSolveTranspose - Solves A' x = b, given a factored matrix.

2107:    Collective on Mat and Vec

2109:    Input Parameters:
2110: +  mat - the factored matrix
2111: -  b - the right-hand-side vector

2113:    Output Parameter:
2114: .  x - the result vector

2116:    Notes:
2117:    The vectors b and x cannot be the same.  I.e., one cannot
2118:    call MatSolveTranspose(A,x,x).

2120:    Most users should employ the simplified SLES interface for linear solvers
2121:    instead of working directly with matrix algebra routines such as this.
2122:    See, e.g., SLESCreate().

2124:    Level: developer

2126:    Concepts: matrices^triangular solves

2128: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
2129: @*/
2130: int MatSolveTranspose(Mat mat,Vec b,Vec x)
2131: {

2137:   MatPreallocated(mat);
2142:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2143:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2144:   if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2145:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
2146:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);

2148:   PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
2149:   (*mat->ops->solvetranspose)(mat,b,x);
2150:   PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
2151:   return(0);
2152: }

2156: /*@
2157:    MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 
2158:                       factored matrix. 

2160:    Collective on Mat and Vec

2162:    Input Parameters:
2163: +  mat - the factored matrix
2164: .  b - the right-hand-side vector
2165: -  y - the vector to be added to 

2167:    Output Parameter:
2168: .  x - the result vector

2170:    Notes:
2171:    The vectors b and x cannot be the same.  I.e., one cannot
2172:    call MatSolveTransposeAdd(A,x,y,x).

2174:    Most users should employ the simplified SLES interface for linear solvers
2175:    instead of working directly with matrix algebra routines such as this.
2176:    See, e.g., SLESCreate().

2178:    Level: developer

2180:    Concepts: matrices^triangular solves

2182: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
2183: @*/
2184: int MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
2185: {
2186:   PetscScalar one = 1.0;
2187:   int         ierr;
2188:   Vec         tmp;

2193:   MatPreallocated(mat);
2200:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2201:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2202:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
2203:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);
2204:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
2205:   if (x->n != y->n)   SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);

2207:   PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);
2208:   if (mat->ops->solvetransposeadd) {
2209:     (*mat->ops->solvetransposeadd)(mat,b,y,x);
2210:   } else {
2211:     /* do the solve then the add manually */
2212:     if (x != y) {
2213:       MatSolveTranspose(mat,b,x);
2214:       VecAXPY(&one,y,x);
2215:     } else {
2216:       VecDuplicate(x,&tmp);
2217:       PetscLogObjectParent(mat,tmp);
2218:       VecCopy(x,tmp);
2219:       MatSolveTranspose(mat,b,x);
2220:       VecAXPY(&one,tmp,x);
2221:       VecDestroy(tmp);
2222:     }
2223:   }
2224:   PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);
2225:   return(0);
2226: }
2227: /* ----------------------------------------------------------------*/

2231: /*@
2232:    MatRelax - Computes one relaxation sweep.

2234:    Collective on Mat and Vec

2236:    Input Parameters:
2237: +  mat - the matrix
2238: .  b - the right hand side
2239: .  omega - the relaxation factor
2240: .  flag - flag indicating the type of SOR (see below)
2241: .  shift -  diagonal shift
2242: -  its - the number of iterations
2243: -  lits - the number of local iterations 

2245:    Output Parameters:
2246: .  x - the solution (can contain an initial guess)

2248:    SOR Flags:
2249: .     SOR_FORWARD_SWEEP - forward SOR
2250: .     SOR_BACKWARD_SWEEP - backward SOR
2251: .     SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2252: .     SOR_LOCAL_FORWARD_SWEEP - local forward SOR 
2253: .     SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 
2254: .     SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2255: .     SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 
2256:          upper/lower triangular part of matrix to
2257:          vector (with omega)
2258: .     SOR_ZERO_INITIAL_GUESS - zero initial guess

2260:    Notes:
2261:    SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2262:    SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings
2263:    on each processor. 

2265:    Application programmers will not generally use MatRelax() directly,
2266:    but instead will employ the SLES/PC interface.

2268:    Notes for Advanced Users:
2269:    The flags are implemented as bitwise inclusive or operations.
2270:    For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2271:    to specify a zero initial guess for SSOR.

2273:    Most users should employ the simplified SLES interface for linear solvers
2274:    instead of working directly with matrix algebra routines such as this.
2275:    See, e.g., SLESCreate().

2277:    Level: developer

2279:    Concepts: matrices^relaxation
2280:    Concepts: matrices^SOR
2281:    Concepts: matrices^Gauss-Seidel

2283: @*/
2284: int MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,int its,int lits,Vec x)
2285: {

2291:   MatPreallocated(mat);
2296:   if (!mat->ops->relax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2297:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2298:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2299:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
2300:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
2301:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

2303:   PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2304:   ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2305:   PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2306:   return(0);
2307: }

2311: /*
2312:       Default matrix copy routine.
2313: */
2314: int MatCopy_Basic(Mat A,Mat B,MatStructure str)
2315: {
2316:   int         ierr,i,rstart,rend,nz,*cwork;
2317:   PetscScalar *vwork;

2320:   MatZeroEntries(B);
2321:   MatGetOwnershipRange(A,&rstart,&rend);
2322:   for (i=rstart; i<rend; i++) {
2323:     MatGetRow(A,i,&nz,&cwork,&vwork);
2324:     MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2325:     MatRestoreRow(A,i,&nz,&cwork,&vwork);
2326:   }
2327:   MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2328:   MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2329:   return(0);
2330: }

2334: /*@C  
2335:    MatCopy - Copys a matrix to another matrix.

2337:    Collective on Mat

2339:    Input Parameters:
2340: +  A - the matrix
2341: -  str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN

2343:    Output Parameter:
2344: .  B - where the copy is put

2346:    Notes:
2347:    If you use SAME_NONZERO_PATTERN then the two matrices had better have the 
2348:    same nonzero pattern or the routine will crash.

2350:    MatCopy() copies the matrix entries of a matrix to another existing
2351:    matrix (after first zeroing the second matrix).  A related routine is
2352:    MatConvert(), which first creates a new matrix and then copies the data.

2354:    Level: intermediate
2355:    
2356:    Concepts: matrices^copying

2358: .seealso: MatConvert(), MatDuplicate()

2360: @*/
2361: int MatCopy(Mat A,Mat B,MatStructure str)
2362: {

2369:   MatPreallocated(A);
2371:   MatPreallocated(B);
2373:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2374:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2375:   if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%d,%d) (%d,%d)",A->M,B->M,
2376:                                              A->N,B->N);

2378:   PetscLogEventBegin(MAT_Copy,A,B,0,0);
2379:   if (A->ops->copy) {
2380:     (*A->ops->copy)(A,B,str);
2381:   } else { /* generic conversion */
2382:     MatCopy_Basic(A,B,str);
2383:   }
2384:   if (A->mapping) {
2385:     if (B->mapping) {ISLocalToGlobalMappingDestroy(B->mapping);B->mapping = 0;}
2386:     MatSetLocalToGlobalMapping(B,A->mapping);
2387:   }
2388:   if (A->bmapping) {
2389:     if (B->bmapping) {ISLocalToGlobalMappingDestroy(B->bmapping);B->bmapping = 0;}
2390:     MatSetLocalToGlobalMappingBlock(B,A->mapping);
2391:   }
2392:   PetscLogEventEnd(MAT_Copy,A,B,0,0);
2393:   return(0);
2394: }

2396:  #include petscsys.h
2397: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
2398: PetscFList MatConvertList              = 0;

2402: /*@C
2403:     MatConvertRegister - Allows one to register a routine that converts a sparse matrix
2404:         from one format to another.

2406:   Not Collective

2408:   Input Parameters:
2409: +   type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ.
2410: -   Converter - the function that reads the matrix from the binary file.

2412:   Level: developer

2414: .seealso: MatConvertRegisterAll(), MatConvert()

2416: @*/
2417: int MatConvertRegister(char *sname,char *path,char *name,int (*function)(Mat,MatType,Mat*))
2418: {
2419:   int  ierr;
2420:   char fullname[PETSC_MAX_PATH_LEN];

2423:   PetscFListConcat(path,name,fullname);
2424:   PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);
2425:   return(0);
2426: }

2430: /*@C  
2431:    MatConvert - Converts a matrix to another matrix, either of the same
2432:    or different type.

2434:    Collective on Mat

2436:    Input Parameters:
2437: +  mat - the matrix
2438: -  newtype - new matrix type.  Use MATSAME to create a new matrix of the
2439:    same type as the original matrix.

2441:    Output Parameter:
2442: .  M - pointer to place new matrix

2444:    Notes:
2445:    MatConvert() first creates a new matrix and then copies the data from
2446:    the first matrix.  A related routine is MatCopy(), which copies the matrix
2447:    entries of one matrix to another already existing matrix context.

2449:    Level: intermediate

2451:    Concepts: matrices^converting between storage formats

2453: .seealso: MatCopy(), MatDuplicate()
2454: @*/
2455: int MatConvert(Mat mat,MatType newtype,Mat *M)
2456: {
2457:   int        ierr;
2458:   PetscTruth sametype,issame,flg;
2459:   char       convname[256],mtype[256];

2464:   MatPreallocated(mat);
2466:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2467:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2469:   PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
2470:   if (flg) {
2471:     newtype = mtype;
2472:   }
2473:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2474: 
2475:   PetscTypeCompare((PetscObject)mat,newtype,&sametype);
2476:   PetscStrcmp(newtype,"same",&issame);
2477:   if ((sametype || issame) && mat->ops->duplicate) {
2478:     (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
2479:   } else {
2480:     int (*conv)(Mat,MatType,Mat*)=PETSC_NULL;
2481:     /* 
2482:        Order of precedence:
2483:        1) See if a specialized converter is known to the current matrix.
2484:        2) See if a specialized converter is known to the desired matrix class.
2485:        3) See if a good general converter is registered for the desired class
2486:           (as of 6/27/03 only MATMPIADJ falls into this category).
2487:        4) See if a good general converter is known for the current matrix.
2488:        5) Use a really basic converter.
2489:     */
2490:     PetscStrcpy(convname,"MatConvert_");
2491:     PetscStrcat(convname,mat->type_name);
2492:     PetscStrcat(convname,"_");
2493:     PetscStrcat(convname,newtype);
2494:     PetscStrcat(convname,"_C");
2495:     PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);
2496:     if (!conv) {
2497:       Mat B;
2498:       MatCreate(mat->comm,0,0,0,0,&B);
2499:       MatSetType(B,newtype);
2500:       PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);
2501:       MatDestroy(B);
2502:       if (!conv) {
2503:         if (!MatConvertRegisterAllCalled) {
2504:           MatConvertRegisterAll(PETSC_NULL);
2505:         }
2506:         PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);
2507:         if (!conv) {
2508:           if (mat->ops->convert) {
2509:             conv = mat->ops->convert;
2510:           } else {
2511:             conv = MatConvert_Basic;
2512:           }
2513:         }
2514:       }
2515:     }
2516:     (*conv)(mat,newtype,M);
2517:   }
2518:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2519:   return(0);
2520: }


2525: /*@C  
2526:    MatDuplicate - Duplicates a matrix including the non-zero structure.

2528:    Collective on Mat

2530:    Input Parameters:
2531: +  mat - the matrix
2532: -  op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
2533:         values as well or not

2535:    Output Parameter:
2536: .  M - pointer to place new matrix

2538:    Level: intermediate

2540:    Concepts: matrices^duplicating

2542: .seealso: MatCopy(), MatConvert()
2543: @*/
2544: int MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
2545: {

2551:   MatPreallocated(mat);
2553:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2554:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2556:   *M  = 0;
2557:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2558:   if (!mat->ops->duplicate) {
2559:     SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
2560:   }
2561:   (*mat->ops->duplicate)(mat,op,M);
2562:   if (mat->mapping) {
2563:     MatSetLocalToGlobalMapping(*M,mat->mapping);
2564:   }
2565:   if (mat->bmapping) {
2566:     MatSetLocalToGlobalMappingBlock(*M,mat->mapping);
2567:   }
2568:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2569:   return(0);
2570: }

2574: /*@ 
2575:    MatGetDiagonal - Gets the diagonal of a matrix.

2577:    Collective on Mat and Vec

2579:    Input Parameters:
2580: +  mat - the matrix
2581: -  v - the vector for storing the diagonal

2583:    Output Parameter:
2584: .  v - the diagonal of the matrix

2586:    Notes:
2587:    For the SeqAIJ matrix format, this routine may also be called
2588:    on a LU factored matrix; in that case it routines the reciprocal of 
2589:    the diagonal entries in U. It returns the entries permuted by the 
2590:    row and column permutation used during the symbolic factorization.

2592:    Level: intermediate

2594:    Concepts: matrices^accessing diagonals

2596: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
2597: @*/
2598: int MatGetDiagonal(Mat mat,Vec v)
2599: {

2605:   MatPreallocated(mat);
2608:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2609:   if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

2611:   (*mat->ops->getdiagonal)(mat,v);
2612:   return(0);
2613: }

2617: /*@ 
2618:    MatGetRowMax - Gets the maximum value (in absolute value) of each
2619:         row of the matrix

2621:    Collective on Mat and Vec

2623:    Input Parameters:
2624: .  mat - the matrix

2626:    Output Parameter:
2627: .  v - the vector for storing the maximums

2629:    Level: intermediate

2631:    Concepts: matrices^getting row maximums

2633: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
2634: @*/
2635: int MatGetRowMax(Mat mat,Vec v)
2636: {

2642:   MatPreallocated(mat);
2645:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2646:   if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

2648:   (*mat->ops->getrowmax)(mat,v);
2649:   return(0);
2650: }

2654: /*@C
2655:    MatTranspose - Computes an in-place or out-of-place transpose of a matrix.

2657:    Collective on Mat

2659:    Input Parameter:
2660: .  mat - the matrix to transpose

2662:    Output Parameters:
2663: .  B - the transpose (or pass in PETSC_NULL for an in-place transpose)

2665:    Level: intermediate

2667:    Concepts: matrices^transposing

2669: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsSymmetric()
2670: @*/
2671: int MatTranspose(Mat mat,Mat *B)
2672: {

2678:   MatPreallocated(mat);
2679:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2680:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2681:   if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

2683:   PetscLogEventBegin(MAT_Transpose,mat,0,0,0);
2684:   (*mat->ops->transpose)(mat,B);
2685:   PetscLogEventEnd(MAT_Transpose,mat,0,0,0);
2686:   return(0);
2687: }

2691: /*@C
2692:    MatIsSymmetric - Test whether a matrix is another one's transpose, 
2693:         or its own, in which case it tests symmetry.

2695:    Collective on Mat

2697:    Input Parameter:
2698: +  A - the matrix to test
2699: -  B - the matrix to test against, this can equal the first parameter

2701:    Output Parameters:
2702: .  flg - the result

2704:    Notes:
2705:    Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm
2706:    has a running time of the order of the number of nonzeros; the parallel
2707:    test involves parallel copies of the block-offdiagonal parts of the matrix.

2709:    Level: intermediate

2711:    Concepts: matrices^transposing, matrix^symmetry

2713: .seealso: MatTranspose()
2714: @*/
2715: int MatIsSymmetric(Mat A,Mat B,PetscTruth *flg)
2716: {
2717:   int ierr,(*f)(Mat,Mat,PetscTruth*),(*g)(Mat,Mat,PetscTruth*);

2722:   PetscObjectQueryFunction((PetscObject)A,"MatIsSymmetric_C",(void (**)(void))&f);
2723:   PetscObjectQueryFunction((PetscObject)B,"MatIsSymmetric_C",(void (**)(void))&g);
2724:   if (f && g) {
2725:     if (f==g) {
2726:       (*f)(A,B,flg);
2727:     } else {
2728:       SETERRQ(1,"Matrices do not have the same comparator for symmetry test");
2729:     }
2730:   }
2731:   return(0);
2732: }

2736: /*@C
2737:    MatPermute - Creates a new matrix with rows and columns permuted from the 
2738:    original.

2740:    Collective on Mat

2742:    Input Parameters:
2743: +  mat - the matrix to permute
2744: .  row - row permutation, each processor supplies only the permutation for its rows
2745: -  col - column permutation, each processor needs the entire column permutation, that is
2746:          this is the same size as the total number of columns in the matrix

2748:    Output Parameters:
2749: .  B - the permuted matrix

2751:    Level: advanced

2753:    Concepts: matrices^permuting

2755: .seealso: MatGetOrdering()
2756: @*/
2757: int MatPermute(Mat mat,IS row,IS col,Mat *B)
2758: {

2764:   MatPreallocated(mat);
2767:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2768:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2769:   if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2770:   (*mat->ops->permute)(mat,row,col,B);
2771:   return(0);
2772: }

2776: /*@C
2777:   MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the 
2778:   original and sparsified to the prescribed tolerance.

2780:   Collective on Mat

2782:   Input Parameters:
2783: + A    - The matrix to permute
2784: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
2785: . frac - The half-bandwidth as a fraction of the total size, or 0.0
2786: . tol  - The drop tolerance
2787: . rowp - The row permutation
2788: - colp - The column permutation

2790:   Output Parameter:
2791: . B    - The permuted, sparsified matrix

2793:   Level: advanced

2795:   Note:
2796:   The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
2797:   restrict the half-bandwidth of the resulting matrix to 5% of the
2798:   total matrix size.

2800: .keywords: matrix, permute, sparsify

2802: .seealso: MatGetOrdering(), MatPermute()
2803: @*/
2804: int MatPermuteSparsify(Mat A, int band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
2805: {
2806:   IS           irowp, icolp;
2807:   int         *rows, *cols;
2808:   int          M, N, locRowStart, locRowEnd;
2809:   int          nz, newNz;
2810:   int         *cwork, *cnew;
2811:   PetscScalar *vwork, *vnew;
2812:   int          bw, size;
2813:   int          row, locRow, newRow, col, newCol;
2814:   int          ierr;

2820:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
2821:   if (A->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
2822:   if (!A->ops->permutesparsify) {
2823:     MatGetSize(A, &M, &N);
2824:     MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
2825:     ISGetSize(rowp, &size);
2826:     if (size != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %d for row permutation, should be %d", size, M);
2827:     ISGetSize(colp, &size);
2828:     if (size != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %d for column permutation, should be %d", size, N);
2829:     ISInvertPermutation(rowp, 0, &irowp);
2830:     ISGetIndices(irowp, &rows);
2831:     ISInvertPermutation(colp, 0, &icolp);
2832:     ISGetIndices(icolp, &cols);
2833:     PetscMalloc(N * sizeof(int),         &cnew);
2834:     PetscMalloc(N * sizeof(PetscScalar), &vnew);

2836:     /* Setup bandwidth to include */
2837:     if (band == PETSC_DECIDE) {
2838:       if (frac <= 0.0)
2839:         bw = (int) (M * 0.05);
2840:       else
2841:         bw = (int) (M * frac);
2842:     } else {
2843:       if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
2844:       bw = band;
2845:     }

2847:     /* Put values into new matrix */
2848:     MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
2849:     for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
2850:       MatGetRow(A, row, &nz, &cwork, &vwork);
2851:       newRow   = rows[locRow]+locRowStart;
2852:       for(col = 0, newNz = 0; col < nz; col++) {
2853:         newCol = cols[cwork[col]];
2854:         if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
2855:           cnew[newNz] = newCol;
2856:           vnew[newNz] = vwork[col];
2857:           newNz++;
2858:         }
2859:       }
2860:       MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
2861:       MatRestoreRow(A, row, &nz, &cwork, &vwork);
2862:     }
2863:     PetscFree(cnew);
2864:     PetscFree(vnew);
2865:     MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
2866:     MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
2867:     ISRestoreIndices(irowp, &rows);
2868:     ISRestoreIndices(icolp, &cols);
2869:     ISDestroy(irowp);
2870:     ISDestroy(icolp);
2871:   } else {
2872:     (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
2873:   }
2874:   return(0);
2875: }

2879: /*@
2880:    MatEqual - Compares two matrices.

2882:    Collective on Mat

2884:    Input Parameters:
2885: +  A - the first matrix
2886: -  B - the second matrix

2888:    Output Parameter:
2889: .  flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.

2891:    Level: intermediate

2893:    Concepts: matrices^equality between
2894: @*/
2895: int MatEqual(Mat A,Mat B,PetscTruth *flg)
2896: {

2903:   MatPreallocated(A);
2905:   MatPreallocated(B);
2908:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2909:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2910:   if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d %d %d",A->M,B->M,A->N,B->N);
2911:   if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2912:   if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
2913:   if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name);
2914:   (*A->ops->equal)(A,B,flg);
2915:   return(0);
2916: }

2920: /*@
2921:    MatDiagonalScale - Scales a matrix on the left and right by diagonal
2922:    matrices that are stored as vectors.  Either of the two scaling
2923:    matrices can be PETSC_NULL.

2925:    Collective on Mat

2927:    Input Parameters:
2928: +  mat - the matrix to be scaled
2929: .  l - the left scaling vector (or PETSC_NULL)
2930: -  r - the right scaling vector (or PETSC_NULL)

2932:    Notes:
2933:    MatDiagonalScale() computes A = LAR, where
2934:    L = a diagonal matrix, R = a diagonal matrix

2936:    Level: intermediate

2938:    Concepts: matrices^diagonal scaling
2939:    Concepts: diagonal scaling of matrices

2941: .seealso: MatScale()
2942: @*/
2943: int MatDiagonalScale(Mat mat,Vec l,Vec r)
2944: {

2950:   MatPreallocated(mat);
2951:   if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2954:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2955:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2957:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2958:   (*mat->ops->diagonalscale)(mat,l,r);
2959:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2960:   return(0);
2961: }

2965: /*@
2966:     MatScale - Scales all elements of a matrix by a given number.

2968:     Collective on Mat

2970:     Input Parameters:
2971: +   mat - the matrix to be scaled
2972: -   a  - the scaling value

2974:     Output Parameter:
2975: .   mat - the scaled matrix

2977:     Level: intermediate

2979:     Concepts: matrices^scaling all entries

2981: .seealso: MatDiagonalScale()
2982: @*/
2983: int MatScale(const PetscScalar *a,Mat mat)
2984: {

2990:   MatPreallocated(mat);
2992:   if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2993:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2994:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2996:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2997:   (*mat->ops->scale)(a,mat);
2998:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2999:   return(0);
3000: }

3004: /*@ 
3005:    MatNorm - Calculates various norms of a matrix.

3007:    Collective on Mat

3009:    Input Parameters:
3010: +  mat - the matrix
3011: -  type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY

3013:    Output Parameters:
3014: .  nrm - the resulting norm 

3016:    Level: intermediate

3018:    Concepts: matrices^norm
3019:    Concepts: norm^of matrix
3020: @*/
3021: int MatNorm(Mat mat,NormType type,PetscReal *nrm)
3022: {

3028:   MatPreallocated(mat);

3031:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3032:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3033:   if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3034:   (*mat->ops->norm)(mat,type,nrm);
3035:   return(0);
3036: }

3038: /* 
3039:      This variable is used to prevent counting of MatAssemblyBegin() that
3040:    are called from within a MatAssemblyEnd().
3041: */
3042: static int MatAssemblyEnd_InUse = 0;
3045: /*@
3046:    MatAssemblyBegin - Begins assembling the matrix.  This routine should
3047:    be called after completing all calls to MatSetValues().

3049:    Collective on Mat

3051:    Input Parameters:
3052: +  mat - the matrix 
3053: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3054:  
3055:    Notes: 
3056:    MatSetValues() generally caches the values.  The matrix is ready to
3057:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3058:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3059:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3060:    using the matrix.

3062:    Level: beginner

3064:    Concepts: matrices^assembling

3066: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3067: @*/
3068: int MatAssemblyBegin(Mat mat,MatAssemblyType type)
3069: {

3075:   MatPreallocated(mat);
3076:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3077:   if (mat->assembled) {
3078:     mat->was_assembled = PETSC_TRUE;
3079:     mat->assembled     = PETSC_FALSE;
3080:   }
3081:   if (!MatAssemblyEnd_InUse) {
3082:     PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
3083:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3084:     PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
3085:   } else {
3086:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3087:   }
3088:   return(0);
3089: }

3093: /*@
3094:    MatAssembled - Indicates if a matrix has been assembled and is ready for
3095:      use; for example, in matrix-vector product.

3097:    Collective on Mat

3099:    Input Parameter:
3100: .  mat - the matrix 

3102:    Output Parameter:
3103: .  assembled - PETSC_TRUE or PETSC_FALSE

3105:    Level: advanced

3107:    Concepts: matrices^assembled?

3109: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3110: @*/
3111: int MatAssembled(Mat mat,PetscTruth *assembled)
3112: {
3116:   MatPreallocated(mat);
3117:   *assembled = mat->assembled;
3118:   return(0);
3119: }

3123: /*
3124:     Processes command line options to determine if/how a matrix
3125:   is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3126: */
3127: int MatView_Private(Mat mat)
3128: {
3129:   int               ierr;
3130:   PetscTruth        flg;
3131:   static PetscTruth incall = PETSC_FALSE;

3134:   if (incall) return(0);
3135:   incall = PETSC_TRUE;
3136:   PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3137:     PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);
3138:     if (flg) {
3139:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3140:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3141:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3142:     }
3143:     PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);
3144:     if (flg) {
3145:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3146:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3147:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3148:     }
3149:     PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);
3150:     if (flg) {
3151:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3152:     }
3153:     PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);
3154:     if (flg) {
3155:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3156:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3157:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3158:     }
3159:     PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);
3160:     if (flg) {
3161:       MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3162:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3163:     }
3164:     PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);
3165:     if (flg) {
3166:       MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3167:       PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3168:     }
3169:   PetscOptionsEnd();
3170:   /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */
3171:   PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
3172:   if (flg) {
3173:     PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
3174:     if (flg) {
3175:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3176:     }
3177:     MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3178:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3179:     if (flg) {
3180:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3181:     }
3182:   }
3183:   incall = PETSC_FALSE;
3184:   return(0);
3185: }

3189: /*@
3190:    MatAssemblyEnd - Completes assembling the matrix.  This routine should
3191:    be called after MatAssemblyBegin().

3193:    Collective on Mat

3195:    Input Parameters:
3196: +  mat - the matrix 
3197: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY

3199:    Options Database Keys:
3200: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3201: .  -mat_view_info_detailed - Prints more detailed info
3202: .  -mat_view - Prints matrix in ASCII format
3203: .  -mat_view_matlab - Prints matrix in Matlab format
3204: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3205: .  -display <name> - Sets display name (default is host)
3206: .  -draw_pause <sec> - Sets number of seconds to pause after display
3207: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3208: .  -viewer_socket_machine <machine>
3209: .  -viewer_socket_port <port>
3210: .  -mat_view_binary - save matrix to file in binary format
3211: -  -viewer_binary_filename <name>

3213:    Notes: 
3214:    MatSetValues() generally caches the values.  The matrix is ready to
3215:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3216:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3217:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3218:    using the matrix.

3220:    Level: beginner

3222: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3223: @*/
3224: int MatAssemblyEnd(Mat mat,MatAssemblyType type)
3225: {
3226:   int        ierr;
3227:   static int inassm = 0;
3228:   PetscTruth flg;

3233:   MatPreallocated(mat);

3235:   inassm++;
3236:   MatAssemblyEnd_InUse++;
3237:   if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3238:     PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
3239:     if (mat->ops->assemblyend) {
3240:       (*mat->ops->assemblyend)(mat,type);
3241:     }
3242:     PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
3243:   } else {
3244:     if (mat->ops->assemblyend) {
3245:       (*mat->ops->assemblyend)(mat,type);
3246:     }
3247:   }

3249:   /* Flush assembly is not a true assembly */
3250:   if (type != MAT_FLUSH_ASSEMBLY) {
3251:     mat->assembled  = PETSC_TRUE; mat->num_ass++;
3252:   }
3253:   mat->insertmode = NOT_SET_VALUES;
3254:   MatAssemblyEnd_InUse--;

3256:   if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3257:     MatView_Private(mat);
3258:   }
3259:   inassm--;
3260:   PetscOptionsHasName(mat->prefix,"-help",&flg);
3261:   if (flg) {
3262:     MatPrintHelp(mat);
3263:   }
3264:   return(0);
3265: }


3270: /*@
3271:    MatCompress - Tries to store the matrix in as little space as 
3272:    possible.  May fail if memory is already fully used, since it
3273:    tries to allocate new space.

3275:    Collective on Mat

3277:    Input Parameters:
3278: .  mat - the matrix 

3280:    Level: advanced

3282: @*/
3283: int MatCompress(Mat mat)
3284: {

3290:   MatPreallocated(mat);
3291:   if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3292:   return(0);
3293: }

3297: /*@
3298:    MatSetOption - Sets a parameter option for a matrix. Some options
3299:    may be specific to certain storage formats.  Some options
3300:    determine how values will be inserted (or added). Sorted, 
3301:    row-oriented input will generally assemble the fastest. The default
3302:    is row-oriented, nonsorted input. 

3304:    Collective on Mat

3306:    Input Parameters:
3307: +  mat - the matrix 
3308: -  option - the option, one of those listed below (and possibly others),
3309:              e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

3311:    Options Describing Matrix Structure:
3312: +    MAT_SYMMETRIC - symmetric in terms of both structure and value
3313: -    MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure

3315:    Options For Use with MatSetValues():
3316:    Insert a logically dense subblock, which can be
3317: +    MAT_ROW_ORIENTED - row-oriented (default)
3318: .    MAT_COLUMN_ORIENTED - column-oriented
3319: .    MAT_ROWS_SORTED - sorted by row
3320: .    MAT_ROWS_UNSORTED - not sorted by row (default)
3321: .    MAT_COLUMNS_SORTED - sorted by column
3322: -    MAT_COLUMNS_UNSORTED - not sorted by column (default)

3324:    Not these options reflect the data you pass in with MatSetValues(); it has 
3325:    nothing to do with how the data is stored internally in the matrix 
3326:    data structure.

3328:    When (re)assembling a matrix, we can restrict the input for
3329:    efficiency/debugging purposes.  These options include
3330: +    MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
3331:         allowed if they generate a new nonzero
3332: .    MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
3333: .    MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
3334:          they generate a nonzero in a new diagonal (for block diagonal format only)
3335: .    MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
3336: .    MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
3337: .    MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
3338: -    MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly

3340:    Notes:
3341:    Some options are relevant only for particular matrix types and
3342:    are thus ignored by others.  Other options are not supported by
3343:    certain matrix types and will generate an error message if set.

3345:    If using a Fortran 77 module to compute a matrix, one may need to 
3346:    use the column-oriented option (or convert to the row-oriented 
3347:    format).  

3349:    MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 
3350:    that would generate a new entry in the nonzero structure is instead
3351:    ignored.  Thus, if memory has not alredy been allocated for this particular 
3352:    data, then the insertion is ignored. For dense matrices, in which
3353:    the entire array is allocated, no entries are ever ignored. 
3354:    Set after the first MatAssemblyEnd()

3356:    MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 
3357:    that would generate a new entry in the nonzero structure instead produces 
3358:    an error. (Currently supported for AIJ and BAIJ formats only.)
3359:    This is a useful flag when using SAME_NONZERO_PATTERN in calling
3360:    SLESSetOperators() to ensure that the nonzero pattern truely does 
3361:    remain unchanged. Set after the first MatAssemblyEnd()

3363:    MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 
3364:    that would generate a new entry that has not been preallocated will 
3365:    instead produce an error. (Currently supported for AIJ and BAIJ formats
3366:    only.) This is a useful flag when debugging matrix memory preallocation.

3368:    MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 
3369:    other processors should be dropped, rather than stashed.
3370:    This is useful if you know that the "owning" processor is also 
3371:    always generating the correct matrix entries, so that PETSc need
3372:    not transfer duplicate entries generated on another processor.
3373:    
3374:    MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
3375:    searches during matrix assembly. When this flag is set, the hash table
3376:    is created during the first Matrix Assembly. This hash table is
3377:    used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
3378:    to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 
3379:    should be used with MAT_USE_HASH_TABLE flag. This option is currently
3380:    supported by MATMPIBAIJ format only.

3382:    MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries
3383:    are kept in the nonzero structure

3385:    MAT_IGNORE_ZERO_ENTRIES - for AIJ matrices this will stop zero values from creating
3386:    a zero location in the matrix

3388:    MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 
3389:    ROWBS matrix types

3391:    MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
3392:    with AIJ and ROWBS matrix types

3394:    Level: intermediate

3396:    Concepts: matrices^setting options

3398: @*/
3399: int MatSetOption(Mat mat,MatOption op)
3400: {

3406:   MatPreallocated(mat);
3407:   switch (op) {
3408:   case MAT_SYMMETRIC:
3409:     mat->symmetric              = PETSC_TRUE;
3410:     mat->structurally_symmetric = PETSC_TRUE;
3411:     break;
3412:   case MAT_STRUCTURALLY_SYMMETRIC:
3413:     mat->structurally_symmetric = PETSC_TRUE;
3414:     break;
3415:   default:
3416:     if (mat->ops->setoption) {(*mat->ops->setoption)(mat,op);}
3417:     break;
3418:   }
3419:   return(0);
3420: }

3424: /*@
3425:    MatZeroEntries - Zeros all entries of a matrix.  For sparse matrices
3426:    this routine retains the old nonzero structure.

3428:    Collective on Mat

3430:    Input Parameters:
3431: .  mat - the matrix 

3433:    Level: intermediate

3435:    Concepts: matrices^zeroing

3437: .seealso: MatZeroRows()
3438: @*/
3439: int MatZeroEntries(Mat mat)
3440: {

3446:   MatPreallocated(mat);
3447:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3448:   if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

3450:   PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
3451:   (*mat->ops->zeroentries)(mat);
3452:   PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
3453:   return(0);
3454: }

3458: /*@C
3459:    MatZeroRows - Zeros all entries (except possibly the main diagonal)
3460:    of a set of rows of a matrix.

3462:    Collective on Mat

3464:    Input Parameters:
3465: +  mat - the matrix
3466: .  is - index set of rows to remove
3467: -  diag - pointer to value put in all diagonals of eliminated rows.
3468:           Note that diag is not a pointer to an array, but merely a
3469:           pointer to a single value.

3471:    Notes:
3472:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
3473:    but does not release memory.  For the dense and block diagonal
3474:    formats this does not alter the nonzero structure.

3476:    If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
3477:    of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
3478:    merely zeroed.

3480:    The user can set a value in the diagonal entry (or for the AIJ and
3481:    row formats can optionally remove the main diagonal entry from the
3482:    nonzero structure as well, by passing a null pointer (PETSC_NULL 
3483:    in C or PETSC_NULL_SCALAR in Fortran) as the final argument).

3485:    For the parallel case, all processes that share the matrix (i.e.,
3486:    those in the communicator used for matrix creation) MUST call this
3487:    routine, regardless of whether any rows being zeroed are owned by
3488:    them.

3490:    For the SBAIJ matrix (since only the upper triangular half of the matrix
3491:    is stored) the effect of this call is to also zero the corresponding 
3492:    column.
3493:   
3494:    Level: intermediate

3496:    Concepts: matrices^zeroing rows

3498: .seealso: MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
3499: @*/
3500: int MatZeroRows(Mat mat,IS is,const PetscScalar *diag)
3501: {

3507:   MatPreallocated(mat);
3510:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3511:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3512:   if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

3514:   (*mat->ops->zerorows)(mat,is,diag);
3515:   MatView_Private(mat);
3516:   return(0);
3517: }

3521: /*@C 
3522:    MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
3523:    of a set of rows of a matrix; using local numbering of rows.

3525:    Collective on Mat

3527:    Input Parameters:
3528: +  mat - the matrix
3529: .  is - index set of rows to remove
3530: -  diag - pointer to value put in all diagonals of eliminated rows.
3531:           Note that diag is not a pointer to an array, but merely a
3532:           pointer to a single value.

3534:    Notes:
3535:    Before calling MatZeroRowsLocal(), the user must first set the
3536:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

3538:    For the AIJ matrix formats this removes the old nonzero structure,
3539:    but does not release memory.  For the dense and block diagonal
3540:    formats this does not alter the nonzero structure.

3542:    If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
3543:    of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
3544:    merely zeroed.

3546:    The user can set a value in the diagonal entry (or for the AIJ and
3547:    row formats can optionally remove the main diagonal entry from the
3548:    nonzero structure as well, by passing a null pointer (PETSC_NULL
3549:    in C or PETSC_NULL_SCALAR in Fortran) as the final argument).

3551:    Level: intermediate

3553:    Concepts: matrices^zeroing

3555: .seealso: MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
3556: @*/
3557: int MatZeroRowsLocal(Mat mat,IS is,const PetscScalar *diag)
3558: {
3560:   IS  newis;

3565:   MatPreallocated(mat);
3568:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3569:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3571:   if (mat->ops->zerorowslocal) {
3572:     (*mat->ops->zerorowslocal)(mat,is,diag);
3573:   } else {
3574:     if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
3575:     ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
3576:     (*mat->ops->zerorows)(mat,newis,diag);
3577:     ISDestroy(newis);
3578:   }
3579:   return(0);
3580: }

3584: /*@
3585:    MatGetSize - Returns the numbers of rows and columns in a matrix.

3587:    Not Collective

3589:    Input Parameter:
3590: .  mat - the matrix

3592:    Output Parameters:
3593: +  m - the number of global rows
3594: -  n - the number of global columns

3596:    Level: beginner

3598:    Concepts: matrices^size

3600: .seealso: MatGetLocalSize()
3601: @*/
3602: int MatGetSize(Mat mat,int *m,int* n)
3603: {
3606:   if (m) *m = mat->M;
3607:   if (n) *n = mat->N;
3608:   return(0);
3609: }

3613: /*@
3614:    MatGetLocalSize - Returns the number of rows and columns in a matrix
3615:    stored locally.  This information may be implementation dependent, so
3616:    use with care.

3618:    Not Collective

3620:    Input Parameters:
3621: .  mat - the matrix

3623:    Output Parameters:
3624: +  m - the number of local rows
3625: -  n - the number of local columns

3627:    Level: beginner

3629:    Concepts: matrices^local size

3631: .seealso: MatGetSize()
3632: @*/
3633: int MatGetLocalSize(Mat mat,int *m,int* n)
3634: {
3637:   if (m) *m = mat->m;
3638:   if (n) *n = mat->n;
3639:   return(0);
3640: }

3644: /*@
3645:    MatGetOwnershipRange - Returns the range of matrix rows owned by
3646:    this processor, assuming that the matrix is laid out with the first
3647:    n1 rows on the first processor, the next n2 rows on the second, etc.
3648:    For certain parallel layouts this range may not be well defined.

3650:    Not Collective

3652:    Input Parameters:
3653: .  mat - the matrix

3655:    Output Parameters:
3656: +  m - the global index of the first local row
3657: -  n - one more than the global index of the last local row

3659:    Level: beginner

3661:    Concepts: matrices^row ownership
3662: @*/
3663: int MatGetOwnershipRange(Mat mat,int *m,int* n)
3664: {

3670:   MatPreallocated(mat);
3673:   PetscMapGetLocalRange(mat->rmap,m,n);
3674:   return(0);
3675: }

3679: /*@  
3680:    MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
3681:    Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 
3682:    to complete the factorization.

3684:    Collective on Mat

3686:    Input Parameters:
3687: +  mat - the matrix
3688: .  row - row permutation
3689: .  column - column permutation
3690: -  info - structure containing 
3691: $      levels - number of levels of fill.
3692: $      expected fill - as ratio of original fill.
3693: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
3694:                 missing diagonal entries)

3696:    Output Parameters:
3697: .  fact - new matrix that has been symbolically factored

3699:    Notes:
3700:    See the users manual for additional information about
3701:    choosing the fill factor for better efficiency.

3703:    Most users should employ the simplified SLES interface for linear solvers
3704:    instead of working directly with matrix algebra routines such as this.
3705:    See, e.g., SLESCreate().

3707:    Level: developer

3709:   Concepts: matrices^symbolic LU factorization
3710:   Concepts: matrices^factorization
3711:   Concepts: LU^symbolic factorization

3713: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
3714:           MatGetOrdering(), MatFactorInfo

3716: @*/
3717: int MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
3718: {

3724:   MatPreallocated(mat);
3728:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %d",(int)info->levels);
3729:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
3730:   if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ILU",mat->type_name);
3731:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3732:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3734:   PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
3735:   (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
3736:   PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
3737:   return(0);
3738: }

3742: /*@  
3743:    MatICCFactorSymbolic - Performs symbolic incomplete
3744:    Cholesky factorization for a symmetric matrix.  Use 
3745:    MatCholeskyFactorNumeric() to complete the factorization.

3747:    Collective on Mat

3749:    Input Parameters:
3750: +  mat - the matrix
3751: .  perm - row and column permutation
3752: -  info - structure containing 
3753: $      levels - number of levels of fill.
3754: $      expected fill - as ratio of original fill.

3756:    Output Parameter:
3757: .  fact - the factored matrix

3759:    Notes:
3760:    Currently only no-fill factorization is supported.

3762:    Most users should employ the simplified SLES interface for linear solvers
3763:    instead of working directly with matrix algebra routines such as this.
3764:    See, e.g., SLESCreate().

3766:    Level: developer

3768:   Concepts: matrices^symbolic incomplete Cholesky factorization
3769:   Concepts: matrices^factorization
3770:   Concepts: Cholsky^symbolic factorization

3772: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
3773: @*/
3774: int MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
3775: {

3781:   MatPreallocated(mat);
3784:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3785:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %d",(int) info->levels);
3786:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
3787:   if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ICC",mat->type_name);
3788:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");

3790:   PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
3791:   (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
3792:   PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
3793:   return(0);
3794: }

3798: /*@C
3799:    MatGetArray - Returns a pointer to the element values in the matrix.
3800:    The result of this routine is dependent on the underlying matrix data
3801:    structure, and may not even work for certain matrix types.  You MUST
3802:    call MatRestoreArray() when you no longer need to access the array.

3804:    Not Collective

3806:    Input Parameter:
3807: .  mat - the matrix

3809:    Output Parameter:
3810: .  v - the location of the values


3813:    Fortran Note:
3814:    This routine is used differently from Fortran, e.g.,
3815: .vb
3816:         Mat         mat
3817:         PetscScalar mat_array(1)
3818:         PetscOffset i_mat
3819:         int         ierr
3820:         call MatGetArray(mat,mat_array,i_mat,ierr)

3822:   C  Access first local entry in matrix; note that array is
3823:   C  treated as one dimensional
3824:         value = mat_array(i_mat + 1)

3826:         [... other code ...]
3827:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
3828: .ve

3830:    See the Fortran chapter of the users manual and 
3831:    petsc/src/mat/examples/tests for details.

3833:    Level: advanced

3835:    Concepts: matrices^access array

3837: .seealso: MatRestoreArray(), MatGetArrayF90()
3838: @*/
3839: int MatGetArray(Mat mat,PetscScalar *v[])
3840: {

3846:   MatPreallocated(mat);
3848:   if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3849:   (*mat->ops->getarray)(mat,v);
3850:   return(0);
3851: }

3855: /*@C
3856:    MatRestoreArray - Restores the matrix after MatGetArray() has been called.

3858:    Not Collective

3860:    Input Parameter:
3861: +  mat - the matrix
3862: -  v - the location of the values

3864:    Fortran Note:
3865:    This routine is used differently from Fortran, e.g.,
3866: .vb
3867:         Mat         mat
3868:         PetscScalar mat_array(1)
3869:         PetscOffset i_mat
3870:         int         ierr
3871:         call MatGetArray(mat,mat_array,i_mat,ierr)

3873:   C  Access first local entry in matrix; note that array is
3874:   C  treated as one dimensional
3875:         value = mat_array(i_mat + 1)

3877:         [... other code ...]
3878:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
3879: .ve

3881:    See the Fortran chapter of the users manual and 
3882:    petsc/src/mat/examples/tests for details

3884:    Level: advanced

3886: .seealso: MatGetArray(), MatRestoreArrayF90()
3887: @*/
3888: int MatRestoreArray(Mat mat,PetscScalar *v[])
3889: {

3895:   MatPreallocated(mat);
3897: #if defined(PETSC_USE_BOPT_g)
3898:   CHKMEMQ;
3899: #endif
3900:   if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3901:   (*mat->ops->restorearray)(mat,v);
3902:   return(0);
3903: }

3907: /*@C
3908:    MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
3909:    points to an array of valid matrices, they may be reused to store the new
3910:    submatrices.

3912:    Collective on Mat

3914:    Input Parameters:
3915: +  mat - the matrix
3916: .  n   - the number of submatrixes to be extracted (on this processor, may be zero)
3917: .  irow, icol - index sets of rows and columns to extract
3918: -  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

3920:    Output Parameter:
3921: .  submat - the array of submatrices

3923:    Notes:
3924:    MatGetSubMatrices() can extract only sequential submatrices
3925:    (from both sequential and parallel matrices). Use MatGetSubMatrix()
3926:    to extract a parallel submatrix.

3928:    When extracting submatrices from a parallel matrix, each processor can
3929:    form a different submatrix by setting the rows and columns of its
3930:    individual index sets according to the local submatrix desired.

3932:    When finished using the submatrices, the user should destroy
3933:    them with MatDestroyMatrices().

3935:    MAT_REUSE_MATRIX can only be used when the nonzero structure of the 
3936:    original matrix has not changed from that last call to MatGetSubMatrices().

3938:    This routine creates the matrices in submat; you should NOT create them before
3939:    calling it. It also allocates the array of matrix pointers submat.

3941:    Fortran Note:
3942:    The Fortran interface is slightly different from that given below; it 
3943:    requires one to pass in  as submat a Mat (integer) array of size at least m.

3945:    Level: advanced

3947:    Concepts: matrices^accessing submatrices
3948:    Concepts: submatrices

3950: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
3951: @*/
3952: int MatGetSubMatrices(Mat mat,int n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
3953: {
3954:   int        ierr;

3959:   MatPreallocated(mat);
3960:   if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3961:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3962:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3964:   PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
3965:   (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
3966:   PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
3967:   return(0);
3968: }

3972: /*@C
3973:    MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices().

3975:    Collective on Mat

3977:    Input Parameters:
3978: +  n - the number of local matrices
3979: -  mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
3980:                        sequence of MatGetSubMatrices())

3982:    Level: advanced

3984:     Notes: Frees not only the matrices, but also the array that contains the matrices

3986: .seealso: MatGetSubMatrices()
3987: @*/
3988: int MatDestroyMatrices(int n,Mat *mat[])
3989: {
3990:   int ierr,i;

3993:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %d",n);
3995:   for (i=0; i<n; i++) {
3996:     MatDestroy((*mat)[i]);
3997:   }
3998:   /* memory is allocated even if n = 0 */
3999:   PetscFree(*mat);
4000:   return(0);
4001: }

4005: /*@
4006:    MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4007:    replaces the index sets by larger ones that represent submatrices with
4008:    additional overlap.

4010:    Collective on Mat

4012:    Input Parameters:
4013: +  mat - the matrix
4014: .  n   - the number of index sets
4015: .  is  - the array of index sets (these index sets will changed during the call)
4016: -  ov  - the additional overlap requested

4018:    Level: developer

4020:    Concepts: overlap
4021:    Concepts: ASM^computing overlap

4023: .seealso: MatGetSubMatrices()
4024: @*/
4025: int MatIncreaseOverlap(Mat mat,int n,IS is[],int ov)
4026: {

4032:   MatPreallocated(mat);
4033:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4034:   if (mat->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

4036:   if (!ov) return(0);
4037:   if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4038:   PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
4039:   (*mat->ops->increaseoverlap)(mat,n,is,ov);
4040:   PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
4041:   return(0);
4042: }

4046: /*@
4047:    MatPrintHelp - Prints all the options for the matrix.

4049:    Collective on Mat

4051:    Input Parameter:
4052: .  mat - the matrix 

4054:    Options Database Keys:
4055: +  -help - Prints matrix options
4056: -  -h - Prints matrix options

4058:    Level: developer

4060: .seealso: MatCreate(), MatCreateXXX()
4061: @*/
4062: int MatPrintHelp(Mat mat)
4063: {
4064:   static PetscTruth called = PETSC_FALSE;
4065:   int               ierr;

4070:   MatPreallocated(mat);

4072:   if (!called) {
4073:     if (mat->ops->printhelp) {
4074:       (*mat->ops->printhelp)(mat);
4075:     }
4076:     called = PETSC_TRUE;
4077:   }
4078:   return(0);
4079: }

4083: /*@
4084:    MatGetBlockSize - Returns the matrix block size; useful especially for the
4085:    block row and block diagonal formats.
4086:    
4087:    Not Collective

4089:    Input Parameter:
4090: .  mat - the matrix

4092:    Output Parameter:
4093: .  bs - block size

4095:    Notes:
4096:    Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4097:    Block row formats are MATSEQBAIJ, MATMPIBAIJ

4099:    Level: intermediate

4101:    Concepts: matrices^block size

4103: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4104: @*/
4105: int MatGetBlockSize(Mat mat,int *bs)
4106: {

4112:   MatPreallocated(mat);
4114:   if (!mat->ops->getblocksize) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4115:   (*mat->ops->getblocksize)(mat,bs);
4116:   return(0);
4117: }

4121: /*@C
4122:     MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices.

4124:    Collective on Mat

4126:     Input Parameters:
4127: +   mat - the matrix
4128: .   shift -  0 or 1 indicating we want the indices starting at 0 or 1
4129: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4130:                 symmetrized

4132:     Output Parameters:
4133: +   n - number of rows in the (possibly compressed) matrix
4134: .   ia - the row pointers
4135: .   ja - the column indices
4136: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

4138:     Level: developer

4140: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
4141: @*/
4142: int MatGetRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int *ia[],int* ja[],PetscTruth *done)
4143: {

4149:   MatPreallocated(mat);
4153:   if (!mat->ops->getrowij) *done = PETSC_FALSE;
4154:   else {
4155:     *done = PETSC_TRUE;
4156:     (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
4157:   }
4158:   return(0);
4159: }

4163: /*@C
4164:     MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices.

4166:     Collective on Mat

4168:     Input Parameters:
4169: +   mat - the matrix
4170: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4171: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4172:                 symmetrized

4174:     Output Parameters:
4175: +   n - number of columns in the (possibly compressed) matrix
4176: .   ia - the column pointers
4177: .   ja - the row indices
4178: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

4180:     Level: developer

4182: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
4183: @*/
4184: int MatGetColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int *ia[],int* ja[],PetscTruth *done)
4185: {

4191:   MatPreallocated(mat);

4196:   if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
4197:   else {
4198:     *done = PETSC_TRUE;
4199:     (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
4200:   }
4201:   return(0);
4202: }

4206: /*@C
4207:     MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
4208:     MatGetRowIJ().

4210:     Collective on Mat

4212:     Input Parameters:
4213: +   mat - the matrix
4214: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4215: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4216:                 symmetrized

4218:     Output Parameters:
4219: +   n - size of (possibly compressed) matrix
4220: .   ia - the row pointers
4221: .   ja - the column indices
4222: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

4224:     Level: developer

4226: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
4227: @*/
4228: int MatRestoreRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int *ia[],int* ja[],PetscTruth *done)
4229: {

4235:   MatPreallocated(mat);

4240:   if (!mat->ops->restorerowij) *done = PETSC_FALSE;
4241:   else {
4242:     *done = PETSC_TRUE;
4243:     (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
4244:   }
4245:   return(0);
4246: }

4250: /*@C
4251:     MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
4252:     MatGetColumnIJ().

4254:     Collective on Mat

4256:     Input Parameters:
4257: +   mat - the matrix
4258: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4259: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4260:                 symmetrized

4262:     Output Parameters:
4263: +   n - size of (possibly compressed) matrix
4264: .   ia - the column pointers
4265: .   ja - the row indices
4266: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

4268:     Level: developer

4270: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
4271: @*/
4272: int MatRestoreColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int *ia[],int* ja[],PetscTruth *done)
4273: {

4279:   MatPreallocated(mat);

4284:   if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
4285:   else {
4286:     *done = PETSC_TRUE;
4287:     (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
4288:   }
4289:   return(0);
4290: }

4294: /*@C
4295:     MatColoringPatch -Used inside matrix coloring routines that 
4296:     use MatGetRowIJ() and/or MatGetColumnIJ().

4298:     Collective on Mat

4300:     Input Parameters:
4301: +   mat - the matrix
4302: .   n   - number of colors
4303: -   colorarray - array indicating color for each column

4305:     Output Parameters:
4306: .   iscoloring - coloring generated using colorarray information

4308:     Level: developer

4310: .seealso: MatGetRowIJ(), MatGetColumnIJ()

4312: @*/
4313: int MatColoringPatch(Mat mat,int n,int ncolors,const ISColoringValue colorarray[],ISColoring *iscoloring)
4314: {

4320:   MatPreallocated(mat);

4323:   if (!mat->ops->coloringpatch){
4324:     ISColoringCreate(mat->comm,n,colorarray,iscoloring);
4325:   } else {
4326:     (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);
4327:   }
4328:   return(0);
4329: }


4334: /*@
4335:    MatSetUnfactored - Resets a factored matrix to be treated as unfactored.

4337:    Collective on Mat

4339:    Input Parameter:
4340: .  mat - the factored matrix to be reset

4342:    Notes: 
4343:    This routine should be used only with factored matrices formed by in-place
4344:    factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE
4345:    format).  This option can save memory, for example, when solving nonlinear
4346:    systems with a matrix-free Newton-Krylov method and a matrix-based, in-place
4347:    ILU(0) preconditioner.  

4349:    Note that one can specify in-place ILU(0) factorization by calling 
4350: .vb
4351:      PCType(pc,PCILU);
4352:      PCILUSeUseInPlace(pc);
4353: .ve
4354:    or by using the options -pc_type ilu -pc_ilu_in_place

4356:    In-place factorization ILU(0) can also be used as a local
4357:    solver for the blocks within the block Jacobi or additive Schwarz
4358:    methods (runtime option: -sub_pc_ilu_in_place).  See the discussion 
4359:    of these preconditioners in the users manual for details on setting
4360:    local solver options.

4362:    Most users should employ the simplified SLES interface for linear solvers
4363:    instead of working directly with matrix algebra routines such as this.
4364:    See, e.g., SLESCreate().

4366:    Level: developer

4368: .seealso: PCILUSetUseInPlace(), PCLUSetUseInPlace()

4370:    Concepts: matrices^unfactored

4372: @*/
4373: int MatSetUnfactored(Mat mat)
4374: {

4380:   MatPreallocated(mat);
4381:   mat->factor = 0;
4382:   if (!mat->ops->setunfactored) return(0);
4383:   (*mat->ops->setunfactored)(mat);
4384:   return(0);
4385: }

4387: /*MC
4388:     MatGetArrayF90 - Accesses a matrix array from Fortran90.

4390:     Synopsis:
4391:     MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

4393:     Not collective

4395:     Input Parameter:
4396: .   x - matrix

4398:     Output Parameters:
4399: +   xx_v - the Fortran90 pointer to the array
4400: -   ierr - error code

4402:     Example of Usage: 
4403: .vb
4404:       PetscScalar, pointer xx_v(:)
4405:       ....
4406:       call MatGetArrayF90(x,xx_v,ierr)
4407:       a = xx_v(3)
4408:       call MatRestoreArrayF90(x,xx_v,ierr)
4409: .ve

4411:     Notes:
4412:     Not yet supported for all F90 compilers

4414:     Level: advanced

4416: .seealso:  MatRestoreArrayF90(), MatGetArray(), MatRestoreArray()

4418:     Concepts: matrices^accessing array

4420: M*/

4422: /*MC
4423:     MatRestoreArrayF90 - Restores a matrix array that has been
4424:     accessed with MatGetArrayF90().

4426:     Synopsis:
4427:     MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

4429:     Not collective

4431:     Input Parameters:
4432: +   x - matrix
4433: -   xx_v - the Fortran90 pointer to the array

4435:     Output Parameter:
4436: .   ierr - error code

4438:     Example of Usage: 
4439: .vb
4440:        PetscScalar, pointer xx_v(:)
4441:        ....
4442:        call MatGetArrayF90(x,xx_v,ierr)
4443:        a = xx_v(3)
4444:        call MatRestoreArrayF90(x,xx_v,ierr)
4445: .ve
4446:    
4447:     Notes:
4448:     Not yet supported for all F90 compilers

4450:     Level: advanced

4452: .seealso:  MatGetArrayF90(), MatGetArray(), MatRestoreArray()

4454: M*/


4459: /*@
4460:     MatGetSubMatrix - Gets a single submatrix on the same number of processors
4461:                       as the original matrix.

4463:     Collective on Mat

4465:     Input Parameters:
4466: +   mat - the original matrix
4467: .   isrow - rows this processor should obtain
4468: .   iscol - columns for all processors you wish to keep
4469: .   csize - number of columns "local" to this processor (does nothing for sequential 
4470:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
4471:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
4472: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

4474:     Output Parameter:
4475: .   newmat - the new submatrix, of the same type as the old

4477:     Level: advanced

4479:     Notes: the iscol argument MUST be the same on each processor. You might be 
4480:     able to create the iscol argument with ISAllGather().

4482:       The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
4483:    the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
4484:    to this routine with a mat of the same nonzero structure will reuse the matrix
4485:    generated the first time.

4487:     Concepts: matrices^submatrices

4489: .seealso: MatGetSubMatrices(), ISAllGather()
4490: @*/
4491: int MatGetSubMatrix(Mat mat,IS isrow,IS iscol,int csize,MatReuse cll,Mat *newmat)
4492: {
4493:   int     ierr, size;
4494:   Mat     *local;

4498:   MatPreallocated(mat);
4499:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4500:   MPI_Comm_size(mat->comm,&size);

4502:   /* if original matrix is on just one processor then use submatrix generated */
4503:   if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
4504:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
4505:     return(0);
4506:   } else if (!mat->ops->getsubmatrix && size == 1) {
4507:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
4508:     *newmat = *local;
4509:     PetscFree(local);
4510:     return(0);
4511:   }

4513:   if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4514:   (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
4515:   return(0);
4516: }

4520: /*@C
4521:    MatGetPetscMaps - Returns the maps associated with the matrix.

4523:    Not Collective

4525:    Input Parameter:
4526: .  mat - the matrix

4528:    Output Parameters:
4529: +  rmap - the row (right) map
4530: -  cmap - the column (left) map  

4532:    Level: developer

4534:    Concepts: maps^getting from matrix

4536: @*/
4537: int MatGetPetscMaps(Mat mat,PetscMap *rmap,PetscMap *cmap)
4538: {

4544:   MatPreallocated(mat);
4545:   (*mat->ops->getmaps)(mat,rmap,cmap);
4546:   return(0);
4547: }

4549: /*
4550:       Version that works for all PETSc matrices
4551: */
4554: int MatGetPetscMaps_Petsc(Mat mat,PetscMap *rmap,PetscMap *cmap)
4555: {
4557:   if (rmap) *rmap = mat->rmap;
4558:   if (cmap) *cmap = mat->cmap;
4559:   return(0);
4560: }

4564: /*@
4565:    MatSetStashInitialSize - sets the sizes of the matrix stash, that is
4566:    used during the assembly process to store values that belong to 
4567:    other processors.

4569:    Not Collective

4571:    Input Parameters:
4572: +  mat   - the matrix
4573: .  size  - the initial size of the stash.
4574: -  bsize - the initial size of the block-stash(if used).

4576:    Options Database Keys:
4577: +   -matstash_initial_size <size> or <size0,size1,...sizep-1>
4578: -   -matstash_block_initial_size <bsize>  or <bsize0,bsize1,...bsizep-1>

4580:    Level: intermediate

4582:    Notes: 
4583:      The block-stash is used for values set with VecSetValuesBlocked() while
4584:      the stash is used for values set with VecSetValues()

4586:      Run with the option -log_info and look for output of the form
4587:      MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
4588:      to determine the appropriate value, MM, to use for size and 
4589:      MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
4590:      to determine the value, BMM to use for bsize

4592:    Concepts: stash^setting matrix size
4593:    Concepts: matrices^stash

4595: @*/
4596: int MatSetStashInitialSize(Mat mat,int size, int bsize)
4597: {

4603:   MatPreallocated(mat);
4604:   MatStashSetInitialSize_Private(&mat->stash,size);
4605:   MatStashSetInitialSize_Private(&mat->bstash,bsize);
4606:   return(0);
4607: }

4611: /*@
4612:    MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 
4613:      the matrix

4615:    Collective on Mat

4617:    Input Parameters:
4618: +  mat   - the matrix
4619: .  x,y - the vectors
4620: -  w - where the result is stored

4622:    Level: intermediate

4624:    Notes: 
4625:     w may be the same vector as y. 

4627:     This allows one to use either the restriction or interpolation (its transpose)
4628:     matrix to do the interpolation

4630:     Concepts: interpolation

4632: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()

4634: @*/
4635: int MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
4636: {
4637:   int M,N,ierr;

4641:   MatPreallocated(A);
4642:   MatGetSize(A,&M,&N);
4643:   if (N > M) {
4644:     MatMultTransposeAdd(A,x,y,w);
4645:   } else {
4646:     MatMultAdd(A,x,y,w);
4647:   }
4648:   return(0);
4649: }

4653: /*@
4654:    MatInterpolate - y = A*x or A'*x depending on the shape of 
4655:      the matrix

4657:    Collective on Mat

4659:    Input Parameters:
4660: +  mat   - the matrix
4661: -  x,y - the vectors

4663:    Level: intermediate

4665:    Notes: 
4666:     This allows one to use either the restriction or interpolation (its transpose)
4667:     matrix to do the interpolation

4669:    Concepts: matrices^interpolation

4671: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()

4673: @*/
4674: int MatInterpolate(Mat A,Vec x,Vec y)
4675: {
4676:   int M,N,ierr;

4680:   MatPreallocated(A);
4681:   MatGetSize(A,&M,&N);
4682:   if (N > M) {
4683:     MatMultTranspose(A,x,y);
4684:   } else {
4685:     MatMult(A,x,y);
4686:   }
4687:   return(0);
4688: }

4692: /*@
4693:    MatRestrict - y = A*x or A'*x

4695:    Collective on Mat

4697:    Input Parameters:
4698: +  mat   - the matrix
4699: -  x,y - the vectors

4701:    Level: intermediate

4703:    Notes: 
4704:     This allows one to use either the restriction or interpolation (its transpose)
4705:     matrix to do the restriction

4707:    Concepts: matrices^restriction

4709: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate()

4711: @*/
4712: int MatRestrict(Mat A,Vec x,Vec y)
4713: {
4714:   int M,N,ierr;

4718:   MatPreallocated(A);
4719:   MatGetSize(A,&M,&N);
4720:   if (N > M) {
4721:     MatMult(A,x,y);
4722:   } else {
4723:     MatMultTranspose(A,x,y);
4724:   }
4725:   return(0);
4726: }

4730: /*@C
4731:    MatNullSpaceAttach - attaches a null space to a matrix.
4732:         This null space will be removed from the resulting vector whenever
4733:         MatMult() is called

4735:    Collective on Mat

4737:    Input Parameters:
4738: +  mat - the matrix
4739: -  nullsp - the null space object

4741:    Level: developer

4743:    Notes:
4744:       Overwrites any previous null space that may have been attached

4746:    Concepts: null space^attaching to matrix

4748: .seealso: MatCreate(), MatNullSpaceCreate()
4749: @*/
4750: int MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
4751: {

4757:   MatPreallocated(mat);

4760:   if (mat->nullsp) {
4761:     MatNullSpaceDestroy(mat->nullsp);
4762:   }
4763:   mat->nullsp = nullsp;
4764:   PetscObjectReference((PetscObject)nullsp);
4765:   return(0);
4766: }

4770: /*@  
4771:    MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.

4773:    Collective on Mat

4775:    Input Parameters:
4776: +  mat - the matrix
4777: .  row - row/column permutation
4778: .  fill - expected fill factor >= 1.0
4779: -  level - level of fill, for ICC(k)

4781:    Notes: 
4782:    Probably really in-place only when level of fill is zero, otherwise allocates
4783:    new space to store factored matrix and deletes previous memory.

4785:    Most users should employ the simplified SLES interface for linear solvers
4786:    instead of working directly with matrix algebra routines such as this.
4787:    See, e.g., SLESCreate().

4789:    Level: developer

4791:    Concepts: matrices^incomplete Cholesky factorization
4792:    Concepts: Cholesky factorization

4794: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4795: @*/
4796: int MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
4797: {

4803:   MatPreallocated(mat);
4804:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
4805:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4806:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4807:   if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4808:   (*mat->ops->iccfactor)(mat,row,info);
4809:   return(0);
4810: }

4814: /*@ 
4815:    MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix.

4817:    Not Collective

4819:    Input Parameters:
4820: +  mat - the matrix
4821: -  v - the values compute with ADIC

4823:    Level: developer

4825:    Notes:
4826:      Must call MatSetColoring() before using this routine. Also this matrix must already
4827:      have its nonzero pattern determined.

4829: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
4830:           MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
4831: @*/
4832: int MatSetValuesAdic(Mat mat,void *v)
4833: {


4840:   if (!mat->assembled) {
4841:     SETERRQ(1,"Matrix must be already assembled");
4842:   }
4843:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
4844:   if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4845:   (*mat->ops->setvaluesadic)(mat,v);
4846:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
4847:   MatView_Private(mat);
4848:   return(0);
4849: }


4854: /*@ 
4855:    MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic()

4857:    Not Collective

4859:    Input Parameters:
4860: +  mat - the matrix
4861: -  coloring - the coloring

4863:    Level: developer

4865: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
4866:           MatSetValues(), MatSetValuesAdic()
4867: @*/
4868: int MatSetColoring(Mat mat,ISColoring coloring)
4869: {


4876:   if (!mat->assembled) {
4877:     SETERRQ(1,"Matrix must be already assembled");
4878:   }
4879:   if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4880:   (*mat->ops->setcoloring)(mat,coloring);
4881:   return(0);
4882: }

4886: /*@ 
4887:    MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix.

4889:    Not Collective

4891:    Input Parameters:
4892: +  mat - the matrix
4893: .  nl - leading dimension of v
4894: -  v - the values compute with ADIFOR

4896:    Level: developer

4898:    Notes:
4899:      Must call MatSetColoring() before using this routine. Also this matrix must already
4900:      have its nonzero pattern determined.

4902: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
4903:           MatSetValues(), MatSetColoring()
4904: @*/
4905: int MatSetValuesAdifor(Mat mat,int nl,void *v)
4906: {


4913:   if (!mat->assembled) {
4914:     SETERRQ(1,"Matrix must be already assembled");
4915:   }
4916:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
4917:   if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4918:   (*mat->ops->setvaluesadifor)(mat,nl,v);
4919:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
4920:   return(0);
4921: }

4923: EXTERN int MatMPIAIJDiagonalScaleLocal(Mat,Vec);
4924: EXTERN int MatMPIBAIJDiagonalScaleLocal(Mat,Vec);

4928: /*@ 
4929:    MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 
4930:          ghosted ones.

4932:    Not Collective

4934:    Input Parameters:
4935: +  mat - the matrix
4936: -  diag = the diagonal values, including ghost ones

4938:    Level: developer

4940:    Notes: Works only for MPIAIJ and MPIBAIJ matrices
4941:       
4942: .seealso: MatDiagonalScale()
4943: @*/
4944: int MatDiagonalScaleLocal(Mat mat,Vec diag)
4945: {
4946:   int        ierr,size;


4953:   if (!mat->assembled) {
4954:     SETERRQ(1,"Matrix must be already assembled");
4955:   }
4956:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
4957:   MPI_Comm_size(mat->comm,&size);
4958:   if (size == 1) {
4959:     int n,m;
4960:     VecGetSize(diag,&n);
4961:     MatGetSize(mat,0,&m);
4962:     if (m == n) {
4963:       MatDiagonalScale(mat,0,diag);
4964:     } else {
4965:       SETERRQ(1,"Only supprted for sequential matrices when no ghost points/periodic conditions");
4966:     }
4967:   } else {
4968:     int (*f)(Mat,Vec);
4969:     PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
4970:     if (f) {
4971:       (*f)(mat,diag);
4972:     } else {
4973:       SETERRQ(1,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
4974:     }
4975:   }
4976:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
4977:   return(0);
4978: }

4982: /*@ 
4983:    MatGetInertia - Gets the inertia from a factored matrix

4985:    Collective on Mat

4987:    Input Parameter:
4988: .  mat - the matrix

4990:    Output Parameters:
4991: +   nneg - number of negative eigenvalues
4992: .   nzero - number of zero eigenvalues
4993: -   npos - number of positive eigenvalues

4995:    Level: advanced

4997:    Notes: Matrix must have been factored by MatCholeskyFactor()


5000: @*/
5001: int MatGetInertia(Mat mat,int *nneg,int *nzero,int *npos)
5002: {
5003:   int        ierr;

5008:   if (!mat->factor)    SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5009:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5010:   if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5011:   (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5012:   return(0);
5013: }

5015: /* ----------------------------------------------------------------*/
5018: /*@
5019:    MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors

5021:    Collective on Mat and Vecs

5023:    Input Parameters:
5024: +  mat - the factored matrix
5025: -  b - the right-hand-side vectors

5027:    Output Parameter:
5028: .  x - the result vectors

5030:    Notes:
5031:    The vectors b and x cannot be the same.  I.e., one cannot
5032:    call MatSolves(A,x,x).

5034:    Notes:
5035:    Most users should employ the simplified SLES interface for linear solvers
5036:    instead of working directly with matrix algebra routines such as this.
5037:    See, e.g., SLESCreate().

5039:    Level: developer

5041:    Concepts: matrices^triangular solves

5043: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
5044: @*/
5045: int MatSolves(Mat mat,Vecs b,Vecs x)
5046: {

5052:   MatPreallocated(mat);
5053:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
5054:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5055:   if (mat->M == 0 && mat->N == 0) return(0);

5057:   if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5058:   PetscLogEventBegin(MAT_Solves,mat,0,0,0);
5059:   (*mat->ops->solves)(mat,b,x);
5060:   PetscLogEventEnd(MAT_Solves,mat,0,0,0);
5061:   return(0);
5062: }