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 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;
 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: /*@C
 32:    MatGetRow - Gets a row of a matrix.  You MUST call MatRestoreRow()
 33:    for each row that you get to ensure that your application does
 34:    not bleed memory.

 36:    Not Collective

 38:    Input Parameters:
 39: +  mat - the matrix
 40: -  row - the row to get

 42:    Output Parameters:
 43: +  ncols -  if not NULL, the number of nonzeros in the row
 44: .  cols - if not NULL, the column numbers
 45: -  vals - if not NULL, the values

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

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

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

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

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

 69:    Fortran Notes:
 70:    The calling sequence from Fortran is 
 71: .vb
 72:    MatGetRow(matrix,row,ncols,cols,values,ierr)
 73:          Mat     matrix (input)
 74:          integer row    (input)
 75:          integer ncols  (output)
 76:          integer cols(maxcols) (output)
 77:          double precision (or double complex) values(maxcols) output
 78: .ve
 79:    where maxcols >= maximum nonzeros in any row of the matrix.


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

 86:    Level: advanced

 88:    Concepts: matrices^row access

 90: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
 91: @*/

 93: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
 94: {
 96:   PetscInt       incols;

101:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
102:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
103:   if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
104:   MatPreallocated(mat);
105:   PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
106:   (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);
107:   if (ncols) *ncols = incols;
108:   PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
109:   return(0);
110: }

114: /*@
115:    MatConjugate - replaces the matrix values with their complex conjugates

117:    Collective on Mat

119:    Input Parameters:
120: .  mat - the matrix

122:    Level: advanced

124: .seealso:  VecConjugate()
125: @*/
126: PetscErrorCode PETSCMAT_DLLEXPORT MatConjugate(Mat mat)
127: {

132:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
133:   if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov");
134:   (*mat->ops->conjugate)(mat);
135:   return(0);
136: }

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

143:    Not Collective

145:    Input Parameters:
146: +  mat - the matrix
147: .  row - the row to get
148: .  ncols, cols - the number of nonzeros and their columns
149: -  vals - if nonzero the column values

151:    Notes: 
152:    This routine should be called after you have finished examining the entries.

154:    Fortran Notes:
155:    The calling sequence from Fortran is 
156: .vb
157:    MatRestoreRow(matrix,row,ncols,cols,values,ierr)
158:       Mat     matrix (input)
159:       integer row    (input)
160:       integer ncols  (output)
161:       integer cols(maxcols) (output)
162:       double precision (or double complex) values(maxcols) output
163: .ve
164:    Where maxcols >= maximum nonzeros in any row of the matrix. 

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

169:    Level: advanced

171: .seealso:  MatGetRow()
172: @*/
173: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
174: {

180:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
181:   if (!mat->ops->restorerow) return(0);
182:   (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);
183:   return(0);
184: }

188: /*@C
189:    MatSetOptionsPrefix - Sets the prefix used for searching for all 
190:    Mat options in the database.

192:    Collective on Mat

194:    Input Parameter:
195: +  A - the Mat context
196: -  prefix - the prefix to prepend to all option names

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

202:    Level: advanced

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

206: .seealso: MatSetFromOptions()
207: @*/
208: PetscErrorCode PETSCMAT_DLLEXPORT MatSetOptionsPrefix(Mat A,const char prefix[])
209: {

214:   PetscObjectSetOptionsPrefix((PetscObject)A,prefix);
215:   return(0);
216: }

220: /*@C
221:    MatAppendOptionsPrefix - Appends to the prefix used for searching for all 
222:    Mat options in the database.

224:    Collective on Mat

226:    Input Parameters:
227: +  A - the Mat context
228: -  prefix - the prefix to prepend to all option names

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

234:    Level: advanced

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

238: .seealso: MatGetOptionsPrefix()
239: @*/
240: PetscErrorCode PETSCMAT_DLLEXPORT MatAppendOptionsPrefix(Mat A,const char prefix[])
241: {
243: 
246:   PetscObjectAppendOptionsPrefix((PetscObject)A,prefix);
247:   return(0);
248: }

252: /*@C
253:    MatGetOptionsPrefix - Sets the prefix used for searching for all 
254:    Mat options in the database.

256:    Not Collective

258:    Input Parameter:
259: .  A - the Mat context

261:    Output Parameter:
262: .  prefix - pointer to the prefix string used

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

267:    Level: advanced

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

271: .seealso: MatAppendOptionsPrefix()
272: @*/
273: PetscErrorCode PETSCMAT_DLLEXPORT MatGetOptionsPrefix(Mat A,const char *prefix[])
274: {

279:   PetscObjectGetOptionsPrefix((PetscObject)A,prefix);
280:   return(0);
281: }

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

288:    Collective on Mat

290:    Input Parameters:
291: .  A - the Mat context

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

297:    Level: advanced

299: .keywords: Mat, setup

301: .seealso: MatCreate(), MatDestroy()
302: @*/
303: PetscErrorCode PETSCMAT_DLLEXPORT MatSetUp(Mat A)
304: {

309:   MatSetUpPreallocation(A);
310:   MatSetFromOptions(A);
311:   return(0);
312: }

316: /*@C
317:    MatView - Visualizes a matrix object.

319:    Collective on Mat

321:    Input Parameters:
322: +  mat - the matrix
323: -  viewer - visualization context

325:   Notes:
326:   The available visualization contexts include
327: +    PETSC_VIEWER_STDOUT_SELF - standard output (default)
328: .    PETSC_VIEWER_STDOUT_WORLD - synchronized standard
329:         output where only the first processor opens
330:         the file.  All other processors send their 
331:         data to the first processor to print. 
332: -     PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure

334:    The user can open alternative visualization contexts with
335: +    PetscViewerASCIIOpen() - Outputs matrix to a specified file
336: .    PetscViewerBinaryOpen() - Outputs matrix in binary to a
337:          specified file; corresponding input uses MatLoad()
338: .    PetscViewerDrawOpen() - Outputs nonzero matrix structure to 
339:          an X window display
340: -    PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
341:          Currently only the sequential dense and AIJ
342:          matrix types support the Socket viewer.

344:    The user can call PetscViewerSetFormat() to specify the output
345:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
346:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
347: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
348: .    PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
349: .    PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
350: .    PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 
351:          format common among all matrix types
352: .    PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 
353:          format (which is in many cases the same as the default)
354: .    PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
355:          size and structure (not the matrix entries)
356: .    PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about
357:          the matrix structure

359:    Options Database Keys:
360: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
361: .  -mat_view_info_detailed - Prints more detailed info
362: .  -mat_view - Prints matrix in ASCII format
363: .  -mat_view_matlab - Prints matrix in Matlab format
364: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
365: .  -display <name> - Sets display name (default is host)
366: .  -draw_pause <sec> - Sets number of seconds to pause after display
367: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
368: .  -viewer_socket_machine <machine>
369: .  -viewer_socket_port <port>
370: .  -mat_view_binary - save matrix to file in binary format
371: -  -viewer_binary_filename <name>
372:    Level: beginner

374:    Concepts: matrices^viewing
375:    Concepts: matrices^plotting
376:    Concepts: matrices^printing

378: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 
379:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
380: @*/
381: PetscErrorCode PETSCMAT_DLLEXPORT MatView(Mat mat,PetscViewer viewer)
382: {
383:   PetscErrorCode    ierr;
384:   PetscInt          rows,cols;
385:   PetscTruth        iascii;
386:   const char        *cstr;
387:   PetscViewerFormat format;

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

398:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
399:   if (iascii) {
400:     PetscViewerGetFormat(viewer,&format);
401:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
402:       if (mat->prefix) {
403:         PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);
404:       } else {
405:         PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");
406:       }
407:       PetscViewerASCIIPushTab(viewer);
408:       MatGetType(mat,&cstr);
409:       MatGetSize(mat,&rows,&cols);
410:       PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);
411:       if (mat->ops->getinfo) {
412:         MatInfo info;
413:         MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
414:         PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n",
415:                           (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);
416:       }
417:     }
418:   }
419:   if (mat->ops->view) {
420:     PetscViewerASCIIPushTab(viewer);
421:     (*mat->ops->view)(mat,viewer);
422:     PetscViewerASCIIPopTab(viewer);
423:   } else if (!iascii) {
424:     SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
425:   }
426:   if (iascii) {
427:     PetscViewerGetFormat(viewer,&format);
428:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
429:       PetscViewerASCIIPopTab(viewer);
430:     }
431:   }
432:   return(0);
433: }

437: /*@C
438:    MatScaleSystem - Scale a vector solution and right hand side to 
439:    match the scaling of a scaled matrix.
440:   
441:    Collective on Mat

443:    Input Parameter:
444: +  mat - the matrix
445: .  x - solution vector (or PETSC_NULL)
446: -  b - right hand side vector (or PETSC_NULL)


449:    Notes: 
450:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
451:    internally scaled, so this does nothing. For MPIROWBS it
452:    permutes and diagonally scales.

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

457:    Level: Developer            

459:    Concepts: matrices^scaling

461: .seealso: MatUseScaledForm(), MatUnScaleSystem()
462: @*/
463: PetscErrorCode PETSCMAT_DLLEXPORT MatScaleSystem(Mat mat,Vec x,Vec b)
464: {

470:   MatPreallocated(mat);

474:   if (mat->ops->scalesystem) {
475:     (*mat->ops->scalesystem)(mat,x,b);
476:   }
477:   return(0);
478: }

482: /*@C
483:    MatUnScaleSystem - Unscales a vector solution and right hand side to 
484:    match the original scaling of a scaled matrix.
485:   
486:    Collective on Mat

488:    Input Parameter:
489: +  mat - the matrix
490: .  x - solution vector (or PETSC_NULL)
491: -  b - right hand side vector (or PETSC_NULL)


494:    Notes: 
495:    For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 
496:    internally scaled, so this does nothing. For MPIROWBS it
497:    permutes and diagonally scales.

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

502:    Level: Developer            

504: .seealso: MatUseScaledForm(), MatScaleSystem()
505: @*/
506: PetscErrorCode PETSCMAT_DLLEXPORT MatUnScaleSystem(Mat mat,Vec x,Vec b)
507: {

513:   MatPreallocated(mat);
516:   if (mat->ops->unscalesystem) {
517:     (*mat->ops->unscalesystem)(mat,x,b);
518:   }
519:   return(0);
520: }

524: /*@C
525:    MatUseScaledForm - For matrix storage formats that scale the 
526:    matrix (for example MPIRowBS matrices are diagonally scaled on
527:    assembly) indicates matrix operations (MatMult() etc) are 
528:    applied using the scaled matrix.
529:   
530:    Collective on Mat

532:    Input Parameter:
533: +  mat - the matrix
534: -  scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 
535:             applying the original matrix

537:    Notes: 
538:    For scaled matrix formats, applying the original, unscaled matrix
539:    will be slightly more expensive

541:    Level: Developer            

543: .seealso: MatScaleSystem(), MatUnScaleSystem()
544: @*/
545: PetscErrorCode PETSCMAT_DLLEXPORT MatUseScaledForm(Mat mat,PetscTruth scaled)
546: {

552:   MatPreallocated(mat);
553:   if (mat->ops->usescaledform) {
554:     (*mat->ops->usescaledform)(mat,scaled);
555:   }
556:   return(0);
557: }

561: /*@C
562:    MatDestroy - Frees space taken by a matrix.
563:   
564:    Collective on Mat

566:    Input Parameter:
567: .  A - the matrix

569:    Level: beginner

571: @*/
572: PetscErrorCode PETSCMAT_DLLEXPORT MatDestroy(Mat A)
573: {

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

581:   MatPreallocated(A);
582:   /* if memory was published with AMS then destroy it */
583:   PetscObjectDepublish(A);
584:   if (A->mapping) {
585:     ISLocalToGlobalMappingDestroy(A->mapping);
586:   }
587:   if (A->bmapping) {
588:     ISLocalToGlobalMappingDestroy(A->bmapping);
589:   }
590:   if (A->rmap) {
591:     PetscMapDestroy(A->rmap);
592:   }
593:   if (A->cmap) {
594:     PetscMapDestroy(A->cmap);
595:   }
596:   (*A->ops->destroy)(A);
597:   PetscHeaderDestroy(A);
598:   return(0);
599: }

603: /*@
604:    MatValid - Checks whether a matrix object is valid.

606:    Collective on Mat

608:    Input Parameter:
609: .  m - the matrix to check 

611:    Output Parameter:
612:    flg - flag indicating matrix status, either
613:    PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.

615:    Level: developer

617:    Concepts: matrices^validity
618: @*/
619: PetscErrorCode PETSCMAT_DLLEXPORT MatValid(Mat m,PetscTruth *flg)
620: {
623:   if (!m)                           *flg = PETSC_FALSE;
624:   else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
625:   else                              *flg = PETSC_TRUE;
626:   return(0);
627: }

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

636:    Not Collective

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

647:    Notes:
648:    By default the values, v, are row-oriented and unsorted.
649:    See MatSetOption() for other options.

651:    Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 
652:    options cannot be mixed without intervening calls to the assembly
653:    routines.

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

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

663:    Efficiency Alert:
664:    The routine MatSetValuesBlocked() may offer much better efficiency
665:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

667:    Level: beginner

669:    Concepts: matrices^putting entries in

671: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
672:           InsertMode, INSERT_VALUES, ADD_VALUES
673: @*/
674: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
675: {

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

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

709: /*@C 
710:    MatSetValuesStencil - Inserts or adds a block of values into a matrix.
711:      Using structured grid indexing

713:    Not Collective

715:    Input Parameters:
716: +  mat - the matrix
717: .  v - a logically two-dimensional array of values
718: .  m - number of rows being entered
719: .  idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
720: .  n - number of columns being entered
721: .  idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 
722: -  addv - either ADD_VALUES or INSERT_VALUES, where
723:    ADD_VALUES adds values to any existing entries, and
724:    INSERT_VALUES replaces existing entries with new values

726:    Notes:
727:    By default the values, v, are row-oriented and unsorted.
728:    See MatSetOption() for other options.

730:    Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 
731:    options cannot be mixed without intervening calls to the assembly
732:    routines.

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

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

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

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

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

750:    In Fortran idxm and idxn should be declared as
751: $     MatStencil idxm(4,m),idxn(4,n)
752:    and the values inserted using
753: $    idxm(MatStencil_i,1) = i
754: $    idxm(MatStencil_j,1) = j
755: $    idxm(MatStencil_k,1) = k
756: $    idxm(MatStencil_c,1) = c
757:    etc

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

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

767:    Efficiency Alert:
768:    The routine MatSetValuesBlockedStencil() may offer much better efficiency
769:    for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).

771:    Level: beginner

773:    Concepts: matrices^putting entries in

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

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

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

795:   for (i=0; i<m; i++) {
796:     for (j=0; j<3-sdim; j++) dxm++;
797:     tmp = *dxm++ - starts[0];
798:     for (j=0; j<dim-1; j++) {
799:       if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
800:       else                                       tmp = tmp*dims[j] + dxm[-1] - starts[j+1];
801:     }
802:     if (mat->stencil.noc) dxm++;
803:     jdxm[i] = tmp;
804:   }
805:   for (i=0; i<n; i++) {
806:     for (j=0; j<3-sdim; j++) dxn++;
807:     tmp = *dxn++ - starts[0];
808:     for (j=0; j<dim-1; j++) {
809:       if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
810:       else                                       tmp = tmp*dims[j] + dxn[-1] - starts[j+1];
811:     }
812:     if (mat->stencil.noc) dxn++;
813:     jdxn[i] = tmp;
814:   }
815:   MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
816:   return(0);
817: }

821: /*@C 
822:    MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix.
823:      Using structured grid indexing

825:    Not Collective

827:    Input Parameters:
828: +  mat - the matrix
829: .  v - a logically two-dimensional array of values
830: .  m - number of rows being entered
831: .  idxm - grid coordinates for matrix rows being entered
832: .  n - number of columns being entered
833: .  idxn - grid coordinates for matrix columns being entered 
834: -  addv - either ADD_VALUES or INSERT_VALUES, where
835:    ADD_VALUES adds values to any existing entries, and
836:    INSERT_VALUES replaces existing entries with new values

838:    Notes:
839:    By default the values, v, are row-oriented and unsorted.
840:    See MatSetOption() for other options.

842:    Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES 
843:    options cannot be mixed without intervening calls to the assembly
844:    routines.

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

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

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

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

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

862:    In Fortran idxm and idxn should be declared as
863: $     MatStencil idxm(4,m),idxn(4,n)
864:    and the values inserted using
865: $    idxm(MatStencil_i,1) = i
866: $    idxm(MatStencil_j,1) = j
867: $    idxm(MatStencil_k,1) = k
868:    etc

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

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

878:    Level: beginner

880:    Concepts: matrices^putting entries in

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

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

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

902:   for (i=0; i<m; i++) {
903:     for (j=0; j<3-sdim; j++) dxm++;
904:     tmp = *dxm++ - starts[0];
905:     for (j=0; j<sdim-1; j++) {
906:       if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
907:       else                                      tmp = tmp*dims[j] + dxm[-1] - starts[j+1];
908:     }
909:     dxm++;
910:     jdxm[i] = tmp;
911:   }
912:   for (i=0; i<n; i++) {
913:     for (j=0; j<3-sdim; j++) dxn++;
914:     tmp = *dxn++ - starts[0];
915:     for (j=0; j<sdim-1; j++) {
916:       if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
917:       else                                       tmp = tmp*dims[j] + dxn[-1] - starts[j+1];
918:     }
919:     dxn++;
920:     jdxn[i] = tmp;
921:   }
922:   MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);
923:   return(0);
924: }

928: /*@ 
929:    MatSetStencil - Sets the grid information for setting values into a matrix via
930:         MatSetValuesStencil()

932:    Not Collective

934:    Input Parameters:
935: +  mat - the matrix
936: .  dim - dimension of the grid 1, 2, or 3
937: .  dims - number of grid points in x, y, and z direction, including ghost points on your processor
938: .  starts - starting point of ghost nodes on your processor in x, y, and z direction 
939: -  dof - number of degrees of freedom per node


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

945:    For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the
946:    user.
947:    
948:    Level: beginner

950:    Concepts: matrices^putting entries in

952: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
953:           MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
954: @*/
955: PetscErrorCode PETSCMAT_DLLEXPORT MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof)
956: {
957:   PetscInt i;


964:   mat->stencil.dim = dim + (dof > 1);
965:   for (i=0; i<dim; i++) {
966:     mat->stencil.dims[i]   = dims[dim-i-1];      /* copy the values in backwards */
967:     mat->stencil.starts[i] = starts[dim-i-1];
968:   }
969:   mat->stencil.dims[dim]   = dof;
970:   mat->stencil.starts[dim] = 0;
971:   mat->stencil.noc         = (PetscTruth)(dof == 1);
972:   return(0);
973: }

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

980:    Not Collective

982:    Input Parameters:
983: +  mat - the matrix
984: .  v - a logically two-dimensional array of values
985: .  m, idxm - the number of block rows and their global block indices 
986: .  n, idxn - the number of block columns and their global block indices
987: -  addv - either ADD_VALUES or INSERT_VALUES, where
988:    ADD_VALUES adds values to any existing entries, and
989:    INSERT_VALUES replaces existing entries with new values

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

995:    Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
996:    options cannot be mixed without intervening calls to the assembly
997:    routines.

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

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

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

1013:    Restrictions:
1014:    MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats

1016:    Level: intermediate

1018:    Concepts: matrices^putting entries in blocked

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

1027:   if (!m || !n) return(0); /* no values to insert */
1033:   MatPreallocated(mat);
1034:   if (mat->insertmode == NOT_SET_VALUES) {
1035:     mat->insertmode = addv;
1036:   }
1037: #if defined(PETSC_USE_DEBUG) 
1038:   else if (mat->insertmode != addv) {
1039:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1040:   }
1041:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1042: #endif

1044:   if (mat->assembled) {
1045:     mat->was_assembled = PETSC_TRUE;
1046:     mat->assembled     = PETSC_FALSE;
1047:   }
1048:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1049:   if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1050:   (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
1051:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1052:   return(0);
1053: }

1057: /*@ 
1058:    MatGetValues - Gets a block of values from a matrix.

1060:    Not Collective; currently only returns a local block

1062:    Input Parameters:
1063: +  mat - the matrix
1064: .  v - a logically two-dimensional array for storing the values
1065: .  m, idxm - the number of rows and their global indices 
1066: -  n, idxn - the number of columns and their global indices

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

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

1076:    MatGetValues() requires that the matrix has been assembled
1077:    with MatAssemblyBegin()/MatAssemblyEnd().  Thus, calls to
1078:    MatSetValues() and MatGetValues() CANNOT be made in succession
1079:    without intermediate matrix assembly.

1081:    Level: advanced

1083:    Concepts: matrices^accessing values

1085: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
1086: @*/
1087: PetscErrorCode PETSCMAT_DLLEXPORT MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[])
1088: {

1097:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1098:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1099:   if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1100:   MatPreallocated(mat);

1102:   PetscLogEventBegin(MAT_GetValues,mat,0,0,0);
1103:   (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
1104:   PetscLogEventEnd(MAT_GetValues,mat,0,0,0);
1105:   return(0);
1106: }

1110: /*@
1111:    MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
1112:    the routine MatSetValuesLocal() to allow users to insert matrix entries
1113:    using a local (per-processor) numbering.

1115:    Not Collective

1117:    Input Parameters:
1118: +  x - the matrix
1119: -  mapping - mapping created with ISLocalToGlobalMappingCreate() 
1120:              or ISLocalToGlobalMappingCreateIS()

1122:    Level: intermediate

1124:    Concepts: matrices^local to global mapping
1125:    Concepts: local to global mapping^for matrices

1127: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
1128: @*/
1129: PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
1130: {
1136:   if (x->mapping) {
1137:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1138:   }
1139:   MatPreallocated(x);

1141:   if (x->ops->setlocaltoglobalmapping) {
1142:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1143:   } else {
1144:     x->mapping = mapping;
1145:     PetscObjectReference((PetscObject)mapping);
1146:   }
1147:   return(0);
1148: }

1152: /*@
1153:    MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
1154:    by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
1155:    entries using a local (per-processor) numbering.

1157:    Not Collective

1159:    Input Parameters:
1160: +  x - the matrix
1161: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or
1162:              ISLocalToGlobalMappingCreateIS()

1164:    Level: intermediate

1166:    Concepts: matrices^local to global mapping blocked
1167:    Concepts: local to global mapping^for matrices, blocked

1169: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
1170:            MatSetValuesBlocked(), MatSetValuesLocal()
1171: @*/
1172: PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
1173: {
1179:   if (x->bmapping) {
1180:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1181:   }
1182:   x->bmapping = mapping;
1183:   PetscObjectReference((PetscObject)mapping);
1184:   return(0);
1185: }

1189: /*@
1190:    MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
1191:    using a local ordering of the nodes. 

1193:    Not Collective

1195:    Input Parameters:
1196: +  x - the matrix
1197: .  nrow, irow - number of rows and their local indices
1198: .  ncol, icol - number of columns and their local indices
1199: .  y -  a logically two-dimensional array of values
1200: -  addv - either INSERT_VALUES or ADD_VALUES, where
1201:    ADD_VALUES adds values to any existing entries, and
1202:    INSERT_VALUES replaces existing entries with new values

1204:    Notes:
1205:    Before calling MatSetValuesLocal(), the user must first set the
1206:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

1208:    Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 
1209:    options cannot be mixed without intervening calls to the assembly
1210:    routines.

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

1215:    Level: intermediate

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

1219: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
1220:            MatSetValueLocal()
1221: @*/
1222: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1223: {
1225:   PetscInt       irowm[2048],icolm[2048];

1233:   MatPreallocated(mat);
1234:   if (mat->insertmode == NOT_SET_VALUES) {
1235:     mat->insertmode = addv;
1236:   }
1237: #if defined(PETSC_USE_DEBUG) 
1238:   else if (mat->insertmode != addv) {
1239:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1240:   }
1241:   if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
1242:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1243:   }
1244:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1245: #endif

1247:   if (mat->assembled) {
1248:     mat->was_assembled = PETSC_TRUE;
1249:     mat->assembled     = PETSC_FALSE;
1250:   }
1251:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1252:   if (!mat->ops->setvalueslocal) {
1253:     ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
1254:     ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
1255:     (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
1256:   } else {
1257:     (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
1258:   }
1259:   mat->same_nonzero = PETSC_FALSE;
1260:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1261:   return(0);
1262: }

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

1270:    Not Collective

1272:    Input Parameters:
1273: +  x - the matrix
1274: .  nrow, irow - number of rows and their local indices
1275: .  ncol, icol - number of columns and their local indices
1276: .  y -  a logically two-dimensional array of values
1277: -  addv - either INSERT_VALUES or ADD_VALUES, where
1278:    ADD_VALUES adds values to any existing entries, and
1279:    INSERT_VALUES replaces existing entries with new values

1281:    Notes:
1282:    Before calling MatSetValuesBlockedLocal(), the user must first set the
1283:    local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
1284:    where the mapping MUST be set for matrix blocks, not for matrix elements.

1286:    Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1287:    options cannot be mixed without intervening calls to the assembly
1288:    routines.

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

1293:    Level: intermediate

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

1297: .seealso:  MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
1298: @*/
1299: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1300: {
1302:   PetscInt       irowm[2048],icolm[2048];

1310:   MatPreallocated(mat);
1311:   if (mat->insertmode == NOT_SET_VALUES) {
1312:     mat->insertmode = addv;
1313:   }
1314: #if defined(PETSC_USE_DEBUG) 
1315:   else if (mat->insertmode != addv) {
1316:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1317:   }
1318:   if (!mat->bmapping) {
1319:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
1320:   }
1321:   if (nrow > 2048 || ncol > 2048) {
1322:     SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1323:   }
1324:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1325: #endif

1327:   if (mat->assembled) {
1328:     mat->was_assembled = PETSC_TRUE;
1329:     mat->assembled     = PETSC_FALSE;
1330:   }
1331:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1332:   ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1333:   ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1334:   (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1335:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1336:   return(0);
1337: }

1339: /* --------------------------------------------------------*/
1342: /*@
1343:    MatMult - Computes the matrix-vector product, y = Ax.

1345:    Collective on Mat and Vec

1347:    Input Parameters:
1348: +  mat - the matrix
1349: -  x   - the vector to be multiplied

1351:    Output Parameters:
1352: .  y - the result

1354:    Notes:
1355:    The vectors x and y cannot be the same.  I.e., one cannot
1356:    call MatMult(A,y,y).

1358:    Level: beginner

1360:    Concepts: matrix-vector product

1362: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1363: @*/
1364: PetscErrorCode PETSCMAT_DLLEXPORT MatMult(Mat mat,Vec x,Vec y)
1365: {


1374:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1375:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1376:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1377: #ifndef PETSC_HAVE_CONSTRAINTS
1378:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
1379:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N);
1380:   if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n);
1381: #endif
1382:   MatPreallocated(mat);

1384:   if (mat->nullsp) {
1385:     MatNullSpaceRemove(mat->nullsp,x,&x);
1386:   }

1388:   PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1389:   (*mat->ops->mult)(mat,x,y);
1390:   PetscLogEventEnd(MAT_Mult,mat,x,y,0);

1392:   if (mat->nullsp) {
1393:     MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1394:   }
1395:   PetscObjectStateIncrease((PetscObject)y);
1396:   return(0);
1397: }

1401: /*@
1402:    MatMultTranspose - Computes matrix transpose times a vector.

1404:    Collective on Mat and Vec

1406:    Input Parameters:
1407: +  mat - the matrix
1408: -  x   - the vector to be multilplied

1410:    Output Parameters:
1411: .  y - the result

1413:    Notes:
1414:    The vectors x and y cannot be the same.  I.e., one cannot
1415:    call MatMultTranspose(A,y,y).

1417:    Level: beginner

1419:    Concepts: matrix vector product^transpose

1421: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1422: @*/
1423: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTranspose(Mat mat,Vec x,Vec y)
1424: {
1426:   PetscTruth     flg1, flg2;


1434:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1435:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1436:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1437: #ifndef PETSC_HAVE_CONSTRAINTS
1438:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N);
1439:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N);
1440: #endif
1441:   MatPreallocated(mat);

1443:   if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP, "Operation not supported");
1444:   PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);
1445:   if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined");
1446: 
1447:   PetscTypeCompare((PetscObject)mat,MATSEQSBAIJ,&flg1);
1448:   PetscTypeCompare((PetscObject)mat,MATMPISBAIJ,&flg2);
1449:   if (flg1 || flg2) { /* mat is in sbaij format */
1450:     (*mat->ops->mult)(mat,x,y);
1451:   } else {
1452:     (*mat->ops->multtranspose)(mat,x,y);
1453:   }
1454:   PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);
1455:   PetscObjectStateIncrease((PetscObject)y);
1456:   return(0);
1457: }

1461: /*@
1462:     MatMultAdd -  Computes v3 = v2 + A * v1.

1464:     Collective on Mat and Vec

1466:     Input Parameters:
1467: +   mat - the matrix
1468: -   v1, v2 - the vectors

1470:     Output Parameters:
1471: .   v3 - the result

1473:     Notes:
1474:     The vectors v1 and v3 cannot be the same.  I.e., one cannot
1475:     call MatMultAdd(A,v1,v2,v1).

1477:     Level: beginner

1479:     Concepts: matrix vector product^addition

1481: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1482: @*/
1483: PetscErrorCode PETSCMAT_DLLEXPORT MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1484: {


1494:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1495:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1496:   if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->N,v1->N);
1497:   if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->M,v2->N);
1498:   if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->M,v3->N);
1499:   if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->m,v3->n);
1500:   if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->m,v2->n);
1501:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1502:   MatPreallocated(mat);

1504:   PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);
1505:   (*mat->ops->multadd)(mat,v1,v2,v3);
1506:   PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);
1507:   PetscObjectStateIncrease((PetscObject)v3);
1508:   return(0);
1509: }

1513: /*@
1514:    MatMultTransposeAdd - Computes v3 = v2 + A' * v1.

1516:    Collective on Mat and Vec

1518:    Input Parameters:
1519: +  mat - the matrix
1520: -  v1, v2 - the vectors

1522:    Output Parameters:
1523: .  v3 - the result

1525:    Notes:
1526:    The vectors v1 and v3 cannot be the same.  I.e., one cannot
1527:    call MatMultTransposeAdd(A,v1,v2,v1).

1529:    Level: beginner

1531:    Concepts: matrix vector product^transpose and addition

1533: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1534: @*/
1535: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1536: {


1546:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1547:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1548:   if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1549:   if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1550:   if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->M,v1->N);
1551:   if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->N,v2->N);
1552:   if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->N,v3->N);
1553:   MatPreallocated(mat);

1555:   PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);
1556:   (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1557:   PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);
1558:   PetscObjectStateIncrease((PetscObject)v3);
1559:   return(0);
1560: }

1564: /*@
1565:    MatMultConstrained - The inner multiplication routine for a
1566:    constrained matrix P^T A P.

1568:    Collective on Mat and Vec

1570:    Input Parameters:
1571: +  mat - the matrix
1572: -  x   - the vector to be multilplied

1574:    Output Parameters:
1575: .  y - the result

1577:    Notes:
1578:    The vectors x and y cannot be the same.  I.e., one cannot
1579:    call MatMult(A,y,y).

1581:    Level: beginner

1583: .keywords: matrix, multiply, matrix-vector product, constraint
1584: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1585: @*/
1586: PetscErrorCode PETSCMAT_DLLEXPORT MatMultConstrained(Mat mat,Vec x,Vec y)
1587: {

1594:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1595:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1596:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1597:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
1598:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N);
1599:   if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n);

1601:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1602:   (*mat->ops->multconstrained)(mat,x,y);
1603:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1604:   PetscObjectStateIncrease((PetscObject)y);

1606:   return(0);
1607: }

1611: /*@
1612:    MatMultTransposeConstrained - The inner multiplication routine for a
1613:    constrained matrix P^T A^T P.

1615:    Collective on Mat and Vec

1617:    Input Parameters:
1618: +  mat - the matrix
1619: -  x   - the vector to be multilplied

1621:    Output Parameters:
1622: .  y - the result

1624:    Notes:
1625:    The vectors x and y cannot be the same.  I.e., one cannot
1626:    call MatMult(A,y,y).

1628:    Level: beginner

1630: .keywords: matrix, multiply, matrix-vector product, constraint
1631: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1632: @*/
1633: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeConstrained(Mat mat,Vec x,Vec y)
1634: {

1641:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1642:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1643:   if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1644:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
1645:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N);

1647:   PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1648:   (*mat->ops->multtransposeconstrained)(mat,x,y);
1649:   PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1650:   PetscObjectStateIncrease((PetscObject)y);

1652:   return(0);
1653: }
1654: /* ------------------------------------------------------------*/
1657: /*@C
1658:    MatGetInfo - Returns information about matrix storage (number of
1659:    nonzeros, memory, etc.).

1661:    Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1662:    as the flag

1664:    Input Parameters:
1665: .  mat - the matrix

1667:    Output Parameters:
1668: +  flag - flag indicating the type of parameters to be returned
1669:    (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1670:    MAT_GLOBAL_SUM - sum over all processors)
1671: -  info - matrix information context

1673:    Notes:
1674:    The MatInfo context contains a variety of matrix data, including
1675:    number of nonzeros allocated and used, number of mallocs during
1676:    matrix assembly, etc.  Additional information for factored matrices
1677:    is provided (such as the fill ratio, number of mallocs during
1678:    factorization, etc.).  Much of this info is printed to STDOUT
1679:    when using the runtime options 
1680: $       -log_info -mat_view_info

1682:    Example for C/C++ Users:
1683:    See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1684:    data within the MatInfo context.  For example, 
1685: .vb
1686:       MatInfo info;
1687:       Mat     A;
1688:       double  mal, nz_a, nz_u;

1690:       MatGetInfo(A,MAT_LOCAL,&info);
1691:       mal  = info.mallocs;
1692:       nz_a = info.nz_allocated;
1693: .ve

1695:    Example for Fortran Users:
1696:    Fortran users should declare info as a double precision
1697:    array of dimension MAT_INFO_SIZE, and then extract the parameters
1698:    of interest.  See the file ${PETSC_DIR}/include/finclude/petscmat.h
1699:    a complete list of parameter names.
1700: .vb
1701:       double  precision info(MAT_INFO_SIZE)
1702:       double  precision mal, nz_a
1703:       Mat     A
1704:       integer ierr

1706:       call MatGetInfo(A,MAT_LOCAL,info,ierr)
1707:       mal = info(MAT_INFO_MALLOCS)
1708:       nz_a = info(MAT_INFO_NZ_ALLOCATED)
1709: .ve

1711:     Level: intermediate

1713:     Concepts: matrices^getting information on
1714:  
1715: @*/
1716: PetscErrorCode PETSCMAT_DLLEXPORT MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1717: {

1724:   if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1725:   MatPreallocated(mat);
1726:   (*mat->ops->getinfo)(mat,flag,info);
1727:   return(0);
1728: }

1730: /* ----------------------------------------------------------*/
1733: /*@C  
1734:    MatILUDTFactor - Performs a drop tolerance ILU factorization.

1736:    Collective on Mat

1738:    Input Parameters:
1739: +  mat - the matrix
1740: .  row - row permutation
1741: .  col - column permutation
1742: -  info - information about the factorization to be done

1744:    Output Parameters:
1745: .  fact - the factored matrix

1747:    Level: developer

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

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

1759:     Concepts: matrices^ILUDT factorization

1761: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1762: @*/
1763: PetscErrorCode PETSCMAT_DLLEXPORT MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1764: {

1774:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1775:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1776:   if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1777:   MatPreallocated(mat);
1778:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1779:   (*mat->ops->iludtfactor)(mat,row,col,info,fact);
1780:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1781:   PetscObjectStateIncrease((PetscObject)*fact);

1783:   return(0);
1784: }

1788: /*@  
1789:    MatLUFactor - Performs in-place LU factorization of matrix.

1791:    Collective on Mat

1793:    Input Parameters:
1794: +  mat - the matrix
1795: .  row - row permutation
1796: .  col - column permutation
1797: -  info - options for factorization, includes 
1798: $          fill - expected fill as ratio of original fill.
1799: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1800: $                   Run with the option -log_info to determine an optimal value to use

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

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

1810:    Level: developer

1812:    Concepts: matrices^LU factorization

1814: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
1815:           MatGetOrdering(), MatSetUnfactored(), MatFactorInfo

1817: @*/
1818: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
1819: {

1828:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1829:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1830:   if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1831:   MatPreallocated(mat);

1833:   PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);
1834:   (*mat->ops->lufactor)(mat,row,col,info);
1835:   PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);
1836:   PetscObjectStateIncrease((PetscObject)mat);
1837:   return(0);
1838: }

1842: /*@  
1843:    MatILUFactor - Performs in-place ILU factorization of matrix.

1845:    Collective on Mat

1847:    Input Parameters:
1848: +  mat - the matrix
1849: .  row - row permutation
1850: .  col - column permutation
1851: -  info - structure containing 
1852: $      levels - number of levels of fill.
1853: $      expected fill - as ratio of original fill.
1854: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
1855:                 missing diagonal entries)

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

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

1865:    Level: developer

1867:    Concepts: matrices^ILU factorization

1869: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1870: @*/
1871: PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
1872: {

1881:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
1882:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1883:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1884:   if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1885:   MatPreallocated(mat);

1887:   PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1888:   (*mat->ops->ilufactor)(mat,row,col,info);
1889:   PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1890:   PetscObjectStateIncrease((PetscObject)mat);
1891:   return(0);
1892: }

1896: /*@  
1897:    MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
1898:    Call this routine before calling MatLUFactorNumeric().

1900:    Collective on Mat

1902:    Input Parameters:
1903: +  mat - the matrix
1904: .  row, col - row and column permutations
1905: -  info - options for factorization, includes 
1906: $          fill - expected fill as ratio of original fill.
1907: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1908: $                   Run with the option -log_info to determine an optimal value to use

1910:    Output Parameter:
1911: .  fact - new matrix that has been symbolically factored

1913:    Notes:
1914:    See the users manual for additional information about
1915:    choosing the fill factor for better efficiency.

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

1921:    Level: developer

1923:    Concepts: matrices^LU symbolic factorization

1925: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1926: @*/
1927: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1928: {

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

1943:   PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);
1944:   (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
1945:   PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);
1946:   PetscObjectStateIncrease((PetscObject)*fact);
1947:   return(0);
1948: }

1952: /*@  
1953:    MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
1954:    Call this routine after first calling MatLUFactorSymbolic().

1956:    Collective on Mat

1958:    Input Parameters:
1959: +  mat - the matrix
1960: .  info - options for factorization
1961: -  fact - the matrix generated for the factor, from MatLUFactorSymbolic()

1963:    Notes:
1964:    See MatLUFactor() for in-place factorization.  See 
1965:    MatCholeskyFactorNumeric() for the symmetric, positive definite case.  

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

1971:    Level: developer

1973:    Concepts: matrices^LU numeric factorization

1975: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
1976: @*/
1977: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
1978: {

1986:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1987:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1988:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",
1989:             mat->M,(*fact)->M,mat->N,(*fact)->N);
1990:   }
1991:   if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1992:   MatPreallocated(mat);
1993:   PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
1994:   (*(*fact)->ops->lufactornumeric)(mat,info,fact);
1995:   PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);

1997:   MatView_Private(*fact);
1998:   PetscObjectStateIncrease((PetscObject)*fact);
1999:   return(0);
2000: }

2004: /*@  
2005:    MatCholeskyFactor - Performs in-place Cholesky factorization of a
2006:    symmetric matrix. 

2008:    Collective on Mat

2010:    Input Parameters:
2011: +  mat - the matrix
2012: .  perm - row and column permutations
2013: -  f - expected fill as ratio of original fill

2015:    Notes:
2016:    See MatLUFactor() for the nonsymmetric case.  See also
2017:    MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().

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

2023:    Level: developer

2025:    Concepts: matrices^Cholesky factorization

2027: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
2028:           MatGetOrdering()

2030: @*/
2031: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info)
2032: {

2040:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2041:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2042:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2043:   if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2044:   MatPreallocated(mat);

2046:   PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);
2047:   (*mat->ops->choleskyfactor)(mat,perm,info);
2048:   PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);
2049:   PetscObjectStateIncrease((PetscObject)mat);
2050:   return(0);
2051: }

2055: /*@  
2056:    MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
2057:    of a symmetric matrix. 

2059:    Collective on Mat

2061:    Input Parameters:
2062: +  mat - the matrix
2063: .  perm - row and column permutations
2064: -  info - options for factorization, includes 
2065: $          fill - expected fill as ratio of original fill.
2066: $          dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2067: $                   Run with the option -log_info to determine an optimal value to use

2069:    Output Parameter:
2070: .  fact - the factored matrix

2072:    Notes:
2073:    See MatLUFactorSymbolic() for the nonsymmetric case.  See also
2074:    MatCholeskyFactor() and MatCholeskyFactorNumeric().

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

2080:    Level: developer

2082:    Concepts: matrices^Cholesky symbolic factorization

2084: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
2085:           MatGetOrdering()

2087: @*/
2088: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
2089: {

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

2104:   PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
2105:   (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);
2106:   PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
2107:   PetscObjectStateIncrease((PetscObject)*fact);
2108:   return(0);
2109: }

2113: /*@  
2114:    MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
2115:    of a symmetric matrix. Call this routine after first calling
2116:    MatCholeskyFactorSymbolic().

2118:    Collective on Mat

2120:    Input Parameter:
2121: .  mat - the initial matrix
2122: .  info - options for factorization
2123: -  fact - the symbolic factor of mat

2125:    Output Parameter:
2126: .  fact - the factored matrix

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

2133:    Level: developer

2135:    Concepts: matrices^Cholesky numeric factorization

2137: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
2138: @*/
2139: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2140: {

2147:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2148:   if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2149:   if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
2150:     SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->M,(*fact)->M,mat->N,(*fact)->N);
2151:   }
2152:   MatPreallocated(mat);

2154:   PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
2155:   (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);
2156:   PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
2157:   PetscObjectStateIncrease((PetscObject)*fact);
2158:   return(0);
2159: }

2161: /* ----------------------------------------------------------------*/
2164: /*@
2165:    MatSolve - Solves A x = b, given a factored matrix.

2167:    Collective on Mat and Vec

2169:    Input Parameters:
2170: +  mat - the factored matrix
2171: -  b - the right-hand-side vector

2173:    Output Parameter:
2174: .  x - the result vector

2176:    Notes:
2177:    The vectors b and x cannot be the same.  I.e., one cannot
2178:    call MatSolve(A,x,x).

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

2185:    Level: developer

2187:    Concepts: matrices^triangular solves

2189: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
2190: @*/
2191: PetscErrorCode PETSCMAT_DLLEXPORT MatSolve(Mat mat,Vec b,Vec x)
2192: {

2202:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2203:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2204:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2205:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2206:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2207:   if (!mat->M && !mat->N) return(0);
2208:   if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2209:   MatPreallocated(mat);

2211:   PetscLogEventBegin(MAT_Solve,mat,b,x,0);
2212:   (*mat->ops->solve)(mat,b,x);
2213:   PetscLogEventEnd(MAT_Solve,mat,b,x,0);
2214:   PetscObjectStateIncrease((PetscObject)x);
2215:   return(0);
2216: }

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

2223:    Collective on Mat and Vec

2225:    Input Parameters:
2226: +  mat - the factored matrix
2227: -  b - the right-hand-side vector

2229:    Output Parameter:
2230: .  x - the result vector

2232:    Notes:
2233:    MatSolve() should be used for most applications, as it performs
2234:    a forward solve followed by a backward solve.

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

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

2243:    Level: developer

2245:    Concepts: matrices^forward solves

2247: .seealso: MatSolve(), MatBackwardSolve()
2248: @ */
2249: PetscErrorCode PETSCMAT_DLLEXPORT MatForwardSolve(Mat mat,Vec b,Vec x)
2250: {

2260:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2261:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2262:   if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2263:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2264:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2265:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2266:   MatPreallocated(mat);
2267:   PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
2268:   (*mat->ops->forwardsolve)(mat,b,x);
2269:   PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
2270:   PetscObjectStateIncrease((PetscObject)x);
2271:   return(0);
2272: }

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

2279:    Collective on Mat and Vec

2281:    Input Parameters:
2282: +  mat - the factored matrix
2283: -  b - the right-hand-side vector

2285:    Output Parameter:
2286: .  x - the result vector

2288:    Notes:
2289:    MatSolve() should be used for most applications, as it performs
2290:    a forward solve followed by a backward solve.

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

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

2299:    Level: developer

2301:    Concepts: matrices^backward solves

2303: .seealso: MatSolve(), MatForwardSolve()
2304: @ */
2305: PetscErrorCode PETSCMAT_DLLEXPORT MatBackwardSolve(Mat mat,Vec b,Vec x)
2306: {

2316:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2317:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2318:   if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2319:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2320:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2321:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2322:   MatPreallocated(mat);

2324:   PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);
2325:   (*mat->ops->backwardsolve)(mat,b,x);
2326:   PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);
2327:   PetscObjectStateIncrease((PetscObject)x);
2328:   return(0);
2329: }

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

2336:    Collective on Mat and Vec

2338:    Input Parameters:
2339: +  mat - the factored matrix
2340: .  b - the right-hand-side vector
2341: -  y - the vector to be added to 

2343:    Output Parameter:
2344: .  x - the result vector

2346:    Notes:
2347:    The vectors b and x cannot be the same.  I.e., one cannot
2348:    call MatSolveAdd(A,x,y,x).

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

2354:    Level: developer

2356:    Concepts: matrices^triangular solves

2358: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
2359: @*/
2360: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
2361: {
2362:   PetscScalar    one = 1.0;
2363:   Vec            tmp;

2375:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2376:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2377:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2378:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2379:   if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N);
2380:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2381:   if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n);
2382:   MatPreallocated(mat);

2384:   PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);
2385:   if (mat->ops->solveadd)  {
2386:     (*mat->ops->solveadd)(mat,b,y,x);
2387:   } else {
2388:     /* do the solve then the add manually */
2389:     if (x != y) {
2390:       MatSolve(mat,b,x);
2391:       VecAXPY(x,one,y);
2392:     } else {
2393:       VecDuplicate(x,&tmp);
2394:       PetscLogObjectParent(mat,tmp);
2395:       VecCopy(x,tmp);
2396:       MatSolve(mat,b,x);
2397:       VecAXPY(x,one,tmp);
2398:       VecDestroy(tmp);
2399:     }
2400:   }
2401:   PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);
2402:   PetscObjectStateIncrease((PetscObject)x);
2403:   return(0);
2404: }

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

2411:    Collective on Mat and Vec

2413:    Input Parameters:
2414: +  mat - the factored matrix
2415: -  b - the right-hand-side vector

2417:    Output Parameter:
2418: .  x - the result vector

2420:    Notes:
2421:    The vectors b and x cannot be the same.  I.e., one cannot
2422:    call MatSolveTranspose(A,x,x).

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

2428:    Level: developer

2430:    Concepts: matrices^triangular solves

2432: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
2433: @*/
2434: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTranspose(Mat mat,Vec b,Vec x)
2435: {

2445:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2446:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2447:   if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2448:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N);
2449:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N);
2450:   MatPreallocated(mat);
2451:   PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
2452:   (*mat->ops->solvetranspose)(mat,b,x);
2453:   PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
2454:   PetscObjectStateIncrease((PetscObject)x);
2455:   return(0);
2456: }

2460: /*@
2461:    MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 
2462:                       factored matrix. 

2464:    Collective on Mat and Vec

2466:    Input Parameters:
2467: +  mat - the factored matrix
2468: .  b - the right-hand-side vector
2469: -  y - the vector to be added to 

2471:    Output Parameter:
2472: .  x - the result vector

2474:    Notes:
2475:    The vectors b and x cannot be the same.  I.e., one cannot
2476:    call MatSolveTransposeAdd(A,x,y,x).

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

2482:    Level: developer

2484:    Concepts: matrices^triangular solves

2486: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
2487: @*/
2488: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
2489: {
2490:   PetscScalar    one = 1.0;
2492:   Vec            tmp;

2503:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2504:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2505:   if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N);
2506:   if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N);
2507:   if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N);
2508:   if (x->n != y->n)   SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n);
2509:   MatPreallocated(mat);

2511:   PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);
2512:   if (mat->ops->solvetransposeadd) {
2513:     (*mat->ops->solvetransposeadd)(mat,b,y,x);
2514:   } else {
2515:     /* do the solve then the add manually */
2516:     if (x != y) {
2517:       MatSolveTranspose(mat,b,x);
2518:       VecAXPY(x,one,y);
2519:     } else {
2520:       VecDuplicate(x,&tmp);
2521:       PetscLogObjectParent(mat,tmp);
2522:       VecCopy(x,tmp);
2523:       MatSolveTranspose(mat,b,x);
2524:       VecAXPY(x,one,tmp);
2525:       VecDestroy(tmp);
2526:     }
2527:   }
2528:   PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);
2529:   PetscObjectStateIncrease((PetscObject)x);
2530:   return(0);
2531: }
2532: /* ----------------------------------------------------------------*/

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

2539:    Collective on Mat and Vec

2541:    Input Parameters:
2542: +  mat - the matrix
2543: .  b - the right hand side
2544: .  omega - the relaxation factor
2545: .  flag - flag indicating the type of SOR (see below)
2546: .  shift -  diagonal shift
2547: -  its - the number of iterations
2548: -  lits - the number of local iterations 

2550:    Output Parameters:
2551: .  x - the solution (can contain an initial guess)

2553:    SOR Flags:
2554: .     SOR_FORWARD_SWEEP - forward SOR
2555: .     SOR_BACKWARD_SWEEP - backward SOR
2556: .     SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2557: .     SOR_LOCAL_FORWARD_SWEEP - local forward SOR 
2558: .     SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 
2559: .     SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2560: .     SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 
2561:          upper/lower triangular part of matrix to
2562:          vector (with omega)
2563: .     SOR_ZERO_INITIAL_GUESS - zero initial guess

2565:    Notes:
2566:    SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2567:    SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings
2568:    on each processor. 

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

2573:    Notes for Advanced Users:
2574:    The flags are implemented as bitwise inclusive or operations.
2575:    For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2576:    to specify a zero initial guess for SSOR.

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

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

2585:    Level: developer

2587:    Concepts: matrices^relaxation
2588:    Concepts: matrices^SOR
2589:    Concepts: matrices^Gauss-Seidel

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

2603:   if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2604:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2605:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2606:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2607:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2608:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2609:   MatPreallocated(mat);
2610:   PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2611:   if (mat->ops->relax) {
2612:     ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2613:   } else {
2614:     ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2615:   }
2616:   PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2617:   PetscObjectStateIncrease((PetscObject)x);
2618:   return(0);
2619: }

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

2626:    Collective on Mat and Vec

2628:    See MatRelax() for usage

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

2635:    Level: developer

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

2649:   if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2650:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2651:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2652:   if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N);
2653:   if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N);
2654:   if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n);
2655:   MatPreallocated(mat);

2657:   PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2658:   ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2659:   PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2660:   PetscObjectStateIncrease((PetscObject)x);
2661:   return(0);
2662: }

2666: /*
2667:       Default matrix copy routine.
2668: */
2669: PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str)
2670: {
2671:   PetscErrorCode    ierr;
2672:   PetscInt          i,rstart,rend,nz;
2673:   const PetscInt    *cwork;
2674:   const PetscScalar *vwork;

2677:   if (B->assembled) {
2678:     MatZeroEntries(B);
2679:   }
2680:   MatGetOwnershipRange(A,&rstart,&rend);
2681:   for (i=rstart; i<rend; i++) {
2682:     MatGetRow(A,i,&nz,&cwork,&vwork);
2683:     MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2684:     MatRestoreRow(A,i,&nz,&cwork,&vwork);
2685:   }
2686:   MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2687:   MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2688:   PetscObjectStateIncrease((PetscObject)B);
2689:   return(0);
2690: }

2694: /*@C  
2695:    MatCopy - Copys a matrix to another matrix.

2697:    Collective on Mat

2699:    Input Parameters:
2700: +  A - the matrix
2701: -  str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN

2703:    Output Parameter:
2704: .  B - where the copy is put

2706:    Notes:
2707:    If you use SAME_NONZERO_PATTERN then the two matrices had better have the 
2708:    same nonzero pattern or the routine will crash.

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

2714:    Level: intermediate
2715:    
2716:    Concepts: matrices^copying

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

2720: @*/
2721: PetscErrorCode PETSCMAT_DLLEXPORT MatCopy(Mat A,Mat B,MatStructure str)
2722: {

2730:   MatPreallocated(B);
2732:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2733:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2734:   if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->M,B->M,A->N,B->N);
2735:   MatPreallocated(A);

2737:   PetscLogEventBegin(MAT_Copy,A,B,0,0);
2738:   if (A->ops->copy) {
2739:     (*A->ops->copy)(A,B,str);
2740:   } else { /* generic conversion */
2741:     MatCopy_Basic(A,B,str);
2742:   }
2743:   if (A->mapping) {
2744:     if (B->mapping) {ISLocalToGlobalMappingDestroy(B->mapping);B->mapping = 0;}
2745:     MatSetLocalToGlobalMapping(B,A->mapping);
2746:   }
2747:   if (A->bmapping) {
2748:     if (B->bmapping) {ISLocalToGlobalMappingDestroy(B->bmapping);B->bmapping = 0;}
2749:     MatSetLocalToGlobalMappingBlock(B,A->mapping);
2750:   }
2751:   PetscLogEventEnd(MAT_Copy,A,B,0,0);
2752:   PetscObjectStateIncrease((PetscObject)B);
2753:   return(0);
2754: }

2756:  #include petscsys.h
2757: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
2758: PetscFList MatConvertList              = 0;

2762: /*@C
2763:     MatConvertRegister - Allows one to register a routine that converts a sparse matrix
2764:         from one format to another.

2766:   Not Collective

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

2772:   Level: developer

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

2776: @*/
2777: PetscErrorCode PETSCMAT_DLLEXPORT MatConvertRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(Mat,MatType,MatReuse,Mat*))
2778: {
2780:   char           fullname[PETSC_MAX_PATH_LEN];

2783:   PetscFListConcat(path,name,fullname);
2784:   PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);
2785:   return(0);
2786: }

2790: /*@C  
2791:    MatConvert - Converts a matrix to another matrix, either of the same
2792:    or different type.

2794:    Collective on Mat

2796:    Input Parameters:
2797: +  mat - the matrix
2798: .  newtype - new matrix type.  Use MATSAME to create a new matrix of the
2799:    same type as the original matrix.
2800: -  reuse - denotes if the destination matrix is to be created or reused.  Currently
2801:    MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use
2802:    MAT_INITIAL_MATRIX.
2803:    Output Parameter:
2804: .  M - pointer to place new matrix

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

2811:    Level: intermediate

2813:    Concepts: matrices^converting between storage formats

2815: .seealso: MatCopy(), MatDuplicate()
2816: @*/
2817: PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M)
2818: {
2819:   PetscErrorCode         ierr;
2820:   PetscTruth             sametype,issame,flg;
2821:   char                   convname[256],mtype[256];
2822:   Mat                    B;

2828:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2829:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2830:   MatPreallocated(mat);

2832:   PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
2833:   if (flg) {
2834:     newtype = mtype;
2835:   }
2836:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2837: 
2838:   PetscTypeCompare((PetscObject)mat,newtype,&sametype);
2839:   PetscStrcmp(newtype,"same",&issame);
2840:   if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) {
2841:     SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for inplace convertion currently");
2842:   }
2843:   if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) {
2844:     (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
2845:   } else {
2846:     PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL;
2847:     /* 
2848:        Order of precedence:
2849:        1) See if a specialized converter is known to the current matrix.
2850:        2) See if a specialized converter is known to the desired matrix class.
2851:        3) See if a good general converter is registered for the desired class
2852:           (as of 6/27/03 only MATMPIADJ falls into this category).
2853:        4) See if a good general converter is known for the current matrix.
2854:        5) Use a really basic converter.
2855:     */
2856:     PetscStrcpy(convname,"MatConvert_");
2857:     PetscStrcat(convname,mat->type_name);
2858:     PetscStrcat(convname,"_");
2859:     PetscStrcat(convname,newtype);
2860:     PetscStrcat(convname,"_C");
2861:     PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);

2863:     if (!conv) {
2864:       MatCreate(mat->comm,&B);
2865:       MatSetSizes(B,0,0,0,0);
2866:       MatSetType(B,newtype);
2867:       PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);
2868:       MatDestroy(B);
2869:       if (!conv) {
2870:         if (!MatConvertRegisterAllCalled) {
2871:           MatConvertRegisterAll(PETSC_NULL);
2872:         }
2873:         PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);
2874:         if (!conv) {
2875:           if (mat->ops->convert) {
2876:             conv = mat->ops->convert;
2877:           } else {
2878:             conv = MatConvert_Basic;
2879:           }
2880:         }
2881:       }
2882:     }
2883:     (*conv)(mat,newtype,reuse,M);
2884:   }
2885:   B = *M;
2886:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2887:   PetscObjectStateIncrease((PetscObject)B);
2888:   return(0);
2889: }


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

2897:    Collective on Mat

2899:    Input Parameters:
2900: +  mat - the matrix
2901: -  op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
2902:         values as well or not

2904:    Output Parameter:
2905: .  M - pointer to place new matrix

2907:    Level: intermediate

2909:    Concepts: matrices^duplicating

2911: .seealso: MatCopy(), MatConvert()
2912: @*/
2913: PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
2914: {
2916:   Mat            B;

2922:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2923:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2924:   MatPreallocated(mat);

2926:   *M  = 0;
2927:   PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2928:   if (!mat->ops->duplicate) {
2929:     SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
2930:   }
2931:   (*mat->ops->duplicate)(mat,op,M);
2932:   B = *M;
2933:   if (mat->mapping) {
2934:     MatSetLocalToGlobalMapping(B,mat->mapping);
2935:   }
2936:   if (mat->bmapping) {
2937:     MatSetLocalToGlobalMappingBlock(B,mat->bmapping);
2938:   }
2939:   if (mat->rmap){
2940:     if (!B->rmap){
2941:       PetscMapCreateMPI(B->comm,B->m,B->M,&B->rmap);
2942:     }
2943:     PetscMemcpy(B->rmap,mat->rmap,sizeof(PetscMap));
2944:   }
2945:   if (mat->cmap){
2946:     if (!B->cmap){
2947:       PetscMapCreateMPI(B->comm,B->n,B->N,&B->cmap);
2948:     }
2949:     PetscMemcpy(B->cmap,mat->cmap,sizeof(PetscMap));
2950:   }
2951:   PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2952:   PetscObjectStateIncrease((PetscObject)B);
2953:   return(0);
2954: }

2958: /*@ 
2959:    MatGetDiagonal - Gets the diagonal of a matrix.

2961:    Collective on Mat and Vec

2963:    Input Parameters:
2964: +  mat - the matrix
2965: -  v - the vector for storing the diagonal

2967:    Output Parameter:
2968: .  v - the diagonal of the matrix

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

2976:    Level: intermediate

2978:    Concepts: matrices^accessing diagonals

2980: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
2981: @*/
2982: PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v)
2983: {

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

2994:   (*mat->ops->getdiagonal)(mat,v);
2995:   PetscObjectStateIncrease((PetscObject)v);
2996:   return(0);
2997: }

3001: /*@ 
3002:    MatGetRowMax - Gets the maximum value (in absolute value) of each
3003:         row of the matrix

3005:    Collective on Mat and Vec

3007:    Input Parameters:
3008: .  mat - the matrix

3010:    Output Parameter:
3011: .  v - the vector for storing the maximums

3013:    Level: intermediate

3015:    Concepts: matrices^getting row maximums

3017: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
3018: @*/
3019: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v)
3020: {

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

3031:   (*mat->ops->getrowmax)(mat,v);
3032:   PetscObjectStateIncrease((PetscObject)v);
3033:   return(0);
3034: }

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

3041:    Collective on Mat

3043:    Input Parameter:
3044: .  mat - the matrix to transpose

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

3049:    Level: intermediate

3051:    Concepts: matrices^transposing

3053: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose()
3054: @*/
3055: PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B)
3056: {

3062:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3063:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3064:   if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3065:   MatPreallocated(mat);

3067:   PetscLogEventBegin(MAT_Transpose,mat,0,0,0);
3068:   (*mat->ops->transpose)(mat,B);
3069:   PetscLogEventEnd(MAT_Transpose,mat,0,0,0);
3070:   if (B) {PetscObjectStateIncrease((PetscObject)*B);}
3071:   return(0);
3072: }

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

3080:    Collective on Mat

3082:    Input Parameter:
3083: +  A - the matrix to test
3084: -  B - the matrix to test against, this can equal the first parameter

3086:    Output Parameters:
3087: .  flg - the result

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

3094:    Level: intermediate

3096:    Concepts: matrices^transposing, matrix^symmetry

3098: .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian()
3099: @*/
3100: PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg)
3101: {
3102:   PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*);

3108:   PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);
3109:   PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);
3110:   if (f && g) {
3111:     if (f==g) {
3112:       (*f)(A,B,tol,flg);
3113:     } else {
3114:       SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test");
3115:     }
3116:   }
3117:   return(0);
3118: }

3122: /*@C
3123:    MatPermute - Creates a new matrix with rows and columns permuted from the 
3124:    original.

3126:    Collective on Mat

3128:    Input Parameters:
3129: +  mat - the matrix to permute
3130: .  row - row permutation, each processor supplies only the permutation for its rows
3131: -  col - column permutation, each processor needs the entire column permutation, that is
3132:          this is the same size as the total number of columns in the matrix

3134:    Output Parameters:
3135: .  B - the permuted matrix

3137:    Level: advanced

3139:    Concepts: matrices^permuting

3141: .seealso: MatGetOrdering()
3142: @*/
3143: PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B)
3144: {

3153:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3154:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3155:   if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3156:   MatPreallocated(mat);

3158:   (*mat->ops->permute)(mat,row,col,B);
3159:   PetscObjectStateIncrease((PetscObject)*B);
3160:   return(0);
3161: }

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

3169:   Collective on Mat

3171:   Input Parameters:
3172: + A    - The matrix to permute
3173: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
3174: . frac - The half-bandwidth as a fraction of the total size, or 0.0
3175: . tol  - The drop tolerance
3176: . rowp - The row permutation
3177: - colp - The column permutation

3179:   Output Parameter:
3180: . B    - The permuted, sparsified matrix

3182:   Level: advanced

3184:   Note:
3185:   The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
3186:   restrict the half-bandwidth of the resulting matrix to 5% of the
3187:   total matrix size.

3189: .keywords: matrix, permute, sparsify

3191: .seealso: MatGetOrdering(), MatPermute()
3192: @*/
3193: PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
3194: {
3195:   IS                irowp, icolp;
3196:   PetscInt          *rows, *cols;
3197:   PetscInt          M, N, locRowStart, locRowEnd;
3198:   PetscInt          nz, newNz;
3199:   const PetscInt    *cwork;
3200:   PetscInt          *cnew;
3201:   const PetscScalar *vwork;
3202:   PetscScalar       *vnew;
3203:   PetscInt          bw, issize;
3204:   PetscInt          row, locRow, newRow, col, newCol;
3205:   PetscErrorCode    ierr;

3212:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
3213:   if (A->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
3214:   if (!A->ops->permutesparsify) {
3215:     MatGetSize(A, &M, &N);
3216:     MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
3217:     ISGetSize(rowp, &issize);
3218:     if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M);
3219:     ISGetSize(colp, &issize);
3220:     if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N);
3221:     ISInvertPermutation(rowp, 0, &irowp);
3222:     ISGetIndices(irowp, &rows);
3223:     ISInvertPermutation(colp, 0, &icolp);
3224:     ISGetIndices(icolp, &cols);
3225:     PetscMalloc(N * sizeof(PetscInt),         &cnew);
3226:     PetscMalloc(N * sizeof(PetscScalar), &vnew);

3228:     /* Setup bandwidth to include */
3229:     if (band == PETSC_DECIDE) {
3230:       if (frac <= 0.0)
3231:         bw = (PetscInt) (M * 0.05);
3232:       else
3233:         bw = (PetscInt) (M * frac);
3234:     } else {
3235:       if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
3236:       bw = band;
3237:     }

3239:     /* Put values into new matrix */
3240:     MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
3241:     for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
3242:       MatGetRow(A, row, &nz, &cwork, &vwork);
3243:       newRow   = rows[locRow]+locRowStart;
3244:       for(col = 0, newNz = 0; col < nz; col++) {
3245:         newCol = cols[cwork[col]];
3246:         if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
3247:           cnew[newNz] = newCol;
3248:           vnew[newNz] = vwork[col];
3249:           newNz++;
3250:         }
3251:       }
3252:       MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
3253:       MatRestoreRow(A, row, &nz, &cwork, &vwork);
3254:     }
3255:     PetscFree(cnew);
3256:     PetscFree(vnew);
3257:     MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
3258:     MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
3259:     ISRestoreIndices(irowp, &rows);
3260:     ISRestoreIndices(icolp, &cols);
3261:     ISDestroy(irowp);
3262:     ISDestroy(icolp);
3263:   } else {
3264:     (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
3265:   }
3266:   PetscObjectStateIncrease((PetscObject)*B);
3267:   return(0);
3268: }

3272: /*@
3273:    MatEqual - Compares two matrices.

3275:    Collective on Mat

3277:    Input Parameters:
3278: +  A - the first matrix
3279: -  B - the second matrix

3281:    Output Parameter:
3282: .  flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.

3284:    Level: intermediate

3286:    Concepts: matrices^equality between
3287: @*/
3288: PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg)
3289: {

3297:   MatPreallocated(B);
3300:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3301:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3302:   if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->M,B->M,A->N,B->N);
3303:   if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
3304:   if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
3305:   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);
3306:   MatPreallocated(A);

3308:   (*A->ops->equal)(A,B,flg);
3309:   return(0);
3310: }

3314: /*@
3315:    MatDiagonalScale - Scales a matrix on the left and right by diagonal
3316:    matrices that are stored as vectors.  Either of the two scaling
3317:    matrices can be PETSC_NULL.

3319:    Collective on Mat

3321:    Input Parameters:
3322: +  mat - the matrix to be scaled
3323: .  l - the left scaling vector (or PETSC_NULL)
3324: -  r - the right scaling vector (or PETSC_NULL)

3326:    Notes:
3327:    MatDiagonalScale() computes A = LAR, where
3328:    L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector)

3330:    Level: intermediate

3332:    Concepts: matrices^diagonal scaling
3333:    Concepts: diagonal scaling of matrices

3335: .seealso: MatScale()
3336: @*/
3337: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r)
3338: {

3344:   if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3347:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3348:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3349:   MatPreallocated(mat);

3351:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3352:   (*mat->ops->diagonalscale)(mat,l,r);
3353:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3354:   PetscObjectStateIncrease((PetscObject)mat);
3355:   return(0);
3356: }

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

3363:     Collective on Mat

3365:     Input Parameters:
3366: +   mat - the matrix to be scaled
3367: -   a  - the scaling value

3369:     Output Parameter:
3370: .   mat - the scaled matrix

3372:     Level: intermediate

3374:     Concepts: matrices^scaling all entries

3376: .seealso: MatDiagonalScale()
3377: @*/
3378: PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a)
3379: {

3385:   if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3386:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3387:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3388:   MatPreallocated(mat);

3390:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3391:   (*mat->ops->scale)(mat,a);
3392:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3393:   PetscObjectStateIncrease((PetscObject)mat);
3394:   return(0);
3395: }

3399: /*@ 
3400:    MatNorm - Calculates various norms of a matrix.

3402:    Collective on Mat

3404:    Input Parameters:
3405: +  mat - the matrix
3406: -  type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY

3408:    Output Parameters:
3409: .  nrm - the resulting norm 

3411:    Level: intermediate

3413:    Concepts: matrices^norm
3414:    Concepts: norm^of matrix
3415: @*/
3416: PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm)
3417: {


3425:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3426:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3427:   if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3428:   MatPreallocated(mat);

3430:   (*mat->ops->norm)(mat,type,nrm);
3431:   return(0);
3432: }

3434: /* 
3435:      This variable is used to prevent counting of MatAssemblyBegin() that
3436:    are called from within a MatAssemblyEnd().
3437: */
3438: static PetscInt MatAssemblyEnd_InUse = 0;
3441: /*@
3442:    MatAssemblyBegin - Begins assembling the matrix.  This routine should
3443:    be called after completing all calls to MatSetValues().

3445:    Collective on Mat

3447:    Input Parameters:
3448: +  mat - the matrix 
3449: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3450:  
3451:    Notes: 
3452:    MatSetValues() generally caches the values.  The matrix is ready to
3453:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3454:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3455:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3456:    using the matrix.

3458:    Level: beginner

3460:    Concepts: matrices^assembling

3462: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3463: @*/
3464: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type)
3465: {

3471:   MatPreallocated(mat);
3472:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3473:   if (mat->assembled) {
3474:     mat->was_assembled = PETSC_TRUE;
3475:     mat->assembled     = PETSC_FALSE;
3476:   }
3477:   if (!MatAssemblyEnd_InUse) {
3478:     PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
3479:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3480:     PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
3481:   } else {
3482:     if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3483:   }
3484:   return(0);
3485: }

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

3493:    Collective on Mat

3495:    Input Parameter:
3496: .  mat - the matrix 

3498:    Output Parameter:
3499: .  assembled - PETSC_TRUE or PETSC_FALSE

3501:    Level: advanced

3503:    Concepts: matrices^assembled?

3505: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3506: @*/
3507: PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled)
3508: {
3513:   *assembled = mat->assembled;
3514:   return(0);
3515: }

3519: /*
3520:     Processes command line options to determine if/how a matrix
3521:   is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3522: */
3523: PetscErrorCode MatView_Private(Mat mat)
3524: {
3525:   PetscErrorCode    ierr;
3526:   PetscTruth        flg;
3527:   static PetscTruth incall = PETSC_FALSE;

3530:   if (incall) return(0);
3531:   incall = PETSC_TRUE;
3532:   PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3533:     PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);
3534:     if (flg) {
3535:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3536:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3537:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3538:     }
3539:     PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);
3540:     if (flg) {
3541:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3542:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3543:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3544:     }
3545:     PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);
3546:     if (flg) {
3547:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3548:     }
3549:     PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);
3550:     if (flg) {
3551:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3552:       MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3553:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3554:     }
3555: #if defined(PETSC_USE_SOCKET_VIEWER)
3556:     PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);
3557:     if (flg) {
3558:       MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3559:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3560:     }
3561: #endif
3562:     PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);
3563:     if (flg) {
3564:       MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3565:       PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3566:     }
3567:   PetscOptionsEnd();
3568:   /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */
3569:   PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
3570:   if (flg) {
3571:     PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
3572:     if (flg) {
3573:       PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3574:     }
3575:     MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3576:     PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3577:     if (flg) {
3578:       PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3579:     }
3580:   }
3581:   incall = PETSC_FALSE;
3582:   return(0);
3583: }

3587: /*@
3588:    MatAssemblyEnd - Completes assembling the matrix.  This routine should
3589:    be called after MatAssemblyBegin().

3591:    Collective on Mat

3593:    Input Parameters:
3594: +  mat - the matrix 
3595: -  type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY

3597:    Options Database Keys:
3598: +  -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3599: .  -mat_view_info_detailed - Prints more detailed info
3600: .  -mat_view - Prints matrix in ASCII format
3601: .  -mat_view_matlab - Prints matrix in Matlab format
3602: .  -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3603: .  -display <name> - Sets display name (default is host)
3604: .  -draw_pause <sec> - Sets number of seconds to pause after display
3605: .  -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3606: .  -viewer_socket_machine <machine>
3607: .  -viewer_socket_port <port>
3608: .  -mat_view_binary - save matrix to file in binary format
3609: -  -viewer_binary_filename <name>

3611:    Notes: 
3612:    MatSetValues() generally caches the values.  The matrix is ready to
3613:    use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3614:    Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3615:    in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3616:    using the matrix.

3618:    Level: beginner

3620: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3621: @*/
3622: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type)
3623: {
3624:   PetscErrorCode  ierr;
3625:   static PetscInt inassm = 0;
3626:   PetscTruth      flg;


3632:   inassm++;
3633:   MatAssemblyEnd_InUse++;
3634:   if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3635:     PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
3636:     if (mat->ops->assemblyend) {
3637:       (*mat->ops->assemblyend)(mat,type);
3638:     }
3639:     PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
3640:   } else {
3641:     if (mat->ops->assemblyend) {
3642:       (*mat->ops->assemblyend)(mat,type);
3643:     }
3644:   }

3646:   /* Flush assembly is not a true assembly */
3647:   if (type != MAT_FLUSH_ASSEMBLY) {
3648:     mat->assembled  = PETSC_TRUE; mat->num_ass++;
3649:   }
3650:   mat->insertmode = NOT_SET_VALUES;
3651:   MatAssemblyEnd_InUse--;
3652:   PetscObjectStateIncrease((PetscObject)mat);
3653:   if (!mat->symmetric_eternal) {
3654:     mat->symmetric_set              = PETSC_FALSE;
3655:     mat->hermitian_set              = PETSC_FALSE;
3656:     mat->structurally_symmetric_set = PETSC_FALSE;
3657:   }
3658:   if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3659:     MatView_Private(mat);
3660:     PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);
3661:     if (flg) {
3662:       PetscReal tol = 0.0;
3663:       PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);
3664:       MatIsSymmetric(mat,tol,&flg);
3665:       if (flg) {
3666:         PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %g)\n",tol);
3667:       } else {
3668:         PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %g)\n",tol);
3669:       }
3670:     }
3671:   }
3672:   inassm--;
3673:   PetscOptionsHasName(mat->prefix,"-help",&flg);
3674:   if (flg) {
3675:     MatPrintHelp(mat);
3676:   }
3677:   return(0);
3678: }


3683: /*@
3684:    MatCompress - Tries to store the matrix in as little space as 
3685:    possible.  May fail if memory is already fully used, since it
3686:    tries to allocate new space.

3688:    Collective on Mat

3690:    Input Parameters:
3691: .  mat - the matrix 

3693:    Level: advanced

3695: @*/
3696: PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat)
3697: {

3703:   MatPreallocated(mat);
3704:   if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3705:   return(0);
3706: }

3710: /*@
3711:    MatSetOption - Sets a parameter option for a matrix. Some options
3712:    may be specific to certain storage formats.  Some options
3713:    determine how values will be inserted (or added). Sorted, 
3714:    row-oriented input will generally assemble the fastest. The default
3715:    is row-oriented, nonsorted input. 

3717:    Collective on Mat

3719:    Input Parameters:
3720: +  mat - the matrix 
3721: -  option - the option, one of those listed below (and possibly others),
3722:              e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

3724:    Options Describing Matrix Structure:
3725: +    MAT_SYMMETRIC - symmetric in terms of both structure and value
3726: .    MAT_HERMITIAN - transpose is the complex conjugation
3727: .    MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
3728: .    MAT_NOT_SYMMETRIC - not symmetric in value
3729: .    MAT_NOT_HERMITIAN - transpose is not the complex conjugation
3730: .    MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure
3731: .    MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag
3732:                             you set to be kept with all future use of the matrix
3733:                             including after MatAssemblyBegin/End() which could
3734:                             potentially change the symmetry structure, i.e. you 
3735:                             KNOW the matrix will ALWAYS have the property you set.
3736: -    MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 
3737:                                 flags you set will be dropped (in case potentially
3738:                                 the symmetry etc was lost).

3740:    Options For Use with MatSetValues():
3741:    Insert a logically dense subblock, which can be
3742: +    MAT_ROW_ORIENTED - row-oriented (default)
3743: .    MAT_COLUMN_ORIENTED - column-oriented
3744: .    MAT_ROWS_SORTED - sorted by row
3745: .    MAT_ROWS_UNSORTED - not sorted by row (default)
3746: .    MAT_COLUMNS_SORTED - sorted by column
3747: -    MAT_COLUMNS_UNSORTED - not sorted by column (default)

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

3753:    When (re)assembling a matrix, we can restrict the input for
3754:    efficiency/debugging purposes.  These options include
3755: +    MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
3756:         allowed if they generate a new nonzero
3757: .    MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
3758: .    MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
3759:          they generate a nonzero in a new diagonal (for block diagonal format only)
3760: .    MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
3761: .    MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
3762: .    MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
3763: -    MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly

3765:    Notes:
3766:    Some options are relevant only for particular matrix types and
3767:    are thus ignored by others.  Other options are not supported by
3768:    certain matrix types and will generate an error message if set.

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

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

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

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

3793:    MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 
3794:    other processors should be dropped, rather than stashed.
3795:    This is useful if you know that the "owning" processor is also 
3796:    always generating the correct matrix entries, so that PETSc need
3797:    not transfer duplicate entries generated on another processor.
3798:    
3799:    MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
3800:    searches during matrix assembly. When this flag is set, the hash table
3801:    is created during the first Matrix Assembly. This hash table is
3802:    used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
3803:    to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 
3804:    should be used with MAT_USE_HASH_TABLE flag. This option is currently
3805:    supported by MATMPIBAIJ format only.

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

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

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

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

3819:    Level: intermediate

3821:    Concepts: matrices^setting options

3823: @*/
3824: PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op)
3825: {

3831:   MatPreallocated(mat);
3832:   switch (op) {
3833:   case MAT_SYMMETRIC:
3834:     mat->symmetric                  = PETSC_TRUE;
3835:     mat->structurally_symmetric     = PETSC_TRUE;
3836:     mat->symmetric_set              = PETSC_TRUE;
3837:     mat->structurally_symmetric_set = PETSC_TRUE;
3838:     break;
3839:   case MAT_HERMITIAN:
3840:     mat->hermitian                  = PETSC_TRUE;
3841:     mat->structurally_symmetric     = PETSC_TRUE;
3842:     mat->hermitian_set              = PETSC_TRUE;
3843:     mat->structurally_symmetric_set = PETSC_TRUE;
3844:     break;
3845:   case MAT_STRUCTURALLY_SYMMETRIC:
3846:     mat->structurally_symmetric     = PETSC_TRUE;
3847:     mat->structurally_symmetric_set = PETSC_TRUE;
3848:     break;
3849:   case MAT_NOT_SYMMETRIC:
3850:     mat->symmetric                  = PETSC_FALSE;
3851:     mat->symmetric_set              = PETSC_TRUE;
3852:     break;
3853:   case MAT_NOT_HERMITIAN:
3854:     mat->hermitian                  = PETSC_FALSE;
3855:     mat->hermitian_set              = PETSC_TRUE;
3856:     break;
3857:   case MAT_NOT_STRUCTURALLY_SYMMETRIC:
3858:     mat->structurally_symmetric     = PETSC_FALSE;
3859:     mat->structurally_symmetric_set = PETSC_TRUE;
3860:     break;
3861:   case MAT_SYMMETRY_ETERNAL:
3862:     mat->symmetric_eternal          = PETSC_TRUE;
3863:     break;
3864:   case MAT_NOT_SYMMETRY_ETERNAL:
3865:     mat->symmetric_eternal          = PETSC_FALSE;
3866:     break;
3867:   default:
3868:     break;
3869:   }
3870:   if (mat->ops->setoption) {
3871:     (*mat->ops->setoption)(mat,op);
3872:   }
3873:   return(0);
3874: }

3878: /*@
3879:    MatZeroEntries - Zeros all entries of a matrix.  For sparse matrices
3880:    this routine retains the old nonzero structure.

3882:    Collective on Mat

3884:    Input Parameters:
3885: .  mat - the matrix 

3887:    Level: intermediate

3889:    Concepts: matrices^zeroing

3891: .seealso: MatZeroRows()
3892: @*/
3893: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat)
3894: {

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

3905:   PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
3906:   (*mat->ops->zeroentries)(mat);
3907:   PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
3908:   PetscObjectStateIncrease((PetscObject)mat);
3909:   return(0);
3910: }

3914: /*@C
3915:    MatZeroRows - Zeros all entries (except possibly the main diagonal)
3916:    of a set of rows of a matrix.

3918:    Collective on Mat

3920:    Input Parameters:
3921: +  mat - the matrix
3922: .  numRows - the number of rows to remove
3923: .  rows - the global row indices
3924: -  diag - value put in all diagonals of eliminated rows

3926:    Notes:
3927:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
3928:    but does not release memory.  For the dense and block diagonal
3929:    formats this does not alter the nonzero structure.

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

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

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

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

3946:    Level: intermediate

3948:    Concepts: matrices^zeroing rows

3950: .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
3951: @*/
3952: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
3953: {

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

3965:   (*mat->ops->zerorows)(mat,numRows,rows,diag);
3966:   MatView_Private(mat);
3967:   PetscObjectStateIncrease((PetscObject)mat);
3968:   return(0);
3969: }

3973: /*@C
3974:    MatZeroRowsIS - Zeros all entries (except possibly the main diagonal)
3975:    of a set of rows of a matrix.

3977:    Collective on Mat

3979:    Input Parameters:
3980: +  mat - the matrix
3981: .  is - index set of rows to remove
3982: -  diag - value put in all diagonals of eliminated rows

3984:    Notes:
3985:    For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
3986:    but does not release memory.  For the dense and block diagonal
3987:    formats this does not alter the nonzero structure.

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

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

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

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

4004:    Level: intermediate

4006:    Concepts: matrices^zeroing rows

4008: .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4009: @*/
4010: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag)
4011: {
4012:   PetscInt       numRows;
4013:   PetscInt       *rows;

4020:   ISGetLocalSize(is,&numRows);
4021:   ISGetIndices(is,&rows);
4022:   MatZeroRows(mat,numRows,rows,diag);
4023:   ISRestoreIndices(is,&rows);
4024:   return(0);
4025: }

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

4033:    Collective on Mat

4035:    Input Parameters:
4036: +  mat - the matrix
4037: .  numRows - the number of rows to remove
4038: .  rows - the global row indices
4039: -  diag - value put in all diagonals of eliminated rows

4041:    Notes:
4042:    Before calling MatZeroRowsLocal(), the user must first set the
4043:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4045:    For the AIJ matrix formats this removes the old nonzero structure,
4046:    but does not release memory.  For the dense and block diagonal
4047:    formats this does not alter the nonzero structure.

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

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

4057:    Level: intermediate

4059:    Concepts: matrices^zeroing

4061: .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4062: @*/
4063: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4064: {

4071:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4072:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4073:   MatPreallocated(mat);

4075:   if (mat->ops->zerorowslocal) {
4076:     (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);
4077:   } else {
4078:     IS is, newis;
4079:     PetscInt *newRows;

4081:     if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
4082:     ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);
4083:     ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
4084:     ISGetIndices(newis,&newRows);
4085:     (*mat->ops->zerorows)(mat,numRows,newRows,diag);
4086:     ISRestoreIndices(newis,&newRows);
4087:     ISDestroy(newis);
4088:     ISDestroy(is);
4089:   }
4090:   PetscObjectStateIncrease((PetscObject)mat);
4091:   return(0);
4092: }

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

4100:    Collective on Mat

4102:    Input Parameters:
4103: +  mat - the matrix
4104: .  is - index set of rows to remove
4105: -  diag - value put in all diagonals of eliminated rows

4107:    Notes:
4108:    Before calling MatZeroRowsLocal(), the user must first set the
4109:    local-to-global mapping by calling MatSetLocalToGlobalMapping().

4111:    For the AIJ matrix formats this removes the old nonzero structure,
4112:    but does not release memory.  For the dense and block diagonal
4113:    formats this does not alter the nonzero structure.

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

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

4123:    Level: intermediate

4125:    Concepts: matrices^zeroing

4127: .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4128: @*/
4129: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag)
4130: {
4132:   PetscInt       numRows;
4133:   PetscInt       *rows;

4139:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4140:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4141:   MatPreallocated(mat);

4143:   ISGetLocalSize(is,&numRows);
4144:   ISGetIndices(is,&rows);
4145:   MatZeroRowsLocal(mat,numRows,rows,diag);
4146:   ISRestoreIndices(is,&rows);
4147:   return(0);
4148: }

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

4155:    Not Collective

4157:    Input Parameter:
4158: .  mat - the matrix

4160:    Output Parameters:
4161: +  m - the number of global rows
4162: -  n - the number of global columns

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

4166:    Level: beginner

4168:    Concepts: matrices^size

4170: .seealso: MatGetLocalSize()
4171: @*/
4172: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n)
4173: {
4176:   if (m) *m = mat->M;
4177:   if (n) *n = mat->N;
4178:   return(0);
4179: }

4183: /*@
4184:    MatGetLocalSize - Returns the number of rows and columns in a matrix
4185:    stored locally.  This information may be implementation dependent, so
4186:    use with care.

4188:    Not Collective

4190:    Input Parameters:
4191: .  mat - the matrix

4193:    Output Parameters:
4194: +  m - the number of local rows
4195: -  n - the number of local columns

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

4199:    Level: beginner

4201:    Concepts: matrices^local size

4203: .seealso: MatGetSize()
4204: @*/
4205: PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n)
4206: {
4211:   if (m) *m = mat->m;
4212:   if (n) *n = mat->n;
4213:   return(0);
4214: }

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

4224:    Not Collective

4226:    Input Parameters:
4227: .  mat - the matrix

4229:    Output Parameters:
4230: +  m - the global index of the first local row
4231: -  n - one more than the global index of the last local row

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

4235:    Level: beginner

4237:    Concepts: matrices^row ownership
4238: @*/
4239: PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n)
4240: {

4248:   MatPreallocated(mat);
4249:   PetscMapGetLocalRange(mat->rmap,m,n);
4250:   return(0);
4251: }

4255: /*@  
4256:    MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
4257:    Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 
4258:    to complete the factorization.

4260:    Collective on Mat

4262:    Input Parameters:
4263: +  mat - the matrix
4264: .  row - row permutation
4265: .  column - column permutation
4266: -  info - structure containing 
4267: $      levels - number of levels of fill.
4268: $      expected fill - as ratio of original fill.
4269: $      1 or 0 - indicating force fill on diagonal (improves robustness for matrices
4270:                 missing diagonal entries)

4272:    Output Parameters:
4273: .  fact - new matrix that has been symbolically factored

4275:    Notes:
4276:    See the users manual for additional information about
4277:    choosing the fill factor for better efficiency.

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

4283:    Level: developer

4285:   Concepts: matrices^symbolic LU factorization
4286:   Concepts: matrices^factorization
4287:   Concepts: LU^symbolic factorization

4289: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4290:           MatGetOrdering(), MatFactorInfo

4292: @*/
4293: PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
4294: {

4304:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels);
4305:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
4306:   if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ILU",mat->type_name);
4307:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4308:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4309:   MatPreallocated(mat);

4311:   PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
4312:   (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
4313:   PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
4314:   return(0);
4315: }

4319: /*@  
4320:    MatICCFactorSymbolic - Performs symbolic incomplete
4321:    Cholesky factorization for a symmetric matrix.  Use 
4322:    MatCholeskyFactorNumeric() to complete the factorization.

4324:    Collective on Mat

4326:    Input Parameters:
4327: +  mat - the matrix
4328: .  perm - row and column permutation
4329: -  info - structure containing 
4330: $      levels - number of levels of fill.
4331: $      expected fill - as ratio of original fill.

4333:    Output Parameter:
4334: .  fact - the factored matrix

4336:    Notes:
4337:    Currently only no-fill factorization is supported.

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

4343:    Level: developer

4345:   Concepts: matrices^symbolic incomplete Cholesky factorization
4346:   Concepts: matrices^factorization
4347:   Concepts: Cholsky^symbolic factorization

4349: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
4350: @*/
4351: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
4352: {

4361:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4362:   if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels);
4363:   if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
4364:   if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s  symbolic ICC",mat->type_name);
4365:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4366:   MatPreallocated(mat);

4368:   PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
4369:   (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
4370:   PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
4371:   return(0);
4372: }

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

4382:    Not Collective

4384:    Input Parameter:
4385: .  mat - the matrix

4387:    Output Parameter:
4388: .  v - the location of the values


4391:    Fortran Note:
4392:    This routine is used differently from Fortran, e.g.,
4393: .vb
4394:         Mat         mat
4395:         PetscScalar mat_array(1)
4396:         PetscOffset i_mat
4397:         PetscErrorCode ierr
4398:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4404:         [... other code ...]
4405:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4406: .ve

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

4411:    Level: advanced

4413:    Concepts: matrices^access array

4415: .seealso: MatRestoreArray(), MatGetArrayF90()
4416: @*/
4417: PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[])
4418: {

4425:   if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4426:   MatPreallocated(mat);
4427:   (*mat->ops->getarray)(mat,v);
4428:   return(0);
4429: }

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

4436:    Not Collective

4438:    Input Parameter:
4439: +  mat - the matrix
4440: -  v - the location of the values

4442:    Fortran Note:
4443:    This routine is used differently from Fortran, e.g.,
4444: .vb
4445:         Mat         mat
4446:         PetscScalar mat_array(1)
4447:         PetscOffset i_mat
4448:         PetscErrorCode ierr
4449:         call MatGetArray(mat,mat_array,i_mat,ierr)

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

4455:         [... other code ...]
4456:         call MatRestoreArray(mat,mat_array,i_mat,ierr)
4457: .ve

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

4462:    Level: advanced

4464: .seealso: MatGetArray(), MatRestoreArrayF90()
4465: @*/
4466: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[])
4467: {

4474: #if defined(PETSC_USE_DEBUG)
4475:   CHKMEMQ;
4476: #endif
4477:   if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4478:   (*mat->ops->restorearray)(mat,v);
4479:   PetscObjectStateIncrease((PetscObject)mat);
4480:   return(0);
4481: }

4485: /*@C
4486:    MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
4487:    points to an array of valid matrices, they may be reused to store the new
4488:    submatrices.

4490:    Collective on Mat

4492:    Input Parameters:
4493: +  mat - the matrix
4494: .  n   - the number of submatrixes to be extracted (on this processor, may be zero)
4495: .  irow, icol - index sets of rows and columns to extract
4496: -  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

4498:    Output Parameter:
4499: .  submat - the array of submatrices

4501:    Notes:
4502:    MatGetSubMatrices() can extract only sequential submatrices
4503:    (from both sequential and parallel matrices). Use MatGetSubMatrix()
4504:    to extract a parallel submatrix.

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

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

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

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

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

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

4528:    Level: advanced

4530:    Concepts: matrices^accessing submatrices
4531:    Concepts: submatrices

4533: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
4534: @*/
4535: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
4536: {
4538:   PetscInt        i;
4539:   PetscTruth      eq;

4544:   if (n) {
4549:   }
4551:   if (n && scall == MAT_REUSE_MATRIX) {
4554:   }
4555:   if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4556:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4557:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4558:   MatPreallocated(mat);

4560:   PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
4561:   (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
4562:   PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
4563:   for (i=0; i<n; i++) {
4564:     if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) {
4565:       ISEqual(irow[i],icol[i],&eq);
4566:       if (eq) {
4567:         if (mat->symmetric){
4568:           MatSetOption((*submat)[i],MAT_SYMMETRIC);
4569:         } else if (mat->hermitian) {
4570:           MatSetOption((*submat)[i],MAT_HERMITIAN);
4571:         } else if (mat->structurally_symmetric) {
4572:           MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);
4573:         }
4574:       }
4575:     }
4576:   }
4577:   return(0);
4578: }

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

4585:    Collective on Mat

4587:    Input Parameters:
4588: +  n - the number of local matrices
4589: -  mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
4590:                        sequence of MatGetSubMatrices())

4592:    Level: advanced

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

4596: .seealso: MatGetSubMatrices()
4597: @*/
4598: PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[])
4599: {
4601:   PetscInt       i;

4604:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n);
4606:   for (i=0; i<n; i++) {
4607:     MatDestroy((*mat)[i]);
4608:   }
4609:   /* memory is allocated even if n = 0 */
4610:   PetscFree(*mat);
4611:   return(0);
4612: }

4616: /*@
4617:    MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4618:    replaces the index sets by larger ones that represent submatrices with
4619:    additional overlap.

4621:    Collective on Mat

4623:    Input Parameters:
4624: +  mat - the matrix
4625: .  n   - the number of index sets
4626: .  is  - the array of index sets (these index sets will changed during the call)
4627: -  ov  - the additional overlap requested

4629:    Level: developer

4631:    Concepts: overlap
4632:    Concepts: ASM^computing overlap

4634: .seealso: MatGetSubMatrices()
4635: @*/
4636: PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov)
4637: {

4643:   if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n);
4644:   if (n) {
4647:   }
4648:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4649:   if (mat->factor)     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4650:   MatPreallocated(mat);

4652:   if (!ov) return(0);
4653:   if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4654:   PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
4655:   (*mat->ops->increaseoverlap)(mat,n,is,ov);
4656:   PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
4657:   return(0);
4658: }

4662: /*@
4663:    MatPrintHelp - Prints all the options for the matrix.

4665:    Collective on Mat

4667:    Input Parameter:
4668: .  mat - the matrix 

4670:    Options Database Keys:
4671: +  -help - Prints matrix options
4672: -  -h - Prints matrix options

4674:    Level: developer

4676: .seealso: MatCreate(), MatCreateXXX()
4677: @*/
4678: PetscErrorCode PETSCMAT_DLLEXPORT MatPrintHelp(Mat mat)
4679: {
4680:   static PetscTruth called = PETSC_FALSE;
4681:   PetscErrorCode    ierr;

4686:   MatPreallocated(mat);

4688:   if (!called) {
4689:     if (mat->ops->printhelp) {
4690:       (*mat->ops->printhelp)(mat);
4691:     }
4692:     called = PETSC_TRUE;
4693:   }
4694:   return(0);
4695: }

4699: /*@
4700:    MatGetBlockSize - Returns the matrix block size; useful especially for the
4701:    block row and block diagonal formats.
4702:    
4703:    Not Collective

4705:    Input Parameter:
4706: .  mat - the matrix

4708:    Output Parameter:
4709: .  bs - block size

4711:    Notes:
4712:    Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4713:    Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ

4715:    Level: intermediate

4717:    Concepts: matrices^block size

4719: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4720: @*/
4721: PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs)
4722: {

4729:   MatPreallocated(mat);
4730:   *bs = mat->bs;
4731:   return(0);
4732: }

4736: /*@
4737:    MatSetBlockSize - Sets the matrix block size; for many matrix types you 
4738:      cannot use this and MUST set the blocksize when you preallocate the matrix
4739:    
4740:    Not Collective

4742:    Input Parameters:
4743: +  mat - the matrix
4744: -  bs - block size

4746:    Notes:
4747:      Only works for shell and AIJ matrices

4749:    Level: intermediate

4751:    Concepts: matrices^block size

4753: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize()
4754: @*/
4755: PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs)
4756: {

4762:   MatPreallocated(mat);
4763:   if (mat->ops->setblocksize) {
4764:     mat->bs = bs;
4765:     (*mat->ops->setblocksize)(mat,bs);
4766:   } else {
4767:     SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name);
4768:   }
4769:   return(0);
4770: }

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

4777:    Collective on Mat

4779:     Input Parameters:
4780: +   mat - the matrix
4781: .   shift -  0 or 1 indicating we want the indices starting at 0 or 1
4782: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4783:                 symmetrized

4785:     Output Parameters:
4786: +   n - number of rows in the (possibly compressed) matrix
4787: .   ia - the row pointers
4788: .   ja - the column indices
4789: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

4791:     Level: developer

4793: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
4794: @*/
4795: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
4796: {

4806:   MatPreallocated(mat);
4807:   if (!mat->ops->getrowij) *done = PETSC_FALSE;
4808:   else {
4809:     *done = PETSC_TRUE;
4810:     (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
4811:   }
4812:   return(0);
4813: }

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

4820:     Collective on Mat

4822:     Input Parameters:
4823: +   mat - the matrix
4824: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4825: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4826:                 symmetrized

4828:     Output Parameters:
4829: +   n - number of columns in the (possibly compressed) matrix
4830: .   ia - the column pointers
4831: .   ja - the row indices
4832: -   done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned

4834:     Level: developer

4836: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
4837: @*/
4838: PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
4839: {

4849:   MatPreallocated(mat);
4850:   if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
4851:   else {
4852:     *done = PETSC_TRUE;
4853:     (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
4854:   }
4855:   return(0);
4856: }

4860: /*@C
4861:     MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
4862:     MatGetRowIJ().

4864:     Collective on Mat

4866:     Input Parameters:
4867: +   mat - the matrix
4868: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4869: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4870:                 symmetrized

4872:     Output Parameters:
4873: +   n - size of (possibly compressed) matrix
4874: .   ia - the row pointers
4875: .   ja - the column indices
4876: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

4878:     Level: developer

4880: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
4881: @*/
4882: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
4883: {

4892:   MatPreallocated(mat);

4894:   if (!mat->ops->restorerowij) *done = PETSC_FALSE;
4895:   else {
4896:     *done = PETSC_TRUE;
4897:     (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
4898:   }
4899:   return(0);
4900: }

4904: /*@C
4905:     MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
4906:     MatGetColumnIJ().

4908:     Collective on Mat

4910:     Input Parameters:
4911: +   mat - the matrix
4912: .   shift - 1 or zero indicating we want the indices starting at 0 or 1
4913: -   symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4914:                 symmetrized

4916:     Output Parameters:
4917: +   n - size of (possibly compressed) matrix
4918: .   ia - the column pointers
4919: .   ja - the row indices
4920: -   done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned

4922:     Level: developer

4924: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
4925: @*/
4926: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
4927: {

4936:   MatPreallocated(mat);

4938:   if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
4939:   else {
4940:     *done = PETSC_TRUE;
4941:     (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
4942:   }
4943:   return(0);
4944: }

4948: /*@C
4949:     MatColoringPatch -Used inside matrix coloring routines that 
4950:     use MatGetRowIJ() and/or MatGetColumnIJ().

4952:     Collective on Mat

4954:     Input Parameters:
4955: +   mat - the matrix
4956: .   n   - number of colors
4957: -   colorarray - array indicating color for each column

4959:     Output Parameters:
4960: .   iscoloring - coloring generated using colorarray information

4962:     Level: developer

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

4966: @*/
4967: PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt n,PetscInt ncolors,ISColoringValue colorarray[],ISColoring *iscoloring)
4968: {

4976:   MatPreallocated(mat);

4978:   if (!mat->ops->coloringpatch){
4979:     ISColoringCreate(mat->comm,n,colorarray,iscoloring);
4980:   } else {
4981:     (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);
4982:   }
4983:   return(0);
4984: }


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

4992:    Collective on Mat

4994:    Input Parameter:
4995: .  mat - the factored matrix to be reset

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

5004:    Note that one can specify in-place ILU(0) factorization by calling 
5005: .vb
5006:      PCType(pc,PCILU);
5007:      PCILUSeUseInPlace(pc);
5008: .ve
5009:    or by using the options -pc_type ilu -pc_ilu_in_place

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

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

5021:    Level: developer

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

5025:    Concepts: matrices^unfactored

5027: @*/
5028: PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat)
5029: {

5035:   MatPreallocated(mat);
5036:   mat->factor = 0;
5037:   if (!mat->ops->setunfactored) return(0);
5038:   (*mat->ops->setunfactored)(mat);
5039:   return(0);
5040: }

5042: /*MC
5043:     MatGetArrayF90 - Accesses a matrix array from Fortran90.

5045:     Synopsis:
5046:     MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5048:     Not collective

5050:     Input Parameter:
5051: .   x - matrix

5053:     Output Parameters:
5054: +   xx_v - the Fortran90 pointer to the array
5055: -   ierr - error code

5057:     Example of Usage: 
5058: .vb
5059:       PetscScalar, pointer xx_v(:)
5060:       ....
5061:       call MatGetArrayF90(x,xx_v,ierr)
5062:       a = xx_v(3)
5063:       call MatRestoreArrayF90(x,xx_v,ierr)
5064: .ve

5066:     Notes:
5067:     Not yet supported for all F90 compilers

5069:     Level: advanced

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

5073:     Concepts: matrices^accessing array

5075: M*/

5077: /*MC
5078:     MatRestoreArrayF90 - Restores a matrix array that has been
5079:     accessed with MatGetArrayF90().

5081:     Synopsis:
5082:     MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)

5084:     Not collective

5086:     Input Parameters:
5087: +   x - matrix
5088: -   xx_v - the Fortran90 pointer to the array

5090:     Output Parameter:
5091: .   ierr - error code

5093:     Example of Usage: 
5094: .vb
5095:        PetscScalar, pointer xx_v(:)
5096:        ....
5097:        call MatGetArrayF90(x,xx_v,ierr)
5098:        a = xx_v(3)
5099:        call MatRestoreArrayF90(x,xx_v,ierr)
5100: .ve
5101:    
5102:     Notes:
5103:     Not yet supported for all F90 compilers

5105:     Level: advanced

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

5109: M*/


5114: /*@
5115:     MatGetSubMatrix - Gets a single submatrix on the same number of processors
5116:                       as the original matrix.

5118:     Collective on Mat

5120:     Input Parameters:
5121: +   mat - the original matrix
5122: .   isrow - rows this processor should obtain
5123: .   iscol - columns for all processors you wish to keep
5124: .   csize - number of columns "local" to this processor (does nothing for sequential 
5125:             matrices). This should match the result from VecGetLocalSize(x,...) if you 
5126:             plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5127: -   cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX

5129:     Output Parameter:
5130: .   newmat - the new submatrix, of the same type as the old

5132:     Level: advanced

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

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

5142:     Concepts: matrices^submatrices

5144: .seealso: MatGetSubMatrices(), ISAllGather()
5145: @*/
5146: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat)
5147: {
5149:   PetscMPIInt    size;
5150:   Mat            *local;

5159:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5160:   MatPreallocated(mat);
5161:   MPI_Comm_size(mat->comm,&size);

5163:   /* if original matrix is on just one processor then use submatrix generated */
5164:   if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
5165:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
5166:     return(0);
5167:   } else if (!mat->ops->getsubmatrix && size == 1) {
5168:     MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
5169:     *newmat = *local;
5170:     PetscFree(local);
5171:     return(0);
5172:   }

5174:   if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5175:   (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
5176:   PetscObjectStateIncrease((PetscObject)*newmat);
5177:   return(0);
5178: }

5182: /*@C
5183:    MatGetPetscMaps - Returns the maps associated with the matrix.

5185:    Not Collective

5187:    Input Parameter:
5188: .  mat - the matrix

5190:    Output Parameters:
5191: +  rmap - the row (right) map
5192: -  cmap - the column (left) map  

5194:    Level: developer

5196:    Concepts: maps^getting from matrix

5198: @*/
5199: PetscErrorCode PETSCMAT_DLLEXPORT MatGetPetscMaps(Mat mat,PetscMap *rmap,PetscMap *cmap)
5200: {

5206:   MatPreallocated(mat);
5207:   (*mat->ops->getmaps)(mat,rmap,cmap);
5208:   return(0);
5209: }

5211: /*
5212:       Version that works for all PETSc matrices
5213: */
5216: PetscErrorCode MatGetPetscMaps_Petsc(Mat mat,PetscMap *rmap,PetscMap *cmap)
5217: {
5219:   if (rmap) *rmap = mat->rmap;
5220:   if (cmap) *cmap = mat->cmap;
5221:   return(0);
5222: }

5226: /*@
5227:    MatStashSetInitialSize - sets the sizes of the matrix stash, that is
5228:    used during the assembly process to store values that belong to 
5229:    other processors.

5231:    Not Collective

5233:    Input Parameters:
5234: +  mat   - the matrix
5235: .  size  - the initial size of the stash.
5236: -  bsize - the initial size of the block-stash(if used).

5238:    Options Database Keys:
5239: +   -matstash_initial_size <size> or <size0,size1,...sizep-1>
5240: -   -matstash_block_initial_size <bsize>  or <bsize0,bsize1,...bsizep-1>

5242:    Level: intermediate

5244:    Notes: 
5245:      The block-stash is used for values set with MatSetValuesBlocked() while
5246:      the stash is used for values set with MatSetValues()

5248:      Run with the option -log_info and look for output of the form
5249:      MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
5250:      to determine the appropriate value, MM, to use for size and 
5251:      MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
5252:      to determine the value, BMM to use for bsize

5254:    Concepts: stash^setting matrix size
5255:    Concepts: matrices^stash

5257: @*/
5258: PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize)
5259: {

5265:   MatStashSetInitialSize_Private(&mat->stash,size);
5266:   MatStashSetInitialSize_Private(&mat->bstash,bsize);
5267:   return(0);
5268: }

5272: /*@
5273:    MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 
5274:      the matrix

5276:    Collective on Mat

5278:    Input Parameters:
5279: +  mat   - the matrix
5280: .  x,y - the vectors
5281: -  w - where the result is stored

5283:    Level: intermediate

5285:    Notes: 
5286:     w may be the same vector as y. 

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

5291:     Concepts: interpolation

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

5295: @*/
5296: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
5297: {
5299:   PetscInt       M,N;

5307:   MatPreallocated(A);
5308:   MatGetSize(A,&M,&N);
5309:   if (N > M) {
5310:     MatMultTransposeAdd(A,x,y,w);
5311:   } else {
5312:     MatMultAdd(A,x,y,w);
5313:   }
5314:   return(0);
5315: }

5319: /*@
5320:    MatInterpolate - y = A*x or A'*x depending on the shape of 
5321:      the matrix

5323:    Collective on Mat

5325:    Input Parameters:
5326: +  mat   - the matrix
5327: -  x,y - the vectors

5329:    Level: intermediate

5331:    Notes: 
5332:     This allows one to use either the restriction or interpolation (its transpose)
5333:     matrix to do the interpolation

5335:    Concepts: matrices^interpolation

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

5339: @*/
5340: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y)
5341: {
5343:   PetscInt       M,N;

5350:   MatPreallocated(A);
5351:   MatGetSize(A,&M,&N);
5352:   if (N > M) {
5353:     MatMultTranspose(A,x,y);
5354:   } else {
5355:     MatMult(A,x,y);
5356:   }
5357:   return(0);
5358: }

5362: /*@
5363:    MatRestrict - y = A*x or A'*x

5365:    Collective on Mat

5367:    Input Parameters:
5368: +  mat   - the matrix
5369: -  x,y - the vectors

5371:    Level: intermediate

5373:    Notes: 
5374:     This allows one to use either the restriction or interpolation (its transpose)
5375:     matrix to do the restriction

5377:    Concepts: matrices^restriction

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

5381: @*/
5382: PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y)
5383: {
5385:   PetscInt       M,N;

5392:   MatPreallocated(A);

5394:   MatGetSize(A,&M,&N);
5395:   if (N > M) {
5396:     MatMult(A,x,y);
5397:   } else {
5398:     MatMultTranspose(A,x,y);
5399:   }
5400:   return(0);
5401: }

5405: /*@C
5406:    MatNullSpaceAttach - attaches a null space to a matrix.
5407:         This null space will be removed from the resulting vector whenever
5408:         MatMult() is called

5410:    Collective on Mat

5412:    Input Parameters:
5413: +  mat - the matrix
5414: -  nullsp - the null space object

5416:    Level: developer

5418:    Notes:
5419:       Overwrites any previous null space that may have been attached

5421:    Concepts: null space^attaching to matrix

5423: .seealso: MatCreate(), MatNullSpaceCreate()
5424: @*/
5425: PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
5426: {

5433:   MatPreallocated(mat);

5435:   if (mat->nullsp) {
5436:     MatNullSpaceDestroy(mat->nullsp);
5437:   }
5438:   mat->nullsp = nullsp;
5439:   PetscObjectReference((PetscObject)nullsp);
5440:   return(0);
5441: }

5445: /*@  
5446:    MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.

5448:    Collective on Mat

5450:    Input Parameters:
5451: +  mat - the matrix
5452: .  row - row/column permutation
5453: .  fill - expected fill factor >= 1.0
5454: -  level - level of fill, for ICC(k)

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

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

5464:    Level: developer

5466:    Concepts: matrices^incomplete Cholesky factorization
5467:    Concepts: Cholesky factorization

5469: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
5470: @*/
5471: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
5472: {

5480:   if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
5481:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
5482:   if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5483:   if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5484:   MatPreallocated(mat);
5485:   (*mat->ops->iccfactor)(mat,row,info);
5486:   PetscObjectStateIncrease((PetscObject)mat);
5487:   return(0);
5488: }

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

5495:    Not Collective

5497:    Input Parameters:
5498: +  mat - the matrix
5499: -  v - the values compute with ADIC

5501:    Level: developer

5503:    Notes:
5504:      Must call MatSetColoring() before using this routine. Also this matrix must already
5505:      have its nonzero pattern determined.

5507: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5508:           MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
5509: @*/
5510: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v)
5511: {


5519:   if (!mat->assembled) {
5520:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5521:   }
5522:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5523:   if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5524:   (*mat->ops->setvaluesadic)(mat,v);
5525:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5526:   MatView_Private(mat);
5527:   PetscObjectStateIncrease((PetscObject)mat);
5528:   return(0);
5529: }


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

5537:    Not Collective

5539:    Input Parameters:
5540: +  mat - the matrix
5541: -  coloring - the coloring

5543:    Level: developer

5545: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5546:           MatSetValues(), MatSetValuesAdic()
5547: @*/
5548: PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring)
5549: {


5557:   if (!mat->assembled) {
5558:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5559:   }
5560:   if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5561:   (*mat->ops->setcoloring)(mat,coloring);
5562:   return(0);
5563: }

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

5570:    Not Collective

5572:    Input Parameters:
5573: +  mat - the matrix
5574: .  nl - leading dimension of v
5575: -  v - the values compute with ADIFOR

5577:    Level: developer

5579:    Notes:
5580:      Must call MatSetColoring() before using this routine. Also this matrix must already
5581:      have its nonzero pattern determined.

5583: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5584:           MatSetValues(), MatSetColoring()
5585: @*/
5586: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v)
5587: {


5595:   if (!mat->assembled) {
5596:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5597:   }
5598:   PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5599:   if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5600:   (*mat->ops->setvaluesadifor)(mat,nl,v);
5601:   PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5602:   PetscObjectStateIncrease((PetscObject)mat);
5603:   return(0);
5604: }

5608: /*@ 
5609:    MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 
5610:          ghosted ones.

5612:    Not Collective

5614:    Input Parameters:
5615: +  mat - the matrix
5616: -  diag = the diagonal values, including ghost ones

5618:    Level: developer

5620:    Notes: Works only for MPIAIJ and MPIBAIJ matrices
5621:       
5622: .seealso: MatDiagonalScale()
5623: @*/
5624: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag)
5625: {
5627:   PetscMPIInt    size;


5634:   if (!mat->assembled) {
5635:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5636:   }
5637:   PetscLogEventBegin(MAT_Scale,mat,0,0,0);
5638:   MPI_Comm_size(mat->comm,&size);
5639:   if (size == 1) {
5640:     PetscInt n,m;
5641:     VecGetSize(diag,&n);
5642:     MatGetSize(mat,0,&m);
5643:     if (m == n) {
5644:       MatDiagonalScale(mat,0,diag);
5645:     } else {
5646:       SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions");
5647:     }
5648:   } else {
5649:     PetscErrorCode (*f)(Mat,Vec);
5650:     PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
5651:     if (f) {
5652:       (*f)(mat,diag);
5653:     } else {
5654:       SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
5655:     }
5656:   }
5657:   PetscLogEventEnd(MAT_Scale,mat,0,0,0);
5658:   PetscObjectStateIncrease((PetscObject)mat);
5659:   return(0);
5660: }

5664: /*@ 
5665:    MatGetInertia - Gets the inertia from a factored matrix

5667:    Collective on Mat

5669:    Input Parameter:
5670: .  mat - the matrix

5672:    Output Parameters:
5673: +   nneg - number of negative eigenvalues
5674: .   nzero - number of zero eigenvalues
5675: -   npos - number of positive eigenvalues

5677:    Level: advanced

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


5682: @*/
5683: PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos)
5684: {

5690:   if (!mat->factor)    SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5691:   if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5692:   if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5693:   (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5694:   return(0);
5695: }

5697: /* ----------------------------------------------------------------*/
5700: /*@
5701:    MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors

5703:    Collective on Mat and Vecs

5705:    Input Parameters:
5706: +  mat - the factored matrix
5707: -  b - the right-hand-side vectors

5709:    Output Parameter:
5710: .  x - the result vectors

5712:    Notes:
5713:    The vectors b and x cannot be the same.  I.e., one cannot
5714:    call MatSolves(A,x,x).

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

5721:    Level: developer

5723:    Concepts: matrices^triangular solves

5725: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
5726: @*/
5727: PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x)
5728: {

5734:   if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
5735:   if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5736:   if (!mat->M && !mat->N) return(0);

5738:   if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5739:   MatPreallocated(mat);
5740:   PetscLogEventBegin(MAT_Solves,mat,0,0,0);
5741:   (*mat->ops->solves)(mat,b,x);
5742:   PetscLogEventEnd(MAT_Solves,mat,0,0,0);
5743:   return(0);
5744: }

5748: /*@
5749:    MatIsSymmetric - Test whether a matrix is symmetric

5751:    Collective on Mat

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

5757:    Output Parameters:
5758: .  flg - the result

5760:    Level: intermediate

5762:    Concepts: matrix^symmetry

5764: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown()
5765: @*/
5766: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg)
5767: {

5773:   if (!A->symmetric_set) {
5774:     if (!A->ops->issymmetric) {
5775:       MatType mattype;
5776:       MatGetType(A,&mattype);
5777:       SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype);
5778:     }
5779:     (*A->ops->issymmetric)(A,tol,&A->symmetric);
5780:     A->symmetric_set = PETSC_TRUE;
5781:     if (A->symmetric) {
5782:       A->structurally_symmetric_set = PETSC_TRUE;
5783:       A->structurally_symmetric     = PETSC_TRUE;
5784:     }
5785:   }
5786:   *flg = A->symmetric;
5787:   return(0);
5788: }

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

5795:    Collective on Mat

5797:    Input Parameter:
5798: .  A - the matrix to check

5800:    Output Parameters:
5801: +  set - if the symmetric flag is set (this tells you if the next flag is valid)
5802: -  flg - the result

5804:    Level: advanced

5806:    Concepts: matrix^symmetry

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

5811: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
5812: @*/
5813: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg)
5814: {
5819:   if (A->symmetric_set) {
5820:     *set = PETSC_TRUE;
5821:     *flg = A->symmetric;
5822:   } else {
5823:     *set = PETSC_FALSE;
5824:   }
5825:   return(0);
5826: }

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

5833:    Collective on Mat

5835:    Input Parameter:
5836: .  A - the matrix to check

5838:    Output Parameters:
5839: +  set - if the hermitian flag is set (this tells you if the next flag is valid)
5840: -  flg - the result

5842:    Level: advanced

5844:    Concepts: matrix^symmetry

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

5849: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
5850: @*/
5851: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg)
5852: {
5857:   if (A->hermitian_set) {
5858:     *set = PETSC_TRUE;
5859:     *flg = A->hermitian;
5860:   } else {
5861:     *set = PETSC_FALSE;
5862:   }
5863:   return(0);
5864: }

5868: /*@
5869:    MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric

5871:    Collective on Mat

5873:    Input Parameter:
5874: .  A - the matrix to test

5876:    Output Parameters:
5877: .  flg - the result

5879:    Level: intermediate

5881:    Concepts: matrix^symmetry

5883: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption()
5884: @*/
5885: PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg)
5886: {

5892:   if (!A->structurally_symmetric_set) {
5893:     if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric");
5894:     (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);
5895:     A->structurally_symmetric_set = PETSC_TRUE;
5896:   }
5897:   *flg = A->structurally_symmetric;
5898:   return(0);
5899: }

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

5906:    Collective on Mat

5908:    Input Parameter:
5909: .  A - the matrix to test

5911:    Output Parameters:
5912: .  flg - the result

5914:    Level: intermediate

5916:    Concepts: matrix^symmetry

5918: .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption()
5919: @*/
5920: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg)
5921: {

5927:   if (!A->hermitian_set) {
5928:     if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian");
5929:     (*A->ops->ishermitian)(A,&A->hermitian);
5930:     A->hermitian_set = PETSC_TRUE;
5931:     if (A->hermitian) {
5932:       A->structurally_symmetric_set = PETSC_TRUE;
5933:       A->structurally_symmetric     = PETSC_TRUE;
5934:     }
5935:   }
5936:   *flg = A->hermitian;
5937:   return(0);
5938: }

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

5947:     Not collective

5949:    Input Parameter:
5950: .   vec - the vector

5952:    Output Parameters:
5953: +   nstash   - the size of the stash
5954: .   reallocs - the number of additional mallocs incurred.
5955: .   bnstash   - the size of the block stash
5956: -   breallocs - the number of additional mallocs incurred.in the block stash
5957:  
5958:    Level: advanced

5960: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize()
5961:   
5962: @*/
5963: PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
5964: {
5967:   MatStashGetInfo_Private(&mat->stash,nstash,reallocs);
5968:   MatStashGetInfo_Private(&mat->bstash,nstash,reallocs);
5969:   return(0);
5970: }

5974: /*@
5975:    MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 
5976:      parallel layout
5977:    
5978:    Collective on Mat

5980:    Input Parameter:
5981: .  mat - the matrix

5983:    Output Parameter:
5984: +   right - (optional) vector that the matrix can be multiplied against
5985: -   left - (optional) vector that the matrix vector product can be stored in

5987:   Level: advanced

5989: .seealso: MatCreate()
5990: @*/
5991: PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left)
5992: {

5998:   MatPreallocated(mat);
5999:   if (mat->ops->getvecs) {
6000:     (*mat->ops->getvecs)(mat,right,left);
6001:   } else {
6002:     PetscMPIInt size;
6003:     MPI_Comm_size(mat->comm, &size);
6004:     if (right) {
6005:       VecCreate(mat->comm,right);
6006:       VecSetSizes(*right,mat->n,PETSC_DETERMINE);
6007:       if (size > 1) {VecSetType(*right,VECMPI);}
6008:       else {VecSetType(*right,VECSEQ);}
6009:     }
6010:     if (left) {
6011:       VecCreate(mat->comm,left);
6012:       VecSetSizes(*left,mat->m,PETSC_DETERMINE);
6013:       if (size > 1) {VecSetType(*left,VECMPI);}
6014:       else {VecSetType(*left,VECSEQ);}
6015:     }
6016:   }
6017:   if (right) {VecSetBlockSize(*right,mat->bs);}
6018:   if (left) {VecSetBlockSize(*left,mat->bs);}
6019:   return(0);
6020: }

6024: /*@C
6025:    MatFactorInfoInitialize - Initializes a MatFactorInfo data structure
6026:      with default values.

6028:    Not Collective

6030:    Input Parameters:
6031: .    info - the MatFactorInfo data structure


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

6037:    Level: developer

6039: .seealso: MatFactorInfo
6040: @*/

6042: PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info)
6043: {

6047:   PetscMemzero(info,sizeof(MatFactorInfo));
6048:   return(0);
6049: }

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

6056:    Collective on Mat

6058:    Input Parameters:
6059: +  A - the matrix
6060: .  P - the projection matrix
6061: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6062: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P))

6064:    Output Parameters:
6065: .  C - the product matrix

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

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

6073:    Level: intermediate

6075: .seealso: MatPtAPSymbolic(),MatPtAPNumeric(),MatMatMult()
6076: @*/
6077: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C)
6078: {

6084:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6085:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6088:   MatPreallocated(P);
6089:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6090:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6092:   if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N);
6093:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill);
6094:   MatPreallocated(A);

6096:   PetscLogEventBegin(MAT_PtAP,A,P,0,0);
6097:   (*A->ops->ptap)(A,P,scall,fill,C);
6098:   PetscLogEventEnd(MAT_PtAP,A,P,0,0);

6100:   return(0);
6101: }

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

6108:    Collective on Mat

6110:    Input Parameters:
6111: +  A - the matrix
6112: -  P - the projection matrix

6114:    Output Parameters:
6115: .  C - the product matrix

6117:    Notes:
6118:    C must have been created by calling MatPtAPSymbolic and must be destroyed by
6119:    the user using MatDeatroy().

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

6124:    Level: intermediate

6126: .seealso: MatPtAP(),MatPtAPSymbolic(),MatMatMultNumeric()
6127: @*/
6128: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C)
6129: {

6135:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6136:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6139:   MatPreallocated(P);
6140:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6141:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6144:   MatPreallocated(C);
6145:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6146:   if (P->N!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->M);
6147:   if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N);
6148:   if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N);
6149:   if (P->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->N);
6150:   MatPreallocated(A);

6152:   PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);
6153:   (*A->ops->ptapnumeric)(A,P,C);
6154:   PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);
6155:   return(0);
6156: }

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

6163:    Collective on Mat

6165:    Input Parameters:
6166: +  A - the matrix
6167: -  P - the projection matrix

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

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

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

6179:    Level: intermediate

6181: .seealso: MatPtAP(),MatPtAPNumeric(),MatMatMultSymbolic()
6182: @*/
6183: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C)
6184: {

6190:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6191:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6194:   MatPreallocated(P);
6195:   if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6196:   if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6199:   if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N);
6200:   if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N);
6201:   MatPreallocated(A);
6202:   PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);
6203:   (*A->ops->ptapsymbolic)(A,P,fill,C);
6204:   PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);

6206:   MatSetBlockSize(*C,A->bs);

6208:   return(0);
6209: }

6213: /*@
6214:    MatMatMult - Performs Matrix-Matrix Multiplication C=A*B.

6216:    Collective on Mat

6218:    Input Parameters:
6219: +  A - the left matrix
6220: .  B - the right matrix
6221: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6222: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6224:    Output Parameters:
6225: .  C - the product matrix

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

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

6233:    Level: intermediate

6235: .seealso: MatMatMultSymbolic(),MatMatMultNumeric()
6236: @*/
6237: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6238: {
6240:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6241:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);

6246:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6247:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6250:   MatPreallocated(B);
6251:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6252:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6254:   if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N);
6255:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill);
6256:   MatPreallocated(A);

6258:   /* For now, we do not dispatch based on the type of A and B */
6259:   /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6260:   fA = A->ops->matmult;
6261:   if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for A of type %s",A->type_name);
6262:   fB = B->ops->matmult;
6263:   if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name);
6264:   if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6266:   PetscLogEventBegin(MAT_MatMult,A,B,0,0);
6267:   (*A->ops->matmult)(A,B,scall,fill,C);
6268:   PetscLogEventEnd(MAT_MatMult,A,B,0,0);
6269: 
6270:   return(0);
6271: }

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

6279:    Collective on Mat

6281:    Input Parameters:
6282: +  A - the left matrix
6283: .  B - the right matrix
6284: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6286:    Output Parameters:
6287: .  C - the matrix containing the ij structure of product matrix

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

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

6294:    Level: intermediate

6296: .seealso: MatMatMult(),MatMatMultNumeric()
6297: @*/
6298: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C)
6299: {
6301:   PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *);
6302:   PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *);

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

6312:   MatPreallocated(B);
6313:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6314:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6317:   if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N);
6318:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill);
6319:   MatPreallocated(A);

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

6329:   PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);
6330:   (*Asymbolic)(A,B,fill,C);
6331:   PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);

6333:   return(0);
6334: }

6338: /*@
6339:    MatMatMultNumeric - Performs the numeric matrix-matrix product.
6340:    Call this routine after first calling MatMatMultSymbolic().

6342:    Collective on Mat

6344:    Input Parameters:
6345: +  A - the left matrix
6346: -  B - the right matrix

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

6351:    Notes:
6352:    C must have been created with MatMatMultSymbolic.

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

6356:    Level: intermediate

6358: .seealso: MatMatMult(),MatMatMultSymbolic()
6359: @*/
6360: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C)
6361: {
6363:   PetscErrorCode (*Anumeric)(Mat,Mat,Mat);
6364:   PetscErrorCode (*Bnumeric)(Mat,Mat,Mat);


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

6375:   MatPreallocated(B);
6376:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6377:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6381:   MatPreallocated(C);
6382:   if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6383:   if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");

6385:   if (B->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->N,C->N);
6386:   if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N);
6387:   if (A->M!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->M,C->M);
6388:   MatPreallocated(A);

6390:   /* For now, we do not dispatch based on the type of A and B */
6391:   /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6392:   Anumeric = A->ops->matmultnumeric;
6393:   if (!Anumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for A of type %s",A->type_name);
6394:   Bnumeric = B->ops->matmultnumeric;
6395:   if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name);
6396:   if (Bnumeric!=Anumeric) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6398:   PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);
6399:   (*Anumeric)(A,B,C);
6400:   PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);

6402:   return(0);
6403: }

6407: /*@
6408:    MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B.

6410:    Collective on Mat

6412:    Input Parameters:
6413: +  A - the left matrix
6414: .  B - the right matrix
6415: .  scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6416: -  fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))

6418:    Output Parameters:
6419: .  C - the product matrix

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

6424:    This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6425:    which inherit from SeqAIJ.  C will be of type MATSEQAIJ.

6427:    Level: intermediate

6429: .seealso: MatMatMultTransposeSymbolic(),MatMatMultTransposeNumeric()
6430: @*/
6431: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6432: {
6434:   PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6435:   PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);

6440:   if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6441:   if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6444:   MatPreallocated(B);
6445:   if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6446:   if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6448:   if (B->M!=A->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->M);
6449:   if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill);
6450:   MatPreallocated(A);

6452:   fA = A->ops->matmulttranspose;
6453:   if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name);
6454:   fB = B->ops->matmulttranspose;
6455:   if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name);
6456:   if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);

6458:   PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);
6459:   (*A->ops->matmulttranspose)(A,B,scall,fill,C);
6460:   PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);
6461: 
6462:   return(0);
6463: }