Actual source code: matrix.c

  1: /*$Id: matrix.c,v 1.402 2001/04/10 22:35:02 balay Exp $*/

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

  7: #include "src/mat/matimpl.h"        /*I "petscmat.h" I*/
  8: #include "src/vec/vecimpl.h"  

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

 15:    Not Collective

 17:    Input Parameters:
 18: +  mat - the matrix
 19: -  row - the row to get

 21:    Output Parameters:
 22: +  ncols -  the number of nonzeros in the row
 23: .  cols - if not NULL, the column numbers
 24: -  vals - if not NULL, the values

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

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

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

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

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

 48:    Fortran Notes:
 49:    The calling sequence from Fortran is 
 50: .vb
 51:    MatGetRow(matrix,row,ncols,cols,values,ierr)
 52:          Mat     matrix (input)
 53:          integer row    (input)
 54:          integer ncols  (output)
 55:          integer cols(maxcols) (output)
 56:          double precision (or double complex) values(maxcols) output
 57: .ve
 58:    where maxcols >= maximum nonzeros in any row of the matrix.

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

 64:    Level: advanced

 66:    Concepts: matrices^row access

 68: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
 69: @*/
 70: int MatGetRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals)
 71: {
 72:   int   ierr;

 78:   MatPreallocated(mat);
 79:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
 80:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
 81:   if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
 82:   PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
 83:   (*mat->ops->getrow)(mat,row,ncols,cols,vals);
 84:   PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
 85:   return(0);
 86: }

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

 91:    Not Collective

 93:    Input Parameters:
 94: +  mat - the matrix
 95: .  row - the row to get
 96: .  ncols, cols - the number of nonzeros and their columns
 97: -  vals - if nonzero the column values

 99:    Notes: 
100:    This routine should be called after you have finished examining the entries.

102:    Fortran Notes:
103:    The calling sequence from Fortran is 
104: .vb
105:    MatRestoreRow(matrix,row,ncols,cols,values,ierr)
106:       Mat     matrix (input)
107:       integer row    (input)
108:       integer ncols  (output)
109:       integer cols(maxcols) (output)
110:       double precision (or double complex) values(maxcols) output
111: .ve
112:    Where maxcols >= maximum nonzeros in any row of the matrix. 

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

117:    Level: advanced

119: .seealso:  MatGetRow()
120: @*/
121: int MatRestoreRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals)
122: {

128:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
129:   if (!mat->ops->restorerow) return(0);
130:   (*mat->ops->restorerow)(mat,row,ncols,cols,vals);
131:   return(0);
132: }

134: /*@C
135:    MatView - Visualizes a matrix object.

137:    Collective on Mat

139:    Input Parameters:
140: +  mat - the matrix
141: -  ptr - visualization context

143:   Notes:
144:   The available visualization contexts include
145: +    PETSC_VIEWER_STDOUT_SELF - standard output (default)
146: .    PETSC_VIEWER_STDOUT_WORLD - synchronized standard
147:         output where only the first processor opens
148:         the file.  All other processors send their 
149:         data to the first processor to print. 
150: -     PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure

152:    The user can open alternative visualization contexts with
153: +    PetscViewerASCIIOpen() - Outputs matrix to a specified file
154: .    PetscViewerBinaryOpen() - Outputs matrix in binary to a
155:          specified file; corresponding input uses MatLoad()
156: .    PetscViewerDrawOpen() - Outputs nonzero matrix structure to 
157:          an X window display
158: -    PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
159:          Currently only the sequential dense and AIJ
160:          matrix types support the Socket viewer.

162:    The user can call PetscViewerSetFormat() to specify the output
163:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
164:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
165: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
166: .    PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
167: .    PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
168: .    PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 
169:          format common among all matrix types
170: .    PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 
171:          format (which is in many cases the same as the default)
172: .    PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
173:          size and structure (not the matrix entries)
174: -    PETSC_VIEWER_ASCII_INFO_LONG - prints more detailed information about
175:          the matrix structure

177:    Level: beginner

179:    Concepts: matrices^viewing
180:    Concepts: matrices^plotting
181:    Concepts: matrices^printing

183: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 
184:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
185: @*/
186: int MatView(Mat mat,PetscViewer viewer)
187: {
188:   int               ierr,rows,cols;
189:   PetscTruth        isascii;
190:   char              *cstr;
191:   PetscViewerFormat format;

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

202:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);
203:   if (isascii) {
204:     PetscViewerGetFormat(viewer,&format);
205:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_LONG) {
206:       PetscViewerASCIIPrintf(viewer,"Matrix Object:n");
207:       PetscViewerASCIIPushTab(viewer);
208:       MatGetType(mat,&cstr);
209:       MatGetSize(mat,&rows,&cols);
210:       PetscViewerASCIIPrintf(viewer,"type=%s, rows=%d, cols=%dn",cstr,rows,cols);
211:       if (mat->ops->getinfo) {
212:         MatInfo info;
213:         MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
214:         PetscViewerASCIIPrintf(viewer,"total: nonzeros=%d, allocated nonzeros=%dn",
215:                           (int)info.nz_used,(int)info.nz_allocated);
216:       }
217:     }
218:   }
219:   if (mat->ops->view) {
220:     PetscViewerASCIIPushTab(viewer);
221:     (*mat->ops->view)(mat,viewer);
222:     PetscViewerASCIIPopTab(viewer);
223:   } else if (!isascii) {
224:     SETERRQ1(1,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
225:   }
226:   if (isascii) {
227:     PetscViewerGetFormat(viewer,&format);
228:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_LONG) {
229:       PetscViewerASCIIPopTab(viewer);
230:     }
231:   }
232:   return(0);
233: }

235: /*@C
236:    MatScaleSystem - Scale a vector solution and right hand side to 
237:    match the scaling of a scaled matrix.
238:   
239:    Collective on Mat

241:    Input Parameter:
242: +  mat - the matrix
243: .  x - solution vector (or PETSC_NULL)
244: +  b - right hand side vector (or PETSC_NULL)


247:    Notes: 
248:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
249:    internally scaled, so this does nothing. For MPIROWBS it
250:    permutes and diagonally scales.

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

255:    Level: Developer            

257:    Concepts: matrices^scaling

259: .seealso: MatUseScaledForm(), MatUnScaleSystem()
260: @*/
261: int MatScaleSystem(Mat mat,Vec x,Vec b)
262: {

268:   MatPreallocated(mat);

272:   if (mat->ops->scalesystem) {
273:     (*mat->ops->scalesystem)(mat,x,b);
274:   }
275:   return(0);
276: }

278: /*@C
279:    MatUnScaleSystem - Unscales a vector solution and right hand side to 
280:    match the original scaling of a scaled matrix.
281:   
282:    Collective on Mat

284:    Input Parameter:
285: +  mat - the matrix
286: .  x - solution vector (or PETSC_NULL)
287: +  b - right hand side vector (or PETSC_NULL)


290:    Notes: 
291:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
292:    internally scaled, so this does nothing. For MPIROWBS it
293:    permutes and diagonally scales.

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

298:    Level: Developer            

300: .seealso: MatUseScaledForm(), MatScaleSystem()
301: @*/
302: int MatUnScaleSystem(Mat mat,Vec x,Vec b)
303: {

309:   MatPreallocated(mat);
312:   if (mat->ops->unscalesystem) {
313:     (*mat->ops->unscalesystem)(mat,x,b);
314:   }
315:   return(0);
316: }

318: /*@C
319:    MatUseScaledForm - For matrix storage formats that scale the 
320:    matrix (for example MPIRowBS matrices are diagonally scaled on
321:    assembly) indicates matrix operations (MatMult() etc) are 
322:    applied using the scaled matrix.
323:   
324:    Collective on Mat

326:    Input Parameter:
327: +  mat - the matrix
328: -  scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 
329:             applying the original matrix

331:    Notes: 
332:    For scaled matrix formats, applying the original, unscaled matrix
333:    will be slightly more expensive

335:    Level: Developer            

337: .seealso: MatScaleSystem(), MatUnScaleSystem()
338: @*/
339: int MatUseScaledForm(Mat mat,PetscTruth scaled)
340: {

346:   MatPreallocated(mat);
347:   if (mat->ops->usescaledform) {
348:     (*mat->ops->usescaledform)(mat,scaled);
349:   }
350:   return(0);
351: }

353: /*@C
354:    MatDestroy - Frees space taken by a matrix.
355:   
356:    Collective on Mat

358:    Input Parameter:
359: .  A - the matrix

361:    Level: beginner

363: @*/
364: int MatDestroy(Mat A)
365: {

371:   MatPreallocated(A);
372:   if (--A->refct > 0) return(0);

374:   /* if memory was published with AMS then destroy it */
375:   PetscObjectDepublish(A);
376:   if (A->mapping) {
377:     ISLocalToGlobalMappingDestroy(A->mapping);
378:   }
379:   if (A->bmapping) {
380:     ISLocalToGlobalMappingDestroy(A->bmapping);
381:   }
382:   if (A->rmap) {
383:     MapDestroy(A->rmap);
384:   }
385:   if (A->cmap) {
386:     MapDestroy(A->cmap);
387:   }

389:   (*A->ops->destroy)(A);
390:   PetscLogObjectDestroy(A);
391:   PetscHeaderDestroy(A);
392:   return(0);
393: }

395: /*@
396:    MatValid - Checks whether a matrix object is valid.

398:    Collective on Mat

400:    Input Parameter:
401: .  m - the matrix to check 

403:    Output Parameter:
404:    flg - flag indicating matrix status, either
405:    PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.

407:    Level: developer

409:    Concepts: matrices^validity
410: @*/
411: int MatValid(Mat m,PetscTruth *flg)
412: {
415:   if (!m)                           *flg = PETSC_FALSE;
416:   else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
417:   else                              *flg = PETSC_TRUE;
418:   return(0);
419: }

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

426:    Not Collective

428:    Input Parameters:
429: +  mat - the matrix
430: .  v - a logically two-dimensional array of values
431: .  m, idxm - the number of rows and their global indices 
432: .  n, idxn - the number of columns and their global indices
433: -  addv - either ADD_VALUES or INSERT_VALUES, where
434:    ADD_VALUES adds values to any existing entries, and
435:    INSERT_VALUES replaces existing entries with new values

437:    Notes:
438:    By default the values, v, are row-oriented and unsorted.
439:    See MatSetOption() for other options.

441:    Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 
442:    options cannot be mixed without intervening calls to the assembly
443:    routines.

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

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

453:    Efficiency Alert:
454:    The routine MatSetValuesBlocked() may offer much better efficiency
455:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

457:    Level: beginner

459:    Concepts: matrices^putting entries in

461: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
462: @*/
463: int MatSetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv)
464: {

468:   if (!m || !n) return(0); /* no values to insert */
471:   MatPreallocated(mat);
475:   if (mat->insertmode == NOT_SET_VALUES) {
476:     mat->insertmode = addv;
477:   }
478: #if defined(PETSC_USE_BOPT_g)
479:   else if (mat->insertmode != addv) {
480:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
481:   }
482:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
483: #endif

485:   if (mat->assembled) {
486:     mat->was_assembled = PETSC_TRUE;
487:     mat->assembled     = PETSC_FALSE;
488:   }
489:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
490:   if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
491:   (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
492:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
493:   return(0);
494: }

496: /*@C 
497:    MatSetValuesStencil - Inserts or adds a block of values into a matrix.
498:      Using structured grid indexing

500:    Not Collective

502:    Input Parameters:
503: +  mat - the matrix
504: .  v - a logically two-dimensional array of values
505: .  m - number of rows being entered
506: .  idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
507: .  n - number of columns being entered
508: .  idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 
509: -  addv - either ADD_VALUES or INSERT_VALUES, where
510:    ADD_VALUES adds values to any existing entries, and
511:    INSERT_VALUES replaces existing entries with new values

513:    Notes:
514:    By default the values, v, are row-oriented and unsorted.
515:    See MatSetOption() for other options.

517:    Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 
518:    options cannot be mixed without intervening calls to the assembly
519:    routines.

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

524:    In Fortran idxm and idxn should be declared as
525: $     MatStencil idxm(4,m),idxn(4,n)
526:    and the values inserted using
527: $    idxm(MatStencil_i,1) = i
528: $    idxm(MatStencil_j,1) = j
529: $    idxm(MatStencil_k,1) = k
530:    etc

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

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

540:    Efficiency Alert:
541:    The routine MatSetValuesBlockedStencil() may offer much better efficiency
542:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

544:    Level: beginner

546:    Concepts: matrices^putting entries in

548: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
549:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil()
550: @*/
551: int MatSetValuesStencil(Mat mat,int m,MatStencil *idxm,int n,MatStencil *idxn,Scalar *v,InsertMode addv)
552: {
553:   int j,i,ierr,jdxm[128],jdxn[128],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
554:   int *starts = mat->stencil.starts,*dxm = (int*)idxm,*dxn = (int*)idxn,sdim = dim - (1 - (int)mat->stencil.noc);

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

564:   for (i=0; i<m; i++) {
565:     for (j=0; j<3-sdim; j++) dxm++;
566:     tmp = *dxm++ - starts[0];
567:     for (j=0; j<dim-1; j++) {
568:       tmp = tmp*dims[j] + *dxm++ - starts[j+1];
569:     }
570:     if (mat->stencil.noc) dxm++;
571:     jdxm[i] = tmp;
572:   }
573:   for (i=0; i<n; i++) {
574:     for (j=0; j<3-sdim; j++) dxn++;
575:     tmp = *dxn++ - starts[0];
576:     for (j=0; j<dim-1; j++) {
577:       tmp = tmp*dims[j] + *dxn++ - starts[j+1];
578:     }
579:     if (mat->stencil.noc) dxn++;
580:     jdxn[i] = tmp;
581:   }
582:   MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
583:   return(0);
584: }

586: /*@ 
587:    MatSetStencil - Sets the grid information for setting values into a matrix via
588:         MatSetStencil()

590:    Not Collective

592:    Input Parameters:
593: +  mat - the matrix
594: .  dim - dimension of the grid 1,2, or 3
595: .  dims - number of grid points in x, y, and z direction, including ghost points on your processor
596: .  starts - starting point of ghost nodes on your processor in x, y, and z direction 
597: -  dof - number of degrees of freedom per node


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

603:    Level: beginner

605:    Concepts: matrices^putting entries in

607: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
608:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
609: @*/
610: int MatSetStencil(Mat mat,int dim,int *dims,int *starts,int dof)
611: {
612:   int i;


619:   mat->stencil.dim = dim + (dof > 1);
620:   for (i=0; i<dim; i++) {
621:     mat->stencil.dims[i]   = dims[dim-i-1];      /* copy the values in backwards */
622:     mat->stencil.starts[i] = starts[dim-i-1];
623:   }
624:   mat->stencil.dims[dim]   = dof;
625:   mat->stencil.starts[dim] = 0;
626:   mat->stencil.noc         = (PetscTruth)(dof == 1);
627:   return(0);
628: }

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

633:    Not Collective

635:    Input Parameters:
636: +  mat - the matrix
637: .  v - a logically two-dimensional array of values
638: .  m, idxm - the number of block rows and their global block indices 
639: .  n, idxn - the number of block columns and their global block indices
640: -  addv - either ADD_VALUES or INSERT_VALUES, where
641:    ADD_VALUES adds values to any existing entries, and
642:    INSERT_VALUES replaces existing entries with new values

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

648:    Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
649:    options cannot be mixed without intervening calls to the assembly
650:    routines.

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

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

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

666:    Restrictions:
667:    MatSetValuesBlocked() is currently supported only for the block AIJ
668:    matrix format (MATSEQBAIJ and MATMPIBAIJ, which are created via
669:    MatCreateSeqBAIJ() and MatCreateMPIBAIJ()).

671:    Level: intermediate

673:    Concepts: matrices^putting entries in blocked

675: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
676: @*/
677: int MatSetValuesBlocked(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv)
678: {

682:   if (!m || !n) return(0); /* no values to insert */
685:   MatPreallocated(mat);
689:   if (mat->insertmode == NOT_SET_VALUES) {
690:     mat->insertmode = addv;
691:   }
692: #if defined(PETSC_USE_BOPT_g) 
693:   else if (mat->insertmode != addv) {
694:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
695:   }
696:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
697: #endif

699:   if (mat->assembled) {
700:     mat->was_assembled = PETSC_TRUE;
701:     mat->assembled     = PETSC_FALSE;
702:   }
703:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
704:   if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
705:   (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
706:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
707:   return(0);
708: }

710: /*MC
711:    MatSetValue - Set a single entry into a matrix.

713:    Synopsis:
714:    void MatSetValue(Mat m,int row,int col,Scalar value,InsertMode mode);

716:    Not collective

718:    Input Parameters:
719: +  m - the matrix
720: .  row - the row location of the entry
721: .  col - the column location of the entry
722: .  value - the value to insert
723: -  mode - either INSERT_VALUES or ADD_VALUES

725:    Notes: 
726:    For efficiency one should use MatSetValues() and set several or many
727:    values simultaneously if possible.

729:    Note that VecSetValue() does NOT return an error code (since this
730:    is checked internally).

732:    Level: beginner

734: .seealso: MatSetValues()
735: M*/

737: /*@ 
738:    MatGetValues - Gets a block of values from a matrix.

740:    Not Collective; currently only returns a local block

742:    Input Parameters:
743: +  mat - the matrix
744: .  v - a logically two-dimensional array for storing the values
745: .  m, idxm - the number of rows and their global indices 
746: -  n, idxn - the number of columns and their global indices

748:    Notes:
749:    The user must allocate space (m*n Scalars) for the values, v.
750:    The values, v, are then returned in a row-oriented format, 
751:    analogous to that used by default in MatSetValues().

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

756:    MatGetValues() requires that the matrix has been assembled
757:    with MatAssemblyBegin()/MatAssemblyEnd().  Thus, calls to
758:    MatSetValues() and MatGetValues() CANNOT be made in succession
759:    without intermediate matrix assembly.

761:    Level: advanced

763:    Concepts: matrices^accessing values

765: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
766: @*/
767: int MatGetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v)
768: {

774:   MatPreallocated(mat);
778:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
779:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
780:   if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

782:   PetscLogEventBegin(MAT_GetValues,mat,0,0,0);
783:   (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
784:   PetscLogEventEnd(MAT_GetValues,mat,0,0,0);
785:   return(0);
786: }

788: /*@
789:    MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
790:    the routine MatSetValuesLocal() to allow users to insert matrix entries
791:    using a local (per-processor) numbering.

793:    Not Collective

795:    Input Parameters:
796: +  x - the matrix
797: -  mapping - mapping created with ISLocalToGlobalMappingCreate() 
798:              or ISLocalToGlobalMappingCreateIS()

800:    Level: intermediate

802:    Concepts: matrices^local to global mapping
803:    Concepts: local to global mapping^for matrices

805: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
806: @*/
807: int MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
808: {
813:   MatPreallocated(x);
815:   if (x->mapping) {
816:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
817:   }

819:   if (x->ops->setlocaltoglobalmapping) {
820:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
821:   } else {
822:     x->mapping = mapping;
823:     PetscObjectReference((PetscObject)mapping);
824:   }
825:   return(0);
826: }

828: /*@
829:    MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
830:    by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
831:    entries using a local (per-processor) numbering.

833:    Not Collective

835:    Input Parameters:
836: +  x - the matrix
837: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or
838:              ISLocalToGlobalMappingCreateIS()

840:    Level: intermediate

842:    Concepts: matrices^local to global mapping blocked
843:    Concepts: local to global mapping^for matrices, blocked

845: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
846:            MatSetValuesBlocked(), MatSetValuesLocal()
847: @*/
848: int MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
849: {
854:   MatPreallocated(x);
856:   if (x->bmapping) {
857:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
858:   }
859: 
860:   x->bmapping = mapping;
861:   PetscObjectReference((PetscObject)mapping);
862:   return(0);
863: }

865: /*@
866:    MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
867:    using a local ordering of the nodes. 

869:    Not Collective

871:    Input Parameters:
872: +  x - the matrix
873: .  nrow, irow - number of rows and their local indices
874: .  ncol, icol - number of columns and their local indices
875: .  y -  a logically two-dimensional array of values
876: -  addv - either INSERT_VALUES or ADD_VALUES, where
877:    ADD_VALUES adds values to any existing entries, and
878:    INSERT_VALUES replaces existing entries with new values

880:    Notes:
881:    Before calling MatSetValuesLocal(), the user must first set the
882:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

884:    Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 
885:    options cannot be mixed without intervening calls to the assembly
886:    routines.

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

891:    Level: intermediate

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

895: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
896:            MatSetValueLocal()
897: @*/
898: int MatSetValuesLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv)
899: {
900:   int ierr,irowm[2048],icolm[2048];

905:   MatPreallocated(mat);

910:   if (mat->insertmode == NOT_SET_VALUES) {
911:     mat->insertmode = addv;
912:   }
913: #if defined(PETSC_USE_BOPT_g) 
914:   else if (mat->insertmode != addv) {
915:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
916:   }
917:   if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
918:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
919:   }
920:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
921: #endif

923:   if (mat->assembled) {
924:     mat->was_assembled = PETSC_TRUE;
925:     mat->assembled     = PETSC_FALSE;
926:   }
927:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
928:   if (!mat->ops->setvalueslocal) {
929:     ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
930:     ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
931:     (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
932:   } else {
933:     (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
934:   }
935:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
936:   return(0);
937: }

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

943:    Not Collective

945:    Input Parameters:
946: +  x - the matrix
947: .  nrow, irow - number of rows and their local indices
948: .  ncol, icol - number of columns and their local indices
949: .  y -  a logically two-dimensional array of values
950: -  addv - either INSERT_VALUES or ADD_VALUES, where
951:    ADD_VALUES adds values to any existing entries, and
952:    INSERT_VALUES replaces existing entries with new values

954:    Notes:
955:    Before calling MatSetValuesBlockedLocal(), the user must first set the
956:    local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
957:    where the mapping MUST be set for matrix blocks, not for matrix elements.

959:    Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
960:    options cannot be mixed without intervening calls to the assembly
961:    routines.

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

966:    Level: intermediate

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

970: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
971: @*/
972: int MatSetValuesBlockedLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv)
973: {
974:   int ierr,irowm[2048],icolm[2048];

979:   MatPreallocated(mat);
983:   if (mat->insertmode == NOT_SET_VALUES) {
984:     mat->insertmode = addv;
985:   }
986: #if defined(PETSC_USE_BOPT_g) 
987:   else if (mat->insertmode != addv) {
988:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
989:   }
990:   if (!mat->bmapping) {
991:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
992:   }
993:   if (nrow > 2048 || ncol > 2048) {
994:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
995:   }
996:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
997: #endif

999:   if (mat->assembled) {
1000:     mat->was_assembled = PETSC_TRUE;
1001:     mat->assembled     = PETSC_FALSE;
1002:   }
1003:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1004:   ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1005:   ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1006:   (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1007:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1008:   return(0);
1009: }

1011: /* --------------------------------------------------------*/
1012: /*@
1013:    MatMult - Computes the matrix-vector product, y = Ax.

1015:    Collective on Mat and Vec

1017:    Input Parameters:
1018: +  mat - the matrix
1019: -  x   - the vector to be multilplied

1021:    Output Parameters:
1022: .  y - the result

1024:    Notes:
1025:    The vectors x and y cannot be the same.  I.e., one cannot
1026:    call MatMult(A,y,y).

1028:    Level: beginner

1030:    Concepts: matrix-vector product

1032: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1033: @*/
1034: int MatMult(Mat mat,Vec x,Vec y)
1035: {

1041:   MatPreallocated(mat);

1045:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1046:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1047:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1048:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1049:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1050:   if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %d %d",mat->m,y->n);

1052:   if (mat->nullsp) {
1053:     MatNullSpaceRemove(mat->nullsp,x,&x);
1054:   }

1056:   PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1057:   (*mat->ops->mult)(mat,x,y);
1058:   PetscLogEventEnd(MAT_Mult,mat,x,y,0);

1060:   if (mat->nullsp) {
1061:     MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1062:   }
1063:   return(0);
1064: }

1066: /*@
1067:    MatMultTranspose - Computes matrix transpose times a vector.

1069:    Collective on Mat and Vec

1071:    Input Parameters:
1072: +  mat - the matrix
1073: -  x   - the vector to be multilplied

1075:    Output Parameters:
1076: .  y - the result

1078:    Notes:
1079:    The vectors x and y cannot be the same.  I.e., one cannot
1080:    call MatMultTranspose(A,y,y).

1082:    Level: beginner

1084:    Concepts: matrix vector product^transpose

1086: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1087: @*/
1088: int MatMultTranspose(Mat mat,Vec x,Vec y)
1089: {

1095:   MatPreallocated(mat);

1099:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1100:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1101:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1102:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
1103:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
1104: 
1105:   PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);
1106:   (*mat->ops->multtranspose)(mat,x,y);
1107:   PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);
1108:   return(0);
1109: }

1111: /*@
1112:     MatMultAdd -  Computes v3 = v2 + A * v1.

1114:     Collective on Mat and Vec

1116:     Input Parameters:
1117: +   mat - the matrix
1118: -   v1, v2 - the vectors

1120:     Output Parameters:
1121: .   v3 - the result

1123:     Notes:
1124:     The vectors v1 and v3 cannot be the same.  I.e., one cannot
1125:     call MatMultAdd(A,v1,v2,v1).

1127:     Level: beginner

1129:     Concepts: matrix vector product^addition

1131: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1132: @*/
1133: int MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1134: {

1140:   MatPreallocated(mat);

1145:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1146:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1147:   if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->N,v1->N);
1148:   if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->M,v2->N);
1149:   if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->M,v3->N);
1150:   if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %d %d",mat->m,v3->n);
1151:   if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %d %d",mat->m,v2->n);
1152:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");

1154:   PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);
1155:   (*mat->ops->multadd)(mat,v1,v2,v3);
1156:   PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);
1157:   return(0);
1158: }

1160: /*@
1161:    MatMultTransposeAdd - Computes v3 = v2 + A' * v1.

1163:    Collective on Mat and Vec

1165:    Input Parameters:
1166: +  mat - the matrix
1167: -  v1, v2 - the vectors

1169:    Output Parameters:
1170: .  v3 - the result

1172:    Notes:
1173:    The vectors v1 and v3 cannot be the same.  I.e., one cannot
1174:    call MatMultTransposeAdd(A,v1,v2,v1).

1176:    Level: beginner

1178:    Concepts: matrix vector product^transpose and addition

1180: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1181: @*/
1182: int MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1183: {

1189:   MatPreallocated(mat);

1194:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1195:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1196:   if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1197:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1198:   if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->M,v1->N);
1199:   if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->N,v2->N);
1200:   if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->N,v3->N);

1202:   PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);
1203:   (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1204:   PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);
1205:   return(0);
1206: }
1207: /* ------------------------------------------------------------*/
1208: /*@C
1209:    MatGetInfo - Returns information about matrix storage (number of
1210:    nonzeros, memory, etc.).

1212:    Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1213:    as the flag

1215:    Input Parameters:
1216: .  mat - the matrix

1218:    Output Parameters:
1219: +  flag - flag indicating the type of parameters to be returned
1220:    (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1221:    MAT_GLOBAL_SUM - sum over all processors)
1222: -  info - matrix information context

1224:    Notes:
1225:    The MatInfo context contains a variety of matrix data, including
1226:    number of nonzeros allocated and used, number of mallocs during
1227:    matrix assembly, etc.  Additional information for factored matrices
1228:    is provided (such as the fill ratio, number of mallocs during
1229:    factorization, etc.).  Much of this info is printed to STDOUT
1230:    when using the runtime options 
1231: $       -log_info -mat_view_info

1233:    Example for C/C++ Users:
1234:    See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1235:    data within the MatInfo context.  For example, 
1236: .vb
1237:       MatInfo info;
1238:       Mat     A;
1239:       double  mal, nz_a, nz_u;

1241:       MatGetInfo(A,MAT_LOCAL,&info);
1242:       mal  = info.mallocs;
1243:       nz_a = info.nz_allocated;
1244: .ve

1246:    Example for Fortran Users:
1247:    Fortran users should declare info as a double precision
1248:    array of dimension MAT_INFO_SIZE, and then extract the parameters
1249:    of interest.  See the file ${PETSC_DIR}/include/finclude/petscmat.h
1250:    a complete list of parameter names.
1251: .vb
1252:       double  precision info(MAT_INFO_SIZE)
1253:       double  precision mal, nz_a
1254:       Mat     A
1255:       integer ierr

1257:       call MatGetInfo(A,MAT_LOCAL,info,ierr)
1258:       mal = info(MAT_INFO_MALLOCS)
1259:       nz_a = info(MAT_INFO_NZ_ALLOCATED)
1260: .ve

1262:     Level: intermediate

1264:     Concepts: matrices^getting information on
1265:  
1266: @*/
1267: int MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1268: {

1274:   MatPreallocated(mat);
1276:   if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1277:   (*mat->ops->getinfo)(mat,flag,info);
1278:   return(0);
1279: }

1281: /* ----------------------------------------------------------*/
1282: /*@C  
1283:    MatILUDTFactor - Performs a drop tolerance ILU factorization.

1285:    Collective on Mat

1287:    Input Parameters:
1288: +  mat - the matrix
1289: .  info - information about the factorization to be done
1290: .  row - row permutation
1291: -  col - column permutation

1293:    Output Parameters:
1294: .  fact - the factored matrix

1296:    Level: developer

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

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

1308:     Concepts: matrices^ILUDT factorization

1310: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
1311: @*/
1312: int MatILUDTFactor(Mat mat,MatILUInfo *info,IS row,IS col,Mat *fact)
1313: {

1319:   MatPreallocated(mat);
1321:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1322:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1323:   if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1325:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1326:   (*mat->ops->iludtfactor)(mat,info,row,col,fact);
1327:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);

1329:   return(0);
1330: }

1332: /*@  
1333:    MatLUFactor - Performs in-place LU factorization of matrix.

1335:    Collective on Mat

1337:    Input Parameters:
1338: +  mat - the matrix
1339: .  row - row permutation
1340: .  col - column permutation
1341: -  info - options for factorization, includes 
1342: $          fill - expected fill as ratio of original fill.
1343: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1344: $                   Run with the option -log_info to determine an optimal value to use

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

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

1354:    Level: developer

1356:    Concepts: matrices^LU factorization

1358: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
1359:           MatGetOrdering(), MatSetUnfactored()

1361: @*/
1362: int MatLUFactor(Mat mat,IS row,IS col,MatLUInfo *info)
1363: {

1369:   MatPreallocated(mat);
1370:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1371:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1372:   if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1374:   PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);
1375:   (*mat->ops->lufactor)(mat,row,col,info);
1376:   PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);
1377:   return(0);
1378: }

1380: /*@  
1381:    MatILUFactor - Performs in-place ILU factorization of matrix.

1383:    Collective on Mat

1385:    Input Parameters:
1386: +  mat - the matrix
1387: .  row - row permutation
1388: .  col - column permutation
1389: -  info - structure containing 
1390: $      levels - number of levels of fill.
1391: $      expected fill - as ratio of original fill.
1392: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
1393:                 missing diagonal entries)

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

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

1403:    Level: developer

1405:    Concepts: matrices^ILU factorization

1407: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
1408: @*/
1409: int MatILUFactor(Mat mat,IS row,IS col,MatILUInfo *info)
1410: {

1416:   MatPreallocated(mat);
1417:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
1418:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1419:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1420:   if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1422:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1423:   (*mat->ops->ilufactor)(mat,row,col,info);
1424:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1425:   return(0);
1426: }

1428: /*@  
1429:    MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
1430:    Call this routine before calling MatLUFactorNumeric().

1432:    Collective on Mat

1434:    Input Parameters:
1435: +  mat - the matrix
1436: .  row, col - row and column permutations
1437: -  info - options for factorization, includes 
1438: $          fill - expected fill as ratio of original fill.
1439: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1440: $                   Run with the option -log_info to determine an optimal value to use

1442:    Output Parameter:
1443: .  fact - new matrix that has been symbolically factored

1445:    Notes:
1446:    See the users manual for additional information about
1447:    choosing the fill factor for better efficiency.

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

1453:    Level: developer

1455:    Concepts: matrices^LU symbolic factorization

1457: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor()
1458: @*/
1459: int MatLUFactorSymbolic(Mat mat,IS row,IS col,MatLUInfo *info,Mat *fact)
1460: {

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

1472:   PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);
1473:   (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
1474:   PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);
1475:   return(0);
1476: }

1478: /*@  
1479:    MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
1480:    Call this routine after first calling MatLUFactorSymbolic().

1482:    Collective on Mat

1484:    Input Parameters:
1485: +  mat - the matrix
1486: -  fact - the matrix generated for the factor, from MatLUFactorSymbolic()

1488:    Notes:
1489:    See MatLUFactor() for in-place factorization.  See 
1490:    MatCholeskyFactorNumeric() for the symmetric, positive definite case.  

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

1496:    Level: developer

1498:    Concepts: matrices^LU numeric factorization

1500: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
1501: @*/
1502: int MatLUFactorNumeric(Mat mat,Mat *fact)
1503: {
1504:   int        ierr;
1505:   PetscTruth flg;

1510:   MatPreallocated(mat);
1513:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1514:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1515:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %d should = %d %d should = %d",
1516:             mat->M,(*fact)->M,mat->N,(*fact)->N);
1517:   }
1518:   if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1520:   PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
1521:   (*(*fact)->ops->lufactornumeric)(mat,fact);
1522:   PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);
1523:   PetscOptionsHasName(PETSC_NULL,"-mat_view_draw",&flg);
1524:   if (flg) {
1525:     PetscOptionsHasName(PETSC_NULL,"-mat_view_contour",&flg);
1526:     if (flg) {
1527:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
1528:     }
1529:     MatView(*fact,PETSC_VIEWER_DRAW_(mat->comm));
1530:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
1531:     if (flg) {
1532:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
1533:     }
1534:   }
1535:   return(0);
1536: }

1538: /*@  
1539:    MatCholeskyFactor - Performs in-place Cholesky factorization of a
1540:    symmetric matrix. 

1542:    Collective on Mat

1544:    Input Parameters:
1545: +  mat - the matrix
1546: .  perm - row and column permutations
1547: -  f - expected fill as ratio of original fill

1549:    Notes:
1550:    See MatLUFactor() for the nonsymmetric case.  See also
1551:    MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().

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

1557:    Level: developer

1559:    Concepts: matrices^Cholesky factorization

1561: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
1562:           MatGetOrdering()

1564: @*/
1565: int MatCholeskyFactor(Mat mat,IS perm,PetscReal f)
1566: {

1572:   MatPreallocated(mat);
1573:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1574:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1575:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1576:   if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1578:   PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);
1579:   (*mat->ops->choleskyfactor)(mat,perm,f);
1580:   PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);
1581:   return(0);
1582: }

1584: /*@  
1585:    MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
1586:    of a symmetric matrix. 

1588:    Collective on Mat

1590:    Input Parameters:
1591: +  mat - the matrix
1592: .  perm - row and column permutations
1593: -  f - expected fill as ratio of original

1595:    Output Parameter:
1596: .  fact - the factored matrix

1598:    Notes:
1599:    See MatLUFactorSymbolic() for the nonsymmetric case.  See also
1600:    MatCholeskyFactor() and MatCholeskyFactorNumeric().

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

1606:    Level: developer

1608:    Concepts: matrices^Cholesky symbolic factorization

1610: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
1611:           MatGetOrdering()

1613: @*/
1614: int MatCholeskyFactorSymbolic(Mat mat,IS perm,PetscReal f,Mat *fact)
1615: {

1621:   MatPreallocated(mat);
1623:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1624:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1625:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1626:   if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

1628:   PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1629:   (*mat->ops->choleskyfactorsymbolic)(mat,perm,f,fact);
1630:   PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1631:   return(0);
1632: }

1634: /*@  
1635:    MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
1636:    of a symmetric matrix. Call this routine after first calling
1637:    MatCholeskyFactorSymbolic().

1639:    Collective on Mat

1641:    Input Parameter:
1642: .  mat - the initial matrix

1644:    Output Parameter:
1645: .  fact - the factored matrix

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

1652:    Level: developer

1654:    Concepts: matrices^Cholesky numeric factorization

1656: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
1657: @*/
1658: int MatCholeskyFactorNumeric(Mat mat,Mat *fact)
1659: {

1665:   MatPreallocated(mat);
1667:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1668:   if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1669:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1670:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %d should = %d %d should = %d",
1671:             mat->M,(*fact)->M,mat->N,(*fact)->N);
1672:   }

1674:   PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1675:   (*(*fact)->ops->choleskyfactornumeric)(mat,fact);
1676:   PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1677:   return(0);
1678: }

1680: /* ----------------------------------------------------------------*/
1681: /*@
1682:    MatSolve - Solves A x = b, given a factored matrix.

1684:    Collective on Mat and Vec

1686:    Input Parameters:
1687: +  mat - the factored matrix
1688: -  b - the right-hand-side vector

1690:    Output Parameter:
1691: .  x - the result vector

1693:    Notes:
1694:    The vectors b and x cannot be the same.  I.e., one cannot
1695:    call MatSolve(A,x,x).

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

1702:    Level: developer

1704:    Concepts: matrices^triangular solves

1706: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
1707: @*/
1708: int MatSolve(Mat mat,Vec b,Vec x)
1709: {

1715:   MatPreallocated(mat);
1720:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1721:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1722:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1723:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1724:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1725:   if (mat->M == 0 && mat->N == 0) return(0);

1727:   if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1728:   PetscLogEventBegin(MAT_Solve,mat,b,x,0);
1729:   (*mat->ops->solve)(mat,b,x);
1730:   PetscLogEventEnd(MAT_Solve,mat,b,x,0);
1731:   return(0);
1732: }

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

1737:    Collective on Mat and Vec

1739:    Input Parameters:
1740: +  mat - the factored matrix
1741: -  b - the right-hand-side vector

1743:    Output Parameter:
1744: .  x - the result vector

1746:    Notes:
1747:    MatSolve() should be used for most applications, as it performs
1748:    a forward solve followed by a backward solve.

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

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

1757:    Level: developer

1759:    Concepts: matrices^forward solves

1761: .seealso: MatSolve(), MatBackwardSolve()
1762: @ */
1763: int MatForwardSolve(Mat mat,Vec b,Vec x)
1764: {

1770:   MatPreallocated(mat);
1775:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1776:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1777:   if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1778:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1779:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1780:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

1782:   PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
1783:   (*mat->ops->forwardsolve)(mat,b,x);
1784:   PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
1785:   return(0);
1786: }

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

1791:    Collective on Mat and Vec

1793:    Input Parameters:
1794: +  mat - the factored matrix
1795: -  b - the right-hand-side vector

1797:    Output Parameter:
1798: .  x - the result vector

1800:    Notes:
1801:    MatSolve() should be used for most applications, as it performs
1802:    a forward solve followed by a backward solve.

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

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

1811:    Level: developer

1813:    Concepts: matrices^backward solves

1815: .seealso: MatSolve(), MatForwardSolve()
1816: @ */
1817: int MatBackwardSolve(Mat mat,Vec b,Vec x)
1818: {

1824:   MatPreallocated(mat);
1829:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1830:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1831:   if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1832:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1833:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1834:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

1836:   PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);
1837:   (*mat->ops->backwardsolve)(mat,b,x);
1838:   PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);
1839:   return(0);
1840: }

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

1845:    Collective on Mat and Vec

1847:    Input Parameters:
1848: +  mat - the factored matrix
1849: .  b - the right-hand-side vector
1850: -  y - the vector to be added to 

1852:    Output Parameter:
1853: .  x - the result vector

1855:    Notes:
1856:    The vectors b and x cannot be the same.  I.e., one cannot
1857:    call MatSolveAdd(A,x,y,x).

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

1863:    Level: developer

1865:    Concepts: matrices^triangular solves

1867: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
1868: @*/
1869: int MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
1870: {
1871:   Scalar one = 1.0;
1872:   Vec    tmp;
1873:   int    ierr;

1878:   MatPreallocated(mat);
1885:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1886:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1887:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1888:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1889:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1890:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1891:   if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);

1893:   PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);
1894:   if (mat->ops->solveadd)  {
1895:     (*mat->ops->solveadd)(mat,b,y,x);
1896:   } else {
1897:     /* do the solve then the add manually */
1898:     if (x != y) {
1899:       MatSolve(mat,b,x);
1900:       VecAXPY(&one,y,x);
1901:     } else {
1902:       VecDuplicate(x,&tmp);
1903:       PetscLogObjectParent(mat,tmp);
1904:       VecCopy(x,tmp);
1905:       MatSolve(mat,b,x);
1906:       VecAXPY(&one,tmp,x);
1907:       VecDestroy(tmp);
1908:     }
1909:   }
1910:   PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);
1911:   return(0);
1912: }

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

1917:    Collective on Mat and Vec

1919:    Input Parameters:
1920: +  mat - the factored matrix
1921: -  b - the right-hand-side vector

1923:    Output Parameter:
1924: .  x - the result vector

1926:    Notes:
1927:    The vectors b and x cannot be the same.  I.e., one cannot
1928:    call MatSolveTranspose(A,x,x).

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

1934:    Level: developer

1936:    Concepts: matrices^triangular solves

1938: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
1939: @*/
1940: int MatSolveTranspose(Mat mat,Vec b,Vec x)
1941: {

1947:   MatPreallocated(mat);
1952:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1953:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1954:   if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
1955:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
1956:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);

1958:   PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
1959:   (*mat->ops->solvetranspose)(mat,b,x);
1960:   PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
1961:   return(0);
1962: }

1964: /*@
1965:    MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 
1966:                       factored matrix. 

1968:    Collective on Mat and Vec

1970:    Input Parameters:
1971: +  mat - the factored matrix
1972: .  b - the right-hand-side vector
1973: -  y - the vector to be added to 

1975:    Output Parameter:
1976: .  x - the result vector

1978:    Notes:
1979:    The vectors b and x cannot be the same.  I.e., one cannot
1980:    call MatSolveTransposeAdd(A,x,y,x).

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

1986:    Level: developer

1988:    Concepts: matrices^triangular solves

1990: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
1991: @*/
1992: int MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
1993: {
1994:   Scalar one = 1.0;
1995:   int    ierr;
1996:   Vec    tmp;

2001:   MatPreallocated(mat);
2008:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2009:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2010:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
2011:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);
2012:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
2013:   if (x->n != y->n)   SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);

2015:   PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);
2016:   if (mat->ops->solvetransposeadd) {
2017:     (*mat->ops->solvetransposeadd)(mat,b,y,x);
2018:   } else {
2019:     /* do the solve then the add manually */
2020:     if (x != y) {
2021:       MatSolveTranspose(mat,b,x);
2022:       VecAXPY(&one,y,x);
2023:     } else {
2024:       VecDuplicate(x,&tmp);
2025:       PetscLogObjectParent(mat,tmp);
2026:       VecCopy(x,tmp);
2027:       MatSolveTranspose(mat,b,x);
2028:       VecAXPY(&one,tmp,x);
2029:       VecDestroy(tmp);
2030:     }
2031:   }
2032:   PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);
2033:   return(0);
2034: }
2035: /* ----------------------------------------------------------------*/

2037: /*@
2038:    MatRelax - Computes one relaxation sweep.

2040:    Collective on Mat and Vec

2042:    Input Parameters:
2043: +  mat - the matrix
2044: .  b - the right hand side
2045: .  omega - the relaxation factor
2046: .  flag - flag indicating the type of SOR (see below)
2047: .  shift -  diagonal shift
2048: -  its - the number of iterations

2050:    Output Parameters:
2051: .  x - the solution (can contain an initial guess)

2053:    SOR Flags:
2054: .     SOR_FORWARD_SWEEP - forward SOR
2055: .     SOR_BACKWARD_SWEEP - backward SOR
2056: .     SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2057: .     SOR_LOCAL_FORWARD_SWEEP - local forward SOR 
2058: .     SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 
2059: .     SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2060: .     SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 
2061:          upper/lower triangular part of matrix to
2062:          vector (with omega)
2063: .     SOR_ZERO_INITIAL_GUESS - zero initial guess

2065:    Notes:
2066:    SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2067:    SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings
2068:    on each processor. 

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

2073:    Notes for Advanced Users:
2074:    The flags are implemented as bitwise inclusive or operations.
2075:    For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2076:    to specify a zero initial guess for SSOR.

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

2082:    Level: developer

2084:    Concepts: matrices^relaxation
2085:    Concepts: matrices^SOR
2086:    Concepts: matrices^Gauss-Seidel

2088: @*/
2089: int MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,int its,Vec x)
2090: {

2096:   MatPreallocated(mat);
2101:   if (!mat->ops->relax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2102:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2103:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2104:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
2105:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
2106:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);

2108:   PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2109:   ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,x);
2110:   PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2111:   return(0);
2112: }

2114: /*
2115:       Default matrix copy routine.
2116: */
2117: int MatCopy_Basic(Mat A,Mat B,MatStructure str)
2118: {
2119:   int    ierr,i,rstart,rend,nz,*cwork;
2120:   Scalar *vwork;

2123:   MatZeroEntries(B);
2124:   MatGetOwnershipRange(A,&rstart,&rend);
2125:   for (i=rstart; i<rend; i++) {
2126:     MatGetRow(A,i,&nz,&cwork,&vwork);
2127:     MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2128:     MatRestoreRow(A,i,&nz,&cwork,&vwork);
2129:   }
2130:   MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2131:   MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2132:   return(0);
2133: }

2135: /*@C  
2136:    MatCopy - Copys a matrix to another matrix.

2138:    Collective on Mat

2140:    Input Parameters:
2141: +  A - the matrix
2142: -  str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN

2144:    Output Parameter:
2145: .  B - where the copy is put

2147:    Notes:
2148:    If you use SAME_NONZERO_PATTERN then the zero matrices had better have the 
2149:    same nonzero pattern or the routine will crash.

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

2155:    Level: intermediate
2156:    
2157:    Concepts: matrices^copying

2159: .seealso: MatConvert()
2160: @*/
2161: int MatCopy(Mat A,Mat B,MatStructure str)
2162: {

2169:   MatPreallocated(A);
2171:   MatPreallocated(B);
2173:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2174:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2175:   if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d",A->M,B->M,
2176:                                              A->N,B->N);

2178:   PetscLogEventBegin(MAT_Copy,A,B,0,0);
2179:   if (A->ops->copy) {
2180:     (*A->ops->copy)(A,B,str);
2181:   } else { /* generic conversion */
2182:     MatCopy_Basic(A,B,str);
2183:   }
2184:   PetscLogEventEnd(MAT_Copy,A,B,0,0);
2185:   return(0);
2186: }

2188: #include "petscsys.h"
2189: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
2190: PetscFList      MatConvertList              = 0;

2192: /*@C
2193:     MatConvertRegister - Allows one to register a routine that reads matrices
2194:         from a binary file for a particular matrix type.

2196:   Not Collective

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

2202:   Level: developer

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

2206: @*/
2207: int MatConvertRegister(char *sname,char *path,char *name,int (*function)(Mat,MatType,Mat*))
2208: {
2209:   int  ierr;
2210:   char fullname[256];

2213:   PetscFListConcat(path,name,fullname);
2214:   PetscFListAdd(&MatConvertList,sname,fullname,(void (*)())function);
2215:   return(0);
2216: }

2218: /*@C  
2219:    MatConvert - Converts a matrix to another matrix, either of the same
2220:    or different type.

2222:    Collective on Mat

2224:    Input Parameters:
2225: +  mat - the matrix
2226: -  newtype - new matrix type.  Use MATSAME to create a new matrix of the
2227:    same type as the original matrix.

2229:    Output Parameter:
2230: .  M - pointer to place new matrix

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

2237:    Level: intermediate

2239:    Concepts: matrices^converting between storage formats

2241: .seealso: MatCopy(), MatDuplicate()
2242: @*/
2243: int MatConvert(Mat mat,MatType newtype,Mat *M)
2244: {
2245:   int        ierr;
2246:   PetscTruth sametype,issame,flg;
2247:   char       convname[256],mtype[256];

2252:   MatPreallocated(mat);
2254:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2255:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2257:   PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
2258:   if (flg) {
2259:     newtype = mtype;
2260:   }
2261:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2262: 
2263:   PetscTypeCompare((PetscObject)mat,newtype,&sametype);
2264:   PetscStrcmp(newtype,"same",&issame);
2265:   if ((sametype || issame) && mat->ops->duplicate) {
2266:     (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
2267:   } else {
2268:     int (*conv)(Mat,MatType,Mat*);
2269:     PetscStrcpy(convname,"MatConvertTo_");
2270:     PetscStrcat(convname,newtype);
2271:      PetscFListFind(mat->comm,MatConvertList,convname,(void(**)())&conv);
2272:     if (conv) {
2273:       (*conv)(mat,newtype,M);
2274:     } else {
2275:       PetscStrcpy(convname,"MatConvert_");
2276:       PetscStrcat(convname,mat->type_name);
2277:       PetscStrcat(convname,"_");
2278:       PetscStrcat(convname,newtype);
2279:       PetscStrcat(convname,"_C");
2280:       PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)())&conv);
2281:       if (conv) {
2282:         (*conv)(mat,newtype,M);
2283:       } else {
2284:         if (mat->ops->convert) {
2285:           (*mat->ops->convert)(mat,newtype,M);
2286:         } else {
2287:           MatConvert_Basic(mat,newtype,M);
2288:         }
2289:       }
2290:     }
2291:   }
2292:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2293:   return(0);
2294: }


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

2300:    Collective on Mat

2302:    Input Parameters:
2303: +  mat - the matrix
2304: -  op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
2305:         values as well or not

2307:    Output Parameter:
2308: .  M - pointer to place new matrix

2310:    Level: intermediate

2312:    Concepts: matrices^duplicating

2314: .seealso: MatCopy(), MatConvert()
2315: @*/
2316: int MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
2317: {

2323:   MatPreallocated(mat);
2325:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2326:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2328:   *M  = 0;
2329:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2330:   if (!mat->ops->duplicate) {
2331:     SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
2332:   }
2333:   (*mat->ops->duplicate)(mat,op,M);
2334:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2335:   return(0);
2336: }

2338: /*@ 
2339:    MatGetDiagonal - Gets the diagonal of a matrix.

2341:    Collective on Mat and Vec

2343:    Input Parameters:
2344: +  mat - the matrix
2345: -  v - the vector for storing the diagonal

2347:    Output Parameter:
2348: .  v - the diagonal of the matrix

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

2356:    Level: intermediate

2358:    Concepts: matrices^accessing diagonals

2360: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
2361: @*/
2362: int MatGetDiagonal(Mat mat,Vec v)
2363: {

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

2375:   (*mat->ops->getdiagonal)(mat,v);
2376:   return(0);
2377: }

2379: /*@ 
2380:    MatGetRowMax - Gets the maximum value (in absolute value) of each
2381:         row of the matrix

2383:    Collective on Mat and Vec

2385:    Input Parameters:
2386: .  mat - the matrix

2388:    Output Parameter:
2389: .  v - the vector for storing the maximums

2391:    Level: intermediate

2393:    Concepts: matrices^getting row maximums

2395: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
2396: @*/
2397: int MatGetRowMax(Mat mat,Vec v)
2398: {

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

2410:   (*mat->ops->getrowmax)(mat,v);
2411:   return(0);
2412: }

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

2417:    Collective on Mat

2419:    Input Parameter:
2420: .  mat - the matrix to transpose

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

2425:    Level: intermediate

2427:    Concepts: matrices^transposing

2429: .seealso: MatMultTranspose(), MatMultTransposeAdd()
2430: @*/
2431: int MatTranspose(Mat mat,Mat *B)
2432: {

2438:   MatPreallocated(mat);
2439:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2440:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2441:   if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2442:   (*mat->ops->transpose)(mat,B);
2443:   return(0);
2444: }

2446: /*@C
2447:    MatPermute - Creates a new matrix with rows and columns permuted from the 
2448:    original.

2450:    Collective on Mat

2452:    Input Parameters:
2453: +  mat - the matrix to permute
2454: .  row - row permutation, each processor supplies only the permutation for its rows
2455: -  col - column permutation, each processor needs the entire column permutation, that is
2456:          this is the same size as the total number of columns in the matrix

2458:    Output Parameters:
2459: .  B - the permuted matrix

2461:    Level: advanced

2463:    Concepts: matrices^permuting

2465: .seealso: MatGetOrdering()
2466: @*/
2467: int MatPermute(Mat mat,IS row,IS col,Mat *B)
2468: {

2474:   MatPreallocated(mat);
2477:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2478:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2479:   if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2480:   (*mat->ops->permute)(mat,row,col,B);
2481:   return(0);
2482: }

2484: /*@
2485:    MatEqual - Compares two matrices.

2487:    Collective on Mat

2489:    Input Parameters:
2490: +  A - the first matrix
2491: -  B - the second matrix

2493:    Output Parameter:
2494: .  flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.

2496:    Level: intermediate

2498:    Concepts: matrices^equality between
2499: @*/
2500: int MatEqual(Mat A,Mat B,PetscTruth *flg)
2501: {

2508:   MatPreallocated(A);
2510:   MatPreallocated(B);
2513:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2514:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2515:   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);
2516:   if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2517:   (*A->ops->equal)(A,B,flg);
2518:   return(0);
2519: }

2521: /*@
2522:    MatDiagonalScale - Scales a matrix on the left and right by diagonal
2523:    matrices that are stored as vectors.  Either of the two scaling
2524:    matrices can be PETSC_NULL.

2526:    Collective on Mat

2528:    Input Parameters:
2529: +  mat - the matrix to be scaled
2530: .  l - the left scaling vector (or PETSC_NULL)
2531: -  r - the right scaling vector (or PETSC_NULL)

2533:    Notes:
2534:    MatDiagonalScale() computes A = LAR, where
2535:    L = a diagonal matrix, R = a diagonal matrix

2537:    Level: intermediate

2539:    Concepts: matrices^diagonal scaling
2540:    Concepts: diagonal scaling of matrices

2542: .seealso: MatScale()
2543: @*/
2544: int MatDiagonalScale(Mat mat,Vec l,Vec r)
2545: {

2551:   MatPreallocated(mat);
2552:   if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2555:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2556:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2558:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2559:   (*mat->ops->diagonalscale)(mat,l,r);
2560:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2561:   return(0);
2562: }

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

2567:     Collective on Mat

2569:     Input Parameters:
2570: +   mat - the matrix to be scaled
2571: -   a  - the scaling value

2573:     Output Parameter:
2574: .   mat - the scaled matrix

2576:     Level: intermediate

2578:     Concepts: matrices^scaling all entries

2580: .seealso: MatDiagonalScale()
2581: @*/
2582: int MatScale(Scalar *a,Mat mat)
2583: {

2589:   MatPreallocated(mat);
2591:   if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2592:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2593:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

2595:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2596:   (*mat->ops->scale)(a,mat);
2597:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2598:   return(0);
2599: }

2601: /*@ 
2602:    MatNorm - Calculates various norms of a matrix.

2604:    Collective on Mat

2606:    Input Parameters:
2607: +  mat - the matrix
2608: -  type - the type of norm, NORM_1, NORM_2, NORM_FROBENIUS, NORM_INFINITY

2610:    Output Parameters:
2611: .  norm - the resulting norm 

2613:    Level: intermediate

2615:    Concepts: matrices^norm
2616:    Concepts: norm^of matrix
2617: @*/
2618: int MatNorm(Mat mat,NormType type,PetscReal *norm)
2619: {

2625:   MatPreallocated(mat);

2628:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2629:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2630:   if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2631:   (*mat->ops->norm)(mat,type,norm);
2632:   return(0);
2633: }

2635: /* 
2636:      This variable is used to prevent counting of MatAssemblyBegin() that
2637:    are called from within a MatAssemblyEnd().
2638: */
2639: static int MatAssemblyEnd_InUse = 0;
2640: /*@
2641:    MatAssemblyBegin - Begins assembling the matrix.  This routine should
2642:    be called after completing all calls to MatSetValues().

2644:    Collective on Mat

2646:    Input Parameters:
2647: +  mat - the matrix 
2648: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
2649:  
2650:    Notes: 
2651:    MatSetValues() generally caches the values.  The matrix is ready to
2652:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
2653:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
2654:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
2655:    using the matrix.

2657:    Level: beginner

2659:    Concepts: matrices^assembling

2661: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
2662: @*/
2663: int MatAssemblyBegin(Mat mat,MatAssemblyType type)
2664: {

2670:   MatPreallocated(mat);
2671:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.nDid you forget to call MatSetUnfactored()?");
2672:   if (mat->assembled) {
2673:     mat->was_assembled = PETSC_TRUE;
2674:     mat->assembled     = PETSC_FALSE;
2675:   }
2676:   if (!MatAssemblyEnd_InUse) {
2677:     PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
2678:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
2679:     PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
2680:   } else {
2681:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
2682:   }
2683:   return(0);
2684: }

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

2690:    Collective on Mat

2692:    Input Parameter:
2693: .  mat - the matrix 

2695:    Output Parameter:
2696: .  assembled - PETSC_TRUE or PETSC_FALSE

2698:    Level: advanced

2700:    Concepts: matrices^assembled?

2702: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
2703: @*/
2704: int MatAssembled(Mat mat,PetscTruth *assembled)
2705: {
2709:   MatPreallocated(mat);
2710:   *assembled = mat->assembled;
2711:   return(0);
2712: }

2714: /*
2715:     Processes command line options to determine if/how a matrix
2716:   is to be viewed. Called by MatAssemblyEnd() and MatLoad().
2717: */
2718: int MatView_Private(Mat mat)
2719: {
2720:   int        ierr;
2721:   PetscTruth flg;

2724:   PetscOptionsHasName(mat->prefix,"-mat_view_info",&flg);
2725:   if (flg) {
2726:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
2727:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2728:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2729:   }
2730:   PetscOptionsHasName(mat->prefix,"-mat_view_info_detailed",&flg);
2731:   if (flg) {
2732:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_LONG);
2733:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2734:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2735:   }
2736:   PetscOptionsHasName(mat->prefix,"-mat_view",&flg);
2737:   if (flg) {
2738:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2739:   }
2740:   PetscOptionsHasName(mat->prefix,"-mat_view_matlab",&flg);
2741:   if (flg) {
2742:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
2743:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2744:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2745:   }
2746:   PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
2747:   if (flg) {
2748:     PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
2749:     if (flg) {
2750:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
2751:     }
2752:     MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
2753:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
2754:     if (flg) {
2755:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
2756:     }
2757:   }
2758:   PetscOptionsHasName(mat->prefix,"-mat_view_socket",&flg);
2759:   if (flg) {
2760:     MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
2761:     PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
2762:   }
2763:   PetscOptionsHasName(mat->prefix,"-mat_view_binary",&flg);
2764:   if (flg) {
2765:     MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
2766:     PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
2767:   }
2768:   return(0);
2769: }

2771: /*@
2772:    MatAssemblyEnd - Completes assembling the matrix.  This routine should
2773:    be called after MatAssemblyBegin().

2775:    Collective on Mat

2777:    Input Parameters:
2778: +  mat - the matrix 
2779: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY

2781:    Options Database Keys:
2782: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
2783: .  -mat_view_info_detailed - Prints more detailed info
2784: .  -mat_view - Prints matrix in ASCII format
2785: .  -mat_view_matlab - Prints matrix in Matlab format
2786: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
2787: .  -display <name> - Sets display name (default is host)
2788: -  -draw_pause <sec> - Sets number of seconds to pause after display

2790:    Notes: 
2791:    MatSetValues() generally caches the values.  The matrix is ready to
2792:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
2793:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
2794:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
2795:    using the matrix.

2797:    Level: beginner

2799: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled()
2800: @*/
2801: int MatAssemblyEnd(Mat mat,MatAssemblyType type)
2802: {
2803:   int        ierr;
2804:   static int inassm = 0;

2809:   MatPreallocated(mat);

2811:   inassm++;
2812:   MatAssemblyEnd_InUse++;
2813:   if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
2814:     PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
2815:     if (mat->ops->assemblyend) {
2816:       (*mat->ops->assemblyend)(mat,type);
2817:     }
2818:     PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
2819:   } else {
2820:     if (mat->ops->assemblyend) {
2821:       (*mat->ops->assemblyend)(mat,type);
2822:     }
2823:   }

2825:   /* Flush assembly is not a true assembly */
2826:   if (type != MAT_FLUSH_ASSEMBLY) {
2827:     mat->assembled  = PETSC_TRUE; mat->num_ass++;
2828:   }
2829:   mat->insertmode = NOT_SET_VALUES;
2830:   MatAssemblyEnd_InUse--;

2832:   if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
2833:     MatView_Private(mat);
2834:   }
2835:   inassm--;
2836:   return(0);
2837: }


2840: /*@
2841:    MatCompress - Tries to store the matrix in as little space as 
2842:    possible.  May fail if memory is already fully used, since it
2843:    tries to allocate new space.

2845:    Collective on Mat

2847:    Input Parameters:
2848: .  mat - the matrix 

2850:    Level: advanced

2852: @*/
2853: int MatCompress(Mat mat)
2854: {

2860:   MatPreallocated(mat);
2861:   if (mat->ops->compress) {(*mat->ops->compress)(mat);}
2862:   return(0);
2863: }

2865: /*@
2866:    MatSetOption - Sets a parameter option for a matrix. Some options
2867:    may be specific to certain storage formats.  Some options
2868:    determine how values will be inserted (or added). Sorted, 
2869:    row-oriented input will generally assemble the fastest. The default
2870:    is row-oriented, nonsorted input. 

2872:    Collective on Mat

2874:    Input Parameters:
2875: +  mat - the matrix 
2876: -  option - the option, one of those listed below (and possibly others),
2877:              e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

2879:    Options Describing Matrix Structure:
2880: +    MAT_SYMMETRIC - symmetric in terms of both structure and value
2881: -    MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure

2883:    Options For Use with MatSetValues():
2884:    Insert a logically dense subblock, which can be
2885: +    MAT_ROW_ORIENTED - row-oriented
2886: .    MAT_COLUMN_ORIENTED - column-oriented
2887: .    MAT_ROWS_SORTED - sorted by row
2888: .    MAT_ROWS_UNSORTED - not sorted by row
2889: .    MAT_COLUMNS_SORTED - sorted by column
2890: -    MAT_COLUMNS_UNSORTED - not sorted by column

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

2896:    When (re)assembling a matrix, we can restrict the input for
2897:    efficiency/debugging purposes.  These options include
2898: +    MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
2899:         allowed if they generate a new nonzero
2900: .    MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
2901: .    MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
2902:          they generate a nonzero in a new diagonal (for block diagonal format only)
2903: .    MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
2904: .    MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
2905: .    MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
2906: -    MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly

2908:    Notes:
2909:    Some options are relevant only for particular matrix types and
2910:    are thus ignored by others.  Other options are not supported by
2911:    certain matrix types and will generate an error message if set.

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

2917:    MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 
2918:    that would generate a new entry in the nonzero structure is instead
2919:    ignored.  Thus, if memory has not alredy been allocated for this particular 
2920:    data, then the insertion is ignored. For dense matrices, in which
2921:    the entire array is allocated, no entries are ever ignored. 

2923:    MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 
2924:    that would generate a new entry in the nonzero structure instead produces 
2925:    an error. (Currently supported for AIJ and BAIJ formats only.)
2926:    This is a useful flag when using SAME_NONZERO_PATTERN in calling
2927:    SLESSetOperators() to ensure that the nonzero pattern truely does 
2928:    remain unchanged.

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

2935:    MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 
2936:    other processors should be dropped, rather than stashed.
2937:    This is useful if you know that the "owning" processor is also 
2938:    always generating the correct matrix entries, so that PETSc need
2939:    not transfer duplicate entries generated on another processor.
2940:    
2941:    MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
2942:    searches during matrix assembly. When this flag is set, the hash table
2943:    is created during the first Matrix Assembly. This hash table is
2944:    used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
2945:    to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 
2946:    should be used with MAT_USE_HASH_TABLE flag. This option is currently
2947:    supported by MATMPIBAIJ format only.

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

2952:    MAT_IGNORE_ZERO_ENTRIES - when using ADD_VALUES for AIJ matrices this will stop
2953:    zero values from creating a zero location in the matrix

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

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

2961:    Level: intermediate

2963:    Concepts: matrices^setting options

2965: @*/
2966: int MatSetOption(Mat mat,MatOption op)
2967: {

2973:   MatPreallocated(mat);
2974:   if (op == MAT_SYMMETRIC) {
2975:     mat->symmetric              = PETSC_TRUE;
2976:     mat->structurally_symmetric = PETSC_TRUE;
2977:   } else if (op == MAT_STRUCTURALLY_SYMMETRIC) {
2978:     mat->structurally_symmetric = PETSC_TRUE;
2979:   } else {
2980:     if (mat->ops->setoption) {(*mat->ops->setoption)(mat,op);}
2981:   }
2982:   return(0);
2983: }

2985: /*@
2986:    MatZeroEntries - Zeros all entries of a matrix.  For sparse matrices
2987:    this routine retains the old nonzero structure.

2989:    Collective on Mat

2991:    Input Parameters:
2992: .  mat - the matrix 

2994:    Level: intermediate

2996:    Concepts: matrices^zeroing

2998: .seealso: MatZeroRows()
2999: @*/
3000: int MatZeroEntries(Mat mat)
3001: {

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

3011:   PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
3012:   (*mat->ops->zeroentries)(mat);
3013:   PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
3014:   return(0);
3015: }

3017: /*@C
3018:    MatZeroRows - Zeros all entries (except possibly the main diagonal)
3019:    of a set of rows of a matrix.

3021:    Collective on Mat

3023:    Input Parameters:
3024: +  mat - the matrix
3025: .  is - index set of rows to remove
3026: -  diag - pointer to value put in all diagonals of eliminated rows.
3027:           Note that diag is not a pointer to an array, but merely a
3028:           pointer to a single value.

3030:    Notes:
3031:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
3032:    but does not release memory.  For the dense and block diagonal
3033:    formats this does not alter the nonzero structure.

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

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

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

3049:   
3050:    Level: intermediate

3052:    Concepts: matrices^zeroing rows

3054: .seealso: MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
3055: @*/
3056: int MatZeroRows(Mat mat,IS is,Scalar *diag)
3057: {

3063:   MatPreallocated(mat);
3066:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3067:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3068:   if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);

3070:   (*mat->ops->zerorows)(mat,is,diag);
3071:   MatView_Private(mat);
3072:   return(0);
3073: }

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

3079:    Collective on Mat

3081:    Input Parameters:
3082: +  mat - the matrix
3083: .  is - index set of rows to remove
3084: -  diag - pointer to value put in all diagonals of eliminated rows.
3085:           Note that diag is not a pointer to an array, but merely a
3086:           pointer to a single value.

3088:    Notes:
3089:    Before calling MatZeroRowsLocal(), the user must first set the
3090:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

3092:    For the AIJ matrix formats this removes the old nonzero structure,
3093:    but does not release memory.  For the dense and block diagonal
3094:    formats this does not alter the nonzero structure.

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

3101:    Level: intermediate

3103:    Concepts: matrices^zeroing

3105: .seealso: MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
3106: @*/
3107: int MatZeroRowsLocal(Mat mat,IS is,Scalar *diag)
3108: {
3110:   IS  newis;

3115:   MatPreallocated(mat);
3118:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3119:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3121:   if (mat->ops->zerorowslocal) {
3122:     (*mat->ops->zerorowslocal)(mat,is,diag);
3123:   } else {
3124:     if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
3125:     ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
3126:     (*mat->ops->zerorows)(mat,newis,diag);
3127:     ISDestroy(newis);
3128:   }
3129:   return(0);
3130: }

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

3135:    Not Collective

3137:    Input Parameter:
3138: .  mat - the matrix

3140:    Output Parameters:
3141: +  m - the number of global rows
3142: -  n - the number of global columns

3144:    Level: beginner

3146:    Concepts: matrices^size

3148: .seealso: MatGetLocalSize()
3149: @*/
3150: int MatGetSize(Mat mat,int *m,int* n)
3151: {
3154:   if (m) *m = mat->M;
3155:   if (n) *n = mat->N;
3156:   return(0);
3157: }

3159: /*@
3160:    MatGetLocalSize - Returns the number of rows and columns in a matrix
3161:    stored locally.  This information may be implementation dependent, so
3162:    use with care.

3164:    Not Collective

3166:    Input Parameters:
3167: .  mat - the matrix

3169:    Output Parameters:
3170: +  m - the number of local rows
3171: -  n - the number of local columns

3173:    Level: beginner

3175:    Concepts: matrices^local size

3177: .seealso: MatGetSize()
3178: @*/
3179: int MatGetLocalSize(Mat mat,int *m,int* n)
3180: {
3183:   if (m) *m = mat->m;
3184:   if (n) *n = mat->n;
3185:   return(0);
3186: }

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

3194:    Not Collective

3196:    Input Parameters:
3197: .  mat - the matrix

3199:    Output Parameters:
3200: +  m - the global index of the first local row
3201: -  n - one more than the global index of the last local row

3203:    Level: beginner

3205:    Concepts: matrices^row ownership
3206: @*/
3207: int MatGetOwnershipRange(Mat mat,int *m,int* n)
3208: {

3214:   MatPreallocated(mat);
3217:   if (!mat->ops->getownershiprange) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3218:   (*mat->ops->getownershiprange)(mat,m,n);
3219:   return(0);
3220: }

3222: /*@  
3223:    MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
3224:    Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 
3225:    to complete the factorization.

3227:    Collective on Mat

3229:    Input Parameters:
3230: +  mat - the matrix
3231: .  row - row permutation
3232: .  column - column permutation
3233: -  info - structure containing 
3234: $      levels - number of levels of fill.
3235: $      expected fill - as ratio of original fill.
3236: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
3237:                 missing diagonal entries)

3239:    Output Parameters:
3240: .  fact - new matrix that has been symbolically factored

3242:    Notes:
3243:    See the users manual for additional information about
3244:    choosing the fill factor for better efficiency.

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

3250:    Level: developer

3252:   Concepts: matrices^symbolic LU factorization
3253:   Concepts: matrices^factorization
3254:   Concepts: LU^symbolic factorization

3256: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
3257:           MatGetOrdering()

3259: @*/
3260: int MatILUFactorSymbolic(Mat mat,IS row,IS col,MatILUInfo *info,Mat *fact)
3261: {

3267:   MatPreallocated(mat);
3269:   if (info && info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %d",info->levels);
3270:   if (info && info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
3271:   if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ILU",mat->type_name);
3272:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3273:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3275:   PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
3276:   (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
3277:   PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
3278:   return(0);
3279: }

3281: /*@  
3282:    MatICCFactorSymbolic - Performs symbolic incomplete
3283:    Cholesky factorization for a symmetric matrix.  Use 
3284:    MatCholeskyFactorNumeric() to complete the factorization.

3286:    Collective on Mat

3288:    Input Parameters:
3289: +  mat - the matrix
3290: .  perm - row and column permutation
3291: .  fill - levels of fill
3292: -  f - expected fill as ratio of original fill

3294:    Output Parameter:
3295: .  fact - the factored matrix

3297:    Notes:
3298:    Currently only no-fill factorization is supported.

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

3304:    Level: developer

3306:   Concepts: matrices^symbolic incomplete Cholesky factorization
3307:   Concepts: matrices^factorization
3308:   Concepts: Cholsky^symbolic factorization

3310: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor()
3311: @*/
3312: int MatICCFactorSymbolic(Mat mat,IS perm,PetscReal f,int fill,Mat *fact)
3313: {

3319:   MatPreallocated(mat);
3321:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3322:   if (fill < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Fill negative %d",fill);
3323:   if (f < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",f);
3324:   if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ICC",mat->type_name);
3325:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");

3327:   PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
3328:   (*mat->ops->iccfactorsymbolic)(mat,perm,f,fill,fact);
3329:   PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
3330:   return(0);
3331: }

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

3339:    Not Collective

3341:    Input Parameter:
3342: .  mat - the matrix

3344:    Output Parameter:
3345: .  v - the location of the values


3348:    Fortran Note:
3349:    This routine is used differently from Fortran, e.g.,
3350: .vb
3351:         Mat         mat
3352:         Scalar      mat_array(1)
3353:         PetscOffset i_mat
3354:         int         ierr
3355:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

3361:         [... other code ...]
3362:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
3363: .ve

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

3368:    Level: advanced

3370:    Concepts: matrices^access array

3372: .seealso: MatRestoreArray(), MatGetArrayF90()
3373: @*/
3374: int MatGetArray(Mat mat,Scalar **v)
3375: {

3381:   MatPreallocated(mat);
3383:   if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3384:   (*mat->ops->getarray)(mat,v);
3385:   return(0);
3386: }

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

3391:    Not Collective

3393:    Input Parameter:
3394: +  mat - the matrix
3395: -  v - the location of the values

3397:    Fortran Note:
3398:    This routine is used differently from Fortran, e.g.,
3399: .vb
3400:         Mat         mat
3401:         Scalar      mat_array(1)
3402:         PetscOffset i_mat
3403:         int         ierr
3404:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

3410:         [... other code ...]
3411:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
3412: .ve

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

3417:    Level: advanced

3419: .seealso: MatGetArray(), MatRestoreArrayF90()
3420: @*/
3421: int MatRestoreArray(Mat mat,Scalar **v)
3422: {

3428:   MatPreallocated(mat);
3430:   if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3431:   (*mat->ops->restorearray)(mat,v);
3432:   return(0);
3433: }

3435: /*@C
3436:    MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
3437:    points to an array of valid matrices, they may be reused to store the new
3438:    submatrices.

3440:    Collective on Mat

3442:    Input Parameters:
3443: +  mat - the matrix
3444: .  n   - the number of submatrixes to be extracted (on this processor, may be zero)
3445: .  irow, icol - index sets of rows and columns to extract
3446: -  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

3448:    Output Parameter:
3449: .  submat - the array of submatrices

3451:    Notes:
3452:    MatGetSubMatrices() can extract only sequential submatrices
3453:    (from both sequential and parallel matrices). Use MatGetSubMatrix()
3454:    to extract a parallel submatrix.

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

3460:    When finished using the submatrices, the user should destroy
3461:    them with MatDestroySubMatrices().

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

3466:    This routine creates the matrices submat; you should NOT create them before
3467:    calling it.

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

3473:    Level: advanced

3475:    Concepts: matrices^accessing submatrices
3476:    Concepts: submatrices

3478: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
3479: @*/
3480: int MatGetSubMatrices(Mat mat,int n,IS *irow,IS *icol,MatReuse scall,Mat **submat)
3481: {
3482:   int        ierr;

3487:   MatPreallocated(mat);
3488:   if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3489:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");

3491:   PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
3492:   (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
3493:   PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
3494:   return(0);
3495: }

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

3500:    Collective on Mat

3502:    Input Parameters:
3503: +  n - the number of local matrices
3504: -  mat - the matrices

3506:    Level: advanced

3508: .seealso: MatGetSubMatrices()
3509: @*/
3510: int MatDestroyMatrices(int n,Mat **mat)
3511: {
3512:   int ierr,i;

3515:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %d",n);
3517:   for (i=0; i<n; i++) {
3518:     MatDestroy((*mat)[i]);
3519:   }
3520:   /* memory is allocated even if n = 0 */
3521:   PetscFree(*mat);
3522:   return(0);
3523: }

3525: /*@
3526:    MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
3527:    replaces the index sets by larger ones that represent submatrices with
3528:    additional overlap.

3530:    Collective on Mat

3532:    Input Parameters:
3533: +  mat - the matrix
3534: .  n   - the number of index sets
3535: .  is  - the array of pointers to index sets
3536: -  ov  - the additional overlap requested

3538:    Level: developer

3540:    Concepts: overlap
3541:    Concepts: ASM^computing overlap

3543: .seealso: MatGetSubMatrices()
3544: @*/
3545: int MatIncreaseOverlap(Mat mat,int n,IS *is,int ov)
3546: {

3552:   MatPreallocated(mat);
3553:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3554:   if (mat->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

3556:   if (!ov) return(0);
3557:   if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3558:   PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
3559:   (*mat->ops->increaseoverlap)(mat,n,is,ov);
3560:   PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
3561:   return(0);
3562: }

3564: /*@
3565:    MatPrintHelp - Prints all the options for the matrix.

3567:    Collective on Mat

3569:    Input Parameter:
3570: .  mat - the matrix 

3572:    Options Database Keys:
3573: +  -help - Prints matrix options
3574: -  -h - Prints matrix options

3576:    Level: developer

3578: .seealso: MatCreate(), MatCreateXXX()
3579: @*/
3580: int MatPrintHelp(Mat mat)
3581: {
3582:   static PetscTruth called = PETSC_FALSE;
3583:   int               ierr;
3584:   MPI_Comm          comm;

3589:   MatPreallocated(mat);

3591:   comm = mat->comm;
3592:   if (!called) {
3593:     (*PetscHelpPrintf)(comm,"General matrix options:n");
3594:     (*PetscHelpPrintf)(comm,"  -mat_view_info: view basic matrix info during MatAssemblyEnd()n");
3595:     (*PetscHelpPrintf)(comm,"  -mat_view_info_detailed: view detailed matrix info during MatAssemblyEnd()n");
3596:     (*PetscHelpPrintf)(comm,"  -mat_view_draw: draw nonzero matrix structure during MatAssemblyEnd()n");
3597:     (*PetscHelpPrintf)(comm,"      -draw_pause <sec>: set seconds of display pausen");
3598:     (*PetscHelpPrintf)(comm,"      -display <name>: set alternate displayn");
3599:     called = PETSC_TRUE;
3600:   }
3601:   if (mat->ops->printhelp) {
3602:     (*mat->ops->printhelp)(mat);
3603:   }
3604:   return(0);
3605: }

3607: /*@
3608:    MatGetBlockSize - Returns the matrix block size; useful especially for the
3609:    block row and block diagonal formats.
3610:    
3611:    Not Collective

3613:    Input Parameter:
3614: .  mat - the matrix

3616:    Output Parameter:
3617: .  bs - block size

3619:    Notes:
3620:    Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
3621:    Block row formats are MATSEQBAIJ, MATMPIBAIJ

3623:    Level: intermediate

3625:    Concepts: matrices^block size

3627: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
3628: @*/
3629: int MatGetBlockSize(Mat mat,int *bs)
3630: {

3636:   MatPreallocated(mat);
3638:   if (!mat->ops->getblocksize) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3639:   (*mat->ops->getblocksize)(mat,bs);
3640:   return(0);
3641: }

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

3646:    Collective on Mat

3648:     Input Parameters:
3649: +   mat - the matrix
3650: .   shift -  0 or 1 indicating we want the indices starting at 0 or 1
3651: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3652:                 symmetrized

3654:     Output Parameters:
3655: +   n - number of rows in the (possibly compressed) matrix
3656: .   ia - the row pointers
3657: .   ja - the column indices
3658: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

3660:     Level: developer

3662: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
3663: @*/
3664: int MatGetRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3665: {

3671:   MatPreallocated(mat);
3675:   if (!mat->ops->getrowij) *done = PETSC_FALSE;
3676:   else {
3677:     *done = PETSC_TRUE;
3678:     ierr  = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
3679:   }
3680:   return(0);
3681: }

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

3686:     Collective on Mat

3688:     Input Parameters:
3689: +   mat - the matrix
3690: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
3691: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3692:                 symmetrized

3694:     Output Parameters:
3695: +   n - number of columns in the (possibly compressed) matrix
3696: .   ia - the column pointers
3697: .   ja - the row indices
3698: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

3700:     Level: developer

3702: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
3703: @*/
3704: int MatGetColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3705: {

3711:   MatPreallocated(mat);

3716:   if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
3717:   else {
3718:     *done = PETSC_TRUE;
3719:     ierr  = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
3720:   }
3721:   return(0);
3722: }

3724: /*@C
3725:     MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
3726:     MatGetRowIJ().

3728:     Collective on Mat

3730:     Input Parameters:
3731: +   mat - the matrix
3732: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
3733: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3734:                 symmetrized

3736:     Output Parameters:
3737: +   n - size of (possibly compressed) matrix
3738: .   ia - the row pointers
3739: .   ja - the column indices
3740: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

3742:     Level: developer

3744: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
3745: @*/
3746: int MatRestoreRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3747: {

3753:   MatPreallocated(mat);

3758:   if (!mat->ops->restorerowij) *done = PETSC_FALSE;
3759:   else {
3760:     *done = PETSC_TRUE;
3761:     ierr  = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
3762:   }
3763:   return(0);
3764: }

3766: /*@C
3767:     MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
3768:     MatGetColumnIJ().

3770:     Collective on Mat

3772:     Input Parameters:
3773: +   mat - the matrix
3774: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
3775: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3776:                 symmetrized

3778:     Output Parameters:
3779: +   n - size of (possibly compressed) matrix
3780: .   ia - the column pointers
3781: .   ja - the row indices
3782: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

3784:     Level: developer

3786: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
3787: @*/
3788: int MatRestoreColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3789: {

3795:   MatPreallocated(mat);

3800:   if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
3801:   else {
3802:     *done = PETSC_TRUE;
3803:     ierr  = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
3804:   }
3805:   return(0);
3806: }

3808: /*@C
3809:     MatColoringPatch -Used inside matrix coloring routines that 
3810:     use MatGetRowIJ() and/or MatGetColumnIJ().

3812:     Collective on Mat

3814:     Input Parameters:
3815: +   mat - the matrix
3816: .   n   - number of colors
3817: -   colorarray - array indicating color for each column

3819:     Output Parameters:
3820: .   iscoloring - coloring generated using colorarray information

3822:     Level: developer

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

3826: @*/
3827: int MatColoringPatch(Mat mat,int n,int ncolors,int *colorarray,ISColoring *iscoloring)
3828: {

3834:   MatPreallocated(mat);

3837:   if (!mat->ops->coloringpatch){
3838:     ISColoringCreate(mat->comm,n,colorarray,iscoloring);
3839:   } else {
3840:     (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);
3841:   }
3842:   return(0);
3843: }


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

3849:    Collective on Mat

3851:    Input Parameter:
3852: .  mat - the factored matrix to be reset

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

3861:    Note that one can specify in-place ILU(0) factorization by calling 
3862: .vb
3863:      PCType(pc,PCILU);
3864:      PCILUSeUseInPlace(pc);
3865: .ve
3866:    or by using the options -pc_type ilu -pc_ilu_in_place

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

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

3878:    Level: developer

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

3882:    Concepts: matrices^unfactored

3884: @*/
3885: int MatSetUnfactored(Mat mat)
3886: {

3892:   MatPreallocated(mat);
3893:   mat->factor = 0;
3894:   if (!mat->ops->setunfactored) return(0);
3895:   (*mat->ops->setunfactored)(mat);
3896:   return(0);
3897: }

3899: /*MC
3900:     MatGetArrayF90 - Accesses a matrix array from Fortran90.

3902:     Synopsis:
3903:     MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

3905:     Not collective

3907:     Input Parameter:
3908: .   x - matrix

3910:     Output Parameters:
3911: +   xx_v - the Fortran90 pointer to the array
3912: -   ierr - error code

3914:     Example of Usage: 
3915: .vb
3916:       Scalar, pointer xx_v(:)
3917:       ....
3918:       call MatGetArrayF90(x,xx_v,ierr)
3919:       a = xx_v(3)
3920:       call MatRestoreArrayF90(x,xx_v,ierr)
3921: .ve

3923:     Notes:
3924:     Not yet supported for all F90 compilers

3926:     Level: advanced

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

3930:     Concepts: matrices^accessing array

3932: M*/

3934: /*MC
3935:     MatRestoreArrayF90 - Restores a matrix array that has been
3936:     accessed with MatGetArrayF90().

3938:     Synopsis:
3939:     MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

3941:     Not collective

3943:     Input Parameters:
3944: +   x - matrix
3945: -   xx_v - the Fortran90 pointer to the array

3947:     Output Parameter:
3948: .   ierr - error code

3950:     Example of Usage: 
3951: .vb
3952:        Scalar, pointer xx_v(:)
3953:        ....
3954:        call MatGetArrayF90(x,xx_v,ierr)
3955:        a = xx_v(3)
3956:        call MatRestoreArrayF90(x,xx_v,ierr)
3957: .ve
3958:    
3959:     Notes:
3960:     Not yet supported for all F90 compilers

3962:     Level: advanced

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

3966: M*/


3969: /*@
3970:     MatGetSubMatrix - Gets a single submatrix on the same number of processors
3971:                       as the original matrix.

3973:     Collective on Mat

3975:     Input Parameters:
3976: +   mat - the original matrix
3977: .   isrow - rows this processor should obtain
3978: .   iscol - columns for all processors you wish to keep
3979: .   csize - number of columns "local" to this processor (does nothing for sequential 
3980:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
3981:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
3982: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

3984:     Output Parameter:
3985: .   newmat - the new submatrix, of the same type as the old

3987:     Level: advanced

3989:     Notes: the iscol argument MUST be the same on each processor.

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

3996:     Concepts: matrices^submatrices

3998: .seealso: MatGetSubMatrices()
3999: @*/
4000: int MatGetSubMatrix(Mat mat,IS isrow,IS iscol,int csize,MatReuse cll,Mat *newmat)
4001: {
4002:   int     ierr, size;
4003:   Mat     *local;

4007:   MatPreallocated(mat);
4008:   MPI_Comm_size(mat->comm,&size);

4010:   /* if original matrix is on just one processor then use submatrix generated */
4011:   if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
4012:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
4013:     return(0);
4014:   } else if (!mat->ops->getsubmatrix && size == 1) {
4015:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
4016:     *newmat = *local;
4017:     PetscFree(local);
4018:     return(0);
4019:   }

4021:   if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4022:   (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
4023:   return(0);
4024: }

4026: /*@C
4027:    MatGetMaps - Returns the maps associated with the matrix.

4029:    Not Collective

4031:    Input Parameter:
4032: .  mat - the matrix

4034:    Output Parameters:
4035: +  rmap - the row (right) map
4036: -  cmap - the column (left) map  

4038:    Level: developer

4040:    Concepts: maps^getting from matrix

4042: @*/
4043: int MatGetMaps(Mat mat,Map *rmap,Map *cmap)
4044: {

4050:   MatPreallocated(mat);
4051:   (*mat->ops->getmaps)(mat,rmap,cmap);
4052:   return(0);
4053: }

4055: /*
4056:       Version that works for all PETSc matrices
4057: */
4058: int MatGetMaps_Petsc(Mat mat,Map *rmap,Map *cmap)
4059: {
4061:   if (rmap) *rmap = mat->rmap;
4062:   if (cmap) *cmap = mat->cmap;
4063:   return(0);
4064: }

4066: /*@
4067:    MatSetStashInitialSize - sets the sizes of the matrix stash, that is
4068:    used during the assembly process to store values that belong to 
4069:    other processors.

4071:    Not Collective

4073:    Input Parameters:
4074: +  mat   - the matrix
4075: .  size  - the initial size of the stash.
4076: -  bsize - the initial size of the block-stash(if used).

4078:    Options Database Keys:
4079: +   -matstash_initial_size <size> or <size0,size1,...sizep-1>
4080: -   -matstash_block_initial_size <bsize>  or <bsize0,bsize1,...bsizep-1>

4082:    Level: intermediate

4084:    Notes: 
4085:      The block-stash is used for values set with VecSetValuesBlocked() while
4086:      the stash is used for values set with VecSetValues()

4088:      Run with the option -log_info and look for output of the form
4089:      MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
4090:      to determine the appropriate value, MM, to use for size and 
4091:      MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
4092:      to determine the value, BMM to use for bsize

4094:    Concepts: stash^setting matrix size
4095:    Concepts: matrices^stash

4097: @*/
4098: int MatSetStashInitialSize(Mat mat,int size, int bsize)
4099: {

4105:   MatPreallocated(mat);
4106:   MatStashSetInitialSize_Private(&mat->stash,size);
4107:   MatStashSetInitialSize_Private(&mat->bstash,bsize);
4108:   return(0);
4109: }

4111: /*@
4112:    MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 
4113:      the matrix

4115:    Collective on Mat

4117:    Input Parameters:
4118: +  mat   - the matrix
4119: .  x,y - the vectors
4120: -  w - where the result is stored

4122:    Level: intermediate

4124:    Notes: 
4125:     w may be the same vector as y. 

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

4130:     Concepts: interpolation

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

4134: @*/
4135: int MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
4136: {
4137:   int M,N,ierr;

4141:   MatPreallocated(A);
4142:   MatGetSize(A,&M,&N);
4143:   if (N > M) {
4144:     MatMultTransposeAdd(A,x,y,w);
4145:   } else {
4146:     MatMultAdd(A,x,y,w);
4147:   }
4148:   return(0);
4149: }

4151: /*@
4152:    MatInterpolate - y = A*x or A'*x depending on the shape of 
4153:      the matrix

4155:    Collective on Mat

4157:    Input Parameters:
4158: +  mat   - the matrix
4159: -  x,y - the vectors

4161:    Level: intermediate

4163:    Notes: 
4164:     This allows one to use either the restriction or interpolation (its transpose)
4165:     matrix to do the interpolation

4167:    Concepts: matrices^interpolation

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

4171: @*/
4172: int MatInterpolate(Mat A,Vec x,Vec y)
4173: {
4174:   int M,N,ierr;

4178:   MatPreallocated(A);
4179:   MatGetSize(A,&M,&N);
4180:   if (N > M) {
4181:     MatMultTranspose(A,x,y);
4182:   } else {
4183:     MatMult(A,x,y);
4184:   }
4185:   return(0);
4186: }

4188: /*@
4189:    MatRestrict - y = A*x or A'*x

4191:    Collective on Mat

4193:    Input Parameters:
4194: +  mat   - the matrix
4195: -  x,y - the vectors

4197:    Level: intermediate

4199:    Notes: 
4200:     This allows one to use either the restriction or interpolation (its transpose)
4201:     matrix to do the restriction

4203:    Concepts: matrices^restriction

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

4207: @*/
4208: int MatRestrict(Mat A,Vec x,Vec y)
4209: {
4210:   int M,N,ierr;

4214:   MatPreallocated(A);
4215:   MatGetSize(A,&M,&N);
4216:   if (N > M) {
4217:     MatMult(A,x,y);
4218:   } else {
4219:     MatMultTranspose(A,x,y);
4220:   }
4221:   return(0);
4222: }

4224: /*@C
4225:    MatNullSpaceAttach - attaches a null space to a matrix.
4226:         This null space will be removed from the resulting vector whenever
4227:         MatMult() is called

4229:    Collective on Mat

4231:    Input Parameters:
4232: +  mat - the matrix
4233: -  nullsp - the null space object

4235:    Level: developer

4237:    Notes:
4238:       Overwrites any previous null space that may have been attached

4240:    Concepts: null space^attaching to matrix

4242: .seealso: MatCreate(), MatNullSpaceCreate()
4243: @*/
4244: int MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
4245: {

4251:   MatPreallocated(mat);

4254:   if (mat->nullsp) {
4255:     MatNullSpaceDestroy(mat->nullsp);
4256:   }
4257:   mat->nullsp = nullsp;
4258:   PetscObjectReference((PetscObject)nullsp);
4259:   return(0);
4260: }

4262: /*@  
4263:    MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.

4265:    Collective on Mat

4267:    Input Parameters:
4268: +  mat - the matrix
4269: .  row - row/column permutation
4270: .  fill - expected fill factor >= 1.0
4271: -  level - level of fill, for ICC(k)

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

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

4281:    Level: developer

4283:    Concepts: matrices^incomplete Cholesky factorization
4284:    Concepts: Cholesky factorization

4286: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4287: @*/
4288: int MatICCFactor(Mat mat,IS row,PetscReal fill,int level)
4289: {

4295:   MatPreallocated(mat);
4296:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
4297:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4298:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4299:   if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4300:   (*mat->ops->iccfactor)(mat,row,fill,level);
4301:   return(0);
4302: }