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 PETSCMAT_DLLEXPORT 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    PETSCMAT_DLLEXPORT MatSetValue_Row = 0;
 26: PetscInt    PETSCMAT_DLLEXPORT MatSetValue_Column = 0;
 27: PetscScalar PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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);
167:   PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
168:   (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);
169:   if (ncols) *ncols = incols;
170:   PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT 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 PETSCMAT_DLLEXPORT MatDestroy(Mat A)
701: {

706:   if (--A->refct > 0) return(0);

709:   MatPreallocated(A);
710:   /* if memory was published with AMS then destroy it */
711:   PetscObjectDepublish(A);
712:   if (A->mapping) {
713:     ISLocalToGlobalMappingDestroy(A->mapping);
714:   }
715:   if (A->bmapping) {
716:     ISLocalToGlobalMappingDestroy(A->bmapping);
717:   }
718:   (*A->ops->destroy)(A);
719:   PetscFree(A->rmap.range);
720:   PetscFree(A->cmap.range);
721:   PetscFree(A->spptr);
722:   PetscHeaderDestroy(A);
723:   return(0);
724: }

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

731:    Collective on Mat

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

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

740:    Level: developer

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

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

761:    Not Collective

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

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

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

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

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

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

792:    Level: beginner

794:    Concepts: matrices^putting entries in

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

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

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


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

839:    Not Collective

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

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

849:    All the nonzeros in the row must be provided

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

853:    The row must belong to this process

855:    Level: intermediate

857:    Concepts: matrices^putting entries in

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

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

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

880:    Not Collective

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

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

890:    All the nonzeros in the row must be provided

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

894:    The row must belong to this process

896:    Level: intermediate

898:    Concepts: matrices^putting entries in

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

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

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

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

934:    Not Collective

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

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

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

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

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

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

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

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

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

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

984:    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
985:    a single value per point) you can skip filling those indices.

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

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

994:    Level: beginner

996:    Concepts: matrices^putting entries in

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

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

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

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

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

1048:    Not Collective

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

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

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

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

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

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

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

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

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

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

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

1101:    Level: beginner

1103:    Concepts: matrices^putting entries in

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

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

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

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

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

1155:    Not Collective

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


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

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

1173:    Concepts: matrices^putting entries in

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


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

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

1203:    Not Collective

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

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

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

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

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

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

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

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

1243:    Level: intermediate

1245:    Concepts: matrices^putting entries in blocked

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

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

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

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

1287:    Not Collective; currently only returns a local block

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

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

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

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

1308:    Level: advanced

1310:    Concepts: matrices^accessing values

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

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

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

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

1342:    Not Collective

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

1349:    Level: intermediate

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

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

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

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

1384:    Not Collective

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

1391:    Level: intermediate

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

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

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

1420:    Not Collective

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

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

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

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

1442:    Level: intermediate

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

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

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

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

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

1497:    Not Collective

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

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

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

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

1520:    Level: intermediate

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

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

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

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

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

1572:    Collective on Mat and Vec

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

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

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

1585:    Level: beginner

1587:    Concepts: matrix-vector product

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


1601:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1602:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1603:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1604: #ifndef PETSC_HAVE_CONSTRAINTS
1605:   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);
1606:   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);
1607:   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);
1608: #endif
1609:   MatPreallocated(mat);

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

1615:   if (!mat->ops->mult) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply defined");
1616:   PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1617:   (*mat->ops->mult)(mat,x,y);
1618:   PetscLogEventEnd(MAT_Mult,mat,x,y,0);

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

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

1632:    Collective on Mat and Vec

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

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

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

1645:    Level: beginner

1647:    Concepts: matrix vector product^transpose

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


1661:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1662:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1663:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1664: #ifndef PETSC_HAVE_CONSTRAINTS
1665:   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);
1666:   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);
1667: #endif
1668:   MatPreallocated(mat);

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

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

1683:     Collective on Mat and Vec

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

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

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

1696:     Level: beginner

1698:     Concepts: matrix vector product^addition

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


1713:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1714:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1715:   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);
1716:   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);
1717:   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);
1718:   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);
1719:   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);
1720:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1721:   MatPreallocated(mat);

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

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

1735:    Collective on Mat and Vec

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

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

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

1748:    Level: beginner

1750:    Concepts: matrix vector product^transpose and addition

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


1765:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1766:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1767:   if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1768:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1769:   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);
1770:   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);
1771:   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);
1772:   MatPreallocated(mat);

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

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

1787:    Collective on Mat and Vec

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

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

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

1800:    Level: beginner

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

1813:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1814:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1815:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1816:   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);
1817:   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);
1818:   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:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1821:   (*mat->ops->multconstrained)(mat,x,y);
1822:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1823:   PetscObjectStateIncrease((PetscObject)y);

1825:   return(0);
1826: }

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

1834:    Collective on Mat and Vec

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

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

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

1847:    Level: beginner

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

1860:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1861:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1862:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1863:   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);
1864:   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:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1867:   (*mat->ops->multtransposeconstrained)(mat,x,y);
1868:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1869:   PetscObjectStateIncrease((PetscObject)y);

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

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

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

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

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

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

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

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

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

1930:     Level: intermediate

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

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

1949: /* ----------------------------------------------------------*/
1952: /*@C  
1953:    MatILUDTFactor - Performs a drop tolerance ILU factorization.

1955:    Collective on Mat

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

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

1966:    Level: developer

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

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

1978:     Concepts: matrices^ILUDT factorization

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

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

2002:   return(0);
2003: }

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

2010:    Collective on Mat

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

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

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

2029:    Level: developer

2031:    Concepts: matrices^LU factorization

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

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

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

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

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

2064:    Collective on Mat

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

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

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

2084:    Level: developer

2086:    Concepts: matrices^ILU factorization

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

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

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

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

2119:    Collective on Mat

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

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

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

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

2140:    Level: developer

2142:    Concepts: matrices^LU symbolic factorization

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

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

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

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

2175:    Collective on Mat

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

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

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

2190:    Level: developer

2192:    Concepts: matrices^LU numeric factorization

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

2205:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2206:   if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2207:     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);
2208:   }
2209:   if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2210:   MatPreallocated(mat);
2211:   PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
2212:   (*(*fact)->ops->lufactornumeric)(mat,info,fact);
2213:   PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);

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

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

2226:    Collective on Mat

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

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

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

2241:    Level: developer

2243:    Concepts: matrices^Cholesky factorization

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

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

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

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

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

2277:    Collective on Mat

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

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

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

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

2298:    Level: developer

2300:    Concepts: matrices^Cholesky symbolic factorization

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

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

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

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

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

2336:    Collective on Mat

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

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

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

2351:    Level: developer

2353:    Concepts: matrices^Cholesky numeric factorization

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

2365:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2366:   if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2367:   if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2368:     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);
2369:   }
2370:   MatPreallocated(mat);

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

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

2385:    Collective on Mat and Vec

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

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

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

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

2403:    Level: developer

2405:    Concepts: matrices^triangular solves

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

2420:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2421:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2422:   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);
2423:   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);
2424:   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);
2425:   if (!mat->rmap.N && !mat->cmap.N) return(0);
2426:   if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2427:   MatPreallocated(mat);

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

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

2441:    Collective on Mat 

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

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

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

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

2459:    Level: developer

2461:    Concepts: matrices^triangular solves

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

2476:   if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices");
2477:   if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2478:   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);
2479:   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);
2480:   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);
2481:   if (!A->rmap.N && !A->cmap.N) return(0);
2482:   if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2483:   MatPreallocated(A);

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


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

2498:    Collective on Mat and Vec

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

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

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

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

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

2518:    Level: developer

2520:    Concepts: matrices^forward solves

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

2535:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2536:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2537:   if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2538:   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);
2539:   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);
2540:   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);
2541:   MatPreallocated(mat);
2542:   PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
2543:   (*mat->ops->forwardsolve)(mat,b,x);
2544:   PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
2545:   PetscObjectStateIncrease((PetscObject)x);
2546:   return(0);
2547: }

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

2554:    Collective on Mat and Vec

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

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

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

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

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

2574:    Level: developer

2576:    Concepts: matrices^backward solves

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

2591:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2592:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2593:   if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2594:   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);
2595:   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);
2596:   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);
2597:   MatPreallocated(mat);

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

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

2611:    Collective on Mat and Vec

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

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

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

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

2629:    Level: developer

2631:    Concepts: matrices^triangular solves

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

2650:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2651:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2652:   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);
2653:   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);
2654:   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);
2655:   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);
2656:   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);
2657:   MatPreallocated(mat);

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

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

2686:    Collective on Mat and Vec

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

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

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

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

2703:    Level: developer

2705:    Concepts: matrices^triangular solves

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

2720:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2721:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2722:   if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2723:   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);
2724:   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);
2725:   MatPreallocated(mat);
2726:   PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
2727:   (*mat->ops->solvetranspose)(mat,b,x);
2728:   PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
2729:   PetscObjectStateIncrease((PetscObject)x);
2730:   return(0);
2731: }

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

2739:    Collective on Mat and Vec

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

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

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

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

2757:    Level: developer

2759:    Concepts: matrices^triangular solves

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

2778:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2779:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2780:   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);
2781:   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);
2782:   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);
2783:   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);
2784:   MatPreallocated(mat);

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

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

2814:    Collective on Mat and Vec

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

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

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

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

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

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

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

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

2860:    Level: developer

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

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

2878:   if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2879:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2880:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2881:   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);
2882:   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);
2883:   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);
2884:   MatPreallocated(mat);
2885:   PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2886:   if (mat->ops->relax) {
2887:     ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2888:   } else {
2889:     ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2890:   }
2891:   PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2892:   PetscObjectStateIncrease((PetscObject)x);
2893:   return(0);
2894: }

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

2901:    Collective on Mat and Vec

2903:    See MatRelax() for usage

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

2910:    Level: developer

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

2924:   if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2925:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2926:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2927:   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);
2928:   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);
2929:   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);
2930:   MatPreallocated(mat);

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

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

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

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

2972:    Collective on Mat

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

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

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

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

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

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

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

3005:   MatPreallocated(B);
3007:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3008:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3009:   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);
3010:   MatPreallocated(A);

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

3031:  #include petscsys.h
3032: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
3033: PetscFList MatConvertList              = 0;

3037: /*@C
3038:     MatConvertRegister - Allows one to register a routine that converts a sparse matrix
3039:         from one format to another.

3041:   Not Collective

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

3047:   Level: developer

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

3051: @*/
3052: PetscErrorCode PETSCMAT_DLLEXPORT MatConvertRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(Mat,MatType,MatReuse,Mat*))
3053: {
3055:   char           fullname[PETSC_MAX_PATH_LEN];

3058:   PetscFListConcat(path,name,fullname);
3059:   PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);
3060:   return(0);
3061: }

3065: /*@C  
3066:    MatConvert - Converts a matrix to another matrix, either of the same
3067:    or different type.

3069:    Collective on Mat

3071:    Input Parameters:
3072: +  mat - the matrix
3073: .  newtype - new matrix type.  Use MATSAME to create a new matrix of the
3074:    same type as the original matrix.
3075: -  reuse - denotes if the destination matrix is to be created or reused.  Currently
3076:    MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use
3077:    MAT_INITIAL_MATRIX.
3078:    Output Parameter:
3079: .  M - pointer to place new matrix

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

3086:    Level: intermediate

3088:    Concepts: matrices^converting between storage formats

3090: .seealso: MatCopy(), MatDuplicate()
3091: @*/
3092: PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M)
3093: {
3094:   PetscErrorCode         ierr;
3095:   PetscTruth             sametype,issame,flg;
3096:   char                   convname[256],mtype[256];
3097:   Mat                    B;

3103:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3104:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3105:   MatPreallocated(mat);

3107:   PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
3108:   if (flg) {
3109:     newtype = mtype;
3110:   }
3111:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
3112: 
3113:   PetscTypeCompare((PetscObject)mat,newtype,&sametype);
3114:   PetscStrcmp(newtype,"same",&issame);
3115:   if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) {
3116:     SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for inplace convertion currently");
3117:   }
3118:   if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) {
3119:     (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
3120:   } else {
3121:     PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL;
3122:     /* 
3123:        Order of precedence:
3124:        1) See if a specialized converter is known to the current matrix.
3125:        2) See if a specialized converter is known to the desired matrix class.
3126:        3) See if a good general converter is registered for the desired class
3127:           (as of 6/27/03 only MATMPIADJ falls into this category).
3128:        4) See if a good general converter is known for the current matrix.
3129:        5) Use a really basic converter.
3130:     */
3131:     PetscStrcpy(convname,"MatConvert_");
3132:     PetscStrcat(convname,mat->type_name);
3133:     PetscStrcat(convname,"_");
3134:     PetscStrcat(convname,newtype);
3135:     PetscStrcat(convname,"_C");
3136:     PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);

3138:     if (!conv) {
3139:       MatCreate(mat->comm,&B);
3140:       MatSetSizes(B,mat->rmap.n,mat->cmap.n,mat->rmap.N,mat->cmap.N);
3141:       MatSetType(B,newtype);
3142:       PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);
3143:       MatDestroy(B);
3144:       if (!conv) {
3145:         if (!MatConvertRegisterAllCalled) {
3146:           MatConvertRegisterAll(PETSC_NULL);
3147:         }
3148:         PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);
3149:         if (!conv) {
3150:           if (mat->ops->convert) {
3151:             conv = mat->ops->convert;
3152:           } else {
3153:             conv = MatConvert_Basic;
3154:           }
3155:         }
3156:       }
3157:     }
3158:     (*conv)(mat,newtype,reuse,M);
3159:   }
3160:   B = *M;
3161:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
3162:   PetscObjectStateIncrease((PetscObject)B);
3163:   return(0);
3164: }


3169: /*@
3170:    MatDuplicate - Duplicates a matrix including the non-zero structure.

3172:    Collective on Mat

3174:    Input Parameters:
3175: +  mat - the matrix
3176: -  op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
3177:         values as well or not

3179:    Output Parameter:
3180: .  M - pointer to place new matrix

3182:    Level: intermediate

3184:    Concepts: matrices^duplicating

3186: .seealso: MatCopy(), MatConvert()
3187: @*/
3188: PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
3189: {
3191:   Mat            B;

3197:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3198:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3199:   MatPreallocated(mat);

3201:   *M  = 0;
3202:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
3203:   if (!mat->ops->duplicate) {
3204:     SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
3205:   }
3206:   (*mat->ops->duplicate)(mat,op,M);
3207:   B = *M;
3208:   if (mat->mapping) {
3209:     MatSetLocalToGlobalMapping(B,mat->mapping);
3210:   }
3211:   if (mat->bmapping) {
3212:     MatSetLocalToGlobalMappingBlock(B,mat->bmapping);
3213:   }
3214:   PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);
3215:   PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);
3216: 
3217:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
3218:   PetscObjectStateIncrease((PetscObject)B);
3219:   return(0);
3220: }

3224: /*@ 
3225:    MatGetDiagonal - Gets the diagonal of a matrix.

3227:    Collective on Mat and Vec

3229:    Input Parameters:
3230: +  mat - the matrix
3231: -  v - the vector for storing the diagonal

3233:    Output Parameter:
3234: .  v - the diagonal of the matrix

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

3242:    Level: intermediate

3244:    Concepts: matrices^accessing diagonals

3246: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
3247: @*/
3248: PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v)
3249: {

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

3260:   (*mat->ops->getdiagonal)(mat,v);
3261:   PetscObjectStateIncrease((PetscObject)v);
3262:   return(0);
3263: }

3267: /*@ 
3268:    MatGetRowMax - Gets the maximum value (in absolute value) of each
3269:         row of the matrix

3271:    Collective on Mat and Vec

3273:    Input Parameters:
3274: .  mat - the matrix

3276:    Output Parameter:
3277: .  v - the vector for storing the maximums

3279:    Level: intermediate

3281:    Concepts: matrices^getting row maximums

3283: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
3284: @*/
3285: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v)
3286: {

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

3297:   (*mat->ops->getrowmax)(mat,v);
3298:   PetscObjectStateIncrease((PetscObject)v);
3299:   return(0);
3300: }

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

3307:    Collective on Mat

3309:    Input Parameter:
3310: .  mat - the matrix to transpose

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

3315:    Level: intermediate

3317:    Concepts: matrices^transposing

3319: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose()
3320: @*/
3321: PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B)
3322: {

3328:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3329:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3330:   if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3331:   MatPreallocated(mat);

3333:   PetscLogEventBegin(MAT_Transpose,mat,0,0,0);
3334:   (*mat->ops->transpose)(mat,B);
3335:   PetscLogEventEnd(MAT_Transpose,mat,0,0,0);
3336:   if (B) {PetscObjectStateIncrease((PetscObject)*B);}
3337:   return(0);
3338: }

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

3346:    Collective on Mat

3348:    Input Parameter:
3349: +  A - the matrix to test
3350: -  B - the matrix to test against, this can equal the first parameter

3352:    Output Parameters:
3353: .  flg - the result

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

3360:    Level: intermediate

3362:    Concepts: matrices^transposing, matrix^symmetry

3364: .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian()
3365: @*/
3366: PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg)
3367: {
3368:   PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*);

3374:   PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);
3375:   PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);
3376:   if (f && g) {
3377:     if (f==g) {
3378:       (*f)(A,B,tol,flg);
3379:     } else {
3380:       SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test");
3381:     }
3382:   }
3383:   return(0);
3384: }

3388: /*@C
3389:    MatPermute - Creates a new matrix with rows and columns permuted from the 
3390:    original.

3392:    Collective on Mat

3394:    Input Parameters:
3395: +  mat - the matrix to permute
3396: .  row - row permutation, each processor supplies only the permutation for its rows
3397: -  col - column permutation, each processor needs the entire column permutation, that is
3398:          this is the same size as the total number of columns in the matrix

3400:    Output Parameters:
3401: .  B - the permuted matrix

3403:    Level: advanced

3405:    Concepts: matrices^permuting

3407: .seealso: MatGetOrdering()
3408: @*/
3409: PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B)
3410: {

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

3424:   (*mat->ops->permute)(mat,row,col,B);
3425:   PetscObjectStateIncrease((PetscObject)*B);
3426:   return(0);
3427: }

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

3435:   Collective on Mat

3437:   Input Parameters:
3438: + A    - The matrix to permute
3439: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
3440: . frac - The half-bandwidth as a fraction of the total size, or 0.0
3441: . tol  - The drop tolerance
3442: . rowp - The row permutation
3443: - colp - The column permutation

3445:   Output Parameter:
3446: . B    - The permuted, sparsified matrix

3448:   Level: advanced

3450:   Note:
3451:   The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
3452:   restrict the half-bandwidth of the resulting matrix to 5% of the
3453:   total matrix size.

3455: .keywords: matrix, permute, sparsify

3457: .seealso: MatGetOrdering(), MatPermute()
3458: @*/
3459: PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
3460: {
3461:   IS                irowp, icolp;
3462:   PetscInt          *rows, *cols;
3463:   PetscInt          M, N, locRowStart, locRowEnd;
3464:   PetscInt          nz, newNz;
3465:   const PetscInt    *cwork;
3466:   PetscInt          *cnew;
3467:   const PetscScalar *vwork;
3468:   PetscScalar       *vnew;
3469:   PetscInt          bw, issize;
3470:   PetscInt          row, locRow, newRow, col, newCol;
3471:   PetscErrorCode    ierr;

3478:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
3479:   if (A->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
3480:   if (!A->ops->permutesparsify) {
3481:     MatGetSize(A, &M, &N);
3482:     MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
3483:     ISGetSize(rowp, &issize);
3484:     if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M);
3485:     ISGetSize(colp, &issize);
3486:     if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N);
3487:     ISInvertPermutation(rowp, 0, &irowp);
3488:     ISGetIndices(irowp, &rows);
3489:     ISInvertPermutation(colp, 0, &icolp);
3490:     ISGetIndices(icolp, &cols);
3491:     PetscMalloc(N * sizeof(PetscInt),         &cnew);
3492:     PetscMalloc(N * sizeof(PetscScalar), &vnew);

3494:     /* Setup bandwidth to include */
3495:     if (band == PETSC_DECIDE) {
3496:       if (frac <= 0.0)
3497:         bw = (PetscInt) (M * 0.05);
3498:       else
3499:         bw = (PetscInt) (M * frac);
3500:     } else {
3501:       if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
3502:       bw = band;
3503:     }

3505:     /* Put values into new matrix */
3506:     MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
3507:     for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
3508:       MatGetRow(A, row, &nz, &cwork, &vwork);
3509:       newRow   = rows[locRow]+locRowStart;
3510:       for(col = 0, newNz = 0; col < nz; col++) {
3511:         newCol = cols[cwork[col]];
3512:         if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
3513:           cnew[newNz] = newCol;
3514:           vnew[newNz] = vwork[col];
3515:           newNz++;
3516:         }
3517:       }
3518:       MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
3519:       MatRestoreRow(A, row, &nz, &cwork, &vwork);
3520:     }
3521:     PetscFree(cnew);
3522:     PetscFree(vnew);
3523:     MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
3524:     MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
3525:     ISRestoreIndices(irowp, &rows);
3526:     ISRestoreIndices(icolp, &cols);
3527:     ISDestroy(irowp);
3528:     ISDestroy(icolp);
3529:   } else {
3530:     (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
3531:   }
3532:   PetscObjectStateIncrease((PetscObject)*B);
3533:   return(0);
3534: }

3538: /*@
3539:    MatEqual - Compares two matrices.

3541:    Collective on Mat

3543:    Input Parameters:
3544: +  A - the first matrix
3545: -  B - the second matrix

3547:    Output Parameter:
3548: .  flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.

3550:    Level: intermediate

3552:    Concepts: matrices^equality between
3553: @*/
3554: PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg)
3555: {

3563:   MatPreallocated(B);
3566:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3567:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3568:   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);
3569:   if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
3570:   if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
3571:   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);
3572:   MatPreallocated(A);

3574:   (*A->ops->equal)(A,B,flg);
3575:   return(0);
3576: }

3580: /*@
3581:    MatDiagonalScale - Scales a matrix on the left and right by diagonal
3582:    matrices that are stored as vectors.  Either of the two scaling
3583:    matrices can be PETSC_NULL.

3585:    Collective on Mat

3587:    Input Parameters:
3588: +  mat - the matrix to be scaled
3589: .  l - the left scaling vector (or PETSC_NULL)
3590: -  r - the right scaling vector (or PETSC_NULL)

3592:    Notes:
3593:    MatDiagonalScale() computes A = LAR, where
3594:    L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector)

3596:    Level: intermediate

3598:    Concepts: matrices^diagonal scaling
3599:    Concepts: diagonal scaling of matrices

3601: .seealso: MatScale()
3602: @*/
3603: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r)
3604: {

3610:   if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3613:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3614:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3615:   MatPreallocated(mat);

3617:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3618:   (*mat->ops->diagonalscale)(mat,l,r);
3619:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3620:   PetscObjectStateIncrease((PetscObject)mat);
3621:   return(0);
3622: }

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

3629:     Collective on Mat

3631:     Input Parameters:
3632: +   mat - the matrix to be scaled
3633: -   a  - the scaling value

3635:     Output Parameter:
3636: .   mat - the scaled matrix

3638:     Level: intermediate

3640:     Concepts: matrices^scaling all entries

3642: .seealso: MatDiagonalScale()
3643: @*/
3644: PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a)
3645: {

3651:   if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3652:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3653:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3654:   MatPreallocated(mat);

3656:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3657:   (*mat->ops->scale)(mat,a);
3658:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3659:   PetscObjectStateIncrease((PetscObject)mat);
3660:   return(0);
3661: }

3665: /*@ 
3666:    MatNorm - Calculates various norms of a matrix.

3668:    Collective on Mat

3670:    Input Parameters:
3671: +  mat - the matrix
3672: -  type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY

3674:    Output Parameters:
3675: .  nrm - the resulting norm 

3677:    Level: intermediate

3679:    Concepts: matrices^norm
3680:    Concepts: norm^of matrix
3681: @*/
3682: PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm)
3683: {


3691:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3692:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3693:   if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3694:   MatPreallocated(mat);

3696:   (*mat->ops->norm)(mat,type,nrm);
3697:   return(0);
3698: }

3700: /* 
3701:      This variable is used to prevent counting of MatAssemblyBegin() that
3702:    are called from within a MatAssemblyEnd().
3703: */
3704: static PetscInt MatAssemblyEnd_InUse = 0;
3707: /*@
3708:    MatAssemblyBegin - Begins assembling the matrix.  This routine should
3709:    be called after completing all calls to MatSetValues().

3711:    Collective on Mat

3713:    Input Parameters:
3714: +  mat - the matrix 
3715: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3716:  
3717:    Notes: 
3718:    MatSetValues() generally caches the values.  The matrix is ready to
3719:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3720:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3721:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3722:    using the matrix.

3724:    Level: beginner

3726:    Concepts: matrices^assembling

3728: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3729: @*/
3730: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type)
3731: {

3737:   MatPreallocated(mat);
3738:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3739:   if (mat->assembled) {
3740:     mat->was_assembled = PETSC_TRUE;
3741:     mat->assembled     = PETSC_FALSE;
3742:   }
3743:   if (!MatAssemblyEnd_InUse) {
3744:     PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
3745:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3746:     PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
3747:   } else {
3748:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3749:   }
3750:   return(0);
3751: }

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

3759:    Collective on Mat

3761:    Input Parameter:
3762: .  mat - the matrix 

3764:    Output Parameter:
3765: .  assembled - PETSC_TRUE or PETSC_FALSE

3767:    Level: advanced

3769:    Concepts: matrices^assembled?

3771: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3772: @*/
3773: PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled)
3774: {
3779:   *assembled = mat->assembled;
3780:   return(0);
3781: }

3785: /*
3786:     Processes command line options to determine if/how a matrix
3787:   is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3788: */
3789: PetscErrorCode MatView_Private(Mat mat)
3790: {
3791:   PetscErrorCode    ierr;
3792:   PetscTruth        flg;
3793:   static PetscTruth incall = PETSC_FALSE;

3796:   if (incall) return(0);
3797:   incall = PETSC_TRUE;
3798:   PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3799:     PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);
3800:     if (flg) {
3801:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3802:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3803:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3804:     }
3805:     PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);
3806:     if (flg) {
3807:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3808:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3809:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3810:     }
3811:     PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);
3812:     if (flg) {
3813:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3814:     }
3815:     PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);
3816:     if (flg) {
3817:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3818:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3819:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3820:     }
3821: #if defined(PETSC_USE_SOCKET_VIEWER)
3822:     PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);
3823:     if (flg) {
3824:       MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3825:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3826:     }
3827: #endif
3828:     PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);
3829:     if (flg) {
3830:       MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3831:       PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3832:     }
3833:   PetscOptionsEnd();
3834:   /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */
3835:   PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
3836:   if (flg) {
3837:     PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
3838:     if (flg) {
3839:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3840:     }
3841:     MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3842:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3843:     if (flg) {
3844:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3845:     }
3846:   }
3847:   incall = PETSC_FALSE;
3848:   return(0);
3849: }

3853: /*@
3854:    MatAssemblyEnd - Completes assembling the matrix.  This routine should
3855:    be called after MatAssemblyBegin().

3857:    Collective on Mat

3859:    Input Parameters:
3860: +  mat - the matrix 
3861: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY

3863:    Options Database Keys:
3864: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3865: .  -mat_view_info_detailed - Prints more detailed info
3866: .  -mat_view - Prints matrix in ASCII format
3867: .  -mat_view_matlab - Prints matrix in Matlab format
3868: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3869: .  -display <name> - Sets display name (default is host)
3870: .  -draw_pause <sec> - Sets number of seconds to pause after display
3871: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3872: .  -viewer_socket_machine <machine>
3873: .  -viewer_socket_port <port>
3874: .  -mat_view_binary - save matrix to file in binary format
3875: -  -viewer_binary_filename <name>

3877:    Notes: 
3878:    MatSetValues() generally caches the values.  The matrix is ready to
3879:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3880:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3881:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3882:    using the matrix.

3884:    Level: beginner

3886: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3887: @*/
3888: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type)
3889: {
3890:   PetscErrorCode  ierr;
3891:   static PetscInt inassm = 0;
3892:   PetscTruth      flg;


3898:   inassm++;
3899:   MatAssemblyEnd_InUse++;
3900:   if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3901:     PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
3902:     if (mat->ops->assemblyend) {
3903:       (*mat->ops->assemblyend)(mat,type);
3904:     }
3905:     PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
3906:   } else {
3907:     if (mat->ops->assemblyend) {
3908:       (*mat->ops->assemblyend)(mat,type);
3909:     }
3910:   }

3912:   /* Flush assembly is not a true assembly */
3913:   if (type != MAT_FLUSH_ASSEMBLY) {
3914:     mat->assembled  = PETSC_TRUE; mat->num_ass++;
3915:   }
3916:   mat->insertmode = NOT_SET_VALUES;
3917:   MatAssemblyEnd_InUse--;
3918:   PetscObjectStateIncrease((PetscObject)mat);
3919:   if (!mat->symmetric_eternal) {
3920:     mat->symmetric_set              = PETSC_FALSE;
3921:     mat->hermitian_set              = PETSC_FALSE;
3922:     mat->structurally_symmetric_set = PETSC_FALSE;
3923:   }
3924:   if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3925:     MatView_Private(mat);
3926:     PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);
3927:     if (flg) {
3928:       PetscReal tol = 0.0;
3929:       PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);
3930:       MatIsSymmetric(mat,tol,&flg);
3931:       if (flg) {
3932:         PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);
3933:       } else {
3934:         PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);
3935:       }
3936:     }
3937:   }
3938:   inassm--;
3939:   PetscOptionsHasName(mat->prefix,"-help",&flg);
3940:   if (flg) {
3941:     MatPrintHelp(mat);
3942:   }
3943:   return(0);
3944: }


3949: /*@
3950:    MatCompress - Tries to store the matrix in as little space as 
3951:    possible.  May fail if memory is already fully used, since it
3952:    tries to allocate new space.

3954:    Collective on Mat

3956:    Input Parameters:
3957: .  mat - the matrix 

3959:    Level: advanced

3961: @*/
3962: PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat)
3963: {

3969:   MatPreallocated(mat);
3970:   if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3971:   return(0);
3972: }

3976: /*@
3977:    MatSetOption - Sets a parameter option for a matrix. Some options
3978:    may be specific to certain storage formats.  Some options
3979:    determine how values will be inserted (or added). Sorted, 
3980:    row-oriented input will generally assemble the fastest. The default
3981:    is row-oriented, nonsorted input. 

3983:    Collective on Mat

3985:    Input Parameters:
3986: +  mat - the matrix 
3987: -  option - the option, one of those listed below (and possibly others),
3988:              e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

3990:    Options Describing Matrix Structure:
3991: +    MAT_SYMMETRIC - symmetric in terms of both structure and value
3992: .    MAT_HERMITIAN - transpose is the complex conjugation
3993: .    MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
3994: .    MAT_NOT_SYMMETRIC - not symmetric in value
3995: .    MAT_NOT_HERMITIAN - transpose is not the complex conjugation
3996: .    MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure
3997: .    MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag
3998:                             you set to be kept with all future use of the matrix
3999:                             including after MatAssemblyBegin/End() which could
4000:                             potentially change the symmetry structure, i.e. you 
4001:                             KNOW the matrix will ALWAYS have the property you set.
4002: -    MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 
4003:                                 flags you set will be dropped (in case potentially
4004:                                 the symmetry etc was lost).

4006:    Options For Use with MatSetValues():
4007:    Insert a logically dense subblock, which can be
4008: +    MAT_ROW_ORIENTED - row-oriented (default)
4009: .    MAT_COLUMN_ORIENTED - column-oriented
4010: .    MAT_ROWS_SORTED - sorted by row
4011: .    MAT_ROWS_UNSORTED - not sorted by row (default)
4012: .    MAT_COLUMNS_SORTED - sorted by column
4013: -    MAT_COLUMNS_UNSORTED - not sorted by column (default)

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

4019:    When (re)assembling a matrix, we can restrict the input for
4020:    efficiency/debugging purposes.  These options include
4021: +    MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
4022:         allowed if they generate a new nonzero
4023: .    MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
4024: .    MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
4025:          they generate a nonzero in a new diagonal (for block diagonal format only)
4026: .    MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
4027: .    MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
4028: .    MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
4029: -    MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly

4031:    Notes:
4032:    Some options are relevant only for particular matrix types and
4033:    are thus ignored by others.  Other options are not supported by
4034:    certain matrix types and will generate an error message if set.

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

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

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

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

4059:    MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 
4060:    other processors should be dropped, rather than stashed.
4061:    This is useful if you know that the "owning" processor is also 
4062:    always generating the correct matrix entries, so that PETSc need
4063:    not transfer duplicate entries generated on another processor.
4064:    
4065:    MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
4066:    searches during matrix assembly. When this flag is set, the hash table
4067:    is created during the first Matrix Assembly. This hash table is
4068:    used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
4069:    to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 
4070:    should be used with MAT_USE_HASH_TABLE flag. This option is currently
4071:    supported by MATMPIBAIJ format only.

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

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

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

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

4085:    Level: intermediate

4087:    Concepts: matrices^setting options

4089: @*/
4090: PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op)
4091: {

4097:   MatPreallocated(mat);
4098:   switch (op) {
4099:   case MAT_SYMMETRIC:
4100:     mat->symmetric                  = PETSC_TRUE;
4101:     mat->structurally_symmetric     = PETSC_TRUE;
4102:     mat->symmetric_set              = PETSC_TRUE;
4103:     mat->structurally_symmetric_set = PETSC_TRUE;
4104:     break;
4105:   case MAT_HERMITIAN:
4106:     mat->hermitian                  = PETSC_TRUE;
4107:     mat->structurally_symmetric     = PETSC_TRUE;
4108:     mat->hermitian_set              = PETSC_TRUE;
4109:     mat->structurally_symmetric_set = PETSC_TRUE;
4110:     break;
4111:   case MAT_STRUCTURALLY_SYMMETRIC:
4112:     mat->structurally_symmetric     = PETSC_TRUE;
4113:     mat->structurally_symmetric_set = PETSC_TRUE;
4114:     break;
4115:   case MAT_NOT_SYMMETRIC:
4116:     mat->symmetric                  = PETSC_FALSE;
4117:     mat->symmetric_set              = PETSC_TRUE;
4118:     break;
4119:   case MAT_NOT_HERMITIAN:
4120:     mat->hermitian                  = PETSC_FALSE;
4121:     mat->hermitian_set              = PETSC_TRUE;
4122:     break;
4123:   case MAT_NOT_STRUCTURALLY_SYMMETRIC:
4124:     mat->structurally_symmetric     = PETSC_FALSE;
4125:     mat->structurally_symmetric_set = PETSC_TRUE;
4126:     break;
4127:   case MAT_SYMMETRY_ETERNAL:
4128:     mat->symmetric_eternal          = PETSC_TRUE;
4129:     break;
4130:   case MAT_NOT_SYMMETRY_ETERNAL:
4131:     mat->symmetric_eternal          = PETSC_FALSE;
4132:     break;
4133:   default:
4134:     break;
4135:   }
4136:   if (mat->ops->setoption) {
4137:     (*mat->ops->setoption)(mat,op);
4138:   }
4139:   return(0);
4140: }

4144: /*@
4145:    MatZeroEntries - Zeros all entries of a matrix.  For sparse matrices
4146:    this routine retains the old nonzero structure.

4148:    Collective on Mat

4150:    Input Parameters:
4151: .  mat - the matrix 

4153:    Level: intermediate

4155:    Concepts: matrices^zeroing

4157: .seealso: MatZeroRows()
4158: @*/
4159: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat)
4160: {

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

4171:   PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
4172:   (*mat->ops->zeroentries)(mat);
4173:   PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
4174:   PetscObjectStateIncrease((PetscObject)mat);
4175:   return(0);
4176: }

4180: /*@C
4181:    MatZeroRows - Zeros all entries (except possibly the main diagonal)
4182:    of a set of rows of a matrix.

4184:    Collective on Mat

4186:    Input Parameters:
4187: +  mat - the matrix
4188: .  numRows - the number of rows to remove
4189: .  rows - the global row indices
4190: -  diag - value put in all diagonals of eliminated rows

4192:    Notes:
4193:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4194:    but does not release memory.  For the dense and block diagonal
4195:    formats this does not alter the nonzero structure.

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

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

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

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

4212:    Level: intermediate

4214:    Concepts: matrices^zeroing rows

4216: .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4217: @*/
4218: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4219: {

4226:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4227:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4228:   if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4229:   MatPreallocated(mat);

4231:   (*mat->ops->zerorows)(mat,numRows,rows,diag);
4232:   MatView_Private(mat);
4233:   PetscObjectStateIncrease((PetscObject)mat);
4234:   return(0);
4235: }

4239: /*@C
4240:    MatZeroRowsIS - Zeros all entries (except possibly the main diagonal)
4241:    of a set of rows of a matrix.

4243:    Collective on Mat

4245:    Input Parameters:
4246: +  mat - the matrix
4247: .  is - index set of rows to remove
4248: -  diag - value put in all diagonals of eliminated rows

4250:    Notes:
4251:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4252:    but does not release memory.  For the dense and block diagonal
4253:    formats this does not alter the nonzero structure.

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

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

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

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

4270:    Level: intermediate

4272:    Concepts: matrices^zeroing rows

4274: .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4275: @*/
4276: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag)
4277: {
4278:   PetscInt       numRows;
4279:   PetscInt       *rows;

4286:   ISGetLocalSize(is,&numRows);
4287:   ISGetIndices(is,&rows);
4288:   MatZeroRows(mat,numRows,rows,diag);
4289:   ISRestoreIndices(is,&rows);
4290:   return(0);
4291: }

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

4299:    Collective on Mat

4301:    Input Parameters:
4302: +  mat - the matrix
4303: .  numRows - the number of rows to remove
4304: .  rows - the global row indices
4305: -  diag - value put in all diagonals of eliminated rows

4307:    Notes:
4308:    Before calling MatZeroRowsLocal(), the user must first set the
4309:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4311:    For the AIJ matrix formats this removes the old nonzero structure,
4312:    but does not release memory.  For the dense and block diagonal
4313:    formats this does not alter the nonzero structure.

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

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

4323:    Level: intermediate

4325:    Concepts: matrices^zeroing

4327: .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4328: @*/
4329: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4330: {

4337:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4338:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4339:   MatPreallocated(mat);

4341:   if (mat->ops->zerorowslocal) {
4342:     (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);
4343:   } else {
4344:     IS is, newis;
4345:     PetscInt *newRows;

4347:     if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
4348:     ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);
4349:     ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
4350:     ISGetIndices(newis,&newRows);
4351:     (*mat->ops->zerorows)(mat,numRows,newRows,diag);
4352:     ISRestoreIndices(newis,&newRows);
4353:     ISDestroy(newis);
4354:     ISDestroy(is);
4355:   }
4356:   PetscObjectStateIncrease((PetscObject)mat);
4357:   return(0);
4358: }

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

4366:    Collective on Mat

4368:    Input Parameters:
4369: +  mat - the matrix
4370: .  is - index set of rows to remove
4371: -  diag - value put in all diagonals of eliminated rows

4373:    Notes:
4374:    Before calling MatZeroRowsLocal(), the user must first set the
4375:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4377:    For the AIJ matrix formats this removes the old nonzero structure,
4378:    but does not release memory.  For the dense and block diagonal
4379:    formats this does not alter the nonzero structure.

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

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

4389:    Level: intermediate

4391:    Concepts: matrices^zeroing

4393: .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4394: @*/
4395: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag)
4396: {
4398:   PetscInt       numRows;
4399:   PetscInt       *rows;

4405:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4406:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4407:   MatPreallocated(mat);

4409:   ISGetLocalSize(is,&numRows);
4410:   ISGetIndices(is,&rows);
4411:   MatZeroRowsLocal(mat,numRows,rows,diag);
4412:   ISRestoreIndices(is,&rows);
4413:   return(0);
4414: }

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

4421:    Not Collective

4423:    Input Parameter:
4424: .  mat - the matrix

4426:    Output Parameters:
4427: +  m - the number of global rows
4428: -  n - the number of global columns

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

4432:    Level: beginner

4434:    Concepts: matrices^size

4436: .seealso: MatGetLocalSize()
4437: @*/
4438: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n)
4439: {
4442:   if (m) *m = mat->rmap.N;
4443:   if (n) *n = mat->cmap.N;
4444:   return(0);
4445: }

4449: /*@
4450:    MatGetLocalSize - Returns the number of rows and columns in a matrix
4451:    stored locally.  This information may be implementation dependent, so
4452:    use with care.

4454:    Not Collective

4456:    Input Parameters:
4457: .  mat - the matrix

4459:    Output Parameters:
4460: +  m - the number of local rows
4461: -  n - the number of local columns

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

4465:    Level: beginner

4467:    Concepts: matrices^local size

4469: .seealso: MatGetSize()
4470: @*/
4471: PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n)
4472: {
4477:   if (m) *m = mat->rmap.n;
4478:   if (n) *n = mat->cmap.n;
4479:   return(0);
4480: }

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

4490:    Not Collective

4492:    Input Parameters:
4493: .  mat - the matrix

4495:    Output Parameters:
4496: +  m - the global index of the first local row
4497: -  n - one more than the global index of the last local row

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

4501:    Level: beginner

4503:    Concepts: matrices^row ownership
4504: @*/
4505: PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n)
4506: {

4514:   MatPreallocated(mat);
4515:   if (m) *m = mat->rmap.rstart;
4516:   if (n) *n = mat->rmap.rend;
4517:   return(0);
4518: }

4522: /*@  
4523:    MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
4524:    Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 
4525:    to complete the factorization.

4527:    Collective on Mat

4529:    Input Parameters:
4530: +  mat - the matrix
4531: .  row - row permutation
4532: .  column - column permutation
4533: -  info - structure containing 
4534: $      levels - number of levels of fill.
4535: $      expected fill - as ratio of original fill.
4536: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
4537:                 missing diagonal entries)

4539:    Output Parameters:
4540: .  fact - new matrix that has been symbolically factored

4542:    Notes:
4543:    See the users manual for additional information about
4544:    choosing the fill factor for better efficiency.

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

4550:    Level: developer

4552:   Concepts: matrices^symbolic LU factorization
4553:   Concepts: matrices^factorization
4554:   Concepts: LU^symbolic factorization

4556: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4557:           MatGetOrdering(), MatFactorInfo

4559: @*/
4560: PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
4561: {

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

4578:   PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
4579:   (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
4580:   PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
4581:   return(0);
4582: }

4586: /*@  
4587:    MatICCFactorSymbolic - Performs symbolic incomplete
4588:    Cholesky factorization for a symmetric matrix.  Use 
4589:    MatCholeskyFactorNumeric() to complete the factorization.

4591:    Collective on Mat

4593:    Input Parameters:
4594: +  mat - the matrix
4595: .  perm - row and column permutation
4596: -  info - structure containing 
4597: $      levels - number of levels of fill.
4598: $      expected fill - as ratio of original fill.

4600:    Output Parameter:
4601: .  fact - the factored matrix

4603:    Notes:
4604:    Currently only no-fill factorization is supported.

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

4610:    Level: developer

4612:   Concepts: matrices^symbolic incomplete Cholesky factorization
4613:   Concepts: matrices^factorization
4614:   Concepts: Cholsky^symbolic factorization

4616: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
4617: @*/
4618: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
4619: {

4628:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4629:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels);
4630:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4631:   if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ICC",mat->type_name);
4632:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4633:   MatPreallocated(mat);

4635:   PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
4636:   (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
4637:   PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
4638:   return(0);
4639: }

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

4649:    Not Collective

4651:    Input Parameter:
4652: .  mat - the matrix

4654:    Output Parameter:
4655: .  v - the location of the values


4658:    Fortran Note:
4659:    This routine is used differently from Fortran, e.g.,
4660: .vb
4661:         Mat         mat
4662:         PetscScalar mat_array(1)
4663:         PetscOffset i_mat
4664:         PetscErrorCode ierr
4665:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4671:         [... other code ...]
4672:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4673: .ve

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

4678:    Level: advanced

4680:    Concepts: matrices^access array

4682: .seealso: MatRestoreArray(), MatGetArrayF90()
4683: @*/
4684: PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[])
4685: {

4692:   if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4693:   MatPreallocated(mat);
4694:   (*mat->ops->getarray)(mat,v);
4695:   return(0);
4696: }

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

4703:    Not Collective

4705:    Input Parameter:
4706: +  mat - the matrix
4707: -  v - the location of the values

4709:    Fortran Note:
4710:    This routine is used differently from Fortran, e.g.,
4711: .vb
4712:         Mat         mat
4713:         PetscScalar mat_array(1)
4714:         PetscOffset i_mat
4715:         PetscErrorCode ierr
4716:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4722:         [... other code ...]
4723:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4724: .ve

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

4729:    Level: advanced

4731: .seealso: MatGetArray(), MatRestoreArrayF90()
4732: @*/
4733: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[])
4734: {

4741: #if defined(PETSC_USE_DEBUG)
4742:   CHKMEMQ;
4743: #endif
4744:   if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4745:   (*mat->ops->restorearray)(mat,v);
4746:   PetscObjectStateIncrease((PetscObject)mat);
4747:   return(0);
4748: }

4752: /*@C
4753:    MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
4754:    points to an array of valid matrices, they may be reused to store the new
4755:    submatrices.

4757:    Collective on Mat

4759:    Input Parameters:
4760: +  mat - the matrix
4761: .  n   - the number of submatrixes to be extracted (on this processor, may be zero)
4762: .  irow, icol - index sets of rows and columns to extract
4763: -  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

4765:    Output Parameter:
4766: .  submat - the array of submatrices

4768:    Notes:
4769:    MatGetSubMatrices() can extract only sequential submatrices
4770:    (from both sequential and parallel matrices). Use MatGetSubMatrix()
4771:    to extract a parallel submatrix.

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

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

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

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

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

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

4795:    Level: advanced

4797:    Concepts: matrices^accessing submatrices
4798:    Concepts: submatrices

4800: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
4801: @*/
4802: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
4803: {
4805:   PetscInt        i;
4806:   PetscTruth      eq;

4811:   if (n) {
4816:   }
4818:   if (n && scall == MAT_REUSE_MATRIX) {
4821:   }
4822:   if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4823:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4824:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4825:   MatPreallocated(mat);

4827:   PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
4828:   (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
4829:   PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
4830:   for (i=0; i<n; i++) {
4831:     if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) {
4832:       ISEqual(irow[i],icol[i],&eq);
4833:       if (eq) {
4834:         if (mat->symmetric){
4835:           MatSetOption((*submat)[i],MAT_SYMMETRIC);
4836:         } else if (mat->hermitian) {
4837:           MatSetOption((*submat)[i],MAT_HERMITIAN);
4838:         } else if (mat->structurally_symmetric) {
4839:           MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);
4840:         }
4841:       }
4842:     }
4843:   }
4844:   return(0);
4845: }

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

4852:    Collective on Mat

4854:    Input Parameters:
4855: +  n - the number of local matrices
4856: -  mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
4857:                        sequence of MatGetSubMatrices())

4859:    Level: advanced

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

4863: .seealso: MatGetSubMatrices()
4864: @*/
4865: PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[])
4866: {
4868:   PetscInt       i;

4871:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n);
4873:   for (i=0; i<n; i++) {
4874:     MatDestroy((*mat)[i]);
4875:   }
4876:   /* memory is allocated even if n = 0 */
4877:   PetscFree(*mat);
4878:   return(0);
4879: }

4883: /*@
4884:    MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4885:    replaces the index sets by larger ones that represent submatrices with
4886:    additional overlap.

4888:    Collective on Mat

4890:    Input Parameters:
4891: +  mat - the matrix
4892: .  n   - the number of index sets
4893: .  is  - the array of index sets (these index sets will changed during the call)
4894: -  ov  - the additional overlap requested

4896:    Level: developer

4898:    Concepts: overlap
4899:    Concepts: ASM^computing overlap

4901: .seealso: MatGetSubMatrices()
4902: @*/
4903: PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov)
4904: {

4910:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n);
4911:   if (n) {
4914:   }
4915:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4916:   if (mat->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4917:   MatPreallocated(mat);

4919:   if (!ov) return(0);
4920:   if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4921:   PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
4922:   (*mat->ops->increaseoverlap)(mat,n,is,ov);
4923:   PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
4924:   return(0);
4925: }

4929: /*@
4930:    MatPrintHelp - Prints all the options for the matrix.

4932:    Collective on Mat

4934:    Input Parameter:
4935: .  mat - the matrix 

4937:    Options Database Keys:
4938: +  -help - Prints matrix options
4939: -  -h - Prints matrix options

4941:    Level: developer

4943: .seealso: MatCreate(), MatCreateXXX()
4944: @*/
4945: PetscErrorCode PETSCMAT_DLLEXPORT MatPrintHelp(Mat mat)
4946: {
4947:   static PetscTruth called = PETSC_FALSE;
4948:   PetscErrorCode    ierr;

4953:   MatPreallocated(mat);

4955:   if (!called) {
4956:     if (mat->ops->printhelp) {
4957:       (*mat->ops->printhelp)(mat);
4958:     }
4959:     called = PETSC_TRUE;
4960:   }
4961:   return(0);
4962: }

4966: /*@
4967:    MatGetBlockSize - Returns the matrix block size; useful especially for the
4968:    block row and block diagonal formats.
4969:    
4970:    Not Collective

4972:    Input Parameter:
4973: .  mat - the matrix

4975:    Output Parameter:
4976: .  bs - block size

4978:    Notes:
4979:    Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4980:    Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ

4982:    Level: intermediate

4984:    Concepts: matrices^block size

4986: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4987: @*/
4988: PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs)
4989: {

4996:   MatPreallocated(mat);
4997:   *bs = mat->rmap.bs;
4998:   return(0);
4999: }

5003: /*@
5004:    MatSetBlockSize - Sets the matrix block size; for many matrix types you 
5005:      cannot use this and MUST set the blocksize when you preallocate the matrix
5006:    
5007:    Not Collective

5009:    Input Parameters:
5010: +  mat - the matrix
5011: -  bs - block size

5013:    Notes:
5014:      Only works for shell and AIJ matrices

5016:    Level: intermediate

5018:    Concepts: matrices^block size

5020: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize()
5021: @*/
5022: PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs)
5023: {

5029:   MatPreallocated(mat);
5030:   if (mat->ops->setblocksize) {
5031:     mat->rmap.bs = bs;
5032:     (*mat->ops->setblocksize)(mat,bs);
5033:   } else {
5034:     SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name);
5035:   }
5036:   return(0);
5037: }

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

5044:    Collective on Mat

5046:     Input Parameters:
5047: +   mat - the matrix
5048: .   shift -  0 or 1 indicating we want the indices starting at 0 or 1
5049: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5050:                 symmetrized

5052:     Output Parameters:
5053: +   n - number of rows in the (possibly compressed) matrix
5054: .   ia - the row pointers
5055: .   ja - the column indices
5056: -   done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers
5057:            are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set

5059:     Level: developer

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

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

5065: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5066: @*/
5067: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5068: {

5078:   MatPreallocated(mat);
5079:   if (!mat->ops->getrowij) *done = PETSC_FALSE;
5080:   else {
5081:     *done = PETSC_TRUE;
5082:     (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
5083:   }
5084:   return(0);
5085: }

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

5092:     Collective on Mat

5094:     Input Parameters:
5095: +   mat - the matrix
5096: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5097: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5098:                 symmetrized

5100:     Output Parameters:
5101: +   n - number of columns in the (possibly compressed) matrix
5102: .   ia - the column pointers
5103: .   ja - the row indices
5104: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

5106:     Level: developer

5108: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5109: @*/
5110: PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5111: {

5121:   MatPreallocated(mat);
5122:   if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
5123:   else {
5124:     *done = PETSC_TRUE;
5125:     (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
5126:   }
5127:   return(0);
5128: }

5132: /*@C
5133:     MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
5134:     MatGetRowIJ().

5136:     Collective on Mat

5138:     Input Parameters:
5139: +   mat - the matrix
5140: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5141: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5142:                 symmetrized

5144:     Output Parameters:
5145: +   n - size of (possibly compressed) matrix
5146: .   ia - the row pointers
5147: .   ja - the column indices
5148: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

5150:     Level: developer

5152: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5153: @*/
5154: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5155: {

5164:   MatPreallocated(mat);

5166:   if (!mat->ops->restorerowij) *done = PETSC_FALSE;
5167:   else {
5168:     *done = PETSC_TRUE;
5169:     (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
5170:   }
5171:   return(0);
5172: }

5176: /*@C
5177:     MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
5178:     MatGetColumnIJ().

5180:     Collective on Mat

5182:     Input Parameters:
5183: +   mat - the matrix
5184: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
5185: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5186:                 symmetrized

5188:     Output Parameters:
5189: +   n - size of (possibly compressed) matrix
5190: .   ia - the column pointers
5191: .   ja - the row indices
5192: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

5194:     Level: developer

5196: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5197: @*/
5198: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5199: {

5208:   MatPreallocated(mat);

5210:   if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
5211:   else {
5212:     *done = PETSC_TRUE;
5213:     (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
5214:   }
5215:   return(0);
5216: }

5220: /*@C
5221:     MatColoringPatch -Used inside matrix coloring routines that 
5222:     use MatGetRowIJ() and/or MatGetColumnIJ().

5224:     Collective on Mat

5226:     Input Parameters:
5227: +   mat - the matrix
5228: .   ncolors - max color value
5229: .   n   - number of entries in colorarray
5230: -   colorarray - array indicating color for each column

5232:     Output Parameters:
5233: .   iscoloring - coloring generated using colorarray information

5235:     Level: developer

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

5239: @*/
5240: PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring)
5241: {

5249:   MatPreallocated(mat);

5251:   if (!mat->ops->coloringpatch){
5252:     ISColoringCreate(mat->comm,ncolors,n,colorarray,iscoloring);
5253:   } else {
5254:     (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);
5255:   }
5256:   return(0);
5257: }


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

5265:    Collective on Mat

5267:    Input Parameter:
5268: .  mat - the factored matrix to be reset

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

5277:    Note that one can specify in-place ILU(0) factorization by calling 
5278: .vb
5279:      PCType(pc,PCILU);
5280:      PCFactorSeUseInPlace(pc);
5281: .ve
5282:    or by using the options -pc_type ilu -pc_factor_in_place

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

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

5294:    Level: developer

5296: .seealso: PCFactorSetUseInPlace()

5298:    Concepts: matrices^unfactored

5300: @*/
5301: PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat)
5302: {

5308:   MatPreallocated(mat);
5309:   mat->factor = 0;
5310:   if (!mat->ops->setunfactored) return(0);
5311:   (*mat->ops->setunfactored)(mat);
5312:   return(0);
5313: }

5315: /*MC
5316:     MatGetArrayF90 - Accesses a matrix array from Fortran90.

5318:     Synopsis:
5319:     MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5321:     Not collective

5323:     Input Parameter:
5324: .   x - matrix

5326:     Output Parameters:
5327: +   xx_v - the Fortran90 pointer to the array
5328: -   ierr - error code

5330:     Example of Usage: 
5331: .vb
5332:       PetscScalar, pointer xx_v(:)
5333:       ....
5334:       call MatGetArrayF90(x,xx_v,ierr)
5335:       a = xx_v(3)
5336:       call MatRestoreArrayF90(x,xx_v,ierr)
5337: .ve

5339:     Notes:
5340:     Not yet supported for all F90 compilers

5342:     Level: advanced

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

5346:     Concepts: matrices^accessing array

5348: M*/

5350: /*MC
5351:     MatRestoreArrayF90 - Restores a matrix array that has been
5352:     accessed with MatGetArrayF90().

5354:     Synopsis:
5355:     MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5357:     Not collective

5359:     Input Parameters:
5360: +   x - matrix
5361: -   xx_v - the Fortran90 pointer to the array

5363:     Output Parameter:
5364: .   ierr - error code

5366:     Example of Usage: 
5367: .vb
5368:        PetscScalar, pointer xx_v(:)
5369:        ....
5370:        call MatGetArrayF90(x,xx_v,ierr)
5371:        a = xx_v(3)
5372:        call MatRestoreArrayF90(x,xx_v,ierr)
5373: .ve
5374:    
5375:     Notes:
5376:     Not yet supported for all F90 compilers

5378:     Level: advanced

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

5382: M*/


5387: /*@
5388:     MatGetSubMatrix - Gets a single submatrix on the same number of processors
5389:                       as the original matrix.

5391:     Collective on Mat

5393:     Input Parameters:
5394: +   mat - the original matrix
5395: .   isrow - rows this processor should obtain
5396: .   iscol - columns for all processors you wish to keep
5397: .   csize - number of columns "local" to this processor (does nothing for sequential 
5398:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
5399:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5400: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

5402:     Output Parameter:
5403: .   newmat - the new submatrix, of the same type as the old

5405:     Level: advanced

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

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

5415:     Concepts: matrices^submatrices

5417: .seealso: MatGetSubMatrices(), ISAllGather()
5418: @*/
5419: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat)
5420: {
5422:   PetscMPIInt    size;
5423:   Mat            *local;

5432:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5433:   MatPreallocated(mat);
5434:   MPI_Comm_size(mat->comm,&size);

5436:   /* if original matrix is on just one processor then use submatrix generated */
5437:   if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
5438:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
5439:     return(0);
5440:   } else if (!mat->ops->getsubmatrix && size == 1) {
5441:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
5442:     *newmat = *local;
5443:     PetscFree(local);
5444:     return(0);
5445:   }

5447:   if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5448:   (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
5449:   PetscObjectStateIncrease((PetscObject)*newmat);
5450:   return(0);
5451: }

5455: /*@
5456:     MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors
5457:                          as the original matrix.

5459:     Collective on Mat

5461:     Input Parameters:
5462: +   mat - the original matrix
5463: .   nrows - the number of rows this processor should obtain
5464: .   rows - rows this processor should obtain
5465: .   ncols - the number of columns for all processors you wish to keep
5466: .   cols - columns for all processors you wish to keep
5467: .   csize - number of columns "local" to this processor (does nothing for sequential 
5468:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
5469:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5470: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

5472:     Output Parameter:
5473: .   newmat - the new submatrix, of the same type as the old

5475:     Level: advanced

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

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

5485:     Concepts: matrices^submatrices

5487: .seealso: MatGetSubMatrices(), ISAllGather()
5488: @*/
5489: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat)
5490: {
5491:   IS             isrow, iscol;

5501:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5502:   MatPreallocated(mat);
5503:   ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);
5504:   ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);
5505:   MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);
5506:   ISDestroy(isrow);
5507:   ISDestroy(iscol);
5508:   return(0);
5509: }

5513: /*@
5514:    MatStashSetInitialSize - sets the sizes of the matrix stash, that is
5515:    used during the assembly process to store values that belong to 
5516:    other processors.

5518:    Not Collective

5520:    Input Parameters:
5521: +  mat   - the matrix
5522: .  size  - the initial size of the stash.
5523: -  bsize - the initial size of the block-stash(if used).

5525:    Options Database Keys:
5526: +   -matstash_initial_size <size> or <size0,size1,...sizep-1>
5527: -   -matstash_block_initial_size <bsize>  or <bsize0,bsize1,...bsizep-1>

5529:    Level: intermediate

5531:    Notes: 
5532:      The block-stash is used for values set with MatSetValuesBlocked() while
5533:      the stash is used for values set with MatSetValues()

5535:      Run with the option -info and look for output of the form
5536:      MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
5537:      to determine the appropriate value, MM, to use for size and 
5538:      MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
5539:      to determine the value, BMM to use for bsize

5541:    Concepts: stash^setting matrix size
5542:    Concepts: matrices^stash

5544: @*/
5545: PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize)
5546: {

5552:   MatStashSetInitialSize_Private(&mat->stash,size);
5553:   MatStashSetInitialSize_Private(&mat->bstash,bsize);
5554:   return(0);
5555: }

5559: /*@
5560:    MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 
5561:      the matrix

5563:    Collective on Mat

5565:    Input Parameters:
5566: +  mat   - the matrix
5567: .  x,y - the vectors
5568: -  w - where the result is stored

5570:    Level: intermediate

5572:    Notes: 
5573:     w may be the same vector as y. 

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

5578:     Concepts: interpolation

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

5582: @*/
5583: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
5584: {
5586:   PetscInt       M,N;

5594:   MatPreallocated(A);
5595:   MatGetSize(A,&M,&N);
5596:   if (N > M) {
5597:     MatMultTransposeAdd(A,x,y,w);
5598:   } else {
5599:     MatMultAdd(A,x,y,w);
5600:   }
5601:   return(0);
5602: }

5606: /*@
5607:    MatInterpolate - y = A*x or A'*x depending on the shape of 
5608:      the matrix

5610:    Collective on Mat

5612:    Input Parameters:
5613: +  mat   - the matrix
5614: -  x,y - the vectors

5616:    Level: intermediate

5618:    Notes: 
5619:     This allows one to use either the restriction or interpolation (its transpose)
5620:     matrix to do the interpolation

5622:    Concepts: matrices^interpolation

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

5626: @*/
5627: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y)
5628: {
5630:   PetscInt       M,N;

5637:   MatPreallocated(A);
5638:   MatGetSize(A,&M,&N);
5639:   if (N > M) {
5640:     MatMultTranspose(A,x,y);
5641:   } else {
5642:     MatMult(A,x,y);
5643:   }
5644:   return(0);
5645: }

5649: /*@
5650:    MatRestrict - y = A*x or A'*x

5652:    Collective on Mat

5654:    Input Parameters:
5655: +  mat   - the matrix
5656: -  x,y - the vectors

5658:    Level: intermediate

5660:    Notes: 
5661:     This allows one to use either the restriction or interpolation (its transpose)
5662:     matrix to do the restriction

5664:    Concepts: matrices^restriction

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

5668: @*/
5669: PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y)
5670: {
5672:   PetscInt       M,N;

5679:   MatPreallocated(A);

5681:   MatGetSize(A,&M,&N);
5682:   if (N > M) {
5683:     MatMult(A,x,y);
5684:   } else {
5685:     MatMultTranspose(A,x,y);
5686:   }
5687:   return(0);
5688: }

5692: /*@C
5693:    MatNullSpaceAttach - attaches a null space to a matrix.
5694:         This null space will be removed from the resulting vector whenever
5695:         MatMult() is called

5697:    Collective on Mat

5699:    Input Parameters:
5700: +  mat - the matrix
5701: -  nullsp - the null space object

5703:    Level: developer

5705:    Notes:
5706:       Overwrites any previous null space that may have been attached

5708:    Concepts: null space^attaching to matrix

5710: .seealso: MatCreate(), MatNullSpaceCreate()
5711: @*/
5712: PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
5713: {

5720:   MatPreallocated(mat);

5722:   if (mat->nullsp) {
5723:     MatNullSpaceDestroy(mat->nullsp);
5724:   }
5725:   mat->nullsp = nullsp;
5726:   PetscObjectReference((PetscObject)nullsp);
5727:   return(0);
5728: }

5732: /*@  
5733:    MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.

5735:    Collective on Mat

5737:    Input Parameters:
5738: +  mat - the matrix
5739: .  row - row/column permutation
5740: .  fill - expected fill factor >= 1.0
5741: -  level - level of fill, for ICC(k)

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

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

5751:    Level: developer

5753:    Concepts: matrices^incomplete Cholesky factorization
5754:    Concepts: Cholesky factorization

5756: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
5757: @*/
5758: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
5759: {

5767:   if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
5768:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
5769:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5770:   if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5771:   MatPreallocated(mat);
5772:   (*mat->ops->iccfactor)(mat,row,info);
5773:   PetscObjectStateIncrease((PetscObject)mat);
5774:   return(0);
5775: }

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

5782:    Not Collective

5784:    Input Parameters:
5785: +  mat - the matrix
5786: -  v - the values compute with ADIC

5788:    Level: developer

5790:    Notes:
5791:      Must call MatSetColoring() before using this routine. Also this matrix must already
5792:      have its nonzero pattern determined.

5794: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5795:           MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
5796: @*/
5797: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v)
5798: {


5806:   if (!mat->assembled) {
5807:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5808:   }
5809:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5810:   if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5811:   (*mat->ops->setvaluesadic)(mat,v);
5812:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5813:   MatView_Private(mat);
5814:   PetscObjectStateIncrease((PetscObject)mat);
5815:   return(0);
5816: }


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

5824:    Not Collective

5826:    Input Parameters:
5827: +  mat - the matrix
5828: -  coloring - the coloring

5830:    Level: developer

5832: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5833:           MatSetValues(), MatSetValuesAdic()
5834: @*/
5835: PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring)
5836: {


5844:   if (!mat->assembled) {
5845:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5846:   }
5847:   if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5848:   (*mat->ops->setcoloring)(mat,coloring);
5849:   return(0);
5850: }

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

5857:    Not Collective

5859:    Input Parameters:
5860: +  mat - the matrix
5861: .  nl - leading dimension of v
5862: -  v - the values compute with ADIFOR

5864:    Level: developer

5866:    Notes:
5867:      Must call MatSetColoring() before using this routine. Also this matrix must already
5868:      have its nonzero pattern determined.

5870: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5871:           MatSetValues(), MatSetColoring()
5872: @*/
5873: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v)
5874: {


5882:   if (!mat->assembled) {
5883:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5884:   }
5885:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5886:   if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5887:   (*mat->ops->setvaluesadifor)(mat,nl,v);
5888:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5889:   PetscObjectStateIncrease((PetscObject)mat);
5890:   return(0);
5891: }

5895: /*@ 
5896:    MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 
5897:          ghosted ones.

5899:    Not Collective

5901:    Input Parameters:
5902: +  mat - the matrix
5903: -  diag = the diagonal values, including ghost ones

5905:    Level: developer

5907:    Notes: Works only for MPIAIJ and MPIBAIJ matrices
5908:       
5909: .seealso: MatDiagonalScale()
5910: @*/
5911: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag)
5912: {
5914:   PetscMPIInt    size;


5921:   if (!mat->assembled) {
5922:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5923:   }
5924:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
5925:   MPI_Comm_size(mat->comm,&size);
5926:   if (size == 1) {
5927:     PetscInt n,m;
5928:     VecGetSize(diag,&n);
5929:     MatGetSize(mat,0,&m);
5930:     if (m == n) {
5931:       MatDiagonalScale(mat,0,diag);
5932:     } else {
5933:       SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions");
5934:     }
5935:   } else {
5936:     PetscErrorCode (*f)(Mat,Vec);
5937:     PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
5938:     if (f) {
5939:       (*f)(mat,diag);
5940:     } else {
5941:       SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
5942:     }
5943:   }
5944:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
5945:   PetscObjectStateIncrease((PetscObject)mat);
5946:   return(0);
5947: }

5951: /*@ 
5952:    MatGetInertia - Gets the inertia from a factored matrix

5954:    Collective on Mat

5956:    Input Parameter:
5957: .  mat - the matrix

5959:    Output Parameters:
5960: +   nneg - number of negative eigenvalues
5961: .   nzero - number of zero eigenvalues
5962: -   npos - number of positive eigenvalues

5964:    Level: advanced

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


5969: @*/
5970: PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos)
5971: {

5977:   if (!mat->factor)    SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5978:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5979:   if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5980:   (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5981:   return(0);
5982: }

5984: /* ----------------------------------------------------------------*/
5987: /*@
5988:    MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors

5990:    Collective on Mat and Vecs

5992:    Input Parameters:
5993: +  mat - the factored matrix
5994: -  b - the right-hand-side vectors

5996:    Output Parameter:
5997: .  x - the result vectors

5999:    Notes:
6000:    The vectors b and x cannot be the same.  I.e., one cannot
6001:    call MatSolves(A,x,x).

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

6008:    Level: developer

6010:    Concepts: matrices^triangular solves

6012: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
6013: @*/
6014: PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x)
6015: {

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

6025:   if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
6026:   MatPreallocated(mat);
6027:   PetscLogEventBegin(MAT_Solves,mat,0,0,0);
6028:   (*mat->ops->solves)(mat,b,x);
6029:   PetscLogEventEnd(MAT_Solves,mat,0,0,0);
6030:   return(0);
6031: }

6035: /*@
6036:    MatIsSymmetric - Test whether a matrix is symmetric

6038:    Collective on Mat

6040:    Input Parameter:
6041: +  A - the matrix to test
6042: -  tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose)

6044:    Output Parameters:
6045: .  flg - the result

6047:    Level: intermediate

6049:    Concepts: matrix^symmetry

6051: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown()
6052: @*/
6053: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg)
6054: {

6060:   if (!A->symmetric_set) {
6061:     if (!A->ops->issymmetric) {
6062:       MatType mattype;
6063:       MatGetType(A,&mattype);
6064:       SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype);
6065:     }
6066:     (*A->ops->issymmetric)(A,tol,&A->symmetric);
6067:     A->symmetric_set = PETSC_TRUE;
6068:     if (A->symmetric) {
6069:       A->structurally_symmetric_set = PETSC_TRUE;
6070:       A->structurally_symmetric     = PETSC_TRUE;
6071:     }
6072:   }
6073:   *flg = A->symmetric;
6074:   return(0);
6075: }

6079: /*@
6080:    MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric.

6082:    Collective on Mat

6084:    Input Parameter:
6085: .  A - the matrix to check

6087:    Output Parameters:
6088: +  set - if the symmetric flag is set (this tells you if the next flag is valid)
6089: -  flg - the result

6091:    Level: advanced

6093:    Concepts: matrix^symmetry

6095:    Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric()
6096:          if you want it explicitly checked

6098: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6099: @*/
6100: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6101: {
6106:   if (A->symmetric_set) {
6107:     *set = PETSC_TRUE;
6108:     *flg = A->symmetric;
6109:   } else {
6110:     *set = PETSC_FALSE;
6111:   }
6112:   return(0);
6113: }

6117: /*@
6118:    MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian.

6120:    Collective on Mat

6122:    Input Parameter:
6123: .  A - the matrix to check

6125:    Output Parameters:
6126: +  set - if the hermitian flag is set (this tells you if the next flag is valid)
6127: -  flg - the result

6129:    Level: advanced

6131:    Concepts: matrix^symmetry

6133:    Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian()
6134:          if you want it explicitly checked

6136: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6137: @*/
6138: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6139: {
6144:   if (A->hermitian_set) {
6145:     *set = PETSC_TRUE;
6146:     *flg = A->hermitian;
6147:   } else {
6148:     *set = PETSC_FALSE;
6149:   }
6150:   return(0);
6151: }

6155: /*@
6156:    MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric

6158:    Collective on Mat

6160:    Input Parameter:
6161: .  A - the matrix to test

6163:    Output Parameters:
6164: .  flg - the result

6166:    Level: intermediate

6168:    Concepts: matrix^symmetry

6170: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption()
6171: @*/
6172: PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg)
6173: {

6179:   if (!A->structurally_symmetric_set) {
6180:     if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric");
6181:     (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);
6182:     A->structurally_symmetric_set = PETSC_TRUE;
6183:   }
6184:   *flg = A->structurally_symmetric;
6185:   return(0);
6186: }

6190: /*@
6191:    MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose.

6193:    Collective on Mat

6195:    Input Parameter:
6196: .  A - the matrix to test

6198:    Output Parameters:
6199: .  flg - the result

6201:    Level: intermediate

6203:    Concepts: matrix^symmetry

6205: .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption()
6206: @*/
6207: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg)
6208: {

6214:   if (!A->hermitian_set) {
6215:     if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian");
6216:     (*A->ops->ishermitian)(A,&A->hermitian);
6217:     A->hermitian_set = PETSC_TRUE;
6218:     if (A->hermitian) {
6219:       A->structurally_symmetric_set = PETSC_TRUE;
6220:       A->structurally_symmetric     = PETSC_TRUE;
6221:     }
6222:   }
6223:   *flg = A->hermitian;
6224:   return(0);
6225: }

6230: /*@ 
6231:    MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
6232:        to be communicated to other processors during the MatAssemblyBegin/End() process

6234:     Not collective

6236:    Input Parameter:
6237: .   vec - the vector

6239:    Output Parameters:
6240: +   nstash   - the size of the stash
6241: .   reallocs - the number of additional mallocs incurred.
6242: .   bnstash   - the size of the block stash
6243: -   breallocs - the number of additional mallocs incurred.in the block stash
6244:  
6245:    Level: advanced

6247: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize()
6248:   
6249: @*/
6250: PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
6251: {
6254:   MatStashGetInfo_Private(&mat->stash,nstash,reallocs);
6255:   MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);
6256:   return(0);
6257: }

6261: /*@
6262:    MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 
6263:      parallel layout
6264:    
6265:    Collective on Mat

6267:    Input Parameter:
6268: .  mat - the matrix

6270:    Output Parameter:
6271: +   right - (optional) vector that the matrix can be multiplied against
6272: -   left - (optional) vector that the matrix vector product can be stored in

6274:   Level: advanced

6276: .seealso: MatCreate()
6277: @*/
6278: PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left)
6279: {

6285:   MatPreallocated(mat);
6286:   if (mat->ops->getvecs) {
6287:     (*mat->ops->getvecs)(mat,right,left);
6288:   } else {
6289:     PetscMPIInt size;
6290:     MPI_Comm_size(mat->comm, &size);
6291:     if (right) {
6292:       VecCreate(mat->comm,right);
6293:       VecSetSizes(*right,mat->cmap.n,PETSC_DETERMINE);
6294:       if (size > 1) {VecSetType(*right,VECMPI);}
6295:       else {VecSetType(*right,VECSEQ);}
6296:     }
6297:     if (left) {
6298:       VecCreate(mat->comm,left);
6299:       VecSetSizes(*left,mat->rmap.n,PETSC_DETERMINE);
6300:       if (size > 1) {VecSetType(*left,VECMPI);}
6301:       else {VecSetType(*left,VECSEQ);}
6302:     }
6303:   }
6304:   if (right) {VecSetBlockSize(*right,mat->rmap.bs);}
6305:   if (left) {VecSetBlockSize(*left,mat->rmap.bs);}
6306:   return(0);
6307: }

6311: /*@
6312:    MatFactorInfoInitialize - Initializes a MatFactorInfo data structure
6313:      with default values.

6315:    Not Collective

6317:    Input Parameters:
6318: .    info - the MatFactorInfo data structure


6321:    Notes: The solvers are generally used through the KSP and PC objects, for example
6322:           PCLU, PCILU, PCCHOLESKY, PCICC

6324:    Level: developer

6326: .seealso: MatFactorInfo
6327: @*/

6329: PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info)
6330: {

6334:   PetscMemzero(info,sizeof(MatFactorInfo));
6335:   return(0);
6336: }

6340: /*@
6341:    MatPtAP - Creates the matrix projection C = P^T * A * P

6343:    Collective on Mat

6345:    Input Parameters:
6346: +  A - the matrix
6347: .  P - the projection matrix
6348: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6349: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P))

6351:    Output Parameters:
6352: .  C - the product matrix

6354:    Notes:
6355:    C will be created and must be destroyed by the user with MatDestroy().

6357:    This routine is currently only implemented for pairs of AIJ matrices and classes
6358:    which inherit from AIJ.  

6360:    Level: intermediate

6362: .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult()
6363: @*/
6364: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C)
6365: {

6371:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6372:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6375:   MatPreallocated(P);
6376:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6377:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6379:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6380:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6381:   MatPreallocated(A);

6383:   PetscLogEventBegin(MAT_PtAP,A,P,0,0);
6384:   (*A->ops->ptap)(A,P,scall,fill,C);
6385:   PetscLogEventEnd(MAT_PtAP,A,P,0,0);

6387:   return(0);
6388: }

6392: /*@
6393:    MatPtAPNumeric - Computes the matrix projection C = P^T * A * P

6395:    Collective on Mat

6397:    Input Parameters:
6398: +  A - the matrix
6399: -  P - the projection matrix

6401:    Output Parameters:
6402: .  C - the product matrix

6404:    Notes:
6405:    C must have been created by calling MatPtAPSymbolic and must be destroyed by
6406:    the user using MatDeatroy().

6408:    This routine is currently only implemented for pairs of AIJ matrices and classes
6409:    which inherit from AIJ.  C will be of type MATAIJ.

6411:    Level: intermediate

6413: .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric()
6414: @*/
6415: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C)
6416: {

6422:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6423:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6426:   MatPreallocated(P);
6427:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6428:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6431:   MatPreallocated(C);
6432:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6433:   if (P->cmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->rmap.N);
6434:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6435:   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);
6436:   if (P->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->cmap.N);
6437:   MatPreallocated(A);

6439:   PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);
6440:   (*A->ops->ptapnumeric)(A,P,C);
6441:   PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);
6442:   return(0);
6443: }

6447: /*@
6448:    MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P

6450:    Collective on Mat

6452:    Input Parameters:
6453: +  A - the matrix
6454: -  P - the projection matrix

6456:    Output Parameters:
6457: .  C - the (i,j) structure of the product matrix

6459:    Notes:
6460:    C will be created and must be destroyed by the user with MatDestroy().

6462:    This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6463:    which inherit from SeqAIJ.  C will be of type MATSEQAIJ.  The product is computed using
6464:    this (i,j) structure by calling MatPtAPNumeric().

6466:    Level: intermediate

6468: .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic()
6469: @*/
6470: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C)
6471: {

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(P);
6482:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6483:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6486:   if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6487:   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);
6488:   MatPreallocated(A);
6489:   PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);
6490:   (*A->ops->ptapsymbolic)(A,P,fill,C);
6491:   PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);

6493:   MatSetBlockSize(*C,A->rmap.bs);

6495:   return(0);
6496: }

6500: /*@
6501:    MatMatMult - Performs Matrix-Matrix Multiplication C=A*B.

6503:    Collective on Mat

6505:    Input Parameters:
6506: +  A - the left matrix
6507: .  B - the right matrix
6508: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6509: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6511:    Output Parameters:
6512: .  C - the product matrix

6514:    Notes:
6515:    C will be created and must be destroyed by the user with MatDestroy().
6516:    Unless scall is MAT_REUSE_MATRIX

6518:    This routine is currently only implemented for pairs of AIJ matrices and classes
6519:    which inherit from AIJ.  C will be of type MATAIJ.

6521:    Level: intermediate

6523: .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP()
6524: @*/
6525: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6526: {
6528:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6529:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);

6534:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6535:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6538:   MatPreallocated(B);
6539:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6540:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6542:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6543:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6544:   MatPreallocated(A);

6546:   /* For now, we do not dispatch based on the type of A and B */
6547:   /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6548:   fA = A->ops->matmult;
6549:   if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for A of type %s",A->type_name);
6550:   fB = B->ops->matmult;
6551:   if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name);
6552:   if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6554:   PetscLogEventBegin(MAT_MatMult,A,B,0,0);
6555:   (*A->ops->matmult)(A,B,scall,fill,C);
6556:   PetscLogEventEnd(MAT_MatMult,A,B,0,0);
6557: 
6558:   return(0);
6559: }

6563: /*@
6564:    MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure
6565:    of the matrix-matrix product C=A*B.  Call this routine before calling MatMatMultNumeric().

6567:    Collective on Mat

6569:    Input Parameters:
6570: +  A - the left matrix
6571: .  B - the right matrix
6572: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6574:    Output Parameters:
6575: .  C - the matrix containing the ij structure of product matrix

6577:    Notes:
6578:    C will be created as a MATSEQAIJ matrix and must be destroyed by the user with MatDestroy().

6580:    This routine is currently only implemented for SeqAIJ matrices and classes which inherit from SeqAIJ.

6582:    Level: intermediate

6584: .seealso: MatMatMult(), MatMatMultNumeric()
6585: @*/
6586: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C)
6587: {
6589:   PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *);
6590:   PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *);

6595:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6596:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6600:   MatPreallocated(B);
6601:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6602:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6605:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6606:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6607:   MatPreallocated(A);

6609:   /* For now, we do not dispatch based on the type of A and P */
6610:   /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6611:   Asymbolic = A->ops->matmultsymbolic;
6612:   if (!Asymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for A of type %s",A->type_name);
6613:   Bsymbolic = B->ops->matmultsymbolic;
6614:   if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name);
6615:   if (Bsymbolic!=Asymbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6617:   PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);
6618:   (*Asymbolic)(A,B,fill,C);
6619:   PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);

6621:   return(0);
6622: }

6626: /*@
6627:    MatMatMultNumeric - Performs the numeric matrix-matrix product.
6628:    Call this routine after first calling MatMatMultSymbolic().

6630:    Collective on Mat

6632:    Input Parameters:
6633: +  A - the left matrix
6634: -  B - the right matrix

6636:    Output Parameters:
6637: .  C - the product matrix, whose ij structure was defined from MatMatMultSymbolic().

6639:    Notes:
6640:    C must have been created with MatMatMultSymbolic.

6642:    This routine is currently only implemented for SeqAIJ type matrices.

6644:    Level: intermediate

6646: .seealso: MatMatMult(), MatMatMultSymbolic()
6647: @*/
6648: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C)
6649: {
6651:   PetscErrorCode (*Anumeric)(Mat,Mat,Mat);
6652:   PetscErrorCode (*Bnumeric)(Mat,Mat,Mat);


6658:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6659:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6663:   MatPreallocated(B);
6664:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6665:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6669:   MatPreallocated(C);
6670:   if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6671:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6673:   if (B->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap.N,C->cmap.N);
6674:   if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6675:   if (A->rmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap.N,C->rmap.N);
6676:   MatPreallocated(A);

6678:   /* For now, we do not dispatch based on the type of A and B */
6679:   /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6680:   Anumeric = A->ops->matmultnumeric;
6681:   if (!Anumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for A of type %s",A->type_name);
6682:   Bnumeric = B->ops->matmultnumeric;
6683:   if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name);
6684:   if (Bnumeric!=Anumeric) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6686:   PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);
6687:   (*Anumeric)(A,B,C);
6688:   PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);

6690:   return(0);
6691: }

6695: /*@
6696:    MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B.

6698:    Collective on Mat

6700:    Input Parameters:
6701: +  A - the left matrix
6702: .  B - the right matrix
6703: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6704: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6706:    Output Parameters:
6707: .  C - the product matrix

6709:    Notes:
6710:    C will be created and must be destroyed by the user with MatDestroy().

6712:    This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6713:    which inherit from SeqAIJ.  C will be of type MATSEQAIJ.

6715:    Level: intermediate

6717: .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP()
6718: @*/
6719: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6720: {
6722:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6723:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);

6728:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6729:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6732:   MatPreallocated(B);
6733:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6734:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6736:   if (B->rmap.N!=A->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->rmap.N);
6737:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6738:   MatPreallocated(A);

6740:   fA = A->ops->matmulttranspose;
6741:   if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name);
6742:   fB = B->ops->matmulttranspose;
6743:   if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name);
6744:   if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6746:   PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);
6747:   (*A->ops->matmulttranspose)(A,B,scall,fill,C);
6748:   PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);
6749: 
6750:   return(0);
6751: }