Actual source code: matrix.c

  1: #define PETSCMAT_DLL

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

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

 10: /* Logging support */
 11: PetscCookie  MAT_COOKIE = 0;
 12: PetscEvent  MAT_Mult = 0, MAT_Mults = 0, MAT_MultConstrained = 0, MAT_MultAdd = 0, MAT_MultTranspose = 0;
 13: PetscEvent  MAT_MultTransposeConstrained = 0, MAT_MultTransposeAdd = 0, MAT_Solve = 0, MAT_Solves = 0, MAT_SolveAdd = 0, MAT_SolveTranspose = 0, MAT_MatSolve = 0;
 14: PetscEvent  MAT_SolveTransposeAdd = 0, MAT_Relax = 0, MAT_ForwardSolve = 0, MAT_BackwardSolve = 0, MAT_LUFactor = 0, MAT_LUFactorSymbolic = 0;
 15: PetscEvent  MAT_LUFactorNumeric = 0, MAT_CholeskyFactor = 0, MAT_CholeskyFactorSymbolic = 0, MAT_CholeskyFactorNumeric = 0, MAT_ILUFactor = 0;
 16: PetscEvent  MAT_ILUFactorSymbolic = 0, MAT_ICCFactorSymbolic = 0, MAT_Copy = 0, MAT_Convert = 0, MAT_Scale = 0, MAT_AssemblyBegin = 0;
 17: PetscEvent  MAT_AssemblyEnd = 0, MAT_SetValues = 0, MAT_GetValues = 0, MAT_GetRow = 0, MAT_GetSubMatrices = 0, MAT_GetColoring = 0, MAT_GetOrdering = 0;
 18: PetscEvent  MAT_IncreaseOverlap = 0, MAT_Partitioning = 0, MAT_ZeroEntries = 0, MAT_Load = 0, MAT_View = 0, MAT_AXPY = 0, MAT_FDColoringCreate = 0;
 19: PetscEvent  MAT_FDColoringApply = 0,MAT_Transpose = 0,MAT_FDColoringFunction = 0;
 20: PetscEvent  MAT_MatMult = 0, MAT_MatMultSymbolic = 0, MAT_MatMultNumeric = 0;
 21: PetscEvent  MAT_PtAP = 0, MAT_PtAPSymbolic = 0, MAT_PtAPNumeric = 0;
 22: PetscEvent  MAT_MatMultTranspose = 0, MAT_MatMultTransposeSymbolic = 0, MAT_MatMultTransposeNumeric = 0;

 24: /* nasty global values for MatSetValue() */
 25: PetscInt     MatSetValue_Row = 0;
 26: PetscInt     MatSetValue_Column = 0;
 27: PetscScalar  MatSetValue_Value = 0.0;

 31: /*@
 32:    MatRealPart - Zeros out the imaginary part of the matrix

 34:    Collective on Mat

 36:    Input Parameters:
 37: .  mat - the matrix

 39:    Level: advanced


 42: .seealso: MatImaginaryPart()
 43: @*/

 45: PetscErrorCode  MatRealPart(Mat mat)
 46: {

 52:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
 53:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
 54:   if (!mat->ops->realpart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
 55:   MatPreallocated(mat);
 56:   (*mat->ops->realpart)(mat);
 57:   return(0);
 58: }

 62: /*@
 63:    MatImaginaryPart - Moves the imaginary part of the matrix to the real part and zeros the imaginary part

 65:    Collective on Mat

 67:    Input Parameters:
 68: .  mat - the matrix

 70:    Level: advanced


 73: .seealso: MatRealPart()
 74: @*/

 76: PetscErrorCode  MatImaginaryPart(Mat mat)
 77: {

 83:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
 84:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
 85:   if (!mat->ops->imaginarypart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
 86:   MatPreallocated(mat);
 87:   (*mat->ops->imaginarypart)(mat);
 88:   return(0);
 89: }

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

 98:    Not Collective

100:    Input Parameters:
101: +  mat - the matrix
102: -  row - the row to get

104:    Output Parameters:
105: +  ncols -  if not NULL, the number of nonzeros in the row
106: .  cols - if not NULL, the column numbers
107: -  vals - if not NULL, the values

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

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

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

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

124:    You can only have one call to MatGetRow() outstanding for a particular
125:    matrix at a time, per processor. MatGetRow() can only obtain rows
126:    associated with the given processor, it cannot get rows from the 
127:    other processors; for that we suggest using MatGetSubMatrices(), then
128:    MatGetRow() on the submatrix. The row indix passed to MatGetRows() 
129:    is in the global number of rows.

131:    Fortran Notes:
132:    The calling sequence from Fortran is 
133: .vb
134:    MatGetRow(matrix,row,ncols,cols,values,ierr)
135:          Mat     matrix (input)
136:          integer row    (input)
137:          integer ncols  (output)
138:          integer cols(maxcols) (output)
139:          double precision (or double complex) values(maxcols) output
140: .ve
141:    where maxcols >= maximum nonzeros in any row of the matrix.


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

148:    Level: advanced

150:    Concepts: matrices^row access

152: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
153: @*/

155: PetscErrorCode  MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
156: {
158:   PetscInt       incols;

163:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
164:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
165:   if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
166:   MatPreallocated(mat);
168:   (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);
169:   if (ncols) *ncols = incols;
171:   return(0);
172: }

176: /*@
177:    MatConjugate - replaces the matrix values with their complex conjugates

179:    Collective on Mat

181:    Input Parameters:
182: .  mat - the matrix

184:    Level: advanced

186: .seealso:  VecConjugate()
187: @*/
188: PetscErrorCode  MatConjugate(Mat mat)
189: {

194:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
195:   if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov");
196:   (*mat->ops->conjugate)(mat);
197:   return(0);
198: }

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

205:    Not Collective

207:    Input Parameters:
208: +  mat - the matrix
209: .  row - the row to get
210: .  ncols, cols - the number of nonzeros and their columns
211: -  vals - if nonzero the column values

213:    Notes: 
214:    This routine should be called after you have finished examining the entries.

216:    Fortran Notes:
217:    The calling sequence from Fortran is 
218: .vb
219:    MatRestoreRow(matrix,row,ncols,cols,values,ierr)
220:       Mat     matrix (input)
221:       integer row    (input)
222:       integer ncols  (output)
223:       integer cols(maxcols) (output)
224:       double precision (or double complex) values(maxcols) output
225: .ve
226:    Where maxcols >= maximum nonzeros in any row of the matrix. 

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

231:    Level: advanced

233: .seealso:  MatGetRow()
234: @*/
235: PetscErrorCode  MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
236: {

242:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
243:   if (!mat->ops->restorerow) return(0);
244:   (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);
245:   return(0);
246: }

250: /*@C
251:    MatGetRowUpperTriangular - Sets a flag to enable calls to MatGetRow() for matrix in MATSBAIJ format.  
252:    You should call MatRestoreRowUpperTriangular() after calling MatGetRow/MatRestoreRow() to disable the flag. 

254:    Not Collective

256:    Input Parameters:
257: +  mat - the matrix

259:    Notes:
260:    The flag is to ensure that users are aware of MatGetRow() only provides the upper trianglular part of the row for the matrices in MATSBAIJ format.

262:    Level: advanced

264:    Concepts: matrices^row access

266: .seealso: MatRestoreRowRowUpperTriangular()
267: @*/

269: PetscErrorCode  MatGetRowUpperTriangular(Mat mat)
270: {

276:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
277:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
278:   if (!mat->ops->getrowuppertriangular) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
279:   MatPreallocated(mat);
280:   (*mat->ops->getrowuppertriangular)(mat);
281:   return(0);
282: }

286: /*@C  
287:    MatRestoreRowUpperTriangular - Disable calls to MatGetRow() for matrix in MATSBAIJ format.  

289:    Not Collective

291:    Input Parameters:
292: +  mat - the matrix

294:    Notes: 
295:    This routine should be called after you have finished MatGetRow/MatRestoreRow().


298:    Level: advanced

300: .seealso:  MatGetRowUpperTriangular()
301: @*/
302: PetscErrorCode  MatRestoreRowUpperTriangular(Mat mat)
303: {

308:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
309:   if (!mat->ops->restorerowuppertriangular) return(0);
310:   (*mat->ops->restorerowuppertriangular)(mat);
311:   return(0);
312: }

316: /*@C
317:    MatSetOptionsPrefix - Sets the prefix used for searching for all 
318:    Mat options in the database.

320:    Collective on Mat

322:    Input Parameter:
323: +  A - the Mat context
324: -  prefix - the prefix to prepend to all option names

326:    Notes:
327:    A hyphen (-) must NOT be given at the beginning of the prefix name.
328:    The first character of all runtime options is AUTOMATICALLY the hyphen.

330:    Level: advanced

332: .keywords: Mat, set, options, prefix, database

334: .seealso: MatSetFromOptions()
335: @*/
336: PetscErrorCode  MatSetOptionsPrefix(Mat A,const char prefix[])
337: {

342:   PetscObjectSetOptionsPrefix((PetscObject)A,prefix);
343:   return(0);
344: }

348: /*@C
349:    MatAppendOptionsPrefix - Appends to the prefix used for searching for all 
350:    Mat options in the database.

352:    Collective on Mat

354:    Input Parameters:
355: +  A - the Mat context
356: -  prefix - the prefix to prepend to all option names

358:    Notes:
359:    A hyphen (-) must NOT be given at the beginning of the prefix name.
360:    The first character of all runtime options is AUTOMATICALLY the hyphen.

362:    Level: advanced

364: .keywords: Mat, append, options, prefix, database

366: .seealso: MatGetOptionsPrefix()
367: @*/
368: PetscErrorCode  MatAppendOptionsPrefix(Mat A,const char prefix[])
369: {
371: 
374:   PetscObjectAppendOptionsPrefix((PetscObject)A,prefix);
375:   return(0);
376: }

380: /*@C
381:    MatGetOptionsPrefix - Sets the prefix used for searching for all 
382:    Mat options in the database.

384:    Not Collective

386:    Input Parameter:
387: .  A - the Mat context

389:    Output Parameter:
390: .  prefix - pointer to the prefix string used

392:    Notes: On the fortran side, the user should pass in a string 'prefix' of
393:    sufficient length to hold the prefix.

395:    Level: advanced

397: .keywords: Mat, get, options, prefix, database

399: .seealso: MatAppendOptionsPrefix()
400: @*/
401: PetscErrorCode  MatGetOptionsPrefix(Mat A,const char *prefix[])
402: {

407:   PetscObjectGetOptionsPrefix((PetscObject)A,prefix);
408:   return(0);
409: }

413: /*@
414:    MatSetUp - Sets up the internal matrix data structures for the later use.

416:    Collective on Mat

418:    Input Parameters:
419: .  A - the Mat context

421:    Notes:
422:    For basic use of the Mat classes the user need not explicitly call
423:    MatSetUp(), since these actions will happen automatically.

425:    Level: advanced

427: .keywords: Mat, setup

429: .seealso: MatCreate(), MatDestroy()
430: @*/
431: PetscErrorCode  MatSetUp(Mat A)
432: {

437:   MatSetUpPreallocation(A);
438:   MatSetFromOptions(A);
439:   return(0);
440: }

444: /*@C
445:    MatView - Visualizes a matrix object.

447:    Collective on Mat

449:    Input Parameters:
450: +  mat - the matrix
451: -  viewer - visualization context

453:   Notes:
454:   The available visualization contexts include
455: +    PETSC_VIEWER_STDOUT_SELF - standard output (default)
456: .    PETSC_VIEWER_STDOUT_WORLD - synchronized standard
457:         output where only the first processor opens
458:         the file.  All other processors send their 
459:         data to the first processor to print. 
460: -     PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure

462:    The user can open alternative visualization contexts with
463: +    PetscViewerASCIIOpen() - Outputs matrix to a specified file
464: .    PetscViewerBinaryOpen() - Outputs matrix in binary to a
465:          specified file; corresponding input uses MatLoad()
466: .    PetscViewerDrawOpen() - Outputs nonzero matrix structure to 
467:          an X window display
468: -    PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
469:          Currently only the sequential dense and AIJ
470:          matrix types support the Socket viewer.

472:    The user can call PetscViewerSetFormat() to specify the output
473:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
474:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
475: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
476: .    PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
477: .    PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
478: .    PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 
479:          format common among all matrix types
480: .    PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 
481:          format (which is in many cases the same as the default)
482: .    PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
483:          size and structure (not the matrix entries)
484: .    PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about
485:          the matrix structure

487:    Options Database Keys:
488: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
489: .  -mat_view_info_detailed - Prints more detailed info
490: .  -mat_view - Prints matrix in ASCII format
491: .  -mat_view_matlab - Prints matrix in Matlab format
492: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
493: .  -display <name> - Sets display name (default is host)
494: .  -draw_pause <sec> - Sets number of seconds to pause after display
495: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
496: .  -viewer_socket_machine <machine>
497: .  -viewer_socket_port <port>
498: .  -mat_view_binary - save matrix to file in binary format
499: -  -viewer_binary_filename <name>
500:    Level: beginner

502:    Concepts: matrices^viewing
503:    Concepts: matrices^plotting
504:    Concepts: matrices^printing

506: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 
507:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
508: @*/
509: PetscErrorCode  MatView(Mat mat,PetscViewer viewer)
510: {
511:   PetscErrorCode    ierr;
512:   PetscInt          rows,cols;
513:   PetscTruth        iascii;
514:   const char        *cstr;
515:   PetscViewerFormat format;

520:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm);
523:   if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix");
524:   MatPreallocated(mat);

526:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
527:   if (iascii) {
528:     PetscViewerGetFormat(viewer,&format);
529:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
530:       if (mat->prefix) {
531:         PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);
532:       } else {
533:         PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");
534:       }
535:       PetscViewerASCIIPushTab(viewer);
536:       MatGetType(mat,&cstr);
537:       MatGetSize(mat,&rows,&cols);
538:       PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);
539:       if (mat->ops->getinfo) {
540:         MatInfo info;
541:         MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
542:         PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n",
543:                           (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);
544:       }
545:     }
546:   }
547:   if (mat->ops->view) {
548:     PetscViewerASCIIPushTab(viewer);
549:     (*mat->ops->view)(mat,viewer);
550:     PetscViewerASCIIPopTab(viewer);
551:   } else if (!iascii) {
552:     SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
553:   }
554:   if (iascii) {
555:     PetscViewerGetFormat(viewer,&format);
556:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
557:       PetscViewerASCIIPopTab(viewer);
558:     }
559:   }
560:   return(0);
561: }

565: /*@C
566:    MatScaleSystem - Scale a vector solution and right hand side to 
567:    match the scaling of a scaled matrix.
568:   
569:    Collective on Mat

571:    Input Parameter:
572: +  mat - the matrix
573: .  b - right hand side vector (or PETSC_NULL)
574: -  x - solution vector (or PETSC_NULL)


577:    Notes: 
578:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
579:    internally scaled, so this does nothing. For MPIROWBS it
580:    permutes and diagonally scales.

582:    The KSP methods automatically call this routine when required
583:    (via PCPreSolve()) so it is rarely used directly.

585:    Level: Developer            

587:    Concepts: matrices^scaling

589: .seealso: MatUseScaledForm(), MatUnScaleSystem()
590: @*/
591: PetscErrorCode  MatScaleSystem(Mat mat,Vec b,Vec x)
592: {

598:   MatPreallocated(mat);

602:   if (mat->ops->scalesystem) {
603:     (*mat->ops->scalesystem)(mat,b,x);
604:   }
605:   return(0);
606: }

610: /*@C
611:    MatUnScaleSystem - Unscales a vector solution and right hand side to 
612:    match the original scaling of a scaled matrix.
613:   
614:    Collective on Mat

616:    Input Parameter:
617: +  mat - the matrix
618: .  b - right hand side vector (or PETSC_NULL)
619: -  x - solution vector (or PETSC_NULL)


622:    Notes: 
623:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
624:    internally scaled, so this does nothing. For MPIROWBS it
625:    permutes and diagonally scales.

627:    The KSP methods automatically call this routine when required
628:    (via PCPreSolve()) so it is rarely used directly.

630:    Level: Developer            

632: .seealso: MatUseScaledForm(), MatScaleSystem()
633: @*/
634: PetscErrorCode  MatUnScaleSystem(Mat mat,Vec b,Vec x)
635: {

641:   MatPreallocated(mat);
644:   if (mat->ops->unscalesystem) {
645:     (*mat->ops->unscalesystem)(mat,b,x);
646:   }
647:   return(0);
648: }

652: /*@C
653:    MatUseScaledForm - For matrix storage formats that scale the 
654:    matrix (for example MPIRowBS matrices are diagonally scaled on
655:    assembly) indicates matrix operations (MatMult() etc) are 
656:    applied using the scaled matrix.
657:   
658:    Collective on Mat

660:    Input Parameter:
661: +  mat - the matrix
662: -  scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 
663:             applying the original matrix

665:    Notes: 
666:    For scaled matrix formats, applying the original, unscaled matrix
667:    will be slightly more expensive

669:    Level: Developer            

671: .seealso: MatScaleSystem(), MatUnScaleSystem()
672: @*/
673: PetscErrorCode  MatUseScaledForm(Mat mat,PetscTruth scaled)
674: {

680:   MatPreallocated(mat);
681:   if (mat->ops->usescaledform) {
682:     (*mat->ops->usescaledform)(mat,scaled);
683:   }
684:   return(0);
685: }

689: /*@
690:    MatDestroy - Frees space taken by a matrix.
691:   
692:    Collective on Mat

694:    Input Parameter:
695: .  A - the matrix

697:    Level: beginner

699: @*/
700: PetscErrorCode  MatDestroy(Mat A)
701: {
705:   if (--A->refct > 0) return(0);
706:   MatPreallocated(A);
707:   /* if memory was published with AMS then destroy it */
708:   PetscObjectDepublish(A);
709:   if (A->ops->destroy) {
710:     (*A->ops->destroy)(A);
711:   }
712:   if (A->mapping) {
713:     ISLocalToGlobalMappingDestroy(A->mapping);
714:   }
715:   if (A->bmapping) {
716:     ISLocalToGlobalMappingDestroy(A->bmapping);
717:   }
718:   PetscFree(A->rmap.range);
719:   PetscFree(A->cmap.range);
720:   PetscFree(A->spptr);
721:   PetscHeaderDestroy(A);
722:   return(0);
723: }

727: /*@
728:    MatValid - Checks whether a matrix object is valid.

730:    Collective on Mat

732:    Input Parameter:
733: .  m - the matrix to check 

735:    Output Parameter:
736:    flg - flag indicating matrix status, either
737:    PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.

739:    Level: developer

741:    Concepts: matrices^validity
742: @*/
743: PetscErrorCode  MatValid(Mat m,PetscTruth *flg)
744: {
747:   if (!m)                           *flg = PETSC_FALSE;
748:   else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
749:   else                              *flg = PETSC_TRUE;
750:   return(0);
751: }

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

760:    Not Collective

762:    Input Parameters:
763: +  mat - the matrix
764: .  v - a logically two-dimensional array of values
765: .  m, idxm - the number of rows and their global indices 
766: .  n, idxn - the number of columns and their global indices
767: -  addv - either ADD_VALUES or INSERT_VALUES, where
768:    ADD_VALUES adds values to any existing entries, and
769:    INSERT_VALUES replaces existing entries with new values

771:    Notes:
772:    By default the values, v, are row-oriented and unsorted.
773:    See MatSetOption() for other options.

775:    Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 
776:    options cannot be mixed without intervening calls to the assembly
777:    routines.

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

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

787:    Efficiency Alert:
788:    The routine MatSetValuesBlocked() may offer much better efficiency
789:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

791:    Level: beginner

793:    Concepts: matrices^putting entries in

795: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
796:           InsertMode, INSERT_VALUES, ADD_VALUES
797: @*/
798: PetscErrorCode  MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
799: {

803:   if (!m || !n) return(0); /* no values to insert */
809:   MatPreallocated(mat);
810:   if (mat->insertmode == NOT_SET_VALUES) {
811:     mat->insertmode = addv;
812:   }
813: #if defined(PETSC_USE_DEBUG)
814:   else if (mat->insertmode != addv) {
815:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
816:   }
817:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
818: #endif

820:   if (mat->assembled) {
821:     mat->was_assembled = PETSC_TRUE;
822:     mat->assembled     = PETSC_FALSE;
823:   }
825:   if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
826:   (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
828:   return(0);
829: }


834: /*@ 
835:    MatSetValuesRowLocal - Inserts a row (block row for BAIJ matrices) of nonzero
836:         values into a matrix

838:    Not Collective

840:    Input Parameters:
841: +  mat - the matrix
842: .  row - the (block) row to set
843: -  v - a logically two-dimensional array of values

845:    Notes:
846:    By the values, v, are column-oriented (for the block version) and sorted

848:    All the nonzeros in the row must be provided

850:    The matrix must have previously had its column indices set

852:    The row must belong to this process

854:    Level: intermediate

856:    Concepts: matrices^putting entries in

858: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
859:           InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues(), MatSetValuesRow(), MatSetLocalToGlobalMapping()
860: @*/
861: PetscErrorCode  MatSetValuesRowLocal(Mat mat,PetscInt row,const PetscScalar v[])
862: {

869:   MatSetValuesRow(mat, mat->mapping->indices[row],v);
870:   return(0);
871: }

875: /*@ 
876:    MatSetValuesRow - Inserts a row (block row for BAIJ matrices) of nonzero
877:         values into a matrix

879:    Not Collective

881:    Input Parameters:
882: +  mat - the matrix
883: .  row - the (block) row to set
884: -  v - a logically two-dimensional array of values

886:    Notes:
887:    By the values, v, are column-oriented (for the block version) and sorted

889:    All the nonzeros in the row must be provided

891:    The matrix must have previously had its column indices set

893:    The row must belong to this process

895:    Level: intermediate

897:    Concepts: matrices^putting entries in

899: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
900:           InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues()
901: @*/
902: PetscErrorCode  MatSetValuesRow(Mat mat,PetscInt row,const PetscScalar v[])
903: {

910: #if defined(PETSC_USE_DEBUG)
911:   if (mat->insertmode == ADD_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add and insert values");
912:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
913: #endif
914:   mat->insertmode = INSERT_VALUES;

916:   if (mat->assembled) {
917:     mat->was_assembled = PETSC_TRUE;
918:     mat->assembled     = PETSC_FALSE;
919:   }
921:   if (!mat->ops->setvaluesrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
922:   (*mat->ops->setvaluesrow)(mat,row,v);
924:   return(0);
925: }

929: /*@
930:    MatSetValuesStencil - Inserts or adds a block of values into a matrix.
931:      Using structured grid indexing

933:    Not Collective

935:    Input Parameters:
936: +  mat - the matrix
937: .  v - a logically two-dimensional array of values
938: .  m - number of rows being entered
939: .  idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
940: .  n - number of columns being entered
941: .  idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 
942: -  addv - either ADD_VALUES or INSERT_VALUES, where
943:    ADD_VALUES adds values to any existing entries, and
944:    INSERT_VALUES replaces existing entries with new values

946:    Notes:
947:    By default the values, v, are row-oriented and unsorted.
948:    See MatSetOption() for other options.

950:    Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 
951:    options cannot be mixed without intervening calls to the assembly
952:    routines.

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

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

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

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

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

970:    In Fortran idxm and idxn should be declared as
971: $     MatStencil idxm(4,m),idxn(4,n)
972:    and the values inserted using
973: $    idxm(MatStencil_i,1) = i
974: $    idxm(MatStencil_j,1) = j
975: $    idxm(MatStencil_k,1) = k
976: $    idxm(MatStencil_c,1) = c
977:    etc

979:    For periodic boundary conditions use negative indices for values to the left (below 0; that are to be 
980:    obtained by wrapping values from right edge). For values to the right of the last entry using that index plus one
981:    etc to obtain values that obtained by wrapping the values from the left edge.

983:    For indices that don't mean anything for your case (like the k index when working in 2d) or the c index when you have
984:    a single value per point) you can skip filling those indices.

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

989:    Efficiency Alert:
990:    The routine MatSetValuesBlockedStencil() may offer much better efficiency
991:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

993:    Level: beginner

995:    Concepts: matrices^putting entries in

997: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
998:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
999: @*/
1000: PetscErrorCode  MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1001: {
1003:   PetscInt       j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1004:   PetscInt       *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);

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

1014:   if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1015:   if (n > 256) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);

1017:   for (i=0; i<m; i++) {
1018:     for (j=0; j<3-sdim; j++) dxm++;
1019:     tmp = *dxm++ - starts[0];
1020:     for (j=0; j<dim-1; j++) {
1021:       if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1022:       else                                       tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1023:     }
1024:     if (mat->stencil.noc) dxm++;
1025:     jdxm[i] = tmp;
1026:   }
1027:   for (i=0; i<n; i++) {
1028:     for (j=0; j<3-sdim; j++) dxn++;
1029:     tmp = *dxn++ - starts[0];
1030:     for (j=0; j<dim-1; j++) {
1031:       if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1032:       else                                       tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1033:     }
1034:     if (mat->stencil.noc) dxn++;
1035:     jdxn[i] = tmp;
1036:   }
1037:   MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
1038:   return(0);
1039: }

1043: /*@C 
1044:    MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix.
1045:      Using structured grid indexing

1047:    Not Collective

1049:    Input Parameters:
1050: +  mat - the matrix
1051: .  v - a logically two-dimensional array of values
1052: .  m - number of rows being entered
1053: .  idxm - grid coordinates for matrix rows being entered
1054: .  n - number of columns being entered
1055: .  idxn - grid coordinates for matrix columns being entered 
1056: -  addv - either ADD_VALUES or INSERT_VALUES, where
1057:    ADD_VALUES adds values to any existing entries, and
1058:    INSERT_VALUES replaces existing entries with new values

1060:    Notes:
1061:    By default the values, v, are row-oriented and unsorted.
1062:    See MatSetOption() for other options.

1064:    Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES 
1065:    options cannot be mixed without intervening calls to the assembly
1066:    routines.

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

1070:    MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran 
1071:    as well as in C.

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

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

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

1084:    In Fortran idxm and idxn should be declared as
1085: $     MatStencil idxm(4,m),idxn(4,n)
1086:    and the values inserted using
1087: $    idxm(MatStencil_i,1) = i
1088: $    idxm(MatStencil_j,1) = j
1089: $    idxm(MatStencil_k,1) = k
1090:    etc

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

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

1100:    Level: beginner

1102:    Concepts: matrices^putting entries in

1104: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1105:           MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
1106: @*/
1107: PetscErrorCode  MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1108: {
1110:   PetscInt       j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1111:   PetscInt       *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);

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

1121:   if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1122:   if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);

1124:   for (i=0; i<m; i++) {
1125:     for (j=0; j<3-sdim; j++) dxm++;
1126:     tmp = *dxm++ - starts[0];
1127:     for (j=0; j<sdim-1; j++) {
1128:       if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1129:       else                                      tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1130:     }
1131:     dxm++;
1132:     jdxm[i] = tmp;
1133:   }
1134:   for (i=0; i<n; i++) {
1135:     for (j=0; j<3-sdim; j++) dxn++;
1136:     tmp = *dxn++ - starts[0];
1137:     for (j=0; j<sdim-1; j++) {
1138:       if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1139:       else                                       tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1140:     }
1141:     dxn++;
1142:     jdxn[i] = tmp;
1143:   }
1144:   MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);
1145:   return(0);
1146: }

1150: /*@ 
1151:    MatSetStencil - Sets the grid information for setting values into a matrix via
1152:         MatSetValuesStencil()

1154:    Not Collective

1156:    Input Parameters:
1157: +  mat - the matrix
1158: .  dim - dimension of the grid 1, 2, or 3
1159: .  dims - number of grid points in x, y, and z direction, including ghost points on your processor
1160: .  starts - starting point of ghost nodes on your processor in x, y, and z direction 
1161: -  dof - number of degrees of freedom per node


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

1167:    For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the
1168:    user.
1169:    
1170:    Level: beginner

1172:    Concepts: matrices^putting entries in

1174: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1175:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
1176: @*/
1177: PetscErrorCode  MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof)
1178: {
1179:   PetscInt i;


1186:   mat->stencil.dim = dim + (dof > 1);
1187:   for (i=0; i<dim; i++) {
1188:     mat->stencil.dims[i]   = dims[dim-i-1];      /* copy the values in backwards */
1189:     mat->stencil.starts[i] = starts[dim-i-1];
1190:   }
1191:   mat->stencil.dims[dim]   = dof;
1192:   mat->stencil.starts[dim] = 0;
1193:   mat->stencil.noc         = (PetscTruth)(dof == 1);
1194:   return(0);
1195: }

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

1202:    Not Collective

1204:    Input Parameters:
1205: +  mat - the matrix
1206: .  v - a logically two-dimensional array of values
1207: .  m, idxm - the number of block rows and their global block indices 
1208: .  n, idxn - the number of block columns and their global block indices
1209: -  addv - either ADD_VALUES or INSERT_VALUES, where
1210:    ADD_VALUES adds values to any existing entries, and
1211:    INSERT_VALUES replaces existing entries with new values

1213:    Notes:
1214:    The m and n count the NUMBER of blocks in the row direction and column direction,
1215:    NOT the total number of rows/columns; for example, if the block size is 2 and 
1216:    you are passing in values for rows 2,3,4,5  then m would be 2 (not 4).

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

1221:    Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
1222:    options cannot be mixed without intervening calls to the assembly
1223:    routines.

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

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

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

1239:    Restrictions:
1240:    MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats

1242:    Level: intermediate

1244:    Concepts: matrices^putting entries in blocked

1246: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
1247: @*/
1248: PetscErrorCode  MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
1249: {

1253:   if (!m || !n) return(0); /* no values to insert */
1259:   MatPreallocated(mat);
1260:   if (mat->insertmode == NOT_SET_VALUES) {
1261:     mat->insertmode = addv;
1262:   }
1263: #if defined(PETSC_USE_DEBUG) 
1264:   else if (mat->insertmode != addv) {
1265:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1266:   }
1267:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1268: #endif

1270:   if (mat->assembled) {
1271:     mat->was_assembled = PETSC_TRUE;
1272:     mat->assembled     = PETSC_FALSE;
1273:   }
1275:   if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1276:   (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
1278:   return(0);
1279: }

1283: /*@ 
1284:    MatGetValues - Gets a block of values from a matrix.

1286:    Not Collective; currently only returns a local block

1288:    Input Parameters:
1289: +  mat - the matrix
1290: .  v - a logically two-dimensional array for storing the values
1291: .  m, idxm - the number of rows and their global indices 
1292: -  n, idxn - the number of columns and their global indices

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

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

1302:    MatGetValues() requires that the matrix has been assembled
1303:    with MatAssemblyBegin()/MatAssemblyEnd().  Thus, calls to
1304:    MatSetValues() and MatGetValues() CANNOT be made in succession
1305:    without intermediate matrix assembly.

1307:    Level: advanced

1309:    Concepts: matrices^accessing values

1311: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
1312: @*/
1313: PetscErrorCode  MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[])
1314: {

1323:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1324:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1325:   if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1326:   MatPreallocated(mat);

1329:   (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
1331:   return(0);
1332: }

1336: /*@
1337:    MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
1338:    the routine MatSetValuesLocal() to allow users to insert matrix entries
1339:    using a local (per-processor) numbering.

1341:    Not Collective

1343:    Input Parameters:
1344: +  x - the matrix
1345: -  mapping - mapping created with ISLocalToGlobalMappingCreate() 
1346:              or ISLocalToGlobalMappingCreateIS()

1348:    Level: intermediate

1350:    Concepts: matrices^local to global mapping
1351:    Concepts: local to global mapping^for matrices

1353: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
1354: @*/
1355: PetscErrorCode  MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
1356: {
1362:   if (x->mapping) {
1363:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1364:   }
1365:   MatPreallocated(x);

1367:   if (x->ops->setlocaltoglobalmapping) {
1368:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1369:   } else {
1370:     x->mapping = mapping;
1371:     PetscObjectReference((PetscObject)mapping);
1372:   }
1373:   return(0);
1374: }

1378: /*@
1379:    MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
1380:    by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
1381:    entries using a local (per-processor) numbering.

1383:    Not Collective

1385:    Input Parameters:
1386: +  x - the matrix
1387: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or
1388:              ISLocalToGlobalMappingCreateIS()

1390:    Level: intermediate

1392:    Concepts: matrices^local to global mapping blocked
1393:    Concepts: local to global mapping^for matrices, blocked

1395: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
1396:            MatSetValuesBlocked(), MatSetValuesLocal()
1397: @*/
1398: PetscErrorCode  MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
1399: {
1405:   if (x->bmapping) {
1406:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1407:   }
1408:   x->bmapping = mapping;
1409:   PetscObjectReference((PetscObject)mapping);
1410:   return(0);
1411: }

1415: /*@
1416:    MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
1417:    using a local ordering of the nodes. 

1419:    Not Collective

1421:    Input Parameters:
1422: +  x - the matrix
1423: .  nrow, irow - number of rows and their local indices
1424: .  ncol, icol - number of columns and their local indices
1425: .  y -  a logically two-dimensional array of values
1426: -  addv - either INSERT_VALUES or ADD_VALUES, where
1427:    ADD_VALUES adds values to any existing entries, and
1428:    INSERT_VALUES replaces existing entries with new values

1430:    Notes:
1431:    Before calling MatSetValuesLocal(), the user must first set the
1432:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

1434:    Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 
1435:    options cannot be mixed without intervening calls to the assembly
1436:    routines.

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

1441:    Level: intermediate

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

1445: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
1446:            MatSetValueLocal()
1447: @*/
1448: PetscErrorCode  MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1449: {
1451:   PetscInt       irowm[2048],icolm[2048];

1459:   MatPreallocated(mat);
1460:   if (mat->insertmode == NOT_SET_VALUES) {
1461:     mat->insertmode = addv;
1462:   }
1463: #if defined(PETSC_USE_DEBUG) 
1464:   else if (mat->insertmode != addv) {
1465:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1466:   }
1467:   if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
1468:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1469:   }
1470:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1471: #endif

1473:   if (mat->assembled) {
1474:     mat->was_assembled = PETSC_TRUE;
1475:     mat->assembled     = PETSC_FALSE;
1476:   }
1478:   if (!mat->ops->setvalueslocal) {
1479:     ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
1480:     ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
1481:     (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
1482:   } else {
1483:     (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
1484:   }
1485:   mat->same_nonzero = PETSC_FALSE;
1487:   return(0);
1488: }

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

1496:    Not Collective

1498:    Input Parameters:
1499: +  x - the matrix
1500: .  nrow, irow - number of rows and their local indices
1501: .  ncol, icol - number of columns and their local indices
1502: .  y -  a logically two-dimensional array of values
1503: -  addv - either INSERT_VALUES or ADD_VALUES, where
1504:    ADD_VALUES adds values to any existing entries, and
1505:    INSERT_VALUES replaces existing entries with new values

1507:    Notes:
1508:    Before calling MatSetValuesBlockedLocal(), the user must first set the
1509:    local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
1510:    where the mapping MUST be set for matrix blocks, not for matrix elements.

1512:    Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1513:    options cannot be mixed without intervening calls to the assembly
1514:    routines.

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

1519:    Level: intermediate

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

1523: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
1524: @*/
1525: PetscErrorCode  MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1526: {
1528:   PetscInt       irowm[2048],icolm[2048];

1536:   MatPreallocated(mat);
1537:   if (mat->insertmode == NOT_SET_VALUES) {
1538:     mat->insertmode = addv;
1539:   }
1540: #if defined(PETSC_USE_DEBUG) 
1541:   else if (mat->insertmode != addv) {
1542:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1543:   }
1544:   if (!mat->bmapping) {
1545:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
1546:   }
1547:   if (nrow > 2048 || ncol > 2048) {
1548:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1549:   }
1550:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1551: #endif

1553:   if (mat->assembled) {
1554:     mat->was_assembled = PETSC_TRUE;
1555:     mat->assembled     = PETSC_FALSE;
1556:   }
1558:   ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1559:   ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1560:   (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1562:   return(0);
1563: }

1565: /* --------------------------------------------------------*/
1568: /*@
1569:    MatMult - Computes the matrix-vector product, y = Ax.

1571:    Collective on Mat and Vec

1573:    Input Parameters:
1574: +  mat - the matrix
1575: -  x   - the vector to be multiplied

1577:    Output Parameters:
1578: .  y - the result

1580:    Notes:
1581:    The vectors x and y cannot be the same.  I.e., one cannot
1582:    call MatMult(A,y,y).

1584:    Level: beginner

1586:    Concepts: matrix-vector product

1588: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1589: @*/
1590: PetscErrorCode  MatMult(Mat mat,Vec x,Vec y)
1591: {


1600:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1601:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1602:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1603: #ifndef PETSC_HAVE_CONSTRAINTS
1604:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1605:   if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1606:   if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);
1607: #endif
1608:   MatPreallocated(mat);

1610:   if (mat->nullsp) {
1611:     MatNullSpaceRemove(mat->nullsp,x,&x);
1612:   }

1614:   if (!mat->ops->mult) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply defined");
1616:   (*mat->ops->mult)(mat,x,y);

1619:   if (mat->nullsp) {
1620:     MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1621:   }
1622:   PetscObjectStateIncrease((PetscObject)y);
1623:   return(0);
1624: }

1628: /*@
1629:    MatMultTranspose - Computes matrix transpose times a vector.

1631:    Collective on Mat and Vec

1633:    Input Parameters:
1634: +  mat - the matrix
1635: -  x   - the vector to be multilplied

1637:    Output Parameters:
1638: .  y - the result

1640:    Notes:
1641:    The vectors x and y cannot be the same.  I.e., one cannot
1642:    call MatMultTranspose(A,y,y).

1644:    Level: beginner

1646:    Concepts: matrix vector product^transpose

1648: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1649: @*/
1650: PetscErrorCode  MatMultTranspose(Mat mat,Vec x,Vec y)
1651: {


1660:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1661:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1662:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1663: #ifndef PETSC_HAVE_CONSTRAINTS
1664:   if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
1665:   if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
1666: #endif
1667:   MatPreallocated(mat);

1669:   if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined");
1671:   (*mat->ops->multtranspose)(mat,x,y);
1673:   PetscObjectStateIncrease((PetscObject)y);
1674:   return(0);
1675: }

1679: /*@
1680:     MatMultAdd -  Computes v3 = v2 + A * v1.

1682:     Collective on Mat and Vec

1684:     Input Parameters:
1685: +   mat - the matrix
1686: -   v1, v2 - the vectors

1688:     Output Parameters:
1689: .   v3 - the result

1691:     Notes:
1692:     The vectors v1 and v3 cannot be the same.  I.e., one cannot
1693:     call MatMultAdd(A,v1,v2,v1).

1695:     Level: beginner

1697:     Concepts: matrix vector product^addition

1699: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1700: @*/
1701: PetscErrorCode  MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1702: {


1712:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1713:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1714:   if (mat->cmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->cmap.N,v1->map.N);
1715:   if (mat->rmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->rmap.N,v2->map.N);
1716:   if (mat->rmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->rmap.N,v3->map.N);
1717:   if (mat->rmap.n != v3->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->rmap.n,v3->map.n);
1718:   if (mat->rmap.n != v2->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->rmap.n,v2->map.n);
1719:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1720:   MatPreallocated(mat);

1723:   (*mat->ops->multadd)(mat,v1,v2,v3);
1725:   PetscObjectStateIncrease((PetscObject)v3);
1726:   return(0);
1727: }

1731: /*@
1732:    MatMultTransposeAdd - Computes v3 = v2 + A' * v1.

1734:    Collective on Mat and Vec

1736:    Input Parameters:
1737: +  mat - the matrix
1738: -  v1, v2 - the vectors

1740:    Output Parameters:
1741: .  v3 - the result

1743:    Notes:
1744:    The vectors v1 and v3 cannot be the same.  I.e., one cannot
1745:    call MatMultTransposeAdd(A,v1,v2,v1).

1747:    Level: beginner

1749:    Concepts: matrix vector product^transpose and addition

1751: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1752: @*/
1753: PetscErrorCode  MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1754: {


1764:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1765:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1766:   if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1767:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1768:   if (mat->rmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->rmap.N,v1->map.N);
1769:   if (mat->cmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->cmap.N,v2->map.N);
1770:   if (mat->cmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->cmap.N,v3->map.N);
1771:   MatPreallocated(mat);

1774:   (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1776:   PetscObjectStateIncrease((PetscObject)v3);
1777:   return(0);
1778: }

1782: /*@
1783:    MatMultConstrained - The inner multiplication routine for a
1784:    constrained matrix P^T A P.

1786:    Collective on Mat and Vec

1788:    Input Parameters:
1789: +  mat - the matrix
1790: -  x   - the vector to be multilplied

1792:    Output Parameters:
1793: .  y - the result

1795:    Notes:
1796:    The vectors x and y cannot be the same.  I.e., one cannot
1797:    call MatMult(A,y,y).

1799:    Level: beginner

1801: .keywords: matrix, multiply, matrix-vector product, constraint
1802: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1803: @*/
1804: PetscErrorCode  MatMultConstrained(Mat mat,Vec x,Vec y)
1805: {

1812:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1813:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1814:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1815:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1816:   if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1817:   if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);

1820:   (*mat->ops->multconstrained)(mat,x,y);
1822:   PetscObjectStateIncrease((PetscObject)y);

1824:   return(0);
1825: }

1829: /*@
1830:    MatMultTransposeConstrained - The inner multiplication routine for a
1831:    constrained matrix P^T A^T P.

1833:    Collective on Mat and Vec

1835:    Input Parameters:
1836: +  mat - the matrix
1837: -  x   - the vector to be multilplied

1839:    Output Parameters:
1840: .  y - the result

1842:    Notes:
1843:    The vectors x and y cannot be the same.  I.e., one cannot
1844:    call MatMult(A,y,y).

1846:    Level: beginner

1848: .keywords: matrix, multiply, matrix-vector product, constraint
1849: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1850: @*/
1851: PetscErrorCode  MatMultTransposeConstrained(Mat mat,Vec x,Vec y)
1852: {

1859:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1860:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1861:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1862:   if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1863:   if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);

1866:   (*mat->ops->multtransposeconstrained)(mat,x,y);
1868:   PetscObjectStateIncrease((PetscObject)y);

1870:   return(0);
1871: }
1872: /* ------------------------------------------------------------*/
1875: /*@
1876:    MatGetInfo - Returns information about matrix storage (number of
1877:    nonzeros, memory, etc.).

1879:    Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1880:    as the flag

1882:    Input Parameters:
1883: .  mat - the matrix

1885:    Output Parameters:
1886: +  flag - flag indicating the type of parameters to be returned
1887:    (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1888:    MAT_GLOBAL_SUM - sum over all processors)
1889: -  info - matrix information context

1891:    Notes:
1892:    The MatInfo context contains a variety of matrix data, including
1893:    number of nonzeros allocated and used, number of mallocs during
1894:    matrix assembly, etc.  Additional information for factored matrices
1895:    is provided (such as the fill ratio, number of mallocs during
1896:    factorization, etc.).  Much of this info is printed to STDOUT
1897:    when using the runtime options 
1898: $       -info -mat_view_info

1900:    Example for C/C++ Users:
1901:    See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1902:    data within the MatInfo context.  For example, 
1903: .vb
1904:       MatInfo info;
1905:       Mat     A;
1906:       double  mal, nz_a, nz_u;

1908:       MatGetInfo(A,MAT_LOCAL,&info);
1909:       mal  = info.mallocs;
1910:       nz_a = info.nz_allocated;
1911: .ve

1913:    Example for Fortran Users:
1914:    Fortran users should declare info as a double precision
1915:    array of dimension MAT_INFO_SIZE, and then extract the parameters
1916:    of interest.  See the file ${PETSC_DIR}/include/finclude/petscmat.h
1917:    a complete list of parameter names.
1918: .vb
1919:       double  precision info(MAT_INFO_SIZE)
1920:       double  precision mal, nz_a
1921:       Mat     A
1922:       integer ierr

1924:       call MatGetInfo(A,MAT_LOCAL,info,ierr)
1925:       mal = info(MAT_INFO_MALLOCS)
1926:       nz_a = info(MAT_INFO_NZ_ALLOCATED)
1927: .ve

1929:     Level: intermediate

1931:     Concepts: matrices^getting information on
1932:  
1933: @*/
1934: PetscErrorCode  MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1935: {

1942:   if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1943:   MatPreallocated(mat);
1944:   (*mat->ops->getinfo)(mat,flag,info);
1945:   return(0);
1946: }

1948: /* ----------------------------------------------------------*/
1951: /*@C  
1952:    MatILUDTFactor - Performs a drop tolerance ILU factorization.

1954:    Collective on Mat

1956:    Input Parameters:
1957: +  mat - the matrix
1958: .  row - row permutation
1959: .  col - column permutation
1960: -  info - information about the factorization to be done

1962:    Output Parameters:
1963: .  fact - the factored matrix

1965:    Level: developer

1967:    Notes:
1968:    Most users should employ the simplified KSP interface for linear solvers
1969:    instead of working directly with matrix algebra routines such as this.
1970:    See, e.g., KSPCreate().

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

1977:     Concepts: matrices^ILUDT factorization

1979: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1980: @*/
1981: PetscErrorCode  MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1982: {

1992:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1993:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1994:   if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1995:   MatPreallocated(mat);
1997:   (*mat->ops->iludtfactor)(mat,row,col,info,fact);
1999:   PetscObjectStateIncrease((PetscObject)*fact);

2001:   return(0);
2002: }

2006: /*@  
2007:    MatLUFactor - Performs in-place LU factorization of matrix.

2009:    Collective on Mat

2011:    Input Parameters:
2012: +  mat - the matrix
2013: .  row - row permutation
2014: .  col - column permutation
2015: -  info - options for factorization, includes 
2016: $          fill - expected fill as ratio of original fill.
2017: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2018: $                   Run with the option -info to determine an optimal value to use

2020:    Notes:
2021:    Most users should employ the simplified KSP interface for linear solvers
2022:    instead of working directly with matrix algebra routines such as this.
2023:    See, e.g., KSPCreate().

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

2028:    Level: developer

2030:    Concepts: matrices^LU factorization

2032: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
2033:           MatGetOrdering(), MatSetUnfactored(), MatFactorInfo

2035: @*/
2036: PetscErrorCode  MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2037: {

2046:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2047:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2048:   if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2049:   MatPreallocated(mat);

2052:   (*mat->ops->lufactor)(mat,row,col,info);
2054:   PetscObjectStateIncrease((PetscObject)mat);
2055:   return(0);
2056: }

2060: /*@  
2061:    MatILUFactor - Performs in-place ILU factorization of matrix.

2063:    Collective on Mat

2065:    Input Parameters:
2066: +  mat - the matrix
2067: .  row - row permutation
2068: .  col - column permutation
2069: -  info - structure containing 
2070: $      levels - number of levels of fill.
2071: $      expected fill - as ratio of original fill.
2072: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
2073:                 missing diagonal entries)

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

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

2083:    Level: developer

2085:    Concepts: matrices^ILU factorization

2087: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2088: @*/
2089: PetscErrorCode  MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2090: {

2099:   if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
2100:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2101:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2102:   if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2103:   MatPreallocated(mat);

2106:   (*mat->ops->ilufactor)(mat,row,col,info);
2108:   PetscObjectStateIncrease((PetscObject)mat);
2109:   return(0);
2110: }

2114: /*@  
2115:    MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
2116:    Call this routine before calling MatLUFactorNumeric().

2118:    Collective on Mat

2120:    Input Parameters:
2121: +  mat - the matrix
2122: .  row, col - row and column permutations
2123: -  info - options for factorization, includes 
2124: $          fill - expected fill as ratio of original fill.
2125: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2126: $                   Run with the option -info to determine an optimal value to use

2128:    Output Parameter:
2129: .  fact - new matrix that has been symbolically factored

2131:    Notes:
2132:    See the users manual for additional information about
2133:    choosing the fill factor for better efficiency.

2135:    Most users should employ the simplified KSP interface for linear solvers
2136:    instead of working directly with matrix algebra routines such as this.
2137:    See, e.g., KSPCreate().

2139:    Level: developer

2141:    Concepts: matrices^LU symbolic factorization

2143: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2144: @*/
2145: PetscErrorCode  MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
2146: {

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

2162:   (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
2164:   PetscObjectStateIncrease((PetscObject)*fact);
2165:   return(0);
2166: }

2170: /*@  
2171:    MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
2172:    Call this routine after first calling MatLUFactorSymbolic().

2174:    Collective on Mat

2176:    Input Parameters:
2177: +  mat - the matrix
2178: .  info - options for factorization
2179: -  fact - the matrix generated for the factor, from MatLUFactorSymbolic()

2181:    Notes:
2182:    See MatLUFactor() for in-place factorization.  See 
2183:    MatCholeskyFactorNumeric() for the symmetric, positive definite case.  

2185:    Most users should employ the simplified KSP interface for linear solvers
2186:    instead of working directly with matrix algebra routines such as this.
2187:    See, e.g., KSPCreate().

2189:    Level: developer

2191:    Concepts: matrices^LU numeric factorization

2193: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
2194: @*/
2195: PetscErrorCode  MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2196: {

2204:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2205:   if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2206:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2207:   }
2208:   if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2209:   MatPreallocated(mat);
2211:   (*(*fact)->ops->lufactornumeric)(mat,info,fact);

2214:   MatView_Private(*fact);
2215:   PetscObjectStateIncrease((PetscObject)*fact);
2216:   return(0);
2217: }

2221: /*@  
2222:    MatCholeskyFactor - Performs in-place Cholesky factorization of a
2223:    symmetric matrix. 

2225:    Collective on Mat

2227:    Input Parameters:
2228: +  mat - the matrix
2229: .  perm - row and column permutations
2230: -  f - expected fill as ratio of original fill

2232:    Notes:
2233:    See MatLUFactor() for the nonsymmetric case.  See also
2234:    MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().

2236:    Most users should employ the simplified KSP interface for linear solvers
2237:    instead of working directly with matrix algebra routines such as this.
2238:    See, e.g., KSPCreate().

2240:    Level: developer

2242:    Concepts: matrices^Cholesky factorization

2244: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
2245:           MatGetOrdering()

2247: @*/
2248: PetscErrorCode  MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info)
2249: {

2257:   if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2258:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2259:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2260:   if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2261:   MatPreallocated(mat);

2264:   (*mat->ops->choleskyfactor)(mat,perm,info);
2266:   PetscObjectStateIncrease((PetscObject)mat);
2267:   return(0);
2268: }

2272: /*@  
2273:    MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
2274:    of a symmetric matrix. 

2276:    Collective on Mat

2278:    Input Parameters:
2279: +  mat - the matrix
2280: .  perm - row and column permutations
2281: -  info - options for factorization, includes 
2282: $          fill - expected fill as ratio of original fill.
2283: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2284: $                   Run with the option -info to determine an optimal value to use

2286:    Output Parameter:
2287: .  fact - the factored matrix

2289:    Notes:
2290:    See MatLUFactorSymbolic() for the nonsymmetric case.  See also
2291:    MatCholeskyFactor() and MatCholeskyFactorNumeric().

2293:    Most users should employ the simplified KSP interface for linear solvers
2294:    instead of working directly with matrix algebra routines such as this.
2295:    See, e.g., KSPCreate().

2297:    Level: developer

2299:    Concepts: matrices^Cholesky symbolic factorization

2301: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
2302:           MatGetOrdering()

2304: @*/
2305: PetscErrorCode  MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
2306: {

2315:   if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2316:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2317:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2318:   if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2319:   MatPreallocated(mat);

2322:   (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);
2324:   PetscObjectStateIncrease((PetscObject)*fact);
2325:   return(0);
2326: }

2330: /*@  
2331:    MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
2332:    of a symmetric matrix. Call this routine after first calling
2333:    MatCholeskyFactorSymbolic().

2335:    Collective on Mat

2337:    Input Parameter:
2338: .  mat - the initial matrix
2339: .  info - options for factorization
2340: -  fact - the symbolic factor of mat

2342:    Output Parameter:
2343: .  fact - the factored matrix

2345:    Notes:
2346:    Most users should employ the simplified KSP interface for linear solvers
2347:    instead of working directly with matrix algebra routines such as this.
2348:    See, e.g., KSPCreate().

2350:    Level: developer

2352:    Concepts: matrices^Cholesky numeric factorization

2354: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
2355: @*/
2356: PetscErrorCode  MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2357: {

2364:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2365:   if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2366:   if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2367:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2368:   }
2369:   MatPreallocated(mat);

2372:   (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);
2374:   PetscObjectStateIncrease((PetscObject)*fact);
2375:   return(0);
2376: }

2378: /* ----------------------------------------------------------------*/
2381: /*@
2382:    MatSolve - Solves A x = b, given a factored matrix.

2384:    Collective on Mat and Vec

2386:    Input Parameters:
2387: +  mat - the factored matrix
2388: -  b - the right-hand-side vector

2390:    Output Parameter:
2391: .  x - the result vector

2393:    Notes:
2394:    The vectors b and x cannot be the same.  I.e., one cannot
2395:    call MatSolve(A,x,x).

2397:    Notes:
2398:    Most users should employ the simplified KSP interface for linear solvers
2399:    instead of working directly with matrix algebra routines such as this.
2400:    See, e.g., KSPCreate().

2402:    Level: developer

2404:    Concepts: matrices^triangular solves

2406: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
2407: @*/
2408: PetscErrorCode  MatSolve(Mat mat,Vec b,Vec x)
2409: {

2419:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2420:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2421:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2422:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2423:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2424:   if (!mat->rmap.N && !mat->cmap.N) return(0);
2425:   if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2426:   MatPreallocated(mat);

2429:   (*mat->ops->solve)(mat,b,x);
2431:   PetscObjectStateIncrease((PetscObject)x);
2432:   return(0);
2433: }

2437: /*@
2438:    MatMatSolve - Solves A X = B, given a factored matrix.

2440:    Collective on Mat 

2442:    Input Parameters:
2443: +  mat - the factored matrix
2444: -  b - the right-hand-side vector

2446:    Output Parameter:
2447: .  x - the result vector

2449:    Notes:
2450:    The vectors b and x cannot be the same.  I.e., one cannot
2451:    call MatMatSolve(A,x,x).

2453:    Notes:
2454:    Most users should employ the simplified KSP interface for linear solvers
2455:    instead of working directly with matrix algebra routines such as this.
2456:    See, e.g., KSPCreate().

2458:    Level: developer

2460:    Concepts: matrices^triangular solves

2462: .seealso: MatMatSolveAdd(), MatMatSolveTranspose(), MatMatSolveTransposeAdd()
2463: @*/
2464: PetscErrorCode  MatMatSolve(Mat A,Mat B,Mat X)
2465: {

2475:   if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices");
2476:   if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2477:   if (A->cmap.N != X->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat X: global dim %D %D",A->cmap.N,X->rmap.N);
2478:   if (A->rmap.N != B->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D",A->rmap.N,B->rmap.N);
2479:   if (A->rmap.n != B->rmap.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: local dim %D %D",A->rmap.n,B->rmap.n);
2480:   if (!A->rmap.N && !A->cmap.N) return(0);
2481:   if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2482:   MatPreallocated(A);

2485:   (*A->ops->matsolve)(A,B,X);
2487:   PetscObjectStateIncrease((PetscObject)X);
2488:   return(0);
2489: }


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

2497:    Collective on Mat and Vec

2499:    Input Parameters:
2500: +  mat - the factored matrix
2501: -  b - the right-hand-side vector

2503:    Output Parameter:
2504: .  x - the result vector

2506:    Notes:
2507:    MatSolve() should be used for most applications, as it performs
2508:    a forward solve followed by a backward solve.

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

2513:    Most users should employ the simplified KSP interface for linear solvers
2514:    instead of working directly with matrix algebra routines such as this.
2515:    See, e.g., KSPCreate().

2517:    Level: developer

2519:    Concepts: matrices^forward solves

2521: .seealso: MatSolve(), MatBackwardSolve()
2522: @ */
2523: PetscErrorCode  MatForwardSolve(Mat mat,Vec b,Vec x)
2524: {

2534:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2535:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2536:   if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2537:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2538:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2539:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2540:   MatPreallocated(mat);
2542:   (*mat->ops->forwardsolve)(mat,b,x);
2544:   PetscObjectStateIncrease((PetscObject)x);
2545:   return(0);
2546: }

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

2553:    Collective on Mat and Vec

2555:    Input Parameters:
2556: +  mat - the factored matrix
2557: -  b - the right-hand-side vector

2559:    Output Parameter:
2560: .  x - the result vector

2562:    Notes:
2563:    MatSolve() should be used for most applications, as it performs
2564:    a forward solve followed by a backward solve.

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

2569:    Most users should employ the simplified KSP interface for linear solvers
2570:    instead of working directly with matrix algebra routines such as this.
2571:    See, e.g., KSPCreate().

2573:    Level: developer

2575:    Concepts: matrices^backward solves

2577: .seealso: MatSolve(), MatForwardSolve()
2578: @ */
2579: PetscErrorCode  MatBackwardSolve(Mat mat,Vec b,Vec x)
2580: {

2590:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2591:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2592:   if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2593:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2594:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2595:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2596:   MatPreallocated(mat);

2599:   (*mat->ops->backwardsolve)(mat,b,x);
2601:   PetscObjectStateIncrease((PetscObject)x);
2602:   return(0);
2603: }

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

2610:    Collective on Mat and Vec

2612:    Input Parameters:
2613: +  mat - the factored matrix
2614: .  b - the right-hand-side vector
2615: -  y - the vector to be added to 

2617:    Output Parameter:
2618: .  x - the result vector

2620:    Notes:
2621:    The vectors b and x cannot be the same.  I.e., one cannot
2622:    call MatSolveAdd(A,x,y,x).

2624:    Most users should employ the simplified KSP interface for linear solvers
2625:    instead of working directly with matrix algebra routines such as this.
2626:    See, e.g., KSPCreate().

2628:    Level: developer

2630:    Concepts: matrices^triangular solves

2632: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
2633: @*/
2634: PetscErrorCode  MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
2635: {
2636:   PetscScalar    one = 1.0;
2637:   Vec            tmp;

2649:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2650:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2651:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2652:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2653:   if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
2654:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2655:   if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2656:   MatPreallocated(mat);

2659:   if (mat->ops->solveadd)  {
2660:     (*mat->ops->solveadd)(mat,b,y,x);
2661:   } else {
2662:     /* do the solve then the add manually */
2663:     if (x != y) {
2664:       MatSolve(mat,b,x);
2665:       VecAXPY(x,one,y);
2666:     } else {
2667:       VecDuplicate(x,&tmp);
2668:       PetscLogObjectParent(mat,tmp);
2669:       VecCopy(x,tmp);
2670:       MatSolve(mat,b,x);
2671:       VecAXPY(x,one,tmp);
2672:       VecDestroy(tmp);
2673:     }
2674:   }
2676:   PetscObjectStateIncrease((PetscObject)x);
2677:   return(0);
2678: }

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

2685:    Collective on Mat and Vec

2687:    Input Parameters:
2688: +  mat - the factored matrix
2689: -  b - the right-hand-side vector

2691:    Output Parameter:
2692: .  x - the result vector

2694:    Notes:
2695:    The vectors b and x cannot be the same.  I.e., one cannot
2696:    call MatSolveTranspose(A,x,x).

2698:    Most users should employ the simplified KSP interface for linear solvers
2699:    instead of working directly with matrix algebra routines such as this.
2700:    See, e.g., KSPCreate().

2702:    Level: developer

2704:    Concepts: matrices^triangular solves

2706: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
2707: @*/
2708: PetscErrorCode  MatSolveTranspose(Mat mat,Vec b,Vec x)
2709: {

2719:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2720:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2721:   if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2722:   if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2723:   if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2724:   MatPreallocated(mat);
2726:   (*mat->ops->solvetranspose)(mat,b,x);
2728:   PetscObjectStateIncrease((PetscObject)x);
2729:   return(0);
2730: }

2734: /*@
2735:    MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 
2736:                       factored matrix. 

2738:    Collective on Mat and Vec

2740:    Input Parameters:
2741: +  mat - the factored matrix
2742: .  b - the right-hand-side vector
2743: -  y - the vector to be added to 

2745:    Output Parameter:
2746: .  x - the result vector

2748:    Notes:
2749:    The vectors b and x cannot be the same.  I.e., one cannot
2750:    call MatSolveTransposeAdd(A,x,y,x).

2752:    Most users should employ the simplified KSP interface for linear solvers
2753:    instead of working directly with matrix algebra routines such as this.
2754:    See, e.g., KSPCreate().

2756:    Level: developer

2758:    Concepts: matrices^triangular solves

2760: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
2761: @*/
2762: PetscErrorCode  MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
2763: {
2764:   PetscScalar    one = 1.0;
2766:   Vec            tmp;

2777:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2778:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2779:   if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2780:   if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2781:   if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
2782:   if (x->map.n != y->map.n)   SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2783:   MatPreallocated(mat);

2786:   if (mat->ops->solvetransposeadd) {
2787:     (*mat->ops->solvetransposeadd)(mat,b,y,x);
2788:   } else {
2789:     /* do the solve then the add manually */
2790:     if (x != y) {
2791:       MatSolveTranspose(mat,b,x);
2792:       VecAXPY(x,one,y);
2793:     } else {
2794:       VecDuplicate(x,&tmp);
2795:       PetscLogObjectParent(mat,tmp);
2796:       VecCopy(x,tmp);
2797:       MatSolveTranspose(mat,b,x);
2798:       VecAXPY(x,one,tmp);
2799:       VecDestroy(tmp);
2800:     }
2801:   }
2803:   PetscObjectStateIncrease((PetscObject)x);
2804:   return(0);
2805: }
2806: /* ----------------------------------------------------------------*/

2810: /*@
2811:    MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.

2813:    Collective on Mat and Vec

2815:    Input Parameters:
2816: +  mat - the matrix
2817: .  b - the right hand side
2818: .  omega - the relaxation factor
2819: .  flag - flag indicating the type of SOR (see below)
2820: .  shift -  diagonal shift
2821: -  its - the number of iterations
2822: -  lits - the number of local iterations 

2824:    Output Parameters:
2825: .  x - the solution (can contain an initial guess)

2827:    SOR Flags:
2828: .     SOR_FORWARD_SWEEP - forward SOR
2829: .     SOR_BACKWARD_SWEEP - backward SOR
2830: .     SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2831: .     SOR_LOCAL_FORWARD_SWEEP - local forward SOR 
2832: .     SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 
2833: .     SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2834: .     SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 
2835:          upper/lower triangular part of matrix to
2836:          vector (with omega)
2837: .     SOR_ZERO_INITIAL_GUESS - zero initial guess

2839:    Notes:
2840:    SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2841:    SOR_LOCAL_SYMMETRIC_SWEEP perform separate independent smoothings
2842:    on each processor. 

2844:    Application programmers will not generally use MatRelax() directly,
2845:    but instead will employ the KSP/PC interface.

2847:    Notes for Advanced Users:
2848:    The flags are implemented as bitwise inclusive or operations.
2849:    For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2850:    to specify a zero initial guess for SSOR.

2852:    Most users should employ the simplified KSP interface for linear solvers
2853:    instead of working directly with matrix algebra routines such as this.
2854:    See, e.g., KSPCreate().

2856:    See also, MatPBRelax(). This routine will automatically call the point block
2857:    version if the point version is not available.

2859:    Level: developer

2861:    Concepts: matrices^relaxation
2862:    Concepts: matrices^SOR
2863:    Concepts: matrices^Gauss-Seidel

2865: @*/
2866: PetscErrorCode  MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2867: {

2877:   if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2878:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2879:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2880:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2881:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2882:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2883:   MatPreallocated(mat);
2885:   if (mat->ops->relax) {
2886:     ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2887:   } else {
2888:     ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2889:   }
2891:   PetscObjectStateIncrease((PetscObject)x);
2892:   return(0);
2893: }

2897: /*@
2898:    MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.

2900:    Collective on Mat and Vec

2902:    See MatRelax() for usage

2904:    For multi-component PDEs where the Jacobian is stored in a point block format
2905:    (with the PETSc BAIJ matrix formats) the relaxation is done one point block at 
2906:    a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved
2907:    simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point.

2909:    Level: developer

2911: @*/
2912: PetscErrorCode  MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2913: {

2923:   if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2924:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2925:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2926:   if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2927:   if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2928:   if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2929:   MatPreallocated(mat);

2932:   ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2934:   PetscObjectStateIncrease((PetscObject)x);
2935:   return(0);
2936: }

2940: /*
2941:       Default matrix copy routine.
2942: */
2943: PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str)
2944: {
2945:   PetscErrorCode    ierr;
2946:   PetscInt          i,rstart,rend,nz;
2947:   const PetscInt    *cwork;
2948:   const PetscScalar *vwork;

2951:   if (B->assembled) {
2952:     MatZeroEntries(B);
2953:   }
2954:   MatGetOwnershipRange(A,&rstart,&rend);
2955:   for (i=rstart; i<rend; i++) {
2956:     MatGetRow(A,i,&nz,&cwork,&vwork);
2957:     MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2958:     MatRestoreRow(A,i,&nz,&cwork,&vwork);
2959:   }
2960:   MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2961:   MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2962:   PetscObjectStateIncrease((PetscObject)B);
2963:   return(0);
2964: }

2968: /*@
2969:    MatCopy - Copys a matrix to another matrix.

2971:    Collective on Mat

2973:    Input Parameters:
2974: +  A - the matrix
2975: -  str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN

2977:    Output Parameter:
2978: .  B - where the copy is put

2980:    Notes:
2981:    If you use SAME_NONZERO_PATTERN then the two matrices had better have the 
2982:    same nonzero pattern or the routine will crash.

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

2988:    Level: intermediate
2989:    
2990:    Concepts: matrices^copying

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

2994: @*/
2995: PetscErrorCode  MatCopy(Mat A,Mat B,MatStructure str)
2996: {

3004:   MatPreallocated(B);
3006:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3007:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3008:   if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3009:   MatPreallocated(A);

3012:   if (A->ops->copy) {
3013:     (*A->ops->copy)(A,B,str);
3014:   } else { /* generic conversion */
3015:     MatCopy_Basic(A,B,str);
3016:   }
3017:   if (A->mapping) {
3018:     if (B->mapping) {ISLocalToGlobalMappingDestroy(B->mapping);B->mapping = 0;}
3019:     MatSetLocalToGlobalMapping(B,A->mapping);
3020:   }
3021:   if (A->bmapping) {
3022:     if (B->bmapping) {ISLocalToGlobalMappingDestroy(B->bmapping);B->bmapping = 0;}
3023:     MatSetLocalToGlobalMappingBlock(B,A->mapping);
3024:   }
3026:   PetscObjectStateIncrease((PetscObject)B);
3027:   return(0);
3028: }

3032: /*@C  
3033:    MatConvert - Converts a matrix to another matrix, either of the same
3034:    or different type.

3036:    Collective on Mat

3038:    Input Parameters:
3039: +  mat - the matrix
3040: .  newtype - new matrix type.  Use MATSAME to create a new matrix of the
3041:    same type as the original matrix.
3042: -  reuse - denotes if the destination matrix is to be created or reused.  Currently
3043:    MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use
3044:    MAT_INITIAL_MATRIX.
3045:    Output Parameter:
3046: .  M - pointer to place new matrix

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

3053:    Level: intermediate

3055:    Concepts: matrices^converting between storage formats

3057: .seealso: MatCopy(), MatDuplicate()
3058: @*/
3059: PetscErrorCode  MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M)
3060: {
3061:   PetscErrorCode         ierr;
3062:   PetscTruth             sametype,issame,flg;
3063:   char                   convname[256],mtype[256];
3064:   Mat                    B;

3070:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3071:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3072:   MatPreallocated(mat);

3074:   PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
3075:   if (flg) {
3076:     newtype = mtype;
3077:   }
3079: 
3080:   PetscTypeCompare((PetscObject)mat,newtype,&sametype);
3081:   PetscStrcmp(newtype,"same",&issame);
3082:   if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) {
3083:     SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for in-place conversion currently");
3084:   }
3085:   if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) {
3086:     (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
3087:   } else {
3088:     PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL;
3089:     const char     *prefix[3] = {"seq","mpi",""};
3090:     PetscInt       i;

3092:     /* 
3093:        Order of precedence:
3094:        1) See if a specialized converter is known to the current matrix.
3095:        2) See if a specialized converter is known to the desired matrix class.
3096:        3) See if a good general converter is registered for the desired class
3097:           (as of 6/27/03 only MATMPIADJ falls into this category).
3098:        4) See if a good general converter is known for the current matrix.
3099:        5) Use a really basic converter.
3100:     */
3101:     for (i=0; i<3; i++) {
3102:       /* 1) See if a specialized converter is known to the current matrix and the desired class */
3103:       PetscStrcpy(convname,"MatConvert_");
3104:       PetscStrcat(convname,mat->type_name);
3105:       PetscStrcat(convname,"_");
3106:       PetscStrcat(convname,prefix[i]);
3107:       PetscStrcat(convname,newtype);
3108:       PetscStrcat(convname,"_C");
3109:       PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);
3110:       if (conv) goto foundconv;
3111:     }

3113:     /* 2)  See if a specialized converter is known to the desired matrix class. */
3114:     MatCreate(mat->comm,&B);
3115:     MatSetSizes(B,mat->rmap.n,mat->cmap.n,mat->rmap.N,mat->cmap.N);
3116:     MatSetType(B,newtype);
3117:     PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);

3119:     /* 3) See if a good general converter is registered for the desired class */
3120:     if (!conv) conv = B->ops->convert;
3121:     MatDestroy(B);
3122:     if (conv) goto foundconv;

3124:     /* 4) See if a good general converter is known for the current matrix */
3125:     if (mat->ops->convert) {
3126:       conv = mat->ops->convert;
3127:     }
3128:     if (conv) goto foundconv;

3130:     /* 5) Use a really basic converter. */
3131:     conv = MatConvert_Basic;

3133:     foundconv:
3134:     (*conv)(mat,newtype,reuse,M);
3135:   }
3136:   B = *M;
3138:   PetscObjectStateIncrease((PetscObject)B);
3139:   return(0);
3140: }


3145: /*@
3146:    MatDuplicate - Duplicates a matrix including the non-zero structure.

3148:    Collective on Mat

3150:    Input Parameters:
3151: +  mat - the matrix
3152: -  op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
3153:         values as well or not

3155:    Output Parameter:
3156: .  M - pointer to place new matrix

3158:    Level: intermediate

3160:    Concepts: matrices^duplicating

3162: .seealso: MatCopy(), MatConvert()
3163: @*/
3164: PetscErrorCode  MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
3165: {
3167:   Mat            B;

3173:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3174:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3175:   MatPreallocated(mat);

3177:   *M  = 0;
3179:   if (!mat->ops->duplicate) {
3180:     SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
3181:   }
3182:   (*mat->ops->duplicate)(mat,op,M);
3183:   B = *M;
3184:   if (mat->mapping) {
3185:     MatSetLocalToGlobalMapping(B,mat->mapping);
3186:   }
3187:   if (mat->bmapping) {
3188:     MatSetLocalToGlobalMappingBlock(B,mat->bmapping);
3189:   }
3190:   PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);
3191:   PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);
3192: 
3194:   PetscObjectStateIncrease((PetscObject)B);
3195:   return(0);
3196: }

3200: /*@ 
3201:    MatGetDiagonal - Gets the diagonal of a matrix.

3203:    Collective on Mat and Vec

3205:    Input Parameters:
3206: +  mat - the matrix
3207: -  v - the vector for storing the diagonal

3209:    Output Parameter:
3210: .  v - the diagonal of the matrix

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

3218:    Level: intermediate

3220:    Concepts: matrices^accessing diagonals

3222: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
3223: @*/
3224: PetscErrorCode  MatGetDiagonal(Mat mat,Vec v)
3225: {

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

3236:   (*mat->ops->getdiagonal)(mat,v);
3237:   PetscObjectStateIncrease((PetscObject)v);
3238:   return(0);
3239: }

3243: /*@ 
3244:    MatGetRowMax - Gets the maximum value (in absolute value) of each
3245:         row of the matrix

3247:    Collective on Mat and Vec

3249:    Input Parameters:
3250: .  mat - the matrix

3252:    Output Parameter:
3253: .  v - the vector for storing the maximums

3255:    Level: intermediate

3257:    Concepts: matrices^getting row maximums

3259: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
3260: @*/
3261: PetscErrorCode  MatGetRowMax(Mat mat,Vec v)
3262: {

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

3273:   (*mat->ops->getrowmax)(mat,v);
3274:   PetscObjectStateIncrease((PetscObject)v);
3275:   return(0);
3276: }

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

3283:    Collective on Mat

3285:    Input Parameter:
3286: .  mat - the matrix to transpose

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

3291:    Level: intermediate

3293:    Concepts: matrices^transposing

3295: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose()
3296: @*/
3297: PetscErrorCode  MatTranspose(Mat mat,Mat *B)
3298: {

3304:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3305:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3306:   if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3307:   MatPreallocated(mat);

3310:   (*mat->ops->transpose)(mat,B);
3312:   if (B) {PetscObjectStateIncrease((PetscObject)*B);}
3313:   return(0);
3314: }

3318: /*@C
3319:    MatIsTranspose - Test whether a matrix is another one's transpose, 
3320:         or its own, in which case it tests symmetry.

3322:    Collective on Mat

3324:    Input Parameter:
3325: +  A - the matrix to test
3326: -  B - the matrix to test against, this can equal the first parameter

3328:    Output Parameters:
3329: .  flg - the result

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

3336:    Level: intermediate

3338:    Concepts: matrices^transposing, matrix^symmetry

3340: .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian()
3341: @*/
3342: PetscErrorCode  MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg)
3343: {
3344:   PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*);

3350:   PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);
3351:   PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);
3352:   if (f && g) {
3353:     if (f==g) {
3354:       (*f)(A,B,tol,flg);
3355:     } else {
3356:       SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test");
3357:     }
3358:   }
3359:   return(0);
3360: }

3364: /*@C
3365:    MatPermute - Creates a new matrix with rows and columns permuted from the 
3366:    original.

3368:    Collective on Mat

3370:    Input Parameters:
3371: +  mat - the matrix to permute
3372: .  row - row permutation, each processor supplies only the permutation for its rows
3373: -  col - column permutation, each processor needs the entire column permutation, that is
3374:          this is the same size as the total number of columns in the matrix

3376:    Output Parameters:
3377: .  B - the permuted matrix

3379:    Level: advanced

3381:    Concepts: matrices^permuting

3383: .seealso: MatGetOrdering()
3384: @*/
3385: PetscErrorCode  MatPermute(Mat mat,IS row,IS col,Mat *B)
3386: {

3395:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3396:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3397:   if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"MatPermute not available for Mat type %s",mat->type_name);
3398:   MatPreallocated(mat);

3400:   (*mat->ops->permute)(mat,row,col,B);
3401:   PetscObjectStateIncrease((PetscObject)*B);
3402:   return(0);
3403: }

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

3411:   Collective on Mat

3413:   Input Parameters:
3414: + A    - The matrix to permute
3415: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
3416: . frac - The half-bandwidth as a fraction of the total size, or 0.0
3417: . tol  - The drop tolerance
3418: . rowp - The row permutation
3419: - colp - The column permutation

3421:   Output Parameter:
3422: . B    - The permuted, sparsified matrix

3424:   Level: advanced

3426:   Note:
3427:   The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
3428:   restrict the half-bandwidth of the resulting matrix to 5% of the
3429:   total matrix size.

3431: .keywords: matrix, permute, sparsify

3433: .seealso: MatGetOrdering(), MatPermute()
3434: @*/
3435: PetscErrorCode  MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
3436: {
3437:   IS                irowp, icolp;
3438:   PetscInt          *rows, *cols;
3439:   PetscInt          M, N, locRowStart, locRowEnd;
3440:   PetscInt          nz, newNz;
3441:   const PetscInt    *cwork;
3442:   PetscInt          *cnew;
3443:   const PetscScalar *vwork;
3444:   PetscScalar       *vnew;
3445:   PetscInt          bw, issize;
3446:   PetscInt          row, locRow, newRow, col, newCol;
3447:   PetscErrorCode    ierr;

3454:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
3455:   if (A->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
3456:   if (!A->ops->permutesparsify) {
3457:     MatGetSize(A, &M, &N);
3458:     MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
3459:     ISGetSize(rowp, &issize);
3460:     if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M);
3461:     ISGetSize(colp, &issize);
3462:     if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N);
3463:     ISInvertPermutation(rowp, 0, &irowp);
3464:     ISGetIndices(irowp, &rows);
3465:     ISInvertPermutation(colp, 0, &icolp);
3466:     ISGetIndices(icolp, &cols);
3467:     PetscMalloc(N * sizeof(PetscInt),         &cnew);
3468:     PetscMalloc(N * sizeof(PetscScalar), &vnew);

3470:     /* Setup bandwidth to include */
3471:     if (band == PETSC_DECIDE) {
3472:       if (frac <= 0.0)
3473:         bw = (PetscInt) (M * 0.05);
3474:       else
3475:         bw = (PetscInt) (M * frac);
3476:     } else {
3477:       if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
3478:       bw = band;
3479:     }

3481:     /* Put values into new matrix */
3482:     MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
3483:     for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
3484:       MatGetRow(A, row, &nz, &cwork, &vwork);
3485:       newRow   = rows[locRow]+locRowStart;
3486:       for(col = 0, newNz = 0; col < nz; col++) {
3487:         newCol = cols[cwork[col]];
3488:         if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
3489:           cnew[newNz] = newCol;
3490:           vnew[newNz] = vwork[col];
3491:           newNz++;
3492:         }
3493:       }
3494:       MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
3495:       MatRestoreRow(A, row, &nz, &cwork, &vwork);
3496:     }
3497:     PetscFree(cnew);
3498:     PetscFree(vnew);
3499:     MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
3500:     MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
3501:     ISRestoreIndices(irowp, &rows);
3502:     ISRestoreIndices(icolp, &cols);
3503:     ISDestroy(irowp);
3504:     ISDestroy(icolp);
3505:   } else {
3506:     (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
3507:   }
3508:   PetscObjectStateIncrease((PetscObject)*B);
3509:   return(0);
3510: }

3514: /*@
3515:    MatEqual - Compares two matrices.

3517:    Collective on Mat

3519:    Input Parameters:
3520: +  A - the first matrix
3521: -  B - the second matrix

3523:    Output Parameter:
3524: .  flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.

3526:    Level: intermediate

3528:    Concepts: matrices^equality between
3529: @*/
3530: PetscErrorCode  MatEqual(Mat A,Mat B,PetscTruth *flg)
3531: {

3539:   MatPreallocated(B);
3542:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3543:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3544:   if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3545:   if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
3546:   if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
3547:   if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name);
3548:   MatPreallocated(A);

3550:   (*A->ops->equal)(A,B,flg);
3551:   return(0);
3552: }

3556: /*@
3557:    MatDiagonalScale - Scales a matrix on the left and right by diagonal
3558:    matrices that are stored as vectors.  Either of the two scaling
3559:    matrices can be PETSC_NULL.

3561:    Collective on Mat

3563:    Input Parameters:
3564: +  mat - the matrix to be scaled
3565: .  l - the left scaling vector (or PETSC_NULL)
3566: -  r - the right scaling vector (or PETSC_NULL)

3568:    Notes:
3569:    MatDiagonalScale() computes A = LAR, where
3570:    L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector)

3572:    Level: intermediate

3574:    Concepts: matrices^diagonal scaling
3575:    Concepts: diagonal scaling of matrices

3577: .seealso: MatScale()
3578: @*/
3579: PetscErrorCode  MatDiagonalScale(Mat mat,Vec l,Vec r)
3580: {

3586:   if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3589:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3590:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3591:   MatPreallocated(mat);

3594:   (*mat->ops->diagonalscale)(mat,l,r);
3596:   PetscObjectStateIncrease((PetscObject)mat);
3597:   return(0);
3598: }

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

3605:     Collective on Mat

3607:     Input Parameters:
3608: +   mat - the matrix to be scaled
3609: -   a  - the scaling value

3611:     Output Parameter:
3612: .   mat - the scaled matrix

3614:     Level: intermediate

3616:     Concepts: matrices^scaling all entries

3618: .seealso: MatDiagonalScale()
3619: @*/
3620: PetscErrorCode  MatScale(Mat mat,PetscScalar a)
3621: {

3627:   if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3628:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3629:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3630:   MatPreallocated(mat);

3633:   (*mat->ops->scale)(mat,a);
3635:   PetscObjectStateIncrease((PetscObject)mat);
3636:   return(0);
3637: }

3641: /*@ 
3642:    MatNorm - Calculates various norms of a matrix.

3644:    Collective on Mat

3646:    Input Parameters:
3647: +  mat - the matrix
3648: -  type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY

3650:    Output Parameters:
3651: .  nrm - the resulting norm 

3653:    Level: intermediate

3655:    Concepts: matrices^norm
3656:    Concepts: norm^of matrix
3657: @*/
3658: PetscErrorCode  MatNorm(Mat mat,NormType type,PetscReal *nrm)
3659: {


3667:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3668:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3669:   if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3670:   MatPreallocated(mat);

3672:   (*mat->ops->norm)(mat,type,nrm);
3673:   return(0);
3674: }

3676: /* 
3677:      This variable is used to prevent counting of MatAssemblyBegin() that
3678:    are called from within a MatAssemblyEnd().
3679: */
3680: static PetscInt MatAssemblyEnd_InUse = 0;
3683: /*@
3684:    MatAssemblyBegin - Begins assembling the matrix.  This routine should
3685:    be called after completing all calls to MatSetValues().

3687:    Collective on Mat

3689:    Input Parameters:
3690: +  mat - the matrix 
3691: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3692:  
3693:    Notes: 
3694:    MatSetValues() generally caches the values.  The matrix is ready to
3695:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3696:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3697:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3698:    using the matrix.

3700:    Level: beginner

3702:    Concepts: matrices^assembling

3704: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3705: @*/
3706: PetscErrorCode  MatAssemblyBegin(Mat mat,MatAssemblyType type)
3707: {

3713:   MatPreallocated(mat);
3714:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3715:   if (mat->assembled) {
3716:     mat->was_assembled = PETSC_TRUE;
3717:     mat->assembled     = PETSC_FALSE;
3718:   }
3719:   if (!MatAssemblyEnd_InUse) {
3721:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3723:   } else {
3724:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3725:   }
3726:   return(0);
3727: }

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

3735:    Collective on Mat

3737:    Input Parameter:
3738: .  mat - the matrix 

3740:    Output Parameter:
3741: .  assembled - PETSC_TRUE or PETSC_FALSE

3743:    Level: advanced

3745:    Concepts: matrices^assembled?

3747: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3748: @*/
3749: PetscErrorCode  MatAssembled(Mat mat,PetscTruth *assembled)
3750: {
3755:   *assembled = mat->assembled;
3756:   return(0);
3757: }

3761: /*
3762:     Processes command line options to determine if/how a matrix
3763:   is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3764: */
3765: PetscErrorCode MatView_Private(Mat mat)
3766: {
3767:   PetscErrorCode    ierr;
3768:   PetscTruth        flg1,flg2,flg3,flg4,flg6,flg7,flg8;
3769:   static PetscTruth incall = PETSC_FALSE;
3770: #if defined(PETSC_USE_SOCKET_VIEWER)
3771:   PetscTruth        flg5;
3772: #endif

3775:   if (incall) return(0);
3776:   incall = PETSC_TRUE;
3777:   PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3778:     PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg1);
3779:     PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg2);
3780:     PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg3);
3781:     PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg4);
3782: #if defined(PETSC_USE_SOCKET_VIEWER)
3783:     PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg5);
3784: #endif
3785:     PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg6);
3786:     PetscOptionsName("-mat_view_draw","Draw the matrix nonzero structure","MatView",&flg7);
3787:   PetscOptionsEnd();

3789:   if (flg1) {
3790:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3791:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3792:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3793:   }
3794:   if (flg2) {
3795:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3796:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3797:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3798:   }
3799:   if (flg3) {
3800:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3801:   }
3802:   if (flg4) {
3803:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3804:     MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3805:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3806:   }
3807: #if defined(PETSC_USE_SOCKET_VIEWER)
3808:   if (flg5) {
3809:     MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3810:     PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3811:   }
3812: #endif
3813:   if (flg6) {
3814:     MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3815:     PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3816:   }
3817:   if (flg7) {
3818:     PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg8);
3819:     if (flg8) {
3820:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3821:     }
3822:     MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3823:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3824:     if (flg8) {
3825:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3826:     }
3827:   }
3828:   incall = PETSC_FALSE;
3829:   return(0);
3830: }

3834: /*@
3835:    MatAssemblyEnd - Completes assembling the matrix.  This routine should
3836:    be called after MatAssemblyBegin().

3838:    Collective on Mat

3840:    Input Parameters:
3841: +  mat - the matrix 
3842: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY

3844:    Options Database Keys:
3845: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3846: .  -mat_view_info_detailed - Prints more detailed info
3847: .  -mat_view - Prints matrix in ASCII format
3848: .  -mat_view_matlab - Prints matrix in Matlab format
3849: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3850: .  -display <name> - Sets display name (default is host)
3851: .  -draw_pause <sec> - Sets number of seconds to pause after display
3852: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3853: .  -viewer_socket_machine <machine>
3854: .  -viewer_socket_port <port>
3855: .  -mat_view_binary - save matrix to file in binary format
3856: -  -viewer_binary_filename <name>

3858:    Notes: 
3859:    MatSetValues() generally caches the values.  The matrix is ready to
3860:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3861:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3862:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3863:    using the matrix.

3865:    Level: beginner

3867: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3868: @*/
3869: PetscErrorCode  MatAssemblyEnd(Mat mat,MatAssemblyType type)
3870: {
3871:   PetscErrorCode  ierr;
3872:   static PetscInt inassm = 0;
3873:   PetscTruth      flg;


3879:   inassm++;
3880:   MatAssemblyEnd_InUse++;
3881:   if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3883:     if (mat->ops->assemblyend) {
3884:       (*mat->ops->assemblyend)(mat,type);
3885:     }
3887:   } else {
3888:     if (mat->ops->assemblyend) {
3889:       (*mat->ops->assemblyend)(mat,type);
3890:     }
3891:   }

3893:   /* Flush assembly is not a true assembly */
3894:   if (type != MAT_FLUSH_ASSEMBLY) {
3895:     mat->assembled  = PETSC_TRUE; mat->num_ass++;
3896:   }
3897:   mat->insertmode = NOT_SET_VALUES;
3898:   MatAssemblyEnd_InUse--;
3899:   PetscObjectStateIncrease((PetscObject)mat);
3900:   if (!mat->symmetric_eternal) {
3901:     mat->symmetric_set              = PETSC_FALSE;
3902:     mat->hermitian_set              = PETSC_FALSE;
3903:     mat->structurally_symmetric_set = PETSC_FALSE;
3904:   }
3905:   if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3906:     MatView_Private(mat);
3907:     PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);
3908:     if (flg) {
3909:       PetscReal tol = 0.0;
3910:       PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);
3911:       MatIsSymmetric(mat,tol,&flg);
3912:       if (flg) {
3913:         PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);
3914:       } else {
3915:         PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);
3916:       }
3917:     }
3918:   }
3919:   inassm--;
3920:   return(0);
3921: }


3926: /*@
3927:    MatCompress - Tries to store the matrix in as little space as 
3928:    possible.  May fail if memory is already fully used, since it
3929:    tries to allocate new space.

3931:    Collective on Mat

3933:    Input Parameters:
3934: .  mat - the matrix 

3936:    Level: advanced

3938: @*/
3939: PetscErrorCode  MatCompress(Mat mat)
3940: {

3946:   MatPreallocated(mat);
3947:   if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3948:   return(0);
3949: }

3953: /*@
3954:    MatSetOption - Sets a parameter option for a matrix. Some options
3955:    may be specific to certain storage formats.  Some options
3956:    determine how values will be inserted (or added). Sorted, 
3957:    row-oriented input will generally assemble the fastest. The default
3958:    is row-oriented, nonsorted input. 

3960:    Collective on Mat

3962:    Input Parameters:
3963: +  mat - the matrix 
3964: -  option - the option, one of those listed below (and possibly others),
3965:              e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

3967:    Options Describing Matrix Structure:
3968: +    MAT_SYMMETRIC - symmetric in terms of both structure and value
3969: .    MAT_HERMITIAN - transpose is the complex conjugation
3970: .    MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
3971: .    MAT_NOT_SYMMETRIC - not symmetric in value
3972: .    MAT_NOT_HERMITIAN - transpose is not the complex conjugation
3973: .    MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure
3974: .    MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag
3975:                             you set to be kept with all future use of the matrix
3976:                             including after MatAssemblyBegin/End() which could
3977:                             potentially change the symmetry structure, i.e. you 
3978:                             KNOW the matrix will ALWAYS have the property you set.
3979: -    MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 
3980:                                 flags you set will be dropped (in case potentially
3981:                                 the symmetry etc was lost).

3983:    Options For Use with MatSetValues():
3984:    Insert a logically dense subblock, which can be
3985: +    MAT_ROW_ORIENTED - row-oriented (default)
3986: .    MAT_COLUMN_ORIENTED - column-oriented
3987: .    MAT_ROWS_SORTED - sorted by row
3988: .    MAT_ROWS_UNSORTED - not sorted by row (default)
3989: .    MAT_COLUMNS_SORTED - sorted by column
3990: -    MAT_COLUMNS_UNSORTED - not sorted by column (default)

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

3996:    When (re)assembling a matrix, we can restrict the input for
3997:    efficiency/debugging purposes.  These options include
3998: +    MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
3999:         allowed if they generate a new nonzero
4000: .    MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
4001: .    MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
4002:          they generate a nonzero in a new diagonal (for block diagonal format only)
4003: .    MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
4004: .    MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
4005: .    MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
4006: -    MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly

4008:    Notes:
4009:    Some options are relevant only for particular matrix types and
4010:    are thus ignored by others.  Other options are not supported by
4011:    certain matrix types and will generate an error message if set.

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

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

4024:    MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 
4025:    that would generate a new entry in the nonzero structure instead produces 
4026:    an error. (Currently supported for AIJ and BAIJ formats only.)
4027:    This is a useful flag when using SAME_NONZERO_PATTERN in calling
4028:    KSPSetOperators() to ensure that the nonzero pattern truely does 
4029:    remain unchanged. Set after the first MatAssemblyEnd()

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

4036:    MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 
4037:    other processors should be dropped, rather than stashed.
4038:    This is useful if you know that the "owning" processor is also 
4039:    always generating the correct matrix entries, so that PETSc need
4040:    not transfer duplicate entries generated on another processor.
4041:    
4042:    MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
4043:    searches during matrix assembly. When this flag is set, the hash table
4044:    is created during the first Matrix Assembly. This hash table is
4045:    used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
4046:    to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 
4047:    should be used with MAT_USE_HASH_TABLE flag. This option is currently
4048:    supported by MATMPIBAIJ format only.

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

4053:    MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating
4054:    a zero location in the matrix

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

4059:    MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
4060:    with AIJ and ROWBS matrix types (database option "-mat_no_inode")

4062:    Level: intermediate

4064:    Concepts: matrices^setting options

4066: @*/
4067: PetscErrorCode  MatSetOption(Mat mat,MatOption op)
4068: {

4074:   MatPreallocated(mat);
4075:   switch (op) {
4076:   case MAT_SYMMETRIC:
4077:     mat->symmetric                  = PETSC_TRUE;
4078:     mat->structurally_symmetric     = PETSC_TRUE;
4079:     mat->symmetric_set              = PETSC_TRUE;
4080:     mat->structurally_symmetric_set = PETSC_TRUE;
4081:     break;
4082:   case MAT_HERMITIAN:
4083:     mat->hermitian                  = PETSC_TRUE;
4084:     mat->structurally_symmetric     = PETSC_TRUE;
4085:     mat->hermitian_set              = PETSC_TRUE;
4086:     mat->structurally_symmetric_set = PETSC_TRUE;
4087:     break;
4088:   case MAT_STRUCTURALLY_SYMMETRIC:
4089:     mat->structurally_symmetric     = PETSC_TRUE;
4090:     mat->structurally_symmetric_set = PETSC_TRUE;
4091:     break;
4092:   case MAT_NOT_SYMMETRIC:
4093:     mat->symmetric                  = PETSC_FALSE;
4094:     mat->symmetric_set              = PETSC_TRUE;
4095:     break;
4096:   case MAT_NOT_HERMITIAN:
4097:     mat->hermitian                  = PETSC_FALSE;
4098:     mat->hermitian_set              = PETSC_TRUE;
4099:     break;
4100:   case MAT_NOT_STRUCTURALLY_SYMMETRIC:
4101:     mat->structurally_symmetric     = PETSC_FALSE;
4102:     mat->structurally_symmetric_set = PETSC_TRUE;
4103:     break;
4104:   case MAT_SYMMETRY_ETERNAL:
4105:     mat->symmetric_eternal          = PETSC_TRUE;
4106:     break;
4107:   case MAT_NOT_SYMMETRY_ETERNAL:
4108:     mat->symmetric_eternal          = PETSC_FALSE;
4109:     break;
4110:   default:
4111:     break;
4112:   }
4113:   if (mat->ops->setoption) {
4114:     (*mat->ops->setoption)(mat,op);
4115:   }
4116:   return(0);
4117: }

4121: /*@
4122:    MatZeroEntries - Zeros all entries of a matrix.  For sparse matrices
4123:    this routine retains the old nonzero structure.

4125:    Collective on Mat

4127:    Input Parameters:
4128: .  mat - the matrix 

4130:    Level: intermediate

4132:    Concepts: matrices^zeroing

4134: .seealso: MatZeroRows()
4135: @*/
4136: PetscErrorCode  MatZeroEntries(Mat mat)
4137: {

4143:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4144:   if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled");
4145:   if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4146:   MatPreallocated(mat);

4149:   (*mat->ops->zeroentries)(mat);
4151:   PetscObjectStateIncrease((PetscObject)mat);
4152:   return(0);
4153: }

4157: /*@C
4158:    MatZeroRows - Zeros all entries (except possibly the main diagonal)
4159:    of a set of rows of a matrix.

4161:    Collective on Mat

4163:    Input Parameters:
4164: +  mat - the matrix
4165: .  numRows - the number of rows to remove
4166: .  rows - the global row indices
4167: -  diag - value put in all diagonals of eliminated rows

4169:    Notes:
4170:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4171:    but does not release memory.  For the dense and block diagonal
4172:    formats this does not alter the nonzero structure.

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

4178:    The user can set a value in the diagonal entry (or for the AIJ and
4179:    row formats can optionally remove the main diagonal entry from the
4180:    nonzero structure as well, by passing 0.0 as the final argument).

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

4187:    Each processor should list the rows that IT wants zeroed

4189:    Level: intermediate

4191:    Concepts: matrices^zeroing rows

4193: .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4194: @*/
4195: PetscErrorCode  MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4196: {

4203:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4204:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4205:   if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4206:   MatPreallocated(mat);

4208:   (*mat->ops->zerorows)(mat,numRows,rows,diag);
4209:   MatView_Private(mat);
4210:   PetscObjectStateIncrease((PetscObject)mat);
4211:   return(0);
4212: }

4216: /*@C
4217:    MatZeroRowsIS - Zeros all entries (except possibly the main diagonal)
4218:    of a set of rows of a matrix.

4220:    Collective on Mat

4222:    Input Parameters:
4223: +  mat - the matrix
4224: .  is - index set of rows to remove
4225: -  diag - value put in all diagonals of eliminated rows

4227:    Notes:
4228:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4229:    but does not release memory.  For the dense and block diagonal
4230:    formats this does not alter the nonzero structure.

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

4236:    The user can set a value in the diagonal entry (or for the AIJ and
4237:    row formats can optionally remove the main diagonal entry from the
4238:    nonzero structure as well, by passing 0.0 as the final argument).

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

4245:    Each processor should list the rows that IT wants zeroed

4247:    Level: intermediate

4249:    Concepts: matrices^zeroing rows

4251: .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4252: @*/
4253: PetscErrorCode  MatZeroRowsIS(Mat mat,IS is,PetscScalar diag)
4254: {
4255:   PetscInt       numRows;
4256:   PetscInt       *rows;

4263:   ISGetLocalSize(is,&numRows);
4264:   ISGetIndices(is,&rows);
4265:   MatZeroRows(mat,numRows,rows,diag);
4266:   ISRestoreIndices(is,&rows);
4267:   return(0);
4268: }

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

4276:    Collective on Mat

4278:    Input Parameters:
4279: +  mat - the matrix
4280: .  numRows - the number of rows to remove
4281: .  rows - the global row indices
4282: -  diag - value put in all diagonals of eliminated rows

4284:    Notes:
4285:    Before calling MatZeroRowsLocal(), the user must first set the
4286:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4288:    For the AIJ matrix formats this removes the old nonzero structure,
4289:    but does not release memory.  For the dense and block diagonal
4290:    formats this does not alter the nonzero structure.

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

4296:    The user can set a value in the diagonal entry (or for the AIJ and
4297:    row formats can optionally remove the main diagonal entry from the
4298:    nonzero structure as well, by passing 0.0 as the final argument).

4300:    Level: intermediate

4302:    Concepts: matrices^zeroing

4304: .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4305: @*/
4306: PetscErrorCode  MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4307: {

4314:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4315:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4316:   MatPreallocated(mat);

4318:   if (mat->ops->zerorowslocal) {
4319:     (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);
4320:   } else {
4321:     IS is, newis;
4322:     PetscInt *newRows;

4324:     if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
4325:     ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);
4326:     ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
4327:     ISGetIndices(newis,&newRows);
4328:     (*mat->ops->zerorows)(mat,numRows,newRows,diag);
4329:     ISRestoreIndices(newis,&newRows);
4330:     ISDestroy(newis);
4331:     ISDestroy(is);
4332:   }
4333:   PetscObjectStateIncrease((PetscObject)mat);
4334:   return(0);
4335: }

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

4343:    Collective on Mat

4345:    Input Parameters:
4346: +  mat - the matrix
4347: .  is - index set of rows to remove
4348: -  diag - value put in all diagonals of eliminated rows

4350:    Notes:
4351:    Before calling MatZeroRowsLocal(), the user must first set the
4352:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4354:    For the AIJ matrix formats this removes the old nonzero structure,
4355:    but does not release memory.  For the dense and block diagonal
4356:    formats this does not alter the nonzero structure.

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

4362:    The user can set a value in the diagonal entry (or for the AIJ and
4363:    row formats can optionally remove the main diagonal entry from the
4364:    nonzero structure as well, by passing 0.0 as the final argument).

4366:    Level: intermediate

4368:    Concepts: matrices^zeroing

4370: .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4371: @*/
4372: PetscErrorCode  MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag)
4373: {
4375:   PetscInt       numRows;
4376:   PetscInt       *rows;

4382:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4383:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4384:   MatPreallocated(mat);

4386:   ISGetLocalSize(is,&numRows);
4387:   ISGetIndices(is,&rows);
4388:   MatZeroRowsLocal(mat,numRows,rows,diag);
4389:   ISRestoreIndices(is,&rows);
4390:   return(0);
4391: }

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

4398:    Not Collective

4400:    Input Parameter:
4401: .  mat - the matrix

4403:    Output Parameters:
4404: +  m - the number of global rows
4405: -  n - the number of global columns

4407:    Note: both output parameters can be PETSC_NULL on input.

4409:    Level: beginner

4411:    Concepts: matrices^size

4413: .seealso: MatGetLocalSize()
4414: @*/
4415: PetscErrorCode  MatGetSize(Mat mat,PetscInt *m,PetscInt* n)
4416: {
4419:   if (m) *m = mat->rmap.N;
4420:   if (n) *n = mat->cmap.N;
4421:   return(0);
4422: }

4426: /*@
4427:    MatGetLocalSize - Returns the number of rows and columns in a matrix
4428:    stored locally.  This information may be implementation dependent, so
4429:    use with care.

4431:    Not Collective

4433:    Input Parameters:
4434: .  mat - the matrix

4436:    Output Parameters:
4437: +  m - the number of local rows
4438: -  n - the number of local columns

4440:    Note: both output parameters can be PETSC_NULL on input.

4442:    Level: beginner

4444:    Concepts: matrices^local size

4446: .seealso: MatGetSize()
4447: @*/
4448: PetscErrorCode  MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n)
4449: {
4454:   if (m) *m = mat->rmap.n;
4455:   if (n) *n = mat->cmap.n;
4456:   return(0);
4457: }

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

4467:    Not Collective

4469:    Input Parameters:
4470: .  mat - the matrix

4472:    Output Parameters:
4473: +  m - the global index of the first local row
4474: -  n - one more than the global index of the last local row

4476:    Note: both output parameters can be PETSC_NULL on input.

4478:    Level: beginner

4480:    Concepts: matrices^row ownership
4481: @*/
4482: PetscErrorCode  MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n)
4483: {

4491:   MatPreallocated(mat);
4492:   if (m) *m = mat->rmap.rstart;
4493:   if (n) *n = mat->rmap.rend;
4494:   return(0);
4495: }

4499: /*@  
4500:    MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
4501:    Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 
4502:    to complete the factorization.

4504:    Collective on Mat

4506:    Input Parameters:
4507: +  mat - the matrix
4508: .  row - row permutation
4509: .  column - column permutation
4510: -  info - structure containing 
4511: $      levels - number of levels of fill.
4512: $      expected fill - as ratio of original fill.
4513: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
4514:                 missing diagonal entries)

4516:    Output Parameters:
4517: .  fact - new matrix that has been symbolically factored

4519:    Notes:
4520:    See the users manual for additional information about
4521:    choosing the fill factor for better efficiency.

4523:    Most users should employ the simplified KSP interface for linear solvers
4524:    instead of working directly with matrix algebra routines such as this.
4525:    See, e.g., KSPCreate().

4527:    Level: developer

4529:   Concepts: matrices^symbolic LU factorization
4530:   Concepts: matrices^factorization
4531:   Concepts: LU^symbolic factorization

4533: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4534:           MatGetOrdering(), MatFactorInfo

4536: @*/
4537: PetscErrorCode  MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
4538: {

4548:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels);
4549:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4550:   if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ILU",mat->type_name);
4551:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4552:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4553:   MatPreallocated(mat);

4556:   (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
4558:   return(0);
4559: }

4563: /*@  
4564:    MatICCFactorSymbolic - Performs symbolic incomplete
4565:    Cholesky factorization for a symmetric matrix.  Use 
4566:    MatCholeskyFactorNumeric() to complete the factorization.

4568:    Collective on Mat

4570:    Input Parameters:
4571: +  mat - the matrix
4572: .  perm - row and column permutation
4573: -  info - structure containing 
4574: $      levels - number of levels of fill.
4575: $      expected fill - as ratio of original fill.

4577:    Output Parameter:
4578: .  fact - the factored matrix

4580:    Notes:
4581:    Most users should employ the KSP interface for linear solvers
4582:    instead of working directly with matrix algebra routines such as this.
4583:    See, e.g., KSPCreate().

4585:    Level: developer

4587:   Concepts: matrices^symbolic incomplete Cholesky factorization
4588:   Concepts: matrices^factorization
4589:   Concepts: Cholsky^symbolic factorization

4591: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
4592: @*/
4593: PetscErrorCode  MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
4594: {

4603:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4604:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels);
4605:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4606:   if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ICC",mat->type_name);
4607:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4608:   MatPreallocated(mat);

4611:   (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
4613:   return(0);
4614: }

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

4624:    Not Collective

4626:    Input Parameter:
4627: .  mat - the matrix

4629:    Output Parameter:
4630: .  v - the location of the values


4633:    Fortran Note:
4634:    This routine is used differently from Fortran, e.g.,
4635: .vb
4636:         Mat         mat
4637:         PetscScalar mat_array(1)
4638:         PetscOffset i_mat
4639:         PetscErrorCode ierr
4640:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4646:         [... other code ...]
4647:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4648: .ve

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

4653:    Level: advanced

4655:    Concepts: matrices^access array

4657: .seealso: MatRestoreArray(), MatGetArrayF90()
4658: @*/
4659: PetscErrorCode  MatGetArray(Mat mat,PetscScalar *v[])
4660: {

4667:   if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4668:   MatPreallocated(mat);
4669:   (*mat->ops->getarray)(mat,v);
4670:   CHKMEMQ;
4671:   return(0);
4672: }

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

4679:    Not Collective

4681:    Input Parameter:
4682: +  mat - the matrix
4683: -  v - the location of the values

4685:    Fortran Note:
4686:    This routine is used differently from Fortran, e.g.,
4687: .vb
4688:         Mat         mat
4689:         PetscScalar mat_array(1)
4690:         PetscOffset i_mat
4691:         PetscErrorCode ierr
4692:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4698:         [... other code ...]
4699:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4700: .ve

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

4705:    Level: advanced

4707: .seealso: MatGetArray(), MatRestoreArrayF90()
4708: @*/
4709: PetscErrorCode  MatRestoreArray(Mat mat,PetscScalar *v[])
4710: {

4717: #if defined(PETSC_USE_DEBUG)
4718:   CHKMEMQ;
4719: #endif
4720:   if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4721:   (*mat->ops->restorearray)(mat,v);
4722:   PetscObjectStateIncrease((PetscObject)mat);
4723:   return(0);
4724: }

4728: /*@C
4729:    MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
4730:    points to an array of valid matrices, they may be reused to store the new
4731:    submatrices.

4733:    Collective on Mat

4735:    Input Parameters:
4736: +  mat - the matrix
4737: .  n   - the number of submatrixes to be extracted (on this processor, may be zero)
4738: .  irow, icol - index sets of rows and columns to extract
4739: -  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

4741:    Output Parameter:
4742: .  submat - the array of submatrices

4744:    Notes:
4745:    MatGetSubMatrices() can extract only sequential submatrices
4746:    (from both sequential and parallel matrices). Use MatGetSubMatrix()
4747:    to extract a parallel submatrix.

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

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

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

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

4762:    For BAIJ matrices the index sets must respect the block structure, that is if they
4763:    request one row/column in a block, they must request all rows/columns that are in
4764:    that block. For example, if the block size is 2 you cannot request just row 0 and 
4765:    column 0.

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

4771:    Level: advanced

4773:    Concepts: matrices^accessing submatrices
4774:    Concepts: submatrices

4776: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
4777: @*/
4778: PetscErrorCode  MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
4779: {
4781:   PetscInt        i;
4782:   PetscTruth      eq;

4787:   if (n) {
4792:   }
4794:   if (n && scall == MAT_REUSE_MATRIX) {
4797:   }
4798:   if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4799:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4800:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4801:   MatPreallocated(mat);

4804:   (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
4806:   for (i=0; i<n; i++) {
4807:     if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) {
4808:       ISEqual(irow[i],icol[i],&eq);
4809:       if (eq) {
4810:         if (mat->symmetric){
4811:           MatSetOption((*submat)[i],MAT_SYMMETRIC);
4812:         } else if (mat->hermitian) {
4813:           MatSetOption((*submat)[i],MAT_HERMITIAN);
4814:         } else if (mat->structurally_symmetric) {
4815:           MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);
4816:         }
4817:       }
4818:     }
4819:   }
4820:   return(0);
4821: }

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

4828:    Collective on Mat

4830:    Input Parameters:
4831: +  n - the number of local matrices
4832: -  mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
4833:                        sequence of MatGetSubMatrices())

4835:    Level: advanced

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

4839: .seealso: MatGetSubMatrices()
4840: @*/
4841: PetscErrorCode  MatDestroyMatrices(PetscInt n,Mat *mat[])
4842: {
4844:   PetscInt       i;

4847:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n);
4849:   for (i=0; i<n; i++) {
4850:     MatDestroy((*mat)[i]);
4851:   }
4852:   /* memory is allocated even if n = 0 */
4853:   PetscFree(*mat);
4854:   return(0);
4855: }

4859: /*@
4860:    MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4861:    replaces the index sets by larger ones that represent submatrices with
4862:    additional overlap.

4864:    Collective on Mat

4866:    Input Parameters:
4867: +  mat - the matrix
4868: .  n   - the number of index sets
4869: .  is  - the array of index sets (these index sets will changed during the call)
4870: -  ov  - the additional overlap requested

4872:    Level: developer

4874:    Concepts: overlap
4875:    Concepts: ASM^computing overlap

4877: .seealso: MatGetSubMatrices()
4878: @*/
4879: PetscErrorCode  MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov)
4880: {

4886:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n);
4887:   if (n) {
4890:   }
4891:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4892:   if (mat->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4893:   MatPreallocated(mat);

4895:   if (!ov) return(0);
4896:   if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4898:   (*mat->ops->increaseoverlap)(mat,n,is,ov);
4900:   return(0);
4901: }

4905: /*@
4906:    MatGetBlockSize - Returns the matrix block size; useful especially for the
4907:    block row and block diagonal formats.
4908:    
4909:    Not Collective

4911:    Input Parameter:
4912: .  mat - the matrix

4914:    Output Parameter:
4915: .  bs - block size

4917:    Notes:
4918:    Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4919:    Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ

4921:    Level: intermediate

4923:    Concepts: matrices^block size

4925: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4926: @*/
4927: PetscErrorCode  MatGetBlockSize(Mat mat,PetscInt *bs)
4928: {

4935:   MatPreallocated(mat);
4936:   *bs = mat->rmap.bs;
4937:   return(0);
4938: }

4942: /*@
4943:    MatSetBlockSize - Sets the matrix block size; for many matrix types you 
4944:      cannot use this and MUST set the blocksize when you preallocate the matrix
4945:    
4946:    Not Collective

4948:    Input Parameters:
4949: +  mat - the matrix
4950: -  bs - block size

4952:    Notes:
4953:      Only works for shell and AIJ matrices

4955:    Level: intermediate

4957:    Concepts: matrices^block size

4959: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize()
4960: @*/
4961: PetscErrorCode  MatSetBlockSize(Mat mat,PetscInt bs)
4962: {

4968:   MatPreallocated(mat);
4969:   if (mat->ops->setblocksize) {
4970:     mat->rmap.bs = bs;
4971:     (*mat->ops->setblocksize)(mat,bs);
4972:   } else {
4973:     SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name);
4974:   }
4975:   return(0);
4976: }

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

4983:    Collective on Mat

4985:     Input Parameters:
4986: +   mat - the matrix
4987: .   shift -  0 or 1 indicating we want the indices starting at 0 or 1
4988: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4989:                 symmetrized

4991:     Output Parameters:
4992: +   n - number of rows in the (possibly compressed) matrix
4993: .   ia - the row pointers
4994: .   ja - the column indices
4995: -   done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers
4996:            are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set

4998:     Level: developer

5000:     Notes: You CANNOT change any of the ia[] or ja[] values.

5002:            Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values

5004: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5005: @*/
5006: PetscErrorCode  MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5007: {

5017:   MatPreallocated(mat);
5018:   if (!mat->ops->getrowij) *done = PETSC_FALSE;
5019:   else {
5020:     *done = PETSC_TRUE;
5021:     (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
5022:   }
5023:   return(0);
5024: }

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

5031:     Collective on Mat

5033:     Input Parameters:
5034: +   mat - the matrix
5035: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5036: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5037:                 symmetrized

5039:     Output Parameters:
5040: +   n - number of columns in the (possibly compressed) matrix
5041: .   ia - the column pointers
5042: .   ja - the row indices
5043: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

5045:     Level: developer

5047: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5048: @*/
5049: PetscErrorCode  MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5050: {

5060:   MatPreallocated(mat);
5061:   if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
5062:   else {
5063:     *done = PETSC_TRUE;
5064:     (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
5065:   }
5066:   return(0);
5067: }

5071: /*@C
5072:     MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
5073:     MatGetRowIJ().

5075:     Collective on Mat

5077:     Input Parameters:
5078: +   mat - the matrix
5079: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5080: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5081:                 symmetrized

5083:     Output Parameters:
5084: +   n - size of (possibly compressed) matrix
5085: .   ia - the row pointers
5086: .   ja - the column indices
5087: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

5089:     Level: developer

5091: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5092: @*/
5093: PetscErrorCode  MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5094: {

5103:   MatPreallocated(mat);

5105:   if (!mat->ops->restorerowij) *done = PETSC_FALSE;
5106:   else {
5107:     *done = PETSC_TRUE;
5108:     (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
5109:   }
5110:   return(0);
5111: }

5115: /*@C
5116:     MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
5117:     MatGetColumnIJ().

5119:     Collective on Mat

5121:     Input Parameters:
5122: +   mat - the matrix
5123: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5124: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5125:                 symmetrized

5127:     Output Parameters:
5128: +   n - size of (possibly compressed) matrix
5129: .   ia - the column pointers
5130: .   ja - the row indices
5131: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

5133:     Level: developer

5135: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5136: @*/
5137: PetscErrorCode  MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5138: {

5147:   MatPreallocated(mat);

5149:   if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
5150:   else {
5151:     *done = PETSC_TRUE;
5152:     (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
5153:   }
5154:   return(0);
5155: }

5159: /*@C
5160:     MatColoringPatch -Used inside matrix coloring routines that 
5161:     use MatGetRowIJ() and/or MatGetColumnIJ().

5163:     Collective on Mat

5165:     Input Parameters:
5166: +   mat - the matrix
5167: .   ncolors - max color value
5168: .   n   - number of entries in colorarray
5169: -   colorarray - array indicating color for each column

5171:     Output Parameters:
5172: .   iscoloring - coloring generated using colorarray information

5174:     Level: developer

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

5178: @*/
5179: PetscErrorCode  MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring)
5180: {

5188:   MatPreallocated(mat);

5190:   if (!mat->ops->coloringpatch){
5191:     ISColoringCreate(mat->comm,ncolors,n,colorarray,iscoloring);
5192:   } else {
5193:     (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);
5194:   }
5195:   return(0);
5196: }


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

5204:    Collective on Mat

5206:    Input Parameter:
5207: .  mat - the factored matrix to be reset

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

5216:    Note that one can specify in-place ILU(0) factorization by calling 
5217: .vb
5218:      PCType(pc,PCILU);
5219:      PCFactorSeUseInPlace(pc);
5220: .ve
5221:    or by using the options -pc_type ilu -pc_factor_in_place

5223:    In-place factorization ILU(0) can also be used as a local
5224:    solver for the blocks within the block Jacobi or additive Schwarz
5225:    methods (runtime option: -sub_pc_factor_in_place).  See the discussion 
5226:    of these preconditioners in the users manual for details on setting
5227:    local solver options.

5229:    Most users should employ the simplified KSP interface for linear solvers
5230:    instead of working directly with matrix algebra routines such as this.
5231:    See, e.g., KSPCreate().

5233:    Level: developer

5235: .seealso: PCFactorSetUseInPlace()

5237:    Concepts: matrices^unfactored

5239: @*/
5240: PetscErrorCode  MatSetUnfactored(Mat mat)
5241: {

5247:   MatPreallocated(mat);
5248:   mat->factor = 0;
5249:   if (!mat->ops->setunfactored) return(0);
5250:   (*mat->ops->setunfactored)(mat);
5251:   return(0);
5252: }

5254: /*MC
5255:     MatGetArrayF90 - Accesses a matrix array from Fortran90.

5257:     Synopsis:
5258:     MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5260:     Not collective

5262:     Input Parameter:
5263: .   x - matrix

5265:     Output Parameters:
5266: +   xx_v - the Fortran90 pointer to the array
5267: -   ierr - error code

5269:     Example of Usage: 
5270: .vb
5271:       PetscScalar, pointer xx_v(:)
5272:       ....
5273:       call MatGetArrayF90(x,xx_v,ierr)
5274:       a = xx_v(3)
5275:       call MatRestoreArrayF90(x,xx_v,ierr)
5276: .ve

5278:     Notes:
5279:     Not yet supported for all F90 compilers

5281:     Level: advanced

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

5285:     Concepts: matrices^accessing array

5287: M*/

5289: /*MC
5290:     MatRestoreArrayF90 - Restores a matrix array that has been
5291:     accessed with MatGetArrayF90().

5293:     Synopsis:
5294:     MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5296:     Not collective

5298:     Input Parameters:
5299: +   x - matrix
5300: -   xx_v - the Fortran90 pointer to the array

5302:     Output Parameter:
5303: .   ierr - error code

5305:     Example of Usage: 
5306: .vb
5307:        PetscScalar, pointer xx_v(:)
5308:        ....
5309:        call MatGetArrayF90(x,xx_v,ierr)
5310:        a = xx_v(3)
5311:        call MatRestoreArrayF90(x,xx_v,ierr)
5312: .ve
5313:    
5314:     Notes:
5315:     Not yet supported for all F90 compilers

5317:     Level: advanced

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

5321: M*/


5326: /*@
5327:     MatGetSubMatrix - Gets a single submatrix on the same number of processors
5328:                       as the original matrix.

5330:     Collective on Mat

5332:     Input Parameters:
5333: +   mat - the original matrix
5334: .   isrow - rows this processor should obtain
5335: .   iscol - columns for all processors you wish to keep
5336: .   csize - number of columns "local" to this processor (does nothing for sequential 
5337:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
5338:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5339: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

5341:     Output Parameter:
5342: .   newmat - the new submatrix, of the same type as the old

5344:     Level: advanced

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

5349:       The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5350:    the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5351:    to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX  
5352:    will reuse the matrix generated the first time.

5354:     Concepts: matrices^submatrices

5356: .seealso: MatGetSubMatrices(), ISAllGather()
5357: @*/
5358: PetscErrorCode  MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat)
5359: {
5361:   PetscMPIInt    size;
5362:   Mat            *local;

5371:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5372:   MatPreallocated(mat);
5373:   MPI_Comm_size(mat->comm,&size);

5375:   /* if original matrix is on just one processor then use submatrix generated */
5376:   if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
5377:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
5378:     return(0);
5379:   } else if (!mat->ops->getsubmatrix && size == 1) {
5380:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
5381:     *newmat = *local;
5382:     PetscFree(local);
5383:     return(0);
5384:   }

5386:   if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5387:   (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
5388:   PetscObjectStateIncrease((PetscObject)*newmat);
5389:   return(0);
5390: }

5394: /*@
5395:     MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors
5396:                          as the original matrix.

5398:     Collective on Mat

5400:     Input Parameters:
5401: +   mat - the original matrix
5402: .   nrows - the number of rows this processor should obtain
5403: .   rows - rows this processor should obtain
5404: .   ncols - the number of columns for all processors you wish to keep
5405: .   cols - columns for all processors you wish to keep
5406: .   csize - number of columns "local" to this processor (does nothing for sequential 
5407:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
5408:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5409: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

5411:     Output Parameter:
5412: .   newmat - the new submatrix, of the same type as the old

5414:     Level: advanced

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

5419:       The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5420:    the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5421:    to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX  
5422:    will reuse the matrix generated the first time.

5424:     Concepts: matrices^submatrices

5426: .seealso: MatGetSubMatrices(), ISAllGather()
5427: @*/
5428: PetscErrorCode  MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat)
5429: {
5430:   IS             isrow, iscol;

5440:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5441:   MatPreallocated(mat);
5442:   ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);
5443:   ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);
5444:   MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);
5445:   ISDestroy(isrow);
5446:   ISDestroy(iscol);
5447:   return(0);
5448: }

5452: /*@
5453:    MatStashSetInitialSize - sets the sizes of the matrix stash, that is
5454:    used during the assembly process to store values that belong to 
5455:    other processors.

5457:    Not Collective

5459:    Input Parameters:
5460: +  mat   - the matrix
5461: .  size  - the initial size of the stash.
5462: -  bsize - the initial size of the block-stash(if used).

5464:    Options Database Keys:
5465: +   -matstash_initial_size <size> or <size0,size1,...sizep-1>
5466: -   -matstash_block_initial_size <bsize>  or <bsize0,bsize1,...bsizep-1>

5468:    Level: intermediate

5470:    Notes: 
5471:      The block-stash is used for values set with MatSetValuesBlocked() while
5472:      the stash is used for values set with MatSetValues()

5474:      Run with the option -info and look for output of the form
5475:      MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
5476:      to determine the appropriate value, MM, to use for size and 
5477:      MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
5478:      to determine the value, BMM to use for bsize

5480:    Concepts: stash^setting matrix size
5481:    Concepts: matrices^stash

5483: @*/
5484: PetscErrorCode  MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize)
5485: {

5491:   MatStashSetInitialSize_Private(&mat->stash,size);
5492:   MatStashSetInitialSize_Private(&mat->bstash,bsize);
5493:   return(0);
5494: }

5498: /*@
5499:    MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 
5500:      the matrix

5502:    Collective on Mat

5504:    Input Parameters:
5505: +  mat   - the matrix
5506: .  x,y - the vectors
5507: -  w - where the result is stored

5509:    Level: intermediate

5511:    Notes: 
5512:     w may be the same vector as y. 

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

5517:     Concepts: interpolation

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

5521: @*/
5522: PetscErrorCode  MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
5523: {
5525:   PetscInt       M,N;

5533:   MatPreallocated(A);
5534:   MatGetSize(A,&M,&N);
5535:   if (N > M) {
5536:     MatMultTransposeAdd(A,x,y,w);
5537:   } else {
5538:     MatMultAdd(A,x,y,w);
5539:   }
5540:   return(0);
5541: }

5545: /*@
5546:    MatInterpolate - y = A*x or A'*x depending on the shape of 
5547:      the matrix

5549:    Collective on Mat

5551:    Input Parameters:
5552: +  mat   - the matrix
5553: -  x,y - the vectors

5555:    Level: intermediate

5557:    Notes: 
5558:     This allows one to use either the restriction or interpolation (its transpose)
5559:     matrix to do the interpolation

5561:    Concepts: matrices^interpolation

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

5565: @*/
5566: PetscErrorCode  MatInterpolate(Mat A,Vec x,Vec y)
5567: {
5569:   PetscInt       M,N;

5576:   MatPreallocated(A);
5577:   MatGetSize(A,&M,&N);
5578:   if (N > M) {
5579:     MatMultTranspose(A,x,y);
5580:   } else {
5581:     MatMult(A,x,y);
5582:   }
5583:   return(0);
5584: }

5588: /*@
5589:    MatRestrict - y = A*x or A'*x

5591:    Collective on Mat

5593:    Input Parameters:
5594: +  mat   - the matrix
5595: -  x,y - the vectors

5597:    Level: intermediate

5599:    Notes: 
5600:     This allows one to use either the restriction or interpolation (its transpose)
5601:     matrix to do the restriction

5603:    Concepts: matrices^restriction

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

5607: @*/
5608: PetscErrorCode  MatRestrict(Mat A,Vec x,Vec y)
5609: {
5611:   PetscInt       M,N;

5618:   MatPreallocated(A);

5620:   MatGetSize(A,&M,&N);
5621:   if (N > M) {
5622:     MatMult(A,x,y);
5623:   } else {
5624:     MatMultTranspose(A,x,y);
5625:   }
5626:   return(0);
5627: }

5631: /*@C
5632:    MatNullSpaceAttach - attaches a null space to a matrix.
5633:         This null space will be removed from the resulting vector whenever
5634:         MatMult() is called

5636:    Collective on Mat

5638:    Input Parameters:
5639: +  mat - the matrix
5640: -  nullsp - the null space object

5642:    Level: developer

5644:    Notes:
5645:       Overwrites any previous null space that may have been attached

5647:    Concepts: null space^attaching to matrix

5649: .seealso: MatCreate(), MatNullSpaceCreate()
5650: @*/
5651: PetscErrorCode  MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
5652: {

5659:   MatPreallocated(mat);

5661:   if (mat->nullsp) {
5662:     MatNullSpaceDestroy(mat->nullsp);
5663:   }
5664:   mat->nullsp = nullsp;
5665:   PetscObjectReference((PetscObject)nullsp);
5666:   return(0);
5667: }

5671: /*@  
5672:    MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.

5674:    Collective on Mat

5676:    Input Parameters:
5677: +  mat - the matrix
5678: .  row - row/column permutation
5679: .  fill - expected fill factor >= 1.0
5680: -  level - level of fill, for ICC(k)

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

5686:    Most users should employ the simplified KSP interface for linear solvers
5687:    instead of working directly with matrix algebra routines such as this.
5688:    See, e.g., KSPCreate().

5690:    Level: developer

5692:    Concepts: matrices^incomplete Cholesky factorization
5693:    Concepts: Cholesky factorization

5695: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
5696: @*/
5697: PetscErrorCode  MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
5698: {

5706:   if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
5707:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
5708:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5709:   if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5710:   MatPreallocated(mat);
5711:   (*mat->ops->iccfactor)(mat,row,info);
5712:   PetscObjectStateIncrease((PetscObject)mat);
5713:   return(0);
5714: }

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

5721:    Not Collective

5723:    Input Parameters:
5724: +  mat - the matrix
5725: -  v - the values compute with ADIC

5727:    Level: developer

5729:    Notes:
5730:      Must call MatSetColoring() before using this routine. Also this matrix must already
5731:      have its nonzero pattern determined.

5733: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5734:           MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
5735: @*/
5736: PetscErrorCode  MatSetValuesAdic(Mat mat,void *v)
5737: {


5745:   if (!mat->assembled) {
5746:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5747:   }
5749:   if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5750:   (*mat->ops->setvaluesadic)(mat,v);
5752:   MatView_Private(mat);
5753:   PetscObjectStateIncrease((PetscObject)mat);
5754:   return(0);
5755: }


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

5763:    Not Collective

5765:    Input Parameters:
5766: +  mat - the matrix
5767: -  coloring - the coloring

5769:    Level: developer

5771: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5772:           MatSetValues(), MatSetValuesAdic()
5773: @*/
5774: PetscErrorCode  MatSetColoring(Mat mat,ISColoring coloring)
5775: {


5783:   if (!mat->assembled) {
5784:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5785:   }
5786:   if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5787:   (*mat->ops->setcoloring)(mat,coloring);
5788:   return(0);
5789: }

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

5796:    Not Collective

5798:    Input Parameters:
5799: +  mat - the matrix
5800: .  nl - leading dimension of v
5801: -  v - the values compute with ADIFOR

5803:    Level: developer

5805:    Notes:
5806:      Must call MatSetColoring() before using this routine. Also this matrix must already
5807:      have its nonzero pattern determined.

5809: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5810:           MatSetValues(), MatSetColoring()
5811: @*/
5812: PetscErrorCode  MatSetValuesAdifor(Mat mat,PetscInt nl,void *v)
5813: {


5821:   if (!mat->assembled) {
5822:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5823:   }
5825:   if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5826:   (*mat->ops->setvaluesadifor)(mat,nl,v);
5828:   PetscObjectStateIncrease((PetscObject)mat);
5829:   return(0);
5830: }

5834: /*@ 
5835:    MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 
5836:          ghosted ones.

5838:    Not Collective

5840:    Input Parameters:
5841: +  mat - the matrix
5842: -  diag = the diagonal values, including ghost ones

5844:    Level: developer

5846:    Notes: Works only for MPIAIJ and MPIBAIJ matrices
5847:       
5848: .seealso: MatDiagonalScale()
5849: @*/
5850: PetscErrorCode  MatDiagonalScaleLocal(Mat mat,Vec diag)
5851: {
5853:   PetscMPIInt    size;


5860:   if (!mat->assembled) {
5861:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5862:   }
5864:   MPI_Comm_size(mat->comm,&size);
5865:   if (size == 1) {
5866:     PetscInt n,m;
5867:     VecGetSize(diag,&n);
5868:     MatGetSize(mat,0,&m);
5869:     if (m == n) {
5870:       MatDiagonalScale(mat,0,diag);
5871:     } else {
5872:       SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions");
5873:     }
5874:   } else {
5875:     PetscErrorCode (*f)(Mat,Vec);
5876:     PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
5877:     if (f) {
5878:       (*f)(mat,diag);
5879:     } else {
5880:       SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
5881:     }
5882:   }
5884:   PetscObjectStateIncrease((PetscObject)mat);
5885:   return(0);
5886: }

5890: /*@ 
5891:    MatGetInertia - Gets the inertia from a factored matrix

5893:    Collective on Mat

5895:    Input Parameter:
5896: .  mat - the matrix

5898:    Output Parameters:
5899: +   nneg - number of negative eigenvalues
5900: .   nzero - number of zero eigenvalues
5901: -   npos - number of positive eigenvalues

5903:    Level: advanced

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


5908: @*/
5909: PetscErrorCode  MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos)
5910: {

5916:   if (!mat->factor)    SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5917:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5918:   if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5919:   (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5920:   return(0);
5921: }

5923: /* ----------------------------------------------------------------*/
5926: /*@
5927:    MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors

5929:    Collective on Mat and Vecs

5931:    Input Parameters:
5932: +  mat - the factored matrix
5933: -  b - the right-hand-side vectors

5935:    Output Parameter:
5936: .  x - the result vectors

5938:    Notes:
5939:    The vectors b and x cannot be the same.  I.e., one cannot
5940:    call MatSolves(A,x,x).

5942:    Notes:
5943:    Most users should employ the simplified KSP interface for linear solvers
5944:    instead of working directly with matrix algebra routines such as this.
5945:    See, e.g., KSPCreate().

5947:    Level: developer

5949:    Concepts: matrices^triangular solves

5951: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
5952: @*/
5953: PetscErrorCode  MatSolves(Mat mat,Vecs b,Vecs x)
5954: {

5960:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
5961:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5962:   if (!mat->rmap.N && !mat->cmap.N) return(0);

5964:   if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5965:   MatPreallocated(mat);
5967:   (*mat->ops->solves)(mat,b,x);
5969:   return(0);
5970: }

5974: /*@
5975:    MatIsSymmetric - Test whether a matrix is symmetric

5977:    Collective on Mat

5979:    Input Parameter:
5980: +  A - the matrix to test
5981: -  tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose)

5983:    Output Parameters:
5984: .  flg - the result

5986:    Level: intermediate

5988:    Concepts: matrix^symmetry

5990: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown()
5991: @*/
5992: PetscErrorCode  MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg)
5993: {

5999:   if (!A->symmetric_set) {
6000:     if (!A->ops->issymmetric) {
6001:       MatType mattype;
6002:       MatGetType(A,&mattype);
6003:       SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype);
6004:     }
6005:     (*A->ops->issymmetric)(A,tol,&A->symmetric);
6006:     A->symmetric_set = PETSC_TRUE;
6007:     if (A->symmetric) {
6008:       A->structurally_symmetric_set = PETSC_TRUE;
6009:       A->structurally_symmetric     = PETSC_TRUE;
6010:     }
6011:   }
6012:   *flg = A->symmetric;
6013:   return(0);
6014: }

6018: /*@
6019:    MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric.

6021:    Collective on Mat

6023:    Input Parameter:
6024: .  A - the matrix to check

6026:    Output Parameters:
6027: +  set - if the symmetric flag is set (this tells you if the next flag is valid)
6028: -  flg - the result

6030:    Level: advanced

6032:    Concepts: matrix^symmetry

6034:    Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric()
6035:          if you want it explicitly checked

6037: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6038: @*/
6039: PetscErrorCode  MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6040: {
6045:   if (A->symmetric_set) {
6046:     *set = PETSC_TRUE;
6047:     *flg = A->symmetric;
6048:   } else {
6049:     *set = PETSC_FALSE;
6050:   }
6051:   return(0);
6052: }

6056: /*@
6057:    MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian.

6059:    Collective on Mat

6061:    Input Parameter:
6062: .  A - the matrix to check

6064:    Output Parameters:
6065: +  set - if the hermitian flag is set (this tells you if the next flag is valid)
6066: -  flg - the result

6068:    Level: advanced

6070:    Concepts: matrix^symmetry

6072:    Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian()
6073:          if you want it explicitly checked

6075: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6076: @*/
6077: PetscErrorCode  MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6078: {
6083:   if (A->hermitian_set) {
6084:     *set = PETSC_TRUE;
6085:     *flg = A->hermitian;
6086:   } else {
6087:     *set = PETSC_FALSE;
6088:   }
6089:   return(0);
6090: }

6094: /*@
6095:    MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric

6097:    Collective on Mat

6099:    Input Parameter:
6100: .  A - the matrix to test

6102:    Output Parameters:
6103: .  flg - the result

6105:    Level: intermediate

6107:    Concepts: matrix^symmetry

6109: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption()
6110: @*/
6111: PetscErrorCode  MatIsStructurallySymmetric(Mat A,PetscTruth *flg)
6112: {

6118:   if (!A->structurally_symmetric_set) {
6119:     if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric");
6120:     (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);
6121:     A->structurally_symmetric_set = PETSC_TRUE;
6122:   }
6123:   *flg = A->structurally_symmetric;
6124:   return(0);
6125: }

6129: /*@
6130:    MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose.

6132:    Collective on Mat

6134:    Input Parameter:
6135: .  A - the matrix to test

6137:    Output Parameters:
6138: .  flg - the result

6140:    Level: intermediate

6142:    Concepts: matrix^symmetry

6144: .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption()
6145: @*/
6146: PetscErrorCode  MatIsHermitian(Mat A,PetscTruth *flg)
6147: {

6153:   if (!A->hermitian_set) {
6154:     if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian");
6155:     (*A->ops->ishermitian)(A,&A->hermitian);
6156:     A->hermitian_set = PETSC_TRUE;
6157:     if (A->hermitian) {
6158:       A->structurally_symmetric_set = PETSC_TRUE;
6159:       A->structurally_symmetric     = PETSC_TRUE;
6160:     }
6161:   }
6162:   *flg = A->hermitian;
6163:   return(0);
6164: }

6169: /*@ 
6170:    MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
6171:        to be communicated to other processors during the MatAssemblyBegin/End() process

6173:     Not collective

6175:    Input Parameter:
6176: .   vec - the vector

6178:    Output Parameters:
6179: +   nstash   - the size of the stash
6180: .   reallocs - the number of additional mallocs incurred.
6181: .   bnstash   - the size of the block stash
6182: -   breallocs - the number of additional mallocs incurred.in the block stash
6183:  
6184:    Level: advanced

6186: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize()
6187:   
6188: @*/
6189: PetscErrorCode  MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
6190: {
6193:   MatStashGetInfo_Private(&mat->stash,nstash,reallocs);
6194:   MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);
6195:   return(0);
6196: }

6200: /*@
6201:    MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 
6202:      parallel layout
6203:    
6204:    Collective on Mat

6206:    Input Parameter:
6207: .  mat - the matrix

6209:    Output Parameter:
6210: +   right - (optional) vector that the matrix can be multiplied against
6211: -   left - (optional) vector that the matrix vector product can be stored in

6213:   Level: advanced

6215: .seealso: MatCreate()
6216: @*/
6217: PetscErrorCode  MatGetVecs(Mat mat,Vec *right,Vec *left)
6218: {

6224:   MatPreallocated(mat);
6225:   if (mat->ops->getvecs) {
6226:     (*mat->ops->getvecs)(mat,right,left);
6227:   } else {
6228:     PetscMPIInt size;
6229:     MPI_Comm_size(mat->comm, &size);
6230:     if (right) {
6231:       VecCreate(mat->comm,right);
6232:       VecSetSizes(*right,mat->cmap.n,PETSC_DETERMINE);
6233:       if (size > 1) {VecSetType(*right,VECMPI);}
6234:       else {VecSetType(*right,VECSEQ);}
6235:     }
6236:     if (left) {
6237:       VecCreate(mat->comm,left);
6238:       VecSetSizes(*left,mat->rmap.n,PETSC_DETERMINE);
6239:       if (size > 1) {VecSetType(*left,VECMPI);}
6240:       else {VecSetType(*left,VECSEQ);}
6241:     }
6242:   }
6243:   if (right) {VecSetBlockSize(*right,mat->rmap.bs);}
6244:   if (left) {VecSetBlockSize(*left,mat->rmap.bs);}
6245:   return(0);
6246: }

6250: /*@
6251:    MatFactorInfoInitialize - Initializes a MatFactorInfo data structure
6252:      with default values.

6254:    Not Collective

6256:    Input Parameters:
6257: .    info - the MatFactorInfo data structure


6260:    Notes: The solvers are generally used through the KSP and PC objects, for example
6261:           PCLU, PCILU, PCCHOLESKY, PCICC

6263:    Level: developer

6265: .seealso: MatFactorInfo
6266: @*/

6268: PetscErrorCode  MatFactorInfoInitialize(MatFactorInfo *info)
6269: {

6273:   PetscMemzero(info,sizeof(MatFactorInfo));
6274:   return(0);
6275: }

6279: /*@
6280:    MatPtAP - Creates the matrix projection C = P^T * A * P

6282:    Collective on Mat

6284:    Input Parameters:
6285: +  A - the matrix
6286: .  P - the projection matrix
6287: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6288: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P))

6290:    Output Parameters:
6291: .  C - the product matrix

6293:    Notes:
6294:    C will be created and must be destroyed by the user with MatDestroy().

6296:    This routine is currently only implemented for pairs of AIJ matrices and classes
6297:    which inherit from AIJ.  

6299:    Level: intermediate

6301: .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult()
6302: @*/
6303: PetscErrorCode  MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C)
6304: {

6310:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6311:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6314:   MatPreallocated(P);
6315:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6316:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6318:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6319:   if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6320:   MatPreallocated(A);

6323:   (*A->ops->ptap)(A,P,scall,fill,C);

6326:   return(0);
6327: }

6331: /*@
6332:    MatPtAPNumeric - Computes the matrix projection C = P^T * A * P

6334:    Collective on Mat

6336:    Input Parameters:
6337: +  A - the matrix
6338: -  P - the projection matrix

6340:    Output Parameters:
6341: .  C - the product matrix

6343:    Notes:
6344:    C must have been created by calling MatPtAPSymbolic and must be destroyed by
6345:    the user using MatDeatroy().

6347:    This routine is currently only implemented for pairs of AIJ matrices and classes
6348:    which inherit from AIJ.  C will be of type MATAIJ.

6350:    Level: intermediate

6352: .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric()
6353: @*/
6354: PetscErrorCode  MatPtAPNumeric(Mat A,Mat P,Mat C)
6355: {

6361:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6362:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6365:   MatPreallocated(P);
6366:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6367:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6370:   MatPreallocated(C);
6371:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6372:   if (P->cmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->rmap.N);
6373:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6374:   if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6375:   if (P->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->cmap.N);
6376:   MatPreallocated(A);

6379:   (*A->ops->ptapnumeric)(A,P,C);
6381:   return(0);
6382: }

6386: /*@
6387:    MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P

6389:    Collective on Mat

6391:    Input Parameters:
6392: +  A - the matrix
6393: -  P - the projection matrix

6395:    Output Parameters:
6396: .  C - the (i,j) structure of the product matrix

6398:    Notes:
6399:    C will be created and must be destroyed by the user with MatDestroy().

6401:    This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6402:    which inherit from SeqAIJ.  C will be of type MATSEQAIJ.  The product is computed using
6403:    this (i,j) structure by calling MatPtAPNumeric().

6405:    Level: intermediate

6407: .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic()
6408: @*/
6409: PetscErrorCode  MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C)
6410: {

6416:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6417:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6418:   if (fill <1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6421:   MatPreallocated(P);
6422:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6423:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6426:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6427:   if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6428:   MatPreallocated(A);
6430:   (*A->ops->ptapsymbolic)(A,P,fill,C);

6433:   MatSetBlockSize(*C,A->rmap.bs);

6435:   return(0);
6436: }

6440: /*@
6441:    MatMatMult - Performs Matrix-Matrix Multiplication C=A*B.

6443:    Collective on Mat

6445:    Input Parameters:
6446: +  A - the left matrix
6447: .  B - the right matrix
6448: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6449: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6451:    Output Parameters:
6452: .  C - the product matrix

6454:    Notes:
6455:    C will be created and must be destroyed by the user with MatDestroy().
6456:    Unless scall is MAT_REUSE_MATRIX

6458:    If you have many matrices with the same non-zero structure to multiply, you 
6459:    should either 
6460: $   1) use MAT_REUSE_MATRIX in all calls but the first or
6461: $   2) call MatMatMultSymbolic() once and then MatMatMultNumeric() for each product needed

6463:    Level: intermediate

6465: .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP()
6466: @*/
6467: PetscErrorCode  MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6468: {
6470:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6471:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);
6472:   PetscErrorCode (*mult)(Mat,Mat,MatReuse,PetscReal,Mat *)=PETSC_NULL;

6477:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6478:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6481:   MatPreallocated(B);
6482:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6483:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6485:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6486:   if (fill == PETSC_DEFAULT) fill = 2.0;
6487:   if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6488:   MatPreallocated(A);

6490:   fA = A->ops->matmult;
6491:   fB = B->ops->matmult;
6492:   if (fB == fA) {
6493:     if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name);
6494:     mult = fB;
6495:   } else {
6496:     /* dispatch based on the type of A and B */
6497:     char  multname[256];
6498:     PetscStrcpy(multname,"MatMatMult_");
6499:     PetscStrcat(multname,A->type_name);
6500:     PetscStrcat(multname,"_");
6501:     PetscStrcat(multname,B->type_name);
6502:     PetscStrcat(multname,"_C"); /* e.g., multname = "MatMatMult_aij_dense_C" */
6503:     PetscObjectQueryFunction((PetscObject)B,multname,(void (**)(void))&mult);
6504:     if (!mult) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6505:   }
6507:   (*mult)(A,B,scall,fill,C);
6509:   return(0);
6510: }

6514: /*@
6515:    MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure
6516:    of the matrix-matrix product C=A*B.  Call this routine before calling MatMatMultNumeric().

6518:    Collective on Mat

6520:    Input Parameters:
6521: +  A - the left matrix
6522: .  B - the right matrix
6523: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6525:    Output Parameters:
6526: .  C - the matrix containing the ij structure of product matrix

6528:    Notes:
6529:    C will be created and must be destroyed by the user with MatDestroy().

6531:    This routine is currently implemented for 
6532:     - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ.
6533:     - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE.

6535:    Level: intermediate

6537: .seealso: MatMatMult(), MatMatMultNumeric()
6538: @*/
6539: PetscErrorCode  MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C)
6540: {
6542:   PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *);
6543:   PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *);
6544:   PetscErrorCode (*symbolic)(Mat,Mat,PetscReal,Mat *)=PETSC_NULL;

6549:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6550:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6554:   MatPreallocated(B);
6555:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6556:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6559:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6560:   if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill);
6561:   MatPreallocated(A);
6562: 
6563:   Asymbolic = A->ops->matmultsymbolic;
6564:   Bsymbolic = B->ops->matmultsymbolic;
6565:   if (Asymbolic == Bsymbolic){
6566:     if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name);
6567:     symbolic = Bsymbolic;
6568:   } else { /* dispatch based on the type of A and B */
6569:     char  symbolicname[256];
6570:     PetscStrcpy(symbolicname,"MatMatMultSymbolic_");
6571:     PetscStrcat(symbolicname,A->type_name);
6572:     PetscStrcat(symbolicname,"_");
6573:     PetscStrcat(symbolicname,B->type_name);
6574:     PetscStrcat(symbolicname,"_C");
6575:     PetscObjectQueryFunction((PetscObject)B,symbolicname,(void (**)(void))&symbolic);
6576:     if (!symbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6577:   }
6579:   (*symbolic)(A,B,fill,C);
6581:   return(0);
6582: }

6586: /*@
6587:    MatMatMultNumeric - Performs the numeric matrix-matrix product.
6588:    Call this routine after first calling MatMatMultSymbolic().

6590:    Collective on Mat

6592:    Input Parameters:
6593: +  A - the left matrix
6594: -  B - the right matrix

6596:    Output Parameters:
6597: .  C - the product matrix, whose ij structure was defined from MatMatMultSymbolic().

6599:    Notes:
6600:    C must have been created with MatMatMultSymbolic.

6602:    This routine is currently implemented for 
6603:     - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ.
6604:     - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE.

6606:    Level: intermediate

6608: .seealso: MatMatMult(), MatMatMultSymbolic()
6609: @*/
6610: PetscErrorCode  MatMatMultNumeric(Mat A,Mat B,Mat C)
6611: {
6613:   PetscErrorCode (*Anumeric)(Mat,Mat,Mat);
6614:   PetscErrorCode (*Bnumeric)(Mat,Mat,Mat);
6615:   PetscErrorCode (*numeric)(Mat,Mat,Mat)=PETSC_NULL;

6620:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6621:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6625:   MatPreallocated(B);
6626:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6627:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6631:   MatPreallocated(C);
6632:   if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6633:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6635:   if (B->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap.N,C->cmap.N);
6636:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6637:   if (A->rmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap.N,C->rmap.N);
6638:   MatPreallocated(A);

6640:   Anumeric = A->ops->matmultnumeric;
6641:   Bnumeric = B->ops->matmultnumeric;
6642:   if (Anumeric == Bnumeric){
6643:     if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name);
6644:     numeric = Bnumeric;
6645:   } else {
6646:     char  numericname[256];
6647:     PetscStrcpy(numericname,"MatMatMultNumeric_");
6648:     PetscStrcat(numericname,A->type_name);
6649:     PetscStrcat(numericname,"_");
6650:     PetscStrcat(numericname,B->type_name);
6651:     PetscStrcat(numericname,"_C");
6652:     PetscObjectQueryFunction((PetscObject)B,numericname,(void (**)(void))&numeric);
6653:     if (!numeric)
6654:       SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6655:   }
6657:   (*numeric)(A,B,C);
6659:   return(0);
6660: }

6664: /*@
6665:    MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B.

6667:    Collective on Mat

6669:    Input Parameters:
6670: +  A - the left matrix
6671: .  B - the right matrix
6672: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6673: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6675:    Output Parameters:
6676: .  C - the product matrix

6678:    Notes:
6679:    C will be created and must be destroyed by the user with MatDestroy().

6681:    This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6682:    which inherit from SeqAIJ.  C will be of type MATSEQAIJ.

6684:    Level: intermediate

6686: .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP()
6687: @*/
6688: PetscErrorCode  MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6689: {
6691:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6692:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);

6697:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6698:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6701:   MatPreallocated(B);
6702:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6703:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6705:   if (B->rmap.N!=A->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->rmap.N);
6706:   if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill);
6707:   MatPreallocated(A);

6709:   fA = A->ops->matmulttranspose;
6710:   if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name);
6711:   fB = B->ops->matmulttranspose;
6712:   if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name);
6713:   if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6716:   (*A->ops->matmulttranspose)(A,B,scall,fill,C);
6718: 
6719:   return(0);
6720: }