Actual source code: matrix.c
1: #define PETSCMAT_DLL
3: /*
4: This is where the abstract matrix operations are defined
5: */
7: #include src/mat/matimpl.h
8: #include private/vecimpl.h
10: /* Logging support */
11: PetscCookie PETSCMAT_DLLEXPORT MAT_COOKIE = 0;
12: PetscEvent MAT_Mult = 0, MAT_Mults = 0, MAT_MultConstrained = 0, MAT_MultAdd = 0, MAT_MultTranspose = 0;
13: PetscEvent MAT_MultTransposeConstrained = 0, MAT_MultTransposeAdd = 0, MAT_Solve = 0, MAT_Solves = 0, MAT_SolveAdd = 0, MAT_SolveTranspose = 0, MAT_MatSolve = 0;
14: PetscEvent MAT_SolveTransposeAdd = 0, MAT_Relax = 0, MAT_ForwardSolve = 0, MAT_BackwardSolve = 0, MAT_LUFactor = 0, MAT_LUFactorSymbolic = 0;
15: PetscEvent MAT_LUFactorNumeric = 0, MAT_CholeskyFactor = 0, MAT_CholeskyFactorSymbolic = 0, MAT_CholeskyFactorNumeric = 0, MAT_ILUFactor = 0;
16: PetscEvent MAT_ILUFactorSymbolic = 0, MAT_ICCFactorSymbolic = 0, MAT_Copy = 0, MAT_Convert = 0, MAT_Scale = 0, MAT_AssemblyBegin = 0;
17: PetscEvent MAT_AssemblyEnd = 0, MAT_SetValues = 0, MAT_GetValues = 0, MAT_GetRow = 0, MAT_GetSubMatrices = 0, MAT_GetColoring = 0, MAT_GetOrdering = 0;
18: PetscEvent MAT_IncreaseOverlap = 0, MAT_Partitioning = 0, MAT_ZeroEntries = 0, MAT_Load = 0, MAT_View = 0, MAT_AXPY = 0, MAT_FDColoringCreate = 0;
19: PetscEvent MAT_FDColoringApply = 0,MAT_Transpose = 0,MAT_FDColoringFunction = 0;
20: PetscEvent MAT_MatMult = 0, MAT_MatMultSymbolic = 0, MAT_MatMultNumeric = 0;
21: PetscEvent MAT_PtAP = 0, MAT_PtAPSymbolic = 0, MAT_PtAPNumeric = 0;
22: PetscEvent MAT_MatMultTranspose = 0, MAT_MatMultTransposeSymbolic = 0, MAT_MatMultTransposeNumeric = 0;
24: /* nasty global values for MatSetValue() */
25: PetscInt PETSCMAT_DLLEXPORT MatSetValue_Row = 0;
26: PetscInt PETSCMAT_DLLEXPORT MatSetValue_Column = 0;
27: PetscScalar PETSCMAT_DLLEXPORT MatSetValue_Value = 0.0;
31: /*@
32: MatRealPart - Zeros out the imaginary part of the matrix
34: Collective on Mat
36: Input Parameters:
37: . mat - the matrix
39: Level: advanced
42: .seealso: MatImaginaryPart()
43: @*/
45: PetscErrorCode PETSCMAT_DLLEXPORT MatRealPart(Mat mat)
46: {
52: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
53: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
54: if (!mat->ops->realpart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
55: MatPreallocated(mat);
56: (*mat->ops->realpart)(mat);
57: return(0);
58: }
62: /*@
63: MatImaginaryPart - Moves the imaginary part of the matrix to the real part and zeros the imaginary part
65: Collective on Mat
67: Input Parameters:
68: . mat - the matrix
70: Level: advanced
73: .seealso: MatRealPart()
74: @*/
76: PetscErrorCode PETSCMAT_DLLEXPORT MatImaginaryPart(Mat mat)
77: {
83: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
84: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
85: if (!mat->ops->imaginarypart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
86: MatPreallocated(mat);
87: (*mat->ops->imaginarypart)(mat);
88: return(0);
89: }
93: /*@C
94: MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow()
95: for each row that you get to ensure that your application does
96: not bleed memory.
98: Not Collective
100: Input Parameters:
101: + mat - the matrix
102: - row - the row to get
104: Output Parameters:
105: + ncols - if not NULL, the number of nonzeros in the row
106: . cols - if not NULL, the column numbers
107: - vals - if not NULL, the values
109: Notes:
110: This routine is provided for people who need to have direct access
111: to the structure of a matrix. We hope that we provide enough
112: high-level matrix routines that few users will need it.
114: MatGetRow() always returns 0-based column indices, regardless of
115: whether the internal representation is 0-based (default) or 1-based.
117: For better efficiency, set cols and/or vals to PETSC_NULL if you do
118: not wish to extract these quantities.
120: The user can only examine the values extracted with MatGetRow();
121: the values cannot be altered. To change the matrix entries, one
122: must use MatSetValues().
124: You can only have one call to MatGetRow() outstanding for a particular
125: matrix at a time, per processor. MatGetRow() can only obtain rows
126: associated with the given processor, it cannot get rows from the
127: other processors; for that we suggest using MatGetSubMatrices(), then
128: MatGetRow() on the submatrix. The row indix passed to MatGetRows()
129: is in the global number of rows.
131: Fortran Notes:
132: The calling sequence from Fortran is
133: .vb
134: MatGetRow(matrix,row,ncols,cols,values,ierr)
135: Mat matrix (input)
136: integer row (input)
137: integer ncols (output)
138: integer cols(maxcols) (output)
139: double precision (or double complex) values(maxcols) output
140: .ve
141: where maxcols >= maximum nonzeros in any row of the matrix.
144: Caution:
145: Do not try to change the contents of the output arrays (cols and vals).
146: In some cases, this may corrupt the matrix.
148: Level: advanced
150: Concepts: matrices^row access
152: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
153: @*/
155: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
156: {
158: PetscInt incols;
163: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
164: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
165: if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
166: MatPreallocated(mat);
167: PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
168: (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);
169: if (ncols) *ncols = incols;
170: PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
171: return(0);
172: }
176: /*@
177: MatConjugate - replaces the matrix values with their complex conjugates
179: Collective on Mat
181: Input Parameters:
182: . mat - the matrix
184: Level: advanced
186: .seealso: VecConjugate()
187: @*/
188: PetscErrorCode PETSCMAT_DLLEXPORT MatConjugate(Mat mat)
189: {
194: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
195: if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov");
196: (*mat->ops->conjugate)(mat);
197: return(0);
198: }
202: /*@C
203: MatRestoreRow - Frees any temporary space allocated by MatGetRow().
205: Not Collective
207: Input Parameters:
208: + mat - the matrix
209: . row - the row to get
210: . ncols, cols - the number of nonzeros and their columns
211: - vals - if nonzero the column values
213: Notes:
214: This routine should be called after you have finished examining the entries.
216: Fortran Notes:
217: The calling sequence from Fortran is
218: .vb
219: MatRestoreRow(matrix,row,ncols,cols,values,ierr)
220: Mat matrix (input)
221: integer row (input)
222: integer ncols (output)
223: integer cols(maxcols) (output)
224: double precision (or double complex) values(maxcols) output
225: .ve
226: Where maxcols >= maximum nonzeros in any row of the matrix.
228: In Fortran MatRestoreRow() MUST be called after MatGetRow()
229: before another call to MatGetRow() can be made.
231: Level: advanced
233: .seealso: MatGetRow()
234: @*/
235: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
236: {
242: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
243: if (!mat->ops->restorerow) return(0);
244: (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);
245: return(0);
246: }
250: /*@C
251: MatGetRowUpperTriangular - Sets a flag to enable calls to MatGetRow() for matrix in MATSBAIJ format.
252: You should call MatRestoreRowUpperTriangular() after calling MatGetRow/MatRestoreRow() to disable the flag.
254: Not Collective
256: Input Parameters:
257: + mat - the matrix
259: Notes:
260: The flag is to ensure that users are aware of MatGetRow() only provides the upper trianglular part of the row for the matrices in MATSBAIJ format.
262: Level: advanced
264: Concepts: matrices^row access
266: .seealso: MatRestoreRowRowUpperTriangular()
267: @*/
269: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowUpperTriangular(Mat mat)
270: {
276: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
277: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
278: if (!mat->ops->getrowuppertriangular) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
279: MatPreallocated(mat);
280: (*mat->ops->getrowuppertriangular)(mat);
281: return(0);
282: }
286: /*@C
287: MatRestoreRowUpperTriangular - Disable calls to MatGetRow() for matrix in MATSBAIJ format.
289: Not Collective
291: Input Parameters:
292: + mat - the matrix
294: Notes:
295: This routine should be called after you have finished MatGetRow/MatRestoreRow().
298: Level: advanced
300: .seealso: MatGetRowUpperTriangular()
301: @*/
302: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowUpperTriangular(Mat mat)
303: {
308: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
309: if (!mat->ops->restorerowuppertriangular) return(0);
310: (*mat->ops->restorerowuppertriangular)(mat);
311: return(0);
312: }
316: /*@C
317: MatSetOptionsPrefix - Sets the prefix used for searching for all
318: Mat options in the database.
320: Collective on Mat
322: Input Parameter:
323: + A - the Mat context
324: - prefix - the prefix to prepend to all option names
326: Notes:
327: A hyphen (-) must NOT be given at the beginning of the prefix name.
328: The first character of all runtime options is AUTOMATICALLY the hyphen.
330: Level: advanced
332: .keywords: Mat, set, options, prefix, database
334: .seealso: MatSetFromOptions()
335: @*/
336: PetscErrorCode PETSCMAT_DLLEXPORT MatSetOptionsPrefix(Mat A,const char prefix[])
337: {
342: PetscObjectSetOptionsPrefix((PetscObject)A,prefix);
343: return(0);
344: }
348: /*@C
349: MatAppendOptionsPrefix - Appends to the prefix used for searching for all
350: Mat options in the database.
352: Collective on Mat
354: Input Parameters:
355: + A - the Mat context
356: - prefix - the prefix to prepend to all option names
358: Notes:
359: A hyphen (-) must NOT be given at the beginning of the prefix name.
360: The first character of all runtime options is AUTOMATICALLY the hyphen.
362: Level: advanced
364: .keywords: Mat, append, options, prefix, database
366: .seealso: MatGetOptionsPrefix()
367: @*/
368: PetscErrorCode PETSCMAT_DLLEXPORT MatAppendOptionsPrefix(Mat A,const char prefix[])
369: {
371:
374: PetscObjectAppendOptionsPrefix((PetscObject)A,prefix);
375: return(0);
376: }
380: /*@C
381: MatGetOptionsPrefix - Sets the prefix used for searching for all
382: Mat options in the database.
384: Not Collective
386: Input Parameter:
387: . A - the Mat context
389: Output Parameter:
390: . prefix - pointer to the prefix string used
392: Notes: On the fortran side, the user should pass in a string 'prefix' of
393: sufficient length to hold the prefix.
395: Level: advanced
397: .keywords: Mat, get, options, prefix, database
399: .seealso: MatAppendOptionsPrefix()
400: @*/
401: PetscErrorCode PETSCMAT_DLLEXPORT MatGetOptionsPrefix(Mat A,const char *prefix[])
402: {
407: PetscObjectGetOptionsPrefix((PetscObject)A,prefix);
408: return(0);
409: }
413: /*@
414: MatSetUp - Sets up the internal matrix data structures for the later use.
416: Collective on Mat
418: Input Parameters:
419: . A - the Mat context
421: Notes:
422: For basic use of the Mat classes the user need not explicitly call
423: MatSetUp(), since these actions will happen automatically.
425: Level: advanced
427: .keywords: Mat, setup
429: .seealso: MatCreate(), MatDestroy()
430: @*/
431: PetscErrorCode PETSCMAT_DLLEXPORT MatSetUp(Mat A)
432: {
437: MatSetUpPreallocation(A);
438: MatSetFromOptions(A);
439: return(0);
440: }
444: /*@C
445: MatView - Visualizes a matrix object.
447: Collective on Mat
449: Input Parameters:
450: + mat - the matrix
451: - viewer - visualization context
453: Notes:
454: The available visualization contexts include
455: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
456: . PETSC_VIEWER_STDOUT_WORLD - synchronized standard
457: output where only the first processor opens
458: the file. All other processors send their
459: data to the first processor to print.
460: - PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure
462: The user can open alternative visualization contexts with
463: + PetscViewerASCIIOpen() - Outputs matrix to a specified file
464: . PetscViewerBinaryOpen() - Outputs matrix in binary to a
465: specified file; corresponding input uses MatLoad()
466: . PetscViewerDrawOpen() - Outputs nonzero matrix structure to
467: an X window display
468: - PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
469: Currently only the sequential dense and AIJ
470: matrix types support the Socket viewer.
472: The user can call PetscViewerSetFormat() to specify the output
473: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
474: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
475: + PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
476: . PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
477: . PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
478: . PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse
479: format common among all matrix types
480: . PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific
481: format (which is in many cases the same as the default)
482: . PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
483: size and structure (not the matrix entries)
484: . PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about
485: the matrix structure
487: Options Database Keys:
488: + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
489: . -mat_view_info_detailed - Prints more detailed info
490: . -mat_view - Prints matrix in ASCII format
491: . -mat_view_matlab - Prints matrix in Matlab format
492: . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
493: . -display <name> - Sets display name (default is host)
494: . -draw_pause <sec> - Sets number of seconds to pause after display
495: . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
496: . -viewer_socket_machine <machine>
497: . -viewer_socket_port <port>
498: . -mat_view_binary - save matrix to file in binary format
499: - -viewer_binary_filename <name>
500: Level: beginner
502: Concepts: matrices^viewing
503: Concepts: matrices^plotting
504: Concepts: matrices^printing
506: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(),
507: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
508: @*/
509: PetscErrorCode PETSCMAT_DLLEXPORT MatView(Mat mat,PetscViewer viewer)
510: {
511: PetscErrorCode ierr;
512: PetscInt rows,cols;
513: PetscTruth iascii;
514: const char *cstr;
515: PetscViewerFormat format;
520: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm);
523: if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix");
524: MatPreallocated(mat);
526: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
527: if (iascii) {
528: PetscViewerGetFormat(viewer,&format);
529: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
530: if (mat->prefix) {
531: PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);
532: } else {
533: PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");
534: }
535: PetscViewerASCIIPushTab(viewer);
536: MatGetType(mat,&cstr);
537: MatGetSize(mat,&rows,&cols);
538: PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);
539: if (mat->ops->getinfo) {
540: MatInfo info;
541: MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
542: PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n",
543: (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);
544: }
545: }
546: }
547: if (mat->ops->view) {
548: PetscViewerASCIIPushTab(viewer);
549: (*mat->ops->view)(mat,viewer);
550: PetscViewerASCIIPopTab(viewer);
551: } else if (!iascii) {
552: SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
553: }
554: if (iascii) {
555: PetscViewerGetFormat(viewer,&format);
556: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
557: PetscViewerASCIIPopTab(viewer);
558: }
559: }
560: return(0);
561: }
565: /*@C
566: MatScaleSystem - Scale a vector solution and right hand side to
567: match the scaling of a scaled matrix.
568:
569: Collective on Mat
571: Input Parameter:
572: + mat - the matrix
573: . b - right hand side vector (or PETSC_NULL)
574: - x - solution vector (or PETSC_NULL)
577: Notes:
578: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
579: internally scaled, so this does nothing. For MPIROWBS it
580: permutes and diagonally scales.
582: The KSP methods automatically call this routine when required
583: (via PCPreSolve()) so it is rarely used directly.
585: Level: Developer
587: Concepts: matrices^scaling
589: .seealso: MatUseScaledForm(), MatUnScaleSystem()
590: @*/
591: PetscErrorCode PETSCMAT_DLLEXPORT MatScaleSystem(Mat mat,Vec b,Vec x)
592: {
598: MatPreallocated(mat);
602: if (mat->ops->scalesystem) {
603: (*mat->ops->scalesystem)(mat,b,x);
604: }
605: return(0);
606: }
610: /*@C
611: MatUnScaleSystem - Unscales a vector solution and right hand side to
612: match the original scaling of a scaled matrix.
613:
614: Collective on Mat
616: Input Parameter:
617: + mat - the matrix
618: . b - right hand side vector (or PETSC_NULL)
619: - x - solution vector (or PETSC_NULL)
622: Notes:
623: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
624: internally scaled, so this does nothing. For MPIROWBS it
625: permutes and diagonally scales.
627: The KSP methods automatically call this routine when required
628: (via PCPreSolve()) so it is rarely used directly.
630: Level: Developer
632: .seealso: MatUseScaledForm(), MatScaleSystem()
633: @*/
634: PetscErrorCode PETSCMAT_DLLEXPORT MatUnScaleSystem(Mat mat,Vec b,Vec x)
635: {
641: MatPreallocated(mat);
644: if (mat->ops->unscalesystem) {
645: (*mat->ops->unscalesystem)(mat,b,x);
646: }
647: return(0);
648: }
652: /*@C
653: MatUseScaledForm - For matrix storage formats that scale the
654: matrix (for example MPIRowBS matrices are diagonally scaled on
655: assembly) indicates matrix operations (MatMult() etc) are
656: applied using the scaled matrix.
657:
658: Collective on Mat
660: Input Parameter:
661: + mat - the matrix
662: - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for
663: applying the original matrix
665: Notes:
666: For scaled matrix formats, applying the original, unscaled matrix
667: will be slightly more expensive
669: Level: Developer
671: .seealso: MatScaleSystem(), MatUnScaleSystem()
672: @*/
673: PetscErrorCode PETSCMAT_DLLEXPORT MatUseScaledForm(Mat mat,PetscTruth scaled)
674: {
680: MatPreallocated(mat);
681: if (mat->ops->usescaledform) {
682: (*mat->ops->usescaledform)(mat,scaled);
683: }
684: return(0);
685: }
689: /*@
690: MatDestroy - Frees space taken by a matrix.
691:
692: Collective on Mat
694: Input Parameter:
695: . A - the matrix
697: Level: beginner
699: @*/
700: PetscErrorCode PETSCMAT_DLLEXPORT MatDestroy(Mat A)
701: {
706: if (--A->refct > 0) return(0);
709: MatPreallocated(A);
710: /* if memory was published with AMS then destroy it */
711: PetscObjectDepublish(A);
712: if (A->mapping) {
713: ISLocalToGlobalMappingDestroy(A->mapping);
714: }
715: if (A->bmapping) {
716: ISLocalToGlobalMappingDestroy(A->bmapping);
717: }
718: (*A->ops->destroy)(A);
719: PetscFree(A->rmap.range);
720: PetscFree(A->cmap.range);
721: PetscFree(A->spptr);
722: PetscHeaderDestroy(A);
723: return(0);
724: }
728: /*@
729: MatValid - Checks whether a matrix object is valid.
731: Collective on Mat
733: Input Parameter:
734: . m - the matrix to check
736: Output Parameter:
737: flg - flag indicating matrix status, either
738: PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.
740: Level: developer
742: Concepts: matrices^validity
743: @*/
744: PetscErrorCode PETSCMAT_DLLEXPORT MatValid(Mat m,PetscTruth *flg)
745: {
748: if (!m) *flg = PETSC_FALSE;
749: else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
750: else *flg = PETSC_TRUE;
751: return(0);
752: }
756: /*@
757: MatSetValues - Inserts or adds a block of values into a matrix.
758: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
759: MUST be called after all calls to MatSetValues() have been completed.
761: Not Collective
763: Input Parameters:
764: + mat - the matrix
765: . v - a logically two-dimensional array of values
766: . m, idxm - the number of rows and their global indices
767: . n, idxn - the number of columns and their global indices
768: - addv - either ADD_VALUES or INSERT_VALUES, where
769: ADD_VALUES adds values to any existing entries, and
770: INSERT_VALUES replaces existing entries with new values
772: Notes:
773: By default the values, v, are row-oriented and unsorted.
774: See MatSetOption() for other options.
776: Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES
777: options cannot be mixed without intervening calls to the assembly
778: routines.
780: MatSetValues() uses 0-based row and column numbers in Fortran
781: as well as in C.
783: Negative indices may be passed in idxm and idxn, these rows and columns are
784: simply ignored. This allows easily inserting element stiffness matrices
785: with homogeneous Dirchlet boundary conditions that you don't want represented
786: in the matrix.
788: Efficiency Alert:
789: The routine MatSetValuesBlocked() may offer much better efficiency
790: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
792: Level: beginner
794: Concepts: matrices^putting entries in
796: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
797: InsertMode, INSERT_VALUES, ADD_VALUES
798: @*/
799: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
800: {
804: if (!m || !n) return(0); /* no values to insert */
810: MatPreallocated(mat);
811: if (mat->insertmode == NOT_SET_VALUES) {
812: mat->insertmode = addv;
813: }
814: #if defined(PETSC_USE_DEBUG)
815: else if (mat->insertmode != addv) {
816: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
817: }
818: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
819: #endif
821: if (mat->assembled) {
822: mat->was_assembled = PETSC_TRUE;
823: mat->assembled = PETSC_FALSE;
824: }
825: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
826: if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
827: (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
828: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
829: return(0);
830: }
835: /*@
836: MatSetValuesRowLocal - Inserts a row (block row for BAIJ matrices) of nonzero
837: values into a matrix
839: Not Collective
841: Input Parameters:
842: + mat - the matrix
843: . row - the (block) row to set
844: - v - a logically two-dimensional array of values
846: Notes:
847: By the values, v, are column-oriented (for the block version) and sorted
849: All the nonzeros in the row must be provided
851: The matrix must have previously had its column indices set
853: The row must belong to this process
855: Level: intermediate
857: Concepts: matrices^putting entries in
859: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
860: InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues(), MatSetValuesRow(), MatSetLocalToGlobalMapping()
861: @*/
862: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRowLocal(Mat mat,PetscInt row,const PetscScalar v[])
863: {
870: MatSetValuesRow(mat, mat->mapping->indices[row],v);
871: return(0);
872: }
876: /*@
877: MatSetValuesRow - Inserts a row (block row for BAIJ matrices) of nonzero
878: values into a matrix
880: Not Collective
882: Input Parameters:
883: + mat - the matrix
884: . row - the (block) row to set
885: - v - a logically two-dimensional array of values
887: Notes:
888: By the values, v, are column-oriented (for the block version) and sorted
890: All the nonzeros in the row must be provided
892: The matrix must have previously had its column indices set
894: The row must belong to this process
896: Level: intermediate
898: Concepts: matrices^putting entries in
900: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
901: InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues()
902: @*/
903: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRow(Mat mat,PetscInt row,const PetscScalar v[])
904: {
911: #if defined(PETSC_USE_DEBUG)
912: if (mat->insertmode == ADD_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add and insert values");
913: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
914: #endif
915: mat->insertmode = INSERT_VALUES;
917: if (mat->assembled) {
918: mat->was_assembled = PETSC_TRUE;
919: mat->assembled = PETSC_FALSE;
920: }
921: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
922: if (!mat->ops->setvaluesrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
923: (*mat->ops->setvaluesrow)(mat,row,v);
924: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
925: return(0);
926: }
930: /*@
931: MatSetValuesStencil - Inserts or adds a block of values into a matrix.
932: Using structured grid indexing
934: Not Collective
936: Input Parameters:
937: + mat - the matrix
938: . v - a logically two-dimensional array of values
939: . m - number of rows being entered
940: . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
941: . n - number of columns being entered
942: . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered
943: - addv - either ADD_VALUES or INSERT_VALUES, where
944: ADD_VALUES adds values to any existing entries, and
945: INSERT_VALUES replaces existing entries with new values
947: Notes:
948: By default the values, v, are row-oriented and unsorted.
949: See MatSetOption() for other options.
951: Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES
952: options cannot be mixed without intervening calls to the assembly
953: routines.
955: The grid coordinates are across the entire grid, not just the local portion
957: MatSetValuesStencil() uses 0-based row and column numbers in Fortran
958: as well as in C.
960: For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine
962: In order to use this routine you must either obtain the matrix with DAGetMatrix()
963: or call MatSetLocalToGlobalMapping() and MatSetStencil() first.
965: The columns and rows in the stencil passed in MUST be contained within the
966: ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example,
967: if you create a DA with an overlap of one grid level and on a particular process its first
968: local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the
969: first i index you can use in your column and row indices in MatSetStencil() is 5.
971: In Fortran idxm and idxn should be declared as
972: $ MatStencil idxm(4,m),idxn(4,n)
973: and the values inserted using
974: $ idxm(MatStencil_i,1) = i
975: $ idxm(MatStencil_j,1) = j
976: $ idxm(MatStencil_k,1) = k
977: $ idxm(MatStencil_c,1) = c
978: etc
980: For periodic boundary conditions use negative indices for values to the left (below 0; that are to be
981: obtained by wrapping values from right edge). For values to the right of the last entry using that index plus one
982: etc to obtain values that obtained by wrapping the values from the left edge.
984: For indices that don't mean anything for your case (like the k index when working in 2d) or the c index when you have
985: a single value per point) you can skip filling those indices.
987: Inspired by the structured grid interface to the HYPRE package
988: (http://www.llnl.gov/CASC/hypre)
990: Efficiency Alert:
991: The routine MatSetValuesBlockedStencil() may offer much better efficiency
992: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
994: Level: beginner
996: Concepts: matrices^putting entries in
998: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
999: MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
1000: @*/
1001: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1002: {
1004: PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1005: PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);
1008: if (!m || !n) return(0); /* no values to insert */
1015: if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1016: if (n > 256) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);
1018: for (i=0; i<m; i++) {
1019: for (j=0; j<3-sdim; j++) dxm++;
1020: tmp = *dxm++ - starts[0];
1021: for (j=0; j<dim-1; j++) {
1022: if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1023: else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1024: }
1025: if (mat->stencil.noc) dxm++;
1026: jdxm[i] = tmp;
1027: }
1028: for (i=0; i<n; i++) {
1029: for (j=0; j<3-sdim; j++) dxn++;
1030: tmp = *dxn++ - starts[0];
1031: for (j=0; j<dim-1; j++) {
1032: if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1033: else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1034: }
1035: if (mat->stencil.noc) dxn++;
1036: jdxn[i] = tmp;
1037: }
1038: MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
1039: return(0);
1040: }
1044: /*@C
1045: MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix.
1046: Using structured grid indexing
1048: Not Collective
1050: Input Parameters:
1051: + mat - the matrix
1052: . v - a logically two-dimensional array of values
1053: . m - number of rows being entered
1054: . idxm - grid coordinates for matrix rows being entered
1055: . n - number of columns being entered
1056: . idxn - grid coordinates for matrix columns being entered
1057: - addv - either ADD_VALUES or INSERT_VALUES, where
1058: ADD_VALUES adds values to any existing entries, and
1059: INSERT_VALUES replaces existing entries with new values
1061: Notes:
1062: By default the values, v, are row-oriented and unsorted.
1063: See MatSetOption() for other options.
1065: Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES
1066: options cannot be mixed without intervening calls to the assembly
1067: routines.
1069: The grid coordinates are across the entire grid, not just the local portion
1071: MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran
1072: as well as in C.
1074: For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine
1076: In order to use this routine you must either obtain the matrix with DAGetMatrix()
1077: or call MatSetLocalToGlobalMapping() and MatSetStencil() first.
1079: The columns and rows in the stencil passed in MUST be contained within the
1080: ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example,
1081: if you create a DA with an overlap of one grid level and on a particular process its first
1082: local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the
1083: first i index you can use in your column and row indices in MatSetStencil() is 5.
1085: In Fortran idxm and idxn should be declared as
1086: $ MatStencil idxm(4,m),idxn(4,n)
1087: and the values inserted using
1088: $ idxm(MatStencil_i,1) = i
1089: $ idxm(MatStencil_j,1) = j
1090: $ idxm(MatStencil_k,1) = k
1091: etc
1093: Negative indices may be passed in idxm and idxn, these rows and columns are
1094: simply ignored. This allows easily inserting element stiffness matrices
1095: with homogeneous Dirchlet boundary conditions that you don't want represented
1096: in the matrix.
1098: Inspired by the structured grid interface to the HYPRE package
1099: (http://www.llnl.gov/CASC/hypre)
1101: Level: beginner
1103: Concepts: matrices^putting entries in
1105: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1106: MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
1107: @*/
1108: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1109: {
1111: PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1112: PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);
1115: if (!m || !n) return(0); /* no values to insert */
1122: if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1123: if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);
1125: for (i=0; i<m; i++) {
1126: for (j=0; j<3-sdim; j++) dxm++;
1127: tmp = *dxm++ - starts[0];
1128: for (j=0; j<sdim-1; j++) {
1129: if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1130: else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1131: }
1132: dxm++;
1133: jdxm[i] = tmp;
1134: }
1135: for (i=0; i<n; i++) {
1136: for (j=0; j<3-sdim; j++) dxn++;
1137: tmp = *dxn++ - starts[0];
1138: for (j=0; j<sdim-1; j++) {
1139: if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1140: else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1141: }
1142: dxn++;
1143: jdxn[i] = tmp;
1144: }
1145: MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);
1146: return(0);
1147: }
1151: /*@
1152: MatSetStencil - Sets the grid information for setting values into a matrix via
1153: MatSetValuesStencil()
1155: Not Collective
1157: Input Parameters:
1158: + mat - the matrix
1159: . dim - dimension of the grid 1, 2, or 3
1160: . dims - number of grid points in x, y, and z direction, including ghost points on your processor
1161: . starts - starting point of ghost nodes on your processor in x, y, and z direction
1162: - dof - number of degrees of freedom per node
1165: Inspired by the structured grid interface to the HYPRE package
1166: (www.llnl.gov/CASC/hyper)
1168: For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the
1169: user.
1170:
1171: Level: beginner
1173: Concepts: matrices^putting entries in
1175: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1176: MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
1177: @*/
1178: PetscErrorCode PETSCMAT_DLLEXPORT MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof)
1179: {
1180: PetscInt i;
1187: mat->stencil.dim = dim + (dof > 1);
1188: for (i=0; i<dim; i++) {
1189: mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */
1190: mat->stencil.starts[i] = starts[dim-i-1];
1191: }
1192: mat->stencil.dims[dim] = dof;
1193: mat->stencil.starts[dim] = 0;
1194: mat->stencil.noc = (PetscTruth)(dof == 1);
1195: return(0);
1196: }
1200: /*@
1201: MatSetValuesBlocked - Inserts or adds a block of values into a matrix.
1203: Not Collective
1205: Input Parameters:
1206: + mat - the matrix
1207: . v - a logically two-dimensional array of values
1208: . m, idxm - the number of block rows and their global block indices
1209: . n, idxn - the number of block columns and their global block indices
1210: - addv - either ADD_VALUES or INSERT_VALUES, where
1211: ADD_VALUES adds values to any existing entries, and
1212: INSERT_VALUES replaces existing entries with new values
1214: Notes:
1215: The m and n count the NUMBER of blocks in the row direction and column direction,
1216: NOT the total number of rows/columns; for example, if the block size is 2 and
1217: you are passing in values for rows 2,3,4,5 then m would be 2 (not 4).
1219: By default the values, v, are row-oriented and unsorted. So the layout of
1220: v is the same as for MatSetValues(). See MatSetOption() for other options.
1222: Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1223: options cannot be mixed without intervening calls to the assembly
1224: routines.
1226: MatSetValuesBlocked() uses 0-based row and column numbers in Fortran
1227: as well as in C.
1229: Negative indices may be passed in idxm and idxn, these rows and columns are
1230: simply ignored. This allows easily inserting element stiffness matrices
1231: with homogeneous Dirchlet boundary conditions that you don't want represented
1232: in the matrix.
1234: Each time an entry is set within a sparse matrix via MatSetValues(),
1235: internal searching must be done to determine where to place the the
1236: data in the matrix storage space. By instead inserting blocks of
1237: entries via MatSetValuesBlocked(), the overhead of matrix assembly is
1238: reduced.
1240: Restrictions:
1241: MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats
1243: Level: intermediate
1245: Concepts: matrices^putting entries in blocked
1247: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
1248: @*/
1249: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
1250: {
1254: if (!m || !n) return(0); /* no values to insert */
1260: MatPreallocated(mat);
1261: if (mat->insertmode == NOT_SET_VALUES) {
1262: mat->insertmode = addv;
1263: }
1264: #if defined(PETSC_USE_DEBUG)
1265: else if (mat->insertmode != addv) {
1266: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1267: }
1268: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1269: #endif
1271: if (mat->assembled) {
1272: mat->was_assembled = PETSC_TRUE;
1273: mat->assembled = PETSC_FALSE;
1274: }
1275: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1276: if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1277: (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
1278: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1279: return(0);
1280: }
1284: /*@
1285: MatGetValues - Gets a block of values from a matrix.
1287: Not Collective; currently only returns a local block
1289: Input Parameters:
1290: + mat - the matrix
1291: . v - a logically two-dimensional array for storing the values
1292: . m, idxm - the number of rows and their global indices
1293: - n, idxn - the number of columns and their global indices
1295: Notes:
1296: The user must allocate space (m*n PetscScalars) for the values, v.
1297: The values, v, are then returned in a row-oriented format,
1298: analogous to that used by default in MatSetValues().
1300: MatGetValues() uses 0-based row and column numbers in
1301: Fortran as well as in C.
1303: MatGetValues() requires that the matrix has been assembled
1304: with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to
1305: MatSetValues() and MatGetValues() CANNOT be made in succession
1306: without intermediate matrix assembly.
1308: Level: advanced
1310: Concepts: matrices^accessing values
1312: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
1313: @*/
1314: PetscErrorCode PETSCMAT_DLLEXPORT MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[])
1315: {
1324: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1325: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1326: if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1327: MatPreallocated(mat);
1329: PetscLogEventBegin(MAT_GetValues,mat,0,0,0);
1330: (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
1331: PetscLogEventEnd(MAT_GetValues,mat,0,0,0);
1332: return(0);
1333: }
1337: /*@
1338: MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
1339: the routine MatSetValuesLocal() to allow users to insert matrix entries
1340: using a local (per-processor) numbering.
1342: Not Collective
1344: Input Parameters:
1345: + x - the matrix
1346: - mapping - mapping created with ISLocalToGlobalMappingCreate()
1347: or ISLocalToGlobalMappingCreateIS()
1349: Level: intermediate
1351: Concepts: matrices^local to global mapping
1352: Concepts: local to global mapping^for matrices
1354: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
1355: @*/
1356: PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
1357: {
1363: if (x->mapping) {
1364: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1365: }
1366: MatPreallocated(x);
1368: if (x->ops->setlocaltoglobalmapping) {
1369: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1370: } else {
1371: x->mapping = mapping;
1372: PetscObjectReference((PetscObject)mapping);
1373: }
1374: return(0);
1375: }
1379: /*@
1380: MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
1381: by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
1382: entries using a local (per-processor) numbering.
1384: Not Collective
1386: Input Parameters:
1387: + x - the matrix
1388: - mapping - mapping created with ISLocalToGlobalMappingCreate() or
1389: ISLocalToGlobalMappingCreateIS()
1391: Level: intermediate
1393: Concepts: matrices^local to global mapping blocked
1394: Concepts: local to global mapping^for matrices, blocked
1396: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
1397: MatSetValuesBlocked(), MatSetValuesLocal()
1398: @*/
1399: PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
1400: {
1406: if (x->bmapping) {
1407: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1408: }
1409: x->bmapping = mapping;
1410: PetscObjectReference((PetscObject)mapping);
1411: return(0);
1412: }
1416: /*@
1417: MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
1418: using a local ordering of the nodes.
1420: Not Collective
1422: Input Parameters:
1423: + x - the matrix
1424: . nrow, irow - number of rows and their local indices
1425: . ncol, icol - number of columns and their local indices
1426: . y - a logically two-dimensional array of values
1427: - addv - either INSERT_VALUES or ADD_VALUES, where
1428: ADD_VALUES adds values to any existing entries, and
1429: INSERT_VALUES replaces existing entries with new values
1431: Notes:
1432: Before calling MatSetValuesLocal(), the user must first set the
1433: local-to-global mapping by calling MatSetLocalToGlobalMapping().
1435: Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES
1436: options cannot be mixed without intervening calls to the assembly
1437: routines.
1439: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
1440: MUST be called after all calls to MatSetValuesLocal() have been completed.
1442: Level: intermediate
1444: Concepts: matrices^putting entries in with local numbering
1446: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
1447: MatSetValueLocal()
1448: @*/
1449: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1450: {
1452: PetscInt irowm[2048],icolm[2048];
1460: MatPreallocated(mat);
1461: if (mat->insertmode == NOT_SET_VALUES) {
1462: mat->insertmode = addv;
1463: }
1464: #if defined(PETSC_USE_DEBUG)
1465: else if (mat->insertmode != addv) {
1466: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1467: }
1468: if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
1469: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1470: }
1471: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1472: #endif
1474: if (mat->assembled) {
1475: mat->was_assembled = PETSC_TRUE;
1476: mat->assembled = PETSC_FALSE;
1477: }
1478: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1479: if (!mat->ops->setvalueslocal) {
1480: ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
1481: ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
1482: (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
1483: } else {
1484: (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
1485: }
1486: mat->same_nonzero = PETSC_FALSE;
1487: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1488: return(0);
1489: }
1493: /*@
1494: MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix,
1495: using a local ordering of the nodes a block at a time.
1497: Not Collective
1499: Input Parameters:
1500: + x - the matrix
1501: . nrow, irow - number of rows and their local indices
1502: . ncol, icol - number of columns and their local indices
1503: . y - a logically two-dimensional array of values
1504: - addv - either INSERT_VALUES or ADD_VALUES, where
1505: ADD_VALUES adds values to any existing entries, and
1506: INSERT_VALUES replaces existing entries with new values
1508: Notes:
1509: Before calling MatSetValuesBlockedLocal(), the user must first set the
1510: local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
1511: where the mapping MUST be set for matrix blocks, not for matrix elements.
1513: Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1514: options cannot be mixed without intervening calls to the assembly
1515: routines.
1517: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
1518: MUST be called after all calls to MatSetValuesBlockedLocal() have been completed.
1520: Level: intermediate
1522: Concepts: matrices^putting blocked values in with local numbering
1524: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
1525: @*/
1526: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1527: {
1529: PetscInt irowm[2048],icolm[2048];
1537: MatPreallocated(mat);
1538: if (mat->insertmode == NOT_SET_VALUES) {
1539: mat->insertmode = addv;
1540: }
1541: #if defined(PETSC_USE_DEBUG)
1542: else if (mat->insertmode != addv) {
1543: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1544: }
1545: if (!mat->bmapping) {
1546: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
1547: }
1548: if (nrow > 2048 || ncol > 2048) {
1549: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1550: }
1551: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1552: #endif
1554: if (mat->assembled) {
1555: mat->was_assembled = PETSC_TRUE;
1556: mat->assembled = PETSC_FALSE;
1557: }
1558: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1559: ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1560: ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1561: (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1562: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1563: return(0);
1564: }
1566: /* --------------------------------------------------------*/
1569: /*@
1570: MatMult - Computes the matrix-vector product, y = Ax.
1572: Collective on Mat and Vec
1574: Input Parameters:
1575: + mat - the matrix
1576: - x - the vector to be multiplied
1578: Output Parameters:
1579: . y - the result
1581: Notes:
1582: The vectors x and y cannot be the same. I.e., one cannot
1583: call MatMult(A,y,y).
1585: Level: beginner
1587: Concepts: matrix-vector product
1589: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1590: @*/
1591: PetscErrorCode PETSCMAT_DLLEXPORT MatMult(Mat mat,Vec x,Vec y)
1592: {
1601: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1602: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1603: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1604: #ifndef PETSC_HAVE_CONSTRAINTS
1605: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1606: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1607: if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);
1608: #endif
1609: MatPreallocated(mat);
1611: if (mat->nullsp) {
1612: MatNullSpaceRemove(mat->nullsp,x,&x);
1613: }
1615: if (!mat->ops->mult) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply defined");
1616: PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1617: (*mat->ops->mult)(mat,x,y);
1618: PetscLogEventEnd(MAT_Mult,mat,x,y,0);
1620: if (mat->nullsp) {
1621: MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1622: }
1623: PetscObjectStateIncrease((PetscObject)y);
1624: return(0);
1625: }
1629: /*@
1630: MatMultTranspose - Computes matrix transpose times a vector.
1632: Collective on Mat and Vec
1634: Input Parameters:
1635: + mat - the matrix
1636: - x - the vector to be multilplied
1638: Output Parameters:
1639: . y - the result
1641: Notes:
1642: The vectors x and y cannot be the same. I.e., one cannot
1643: call MatMultTranspose(A,y,y).
1645: Level: beginner
1647: Concepts: matrix vector product^transpose
1649: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1650: @*/
1651: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTranspose(Mat mat,Vec x,Vec y)
1652: {
1661: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1662: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1663: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1664: #ifndef PETSC_HAVE_CONSTRAINTS
1665: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
1666: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
1667: #endif
1668: MatPreallocated(mat);
1670: if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined");
1671: PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);
1672: (*mat->ops->multtranspose)(mat,x,y);
1673: PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);
1674: PetscObjectStateIncrease((PetscObject)y);
1675: return(0);
1676: }
1680: /*@
1681: MatMultAdd - Computes v3 = v2 + A * v1.
1683: Collective on Mat and Vec
1685: Input Parameters:
1686: + mat - the matrix
1687: - v1, v2 - the vectors
1689: Output Parameters:
1690: . v3 - the result
1692: Notes:
1693: The vectors v1 and v3 cannot be the same. I.e., one cannot
1694: call MatMultAdd(A,v1,v2,v1).
1696: Level: beginner
1698: Concepts: matrix vector product^addition
1700: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1701: @*/
1702: PetscErrorCode PETSCMAT_DLLEXPORT MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1703: {
1713: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1714: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1715: if (mat->cmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->cmap.N,v1->map.N);
1716: if (mat->rmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->rmap.N,v2->map.N);
1717: if (mat->rmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->rmap.N,v3->map.N);
1718: if (mat->rmap.n != v3->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->rmap.n,v3->map.n);
1719: if (mat->rmap.n != v2->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->rmap.n,v2->map.n);
1720: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1721: MatPreallocated(mat);
1723: PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);
1724: (*mat->ops->multadd)(mat,v1,v2,v3);
1725: PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);
1726: PetscObjectStateIncrease((PetscObject)v3);
1727: return(0);
1728: }
1732: /*@
1733: MatMultTransposeAdd - Computes v3 = v2 + A' * v1.
1735: Collective on Mat and Vec
1737: Input Parameters:
1738: + mat - the matrix
1739: - v1, v2 - the vectors
1741: Output Parameters:
1742: . v3 - the result
1744: Notes:
1745: The vectors v1 and v3 cannot be the same. I.e., one cannot
1746: call MatMultTransposeAdd(A,v1,v2,v1).
1748: Level: beginner
1750: Concepts: matrix vector product^transpose and addition
1752: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1753: @*/
1754: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1755: {
1765: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1766: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1767: if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1768: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1769: if (mat->rmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->rmap.N,v1->map.N);
1770: if (mat->cmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->cmap.N,v2->map.N);
1771: if (mat->cmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->cmap.N,v3->map.N);
1772: MatPreallocated(mat);
1774: PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);
1775: (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1776: PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);
1777: PetscObjectStateIncrease((PetscObject)v3);
1778: return(0);
1779: }
1783: /*@
1784: MatMultConstrained - The inner multiplication routine for a
1785: constrained matrix P^T A P.
1787: Collective on Mat and Vec
1789: Input Parameters:
1790: + mat - the matrix
1791: - x - the vector to be multilplied
1793: Output Parameters:
1794: . y - the result
1796: Notes:
1797: The vectors x and y cannot be the same. I.e., one cannot
1798: call MatMult(A,y,y).
1800: Level: beginner
1802: .keywords: matrix, multiply, matrix-vector product, constraint
1803: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1804: @*/
1805: PetscErrorCode PETSCMAT_DLLEXPORT MatMultConstrained(Mat mat,Vec x,Vec y)
1806: {
1813: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1814: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1815: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1816: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1817: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1818: if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);
1820: PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1821: (*mat->ops->multconstrained)(mat,x,y);
1822: PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1823: PetscObjectStateIncrease((PetscObject)y);
1825: return(0);
1826: }
1830: /*@
1831: MatMultTransposeConstrained - The inner multiplication routine for a
1832: constrained matrix P^T A^T P.
1834: Collective on Mat and Vec
1836: Input Parameters:
1837: + mat - the matrix
1838: - x - the vector to be multilplied
1840: Output Parameters:
1841: . y - the result
1843: Notes:
1844: The vectors x and y cannot be the same. I.e., one cannot
1845: call MatMult(A,y,y).
1847: Level: beginner
1849: .keywords: matrix, multiply, matrix-vector product, constraint
1850: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1851: @*/
1852: PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeConstrained(Mat mat,Vec x,Vec y)
1853: {
1860: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1861: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1862: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1863: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1864: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1866: PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);
1867: (*mat->ops->multtransposeconstrained)(mat,x,y);
1868: PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);
1869: PetscObjectStateIncrease((PetscObject)y);
1871: return(0);
1872: }
1873: /* ------------------------------------------------------------*/
1876: /*@
1877: MatGetInfo - Returns information about matrix storage (number of
1878: nonzeros, memory, etc.).
1880: Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1881: as the flag
1883: Input Parameters:
1884: . mat - the matrix
1886: Output Parameters:
1887: + flag - flag indicating the type of parameters to be returned
1888: (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1889: MAT_GLOBAL_SUM - sum over all processors)
1890: - info - matrix information context
1892: Notes:
1893: The MatInfo context contains a variety of matrix data, including
1894: number of nonzeros allocated and used, number of mallocs during
1895: matrix assembly, etc. Additional information for factored matrices
1896: is provided (such as the fill ratio, number of mallocs during
1897: factorization, etc.). Much of this info is printed to STDOUT
1898: when using the runtime options
1899: $ -info -mat_view_info
1901: Example for C/C++ Users:
1902: See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1903: data within the MatInfo context. For example,
1904: .vb
1905: MatInfo info;
1906: Mat A;
1907: double mal, nz_a, nz_u;
1909: MatGetInfo(A,MAT_LOCAL,&info);
1910: mal = info.mallocs;
1911: nz_a = info.nz_allocated;
1912: .ve
1914: Example for Fortran Users:
1915: Fortran users should declare info as a double precision
1916: array of dimension MAT_INFO_SIZE, and then extract the parameters
1917: of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h
1918: a complete list of parameter names.
1919: .vb
1920: double precision info(MAT_INFO_SIZE)
1921: double precision mal, nz_a
1922: Mat A
1923: integer ierr
1925: call MatGetInfo(A,MAT_LOCAL,info,ierr)
1926: mal = info(MAT_INFO_MALLOCS)
1927: nz_a = info(MAT_INFO_NZ_ALLOCATED)
1928: .ve
1930: Level: intermediate
1932: Concepts: matrices^getting information on
1933:
1934: @*/
1935: PetscErrorCode PETSCMAT_DLLEXPORT MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1936: {
1943: if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1944: MatPreallocated(mat);
1945: (*mat->ops->getinfo)(mat,flag,info);
1946: return(0);
1947: }
1949: /* ----------------------------------------------------------*/
1952: /*@C
1953: MatILUDTFactor - Performs a drop tolerance ILU factorization.
1955: Collective on Mat
1957: Input Parameters:
1958: + mat - the matrix
1959: . row - row permutation
1960: . col - column permutation
1961: - info - information about the factorization to be done
1963: Output Parameters:
1964: . fact - the factored matrix
1966: Level: developer
1968: Notes:
1969: Most users should employ the simplified KSP interface for linear solvers
1970: instead of working directly with matrix algebra routines such as this.
1971: See, e.g., KSPCreate().
1973: This is currently only supported for the SeqAIJ matrix format using code
1974: from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or
1975: Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright
1976: and thus can be distributed with PETSc.
1978: Concepts: matrices^ILUDT factorization
1980: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1981: @*/
1982: PetscErrorCode PETSCMAT_DLLEXPORT MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1983: {
1993: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1994: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1995: if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1996: MatPreallocated(mat);
1997: PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1998: (*mat->ops->iludtfactor)(mat,row,col,info,fact);
1999: PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
2000: PetscObjectStateIncrease((PetscObject)*fact);
2002: return(0);
2003: }
2007: /*@
2008: MatLUFactor - Performs in-place LU factorization of matrix.
2010: Collective on Mat
2012: Input Parameters:
2013: + mat - the matrix
2014: . row - row permutation
2015: . col - column permutation
2016: - info - options for factorization, includes
2017: $ fill - expected fill as ratio of original fill.
2018: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2019: $ Run with the option -info to determine an optimal value to use
2021: Notes:
2022: Most users should employ the simplified KSP interface for linear solvers
2023: instead of working directly with matrix algebra routines such as this.
2024: See, e.g., KSPCreate().
2026: This changes the state of the matrix to a factored matrix; it cannot be used
2027: for example with MatSetValues() unless one first calls MatSetUnfactored().
2029: Level: developer
2031: Concepts: matrices^LU factorization
2033: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
2034: MatGetOrdering(), MatSetUnfactored(), MatFactorInfo
2036: @*/
2037: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2038: {
2047: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2048: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2049: if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2050: MatPreallocated(mat);
2052: PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);
2053: (*mat->ops->lufactor)(mat,row,col,info);
2054: PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);
2055: PetscObjectStateIncrease((PetscObject)mat);
2056: return(0);
2057: }
2061: /*@
2062: MatILUFactor - Performs in-place ILU factorization of matrix.
2064: Collective on Mat
2066: Input Parameters:
2067: + mat - the matrix
2068: . row - row permutation
2069: . col - column permutation
2070: - info - structure containing
2071: $ levels - number of levels of fill.
2072: $ expected fill - as ratio of original fill.
2073: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
2074: missing diagonal entries)
2076: Notes:
2077: Probably really in-place only when level of fill is zero, otherwise allocates
2078: new space to store factored matrix and deletes previous memory.
2080: Most users should employ the simplified KSP interface for linear solvers
2081: instead of working directly with matrix algebra routines such as this.
2082: See, e.g., KSPCreate().
2084: Level: developer
2086: Concepts: matrices^ILU factorization
2088: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2089: @*/
2090: PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2091: {
2100: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
2101: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2102: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2103: if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2104: MatPreallocated(mat);
2106: PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
2107: (*mat->ops->ilufactor)(mat,row,col,info);
2108: PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
2109: PetscObjectStateIncrease((PetscObject)mat);
2110: return(0);
2111: }
2115: /*@
2116: MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
2117: Call this routine before calling MatLUFactorNumeric().
2119: Collective on Mat
2121: Input Parameters:
2122: + mat - the matrix
2123: . row, col - row and column permutations
2124: - info - options for factorization, includes
2125: $ fill - expected fill as ratio of original fill.
2126: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2127: $ Run with the option -info to determine an optimal value to use
2129: Output Parameter:
2130: . fact - new matrix that has been symbolically factored
2132: Notes:
2133: See the users manual for additional information about
2134: choosing the fill factor for better efficiency.
2136: Most users should employ the simplified KSP interface for linear solvers
2137: instead of working directly with matrix algebra routines such as this.
2138: See, e.g., KSPCreate().
2140: Level: developer
2142: Concepts: matrices^LU symbolic factorization
2144: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2145: @*/
2146: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
2147: {
2157: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2158: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2159: if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic LU",mat->type_name);
2160: MatPreallocated(mat);
2162: PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);
2163: (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
2164: PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);
2165: PetscObjectStateIncrease((PetscObject)*fact);
2166: return(0);
2167: }
2171: /*@
2172: MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
2173: Call this routine after first calling MatLUFactorSymbolic().
2175: Collective on Mat
2177: Input Parameters:
2178: + mat - the matrix
2179: . info - options for factorization
2180: - fact - the matrix generated for the factor, from MatLUFactorSymbolic()
2182: Notes:
2183: See MatLUFactor() for in-place factorization. See
2184: MatCholeskyFactorNumeric() for the symmetric, positive definite case.
2186: Most users should employ the simplified KSP interface for linear solvers
2187: instead of working directly with matrix algebra routines such as this.
2188: See, e.g., KSPCreate().
2190: Level: developer
2192: Concepts: matrices^LU numeric factorization
2194: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
2195: @*/
2196: PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2197: {
2205: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2206: if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2207: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2208: }
2209: if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2210: MatPreallocated(mat);
2211: PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
2212: (*(*fact)->ops->lufactornumeric)(mat,info,fact);
2213: PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);
2215: MatView_Private(*fact);
2216: PetscObjectStateIncrease((PetscObject)*fact);
2217: return(0);
2218: }
2222: /*@
2223: MatCholeskyFactor - Performs in-place Cholesky factorization of a
2224: symmetric matrix.
2226: Collective on Mat
2228: Input Parameters:
2229: + mat - the matrix
2230: . perm - row and column permutations
2231: - f - expected fill as ratio of original fill
2233: Notes:
2234: See MatLUFactor() for the nonsymmetric case. See also
2235: MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().
2237: Most users should employ the simplified KSP interface for linear solvers
2238: instead of working directly with matrix algebra routines such as this.
2239: See, e.g., KSPCreate().
2241: Level: developer
2243: Concepts: matrices^Cholesky factorization
2245: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
2246: MatGetOrdering()
2248: @*/
2249: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info)
2250: {
2258: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2259: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2260: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2261: if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2262: MatPreallocated(mat);
2264: PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);
2265: (*mat->ops->choleskyfactor)(mat,perm,info);
2266: PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);
2267: PetscObjectStateIncrease((PetscObject)mat);
2268: return(0);
2269: }
2273: /*@
2274: MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
2275: of a symmetric matrix.
2277: Collective on Mat
2279: Input Parameters:
2280: + mat - the matrix
2281: . perm - row and column permutations
2282: - info - options for factorization, includes
2283: $ fill - expected fill as ratio of original fill.
2284: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2285: $ Run with the option -info to determine an optimal value to use
2287: Output Parameter:
2288: . fact - the factored matrix
2290: Notes:
2291: See MatLUFactorSymbolic() for the nonsymmetric case. See also
2292: MatCholeskyFactor() and MatCholeskyFactorNumeric().
2294: Most users should employ the simplified KSP interface for linear solvers
2295: instead of working directly with matrix algebra routines such as this.
2296: See, e.g., KSPCreate().
2298: Level: developer
2300: Concepts: matrices^Cholesky symbolic factorization
2302: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
2303: MatGetOrdering()
2305: @*/
2306: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
2307: {
2316: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2317: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2318: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2319: if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2320: MatPreallocated(mat);
2322: PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
2323: (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);
2324: PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
2325: PetscObjectStateIncrease((PetscObject)*fact);
2326: return(0);
2327: }
2331: /*@
2332: MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
2333: of a symmetric matrix. Call this routine after first calling
2334: MatCholeskyFactorSymbolic().
2336: Collective on Mat
2338: Input Parameter:
2339: . mat - the initial matrix
2340: . info - options for factorization
2341: - fact - the symbolic factor of mat
2343: Output Parameter:
2344: . fact - the factored matrix
2346: Notes:
2347: Most users should employ the simplified KSP interface for linear solvers
2348: instead of working directly with matrix algebra routines such as this.
2349: See, e.g., KSPCreate().
2351: Level: developer
2353: Concepts: matrices^Cholesky numeric factorization
2355: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
2356: @*/
2357: PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2358: {
2365: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2366: if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2367: if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2368: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2369: }
2370: MatPreallocated(mat);
2372: PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
2373: (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);
2374: PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
2375: PetscObjectStateIncrease((PetscObject)*fact);
2376: return(0);
2377: }
2379: /* ----------------------------------------------------------------*/
2382: /*@
2383: MatSolve - Solves A x = b, given a factored matrix.
2385: Collective on Mat and Vec
2387: Input Parameters:
2388: + mat - the factored matrix
2389: - b - the right-hand-side vector
2391: Output Parameter:
2392: . x - the result vector
2394: Notes:
2395: The vectors b and x cannot be the same. I.e., one cannot
2396: call MatSolve(A,x,x).
2398: Notes:
2399: Most users should employ the simplified KSP interface for linear solvers
2400: instead of working directly with matrix algebra routines such as this.
2401: See, e.g., KSPCreate().
2403: Level: developer
2405: Concepts: matrices^triangular solves
2407: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
2408: @*/
2409: PetscErrorCode PETSCMAT_DLLEXPORT MatSolve(Mat mat,Vec b,Vec x)
2410: {
2420: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2421: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2422: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2423: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2424: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2425: if (!mat->rmap.N && !mat->cmap.N) return(0);
2426: if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2427: MatPreallocated(mat);
2429: PetscLogEventBegin(MAT_Solve,mat,b,x,0);
2430: (*mat->ops->solve)(mat,b,x);
2431: PetscLogEventEnd(MAT_Solve,mat,b,x,0);
2432: PetscObjectStateIncrease((PetscObject)x);
2433: return(0);
2434: }
2438: /*@
2439: MatMatSolve - Solves A X = B, given a factored matrix.
2441: Collective on Mat
2443: Input Parameters:
2444: + mat - the factored matrix
2445: - b - the right-hand-side vector
2447: Output Parameter:
2448: . x - the result vector
2450: Notes:
2451: The vectors b and x cannot be the same. I.e., one cannot
2452: call MatMatSolve(A,x,x).
2454: Notes:
2455: Most users should employ the simplified KSP interface for linear solvers
2456: instead of working directly with matrix algebra routines such as this.
2457: See, e.g., KSPCreate().
2459: Level: developer
2461: Concepts: matrices^triangular solves
2463: .seealso: MatMatSolveAdd(), MatMatSolveTranspose(), MatMatSolveTransposeAdd()
2464: @*/
2465: PetscErrorCode PETSCMAT_DLLEXPORT MatMatSolve(Mat A,Mat B,Mat X)
2466: {
2476: if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices");
2477: if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2478: if (A->cmap.N != X->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat X: global dim %D %D",A->cmap.N,X->rmap.N);
2479: if (A->rmap.N != B->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D",A->rmap.N,B->rmap.N);
2480: if (A->rmap.n != B->rmap.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: local dim %D %D",A->rmap.n,B->rmap.n);
2481: if (!A->rmap.N && !A->cmap.N) return(0);
2482: if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2483: MatPreallocated(A);
2485: PetscLogEventBegin(MAT_MatSolve,A,B,X,0);
2486: (*A->ops->matsolve)(A,B,X);
2487: PetscLogEventEnd(MAT_MatSolve,A,B,X,0);
2488: PetscObjectStateIncrease((PetscObject)X);
2489: return(0);
2490: }
2495: /* @
2496: MatForwardSolve - Solves L x = b, given a factored matrix, A = LU.
2498: Collective on Mat and Vec
2500: Input Parameters:
2501: + mat - the factored matrix
2502: - b - the right-hand-side vector
2504: Output Parameter:
2505: . x - the result vector
2507: Notes:
2508: MatSolve() should be used for most applications, as it performs
2509: a forward solve followed by a backward solve.
2511: The vectors b and x cannot be the same. I.e., one cannot
2512: call MatForwardSolve(A,x,x).
2514: Most users should employ the simplified KSP interface for linear solvers
2515: instead of working directly with matrix algebra routines such as this.
2516: See, e.g., KSPCreate().
2518: Level: developer
2520: Concepts: matrices^forward solves
2522: .seealso: MatSolve(), MatBackwardSolve()
2523: @ */
2524: PetscErrorCode PETSCMAT_DLLEXPORT MatForwardSolve(Mat mat,Vec b,Vec x)
2525: {
2535: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2536: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2537: if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2538: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2539: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2540: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2541: MatPreallocated(mat);
2542: PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
2543: (*mat->ops->forwardsolve)(mat,b,x);
2544: PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
2545: PetscObjectStateIncrease((PetscObject)x);
2546: return(0);
2547: }
2551: /* @
2552: MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU.
2554: Collective on Mat and Vec
2556: Input Parameters:
2557: + mat - the factored matrix
2558: - b - the right-hand-side vector
2560: Output Parameter:
2561: . x - the result vector
2563: Notes:
2564: MatSolve() should be used for most applications, as it performs
2565: a forward solve followed by a backward solve.
2567: The vectors b and x cannot be the same. I.e., one cannot
2568: call MatBackwardSolve(A,x,x).
2570: Most users should employ the simplified KSP interface for linear solvers
2571: instead of working directly with matrix algebra routines such as this.
2572: See, e.g., KSPCreate().
2574: Level: developer
2576: Concepts: matrices^backward solves
2578: .seealso: MatSolve(), MatForwardSolve()
2579: @ */
2580: PetscErrorCode PETSCMAT_DLLEXPORT MatBackwardSolve(Mat mat,Vec b,Vec x)
2581: {
2591: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2592: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2593: if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2594: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2595: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2596: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2597: MatPreallocated(mat);
2599: PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);
2600: (*mat->ops->backwardsolve)(mat,b,x);
2601: PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);
2602: PetscObjectStateIncrease((PetscObject)x);
2603: return(0);
2604: }
2608: /*@
2609: MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix.
2611: Collective on Mat and Vec
2613: Input Parameters:
2614: + mat - the factored matrix
2615: . b - the right-hand-side vector
2616: - y - the vector to be added to
2618: Output Parameter:
2619: . x - the result vector
2621: Notes:
2622: The vectors b and x cannot be the same. I.e., one cannot
2623: call MatSolveAdd(A,x,y,x).
2625: Most users should employ the simplified KSP interface for linear solvers
2626: instead of working directly with matrix algebra routines such as this.
2627: See, e.g., KSPCreate().
2629: Level: developer
2631: Concepts: matrices^triangular solves
2633: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
2634: @*/
2635: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
2636: {
2637: PetscScalar one = 1.0;
2638: Vec tmp;
2650: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2651: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2652: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2653: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2654: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
2655: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2656: if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2657: MatPreallocated(mat);
2659: PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);
2660: if (mat->ops->solveadd) {
2661: (*mat->ops->solveadd)(mat,b,y,x);
2662: } else {
2663: /* do the solve then the add manually */
2664: if (x != y) {
2665: MatSolve(mat,b,x);
2666: VecAXPY(x,one,y);
2667: } else {
2668: VecDuplicate(x,&tmp);
2669: PetscLogObjectParent(mat,tmp);
2670: VecCopy(x,tmp);
2671: MatSolve(mat,b,x);
2672: VecAXPY(x,one,tmp);
2673: VecDestroy(tmp);
2674: }
2675: }
2676: PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);
2677: PetscObjectStateIncrease((PetscObject)x);
2678: return(0);
2679: }
2683: /*@
2684: MatSolveTranspose - Solves A' x = b, given a factored matrix.
2686: Collective on Mat and Vec
2688: Input Parameters:
2689: + mat - the factored matrix
2690: - b - the right-hand-side vector
2692: Output Parameter:
2693: . x - the result vector
2695: Notes:
2696: The vectors b and x cannot be the same. I.e., one cannot
2697: call MatSolveTranspose(A,x,x).
2699: Most users should employ the simplified KSP interface for linear solvers
2700: instead of working directly with matrix algebra routines such as this.
2701: See, e.g., KSPCreate().
2703: Level: developer
2705: Concepts: matrices^triangular solves
2707: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
2708: @*/
2709: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTranspose(Mat mat,Vec b,Vec x)
2710: {
2720: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2721: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2722: if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2723: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2724: if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2725: MatPreallocated(mat);
2726: PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
2727: (*mat->ops->solvetranspose)(mat,b,x);
2728: PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
2729: PetscObjectStateIncrease((PetscObject)x);
2730: return(0);
2731: }
2735: /*@
2736: MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a
2737: factored matrix.
2739: Collective on Mat and Vec
2741: Input Parameters:
2742: + mat - the factored matrix
2743: . b - the right-hand-side vector
2744: - y - the vector to be added to
2746: Output Parameter:
2747: . x - the result vector
2749: Notes:
2750: The vectors b and x cannot be the same. I.e., one cannot
2751: call MatSolveTransposeAdd(A,x,y,x).
2753: Most users should employ the simplified KSP interface for linear solvers
2754: instead of working directly with matrix algebra routines such as this.
2755: See, e.g., KSPCreate().
2757: Level: developer
2759: Concepts: matrices^triangular solves
2761: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
2762: @*/
2763: PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
2764: {
2765: PetscScalar one = 1.0;
2767: Vec tmp;
2778: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2779: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2780: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2781: if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2782: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
2783: if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2784: MatPreallocated(mat);
2786: PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);
2787: if (mat->ops->solvetransposeadd) {
2788: (*mat->ops->solvetransposeadd)(mat,b,y,x);
2789: } else {
2790: /* do the solve then the add manually */
2791: if (x != y) {
2792: MatSolveTranspose(mat,b,x);
2793: VecAXPY(x,one,y);
2794: } else {
2795: VecDuplicate(x,&tmp);
2796: PetscLogObjectParent(mat,tmp);
2797: VecCopy(x,tmp);
2798: MatSolveTranspose(mat,b,x);
2799: VecAXPY(x,one,tmp);
2800: VecDestroy(tmp);
2801: }
2802: }
2803: PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);
2804: PetscObjectStateIncrease((PetscObject)x);
2805: return(0);
2806: }
2807: /* ----------------------------------------------------------------*/
2811: /*@
2812: MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.
2814: Collective on Mat and Vec
2816: Input Parameters:
2817: + mat - the matrix
2818: . b - the right hand side
2819: . omega - the relaxation factor
2820: . flag - flag indicating the type of SOR (see below)
2821: . shift - diagonal shift
2822: - its - the number of iterations
2823: - lits - the number of local iterations
2825: Output Parameters:
2826: . x - the solution (can contain an initial guess)
2828: SOR Flags:
2829: . SOR_FORWARD_SWEEP - forward SOR
2830: . SOR_BACKWARD_SWEEP - backward SOR
2831: . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2832: . SOR_LOCAL_FORWARD_SWEEP - local forward SOR
2833: . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR
2834: . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2835: . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies
2836: upper/lower triangular part of matrix to
2837: vector (with omega)
2838: . SOR_ZERO_INITIAL_GUESS - zero initial guess
2840: Notes:
2841: SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2842: SOR_LOCAL_SYMMETRIC_SWEEP perform separate independent smoothings
2843: on each processor.
2845: Application programmers will not generally use MatRelax() directly,
2846: but instead will employ the KSP/PC interface.
2848: Notes for Advanced Users:
2849: The flags are implemented as bitwise inclusive or operations.
2850: For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2851: to specify a zero initial guess for SSOR.
2853: Most users should employ the simplified KSP interface for linear solvers
2854: instead of working directly with matrix algebra routines such as this.
2855: See, e.g., KSPCreate().
2857: See also, MatPBRelax(). This routine will automatically call the point block
2858: version if the point version is not available.
2860: Level: developer
2862: Concepts: matrices^relaxation
2863: Concepts: matrices^SOR
2864: Concepts: matrices^Gauss-Seidel
2866: @*/
2867: PetscErrorCode PETSCMAT_DLLEXPORT MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2868: {
2878: if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2879: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2880: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2881: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2882: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2883: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2884: MatPreallocated(mat);
2885: PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2886: if (mat->ops->relax) {
2887: ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2888: } else {
2889: ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2890: }
2891: PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2892: PetscObjectStateIncrease((PetscObject)x);
2893: return(0);
2894: }
2898: /*@
2899: MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.
2901: Collective on Mat and Vec
2903: See MatRelax() for usage
2905: For multi-component PDEs where the Jacobian is stored in a point block format
2906: (with the PETSc BAIJ matrix formats) the relaxation is done one point block at
2907: a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved
2908: simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point.
2910: Level: developer
2912: @*/
2913: PetscErrorCode PETSCMAT_DLLEXPORT MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2914: {
2924: if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2925: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2926: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2927: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2928: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2929: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2930: MatPreallocated(mat);
2932: PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2933: ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2934: PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2935: PetscObjectStateIncrease((PetscObject)x);
2936: return(0);
2937: }
2941: /*
2942: Default matrix copy routine.
2943: */
2944: PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str)
2945: {
2946: PetscErrorCode ierr;
2947: PetscInt i,rstart,rend,nz;
2948: const PetscInt *cwork;
2949: const PetscScalar *vwork;
2952: if (B->assembled) {
2953: MatZeroEntries(B);
2954: }
2955: MatGetOwnershipRange(A,&rstart,&rend);
2956: for (i=rstart; i<rend; i++) {
2957: MatGetRow(A,i,&nz,&cwork,&vwork);
2958: MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2959: MatRestoreRow(A,i,&nz,&cwork,&vwork);
2960: }
2961: MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2962: MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2963: PetscObjectStateIncrease((PetscObject)B);
2964: return(0);
2965: }
2969: /*@
2970: MatCopy - Copys a matrix to another matrix.
2972: Collective on Mat
2974: Input Parameters:
2975: + A - the matrix
2976: - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN
2978: Output Parameter:
2979: . B - where the copy is put
2981: Notes:
2982: If you use SAME_NONZERO_PATTERN then the two matrices had better have the
2983: same nonzero pattern or the routine will crash.
2985: MatCopy() copies the matrix entries of a matrix to another existing
2986: matrix (after first zeroing the second matrix). A related routine is
2987: MatConvert(), which first creates a new matrix and then copies the data.
2989: Level: intermediate
2990:
2991: Concepts: matrices^copying
2993: .seealso: MatConvert(), MatDuplicate()
2995: @*/
2996: PetscErrorCode PETSCMAT_DLLEXPORT MatCopy(Mat A,Mat B,MatStructure str)
2997: {
3005: MatPreallocated(B);
3007: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3008: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3009: if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3010: MatPreallocated(A);
3012: PetscLogEventBegin(MAT_Copy,A,B,0,0);
3013: if (A->ops->copy) {
3014: (*A->ops->copy)(A,B,str);
3015: } else { /* generic conversion */
3016: MatCopy_Basic(A,B,str);
3017: }
3018: if (A->mapping) {
3019: if (B->mapping) {ISLocalToGlobalMappingDestroy(B->mapping);B->mapping = 0;}
3020: MatSetLocalToGlobalMapping(B,A->mapping);
3021: }
3022: if (A->bmapping) {
3023: if (B->bmapping) {ISLocalToGlobalMappingDestroy(B->bmapping);B->bmapping = 0;}
3024: MatSetLocalToGlobalMappingBlock(B,A->mapping);
3025: }
3026: PetscLogEventEnd(MAT_Copy,A,B,0,0);
3027: PetscObjectStateIncrease((PetscObject)B);
3028: return(0);
3029: }
3031: #include petscsys.h
3032: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
3033: PetscFList MatConvertList = 0;
3037: /*@C
3038: MatConvertRegister - Allows one to register a routine that converts a sparse matrix
3039: from one format to another.
3041: Not Collective
3043: Input Parameters:
3044: + type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ.
3045: - Converter - the function that reads the matrix from the binary file.
3047: Level: developer
3049: .seealso: MatConvertRegisterAll(), MatConvert()
3051: @*/
3052: PetscErrorCode PETSCMAT_DLLEXPORT MatConvertRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(Mat,MatType,MatReuse,Mat*))
3053: {
3055: char fullname[PETSC_MAX_PATH_LEN];
3058: PetscFListConcat(path,name,fullname);
3059: PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);
3060: return(0);
3061: }
3065: /*@C
3066: MatConvert - Converts a matrix to another matrix, either of the same
3067: or different type.
3069: Collective on Mat
3071: Input Parameters:
3072: + mat - the matrix
3073: . newtype - new matrix type. Use MATSAME to create a new matrix of the
3074: same type as the original matrix.
3075: - reuse - denotes if the destination matrix is to be created or reused. Currently
3076: MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use
3077: MAT_INITIAL_MATRIX.
3078: Output Parameter:
3079: . M - pointer to place new matrix
3081: Notes:
3082: MatConvert() first creates a new matrix and then copies the data from
3083: the first matrix. A related routine is MatCopy(), which copies the matrix
3084: entries of one matrix to another already existing matrix context.
3086: Level: intermediate
3088: Concepts: matrices^converting between storage formats
3090: .seealso: MatCopy(), MatDuplicate()
3091: @*/
3092: PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M)
3093: {
3094: PetscErrorCode ierr;
3095: PetscTruth sametype,issame,flg;
3096: char convname[256],mtype[256];
3097: Mat B;
3103: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3104: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3105: MatPreallocated(mat);
3107: PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
3108: if (flg) {
3109: newtype = mtype;
3110: }
3111: PetscLogEventBegin(MAT_Convert,mat,0,0,0);
3112:
3113: PetscTypeCompare((PetscObject)mat,newtype,&sametype);
3114: PetscStrcmp(newtype,"same",&issame);
3115: if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) {
3116: SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for inplace convertion currently");
3117: }
3118: if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) {
3119: (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
3120: } else {
3121: PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL;
3122: /*
3123: Order of precedence:
3124: 1) See if a specialized converter is known to the current matrix.
3125: 2) See if a specialized converter is known to the desired matrix class.
3126: 3) See if a good general converter is registered for the desired class
3127: (as of 6/27/03 only MATMPIADJ falls into this category).
3128: 4) See if a good general converter is known for the current matrix.
3129: 5) Use a really basic converter.
3130: */
3131: PetscStrcpy(convname,"MatConvert_");
3132: PetscStrcat(convname,mat->type_name);
3133: PetscStrcat(convname,"_");
3134: PetscStrcat(convname,newtype);
3135: PetscStrcat(convname,"_C");
3136: PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);
3138: if (!conv) {
3139: MatCreate(mat->comm,&B);
3140: MatSetSizes(B,mat->rmap.n,mat->cmap.n,mat->rmap.N,mat->cmap.N);
3141: MatSetType(B,newtype);
3142: PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);
3143: MatDestroy(B);
3144: if (!conv) {
3145: if (!MatConvertRegisterAllCalled) {
3146: MatConvertRegisterAll(PETSC_NULL);
3147: }
3148: PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);
3149: if (!conv) {
3150: if (mat->ops->convert) {
3151: conv = mat->ops->convert;
3152: } else {
3153: conv = MatConvert_Basic;
3154: }
3155: }
3156: }
3157: }
3158: (*conv)(mat,newtype,reuse,M);
3159: }
3160: B = *M;
3161: PetscLogEventEnd(MAT_Convert,mat,0,0,0);
3162: PetscObjectStateIncrease((PetscObject)B);
3163: return(0);
3164: }
3169: /*@
3170: MatDuplicate - Duplicates a matrix including the non-zero structure.
3172: Collective on Mat
3174: Input Parameters:
3175: + mat - the matrix
3176: - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
3177: values as well or not
3179: Output Parameter:
3180: . M - pointer to place new matrix
3182: Level: intermediate
3184: Concepts: matrices^duplicating
3186: .seealso: MatCopy(), MatConvert()
3187: @*/
3188: PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
3189: {
3191: Mat B;
3197: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3198: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3199: MatPreallocated(mat);
3201: *M = 0;
3202: PetscLogEventBegin(MAT_Convert,mat,0,0,0);
3203: if (!mat->ops->duplicate) {
3204: SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
3205: }
3206: (*mat->ops->duplicate)(mat,op,M);
3207: B = *M;
3208: if (mat->mapping) {
3209: MatSetLocalToGlobalMapping(B,mat->mapping);
3210: }
3211: if (mat->bmapping) {
3212: MatSetLocalToGlobalMappingBlock(B,mat->bmapping);
3213: }
3214: PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);
3215: PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);
3216:
3217: PetscLogEventEnd(MAT_Convert,mat,0,0,0);
3218: PetscObjectStateIncrease((PetscObject)B);
3219: return(0);
3220: }
3224: /*@
3225: MatGetDiagonal - Gets the diagonal of a matrix.
3227: Collective on Mat and Vec
3229: Input Parameters:
3230: + mat - the matrix
3231: - v - the vector for storing the diagonal
3233: Output Parameter:
3234: . v - the diagonal of the matrix
3236: Notes:
3237: For the SeqAIJ matrix format, this routine may also be called
3238: on a LU factored matrix; in that case it routines the reciprocal of
3239: the diagonal entries in U. It returns the entries permuted by the
3240: row and column permutation used during the symbolic factorization.
3242: Level: intermediate
3244: Concepts: matrices^accessing diagonals
3246: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
3247: @*/
3248: PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v)
3249: {
3256: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3257: if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3258: MatPreallocated(mat);
3260: (*mat->ops->getdiagonal)(mat,v);
3261: PetscObjectStateIncrease((PetscObject)v);
3262: return(0);
3263: }
3267: /*@
3268: MatGetRowMax - Gets the maximum value (in absolute value) of each
3269: row of the matrix
3271: Collective on Mat and Vec
3273: Input Parameters:
3274: . mat - the matrix
3276: Output Parameter:
3277: . v - the vector for storing the maximums
3279: Level: intermediate
3281: Concepts: matrices^getting row maximums
3283: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
3284: @*/
3285: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v)
3286: {
3293: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3294: if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3295: MatPreallocated(mat);
3297: (*mat->ops->getrowmax)(mat,v);
3298: PetscObjectStateIncrease((PetscObject)v);
3299: return(0);
3300: }
3304: /*@C
3305: MatTranspose - Computes an in-place or out-of-place transpose of a matrix.
3307: Collective on Mat
3309: Input Parameter:
3310: . mat - the matrix to transpose
3312: Output Parameters:
3313: . B - the transpose (or pass in PETSC_NULL for an in-place transpose)
3315: Level: intermediate
3317: Concepts: matrices^transposing
3319: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose()
3320: @*/
3321: PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B)
3322: {
3328: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3329: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3330: if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3331: MatPreallocated(mat);
3333: PetscLogEventBegin(MAT_Transpose,mat,0,0,0);
3334: (*mat->ops->transpose)(mat,B);
3335: PetscLogEventEnd(MAT_Transpose,mat,0,0,0);
3336: if (B) {PetscObjectStateIncrease((PetscObject)*B);}
3337: return(0);
3338: }
3342: /*@C
3343: MatIsTranspose - Test whether a matrix is another one's transpose,
3344: or its own, in which case it tests symmetry.
3346: Collective on Mat
3348: Input Parameter:
3349: + A - the matrix to test
3350: - B - the matrix to test against, this can equal the first parameter
3352: Output Parameters:
3353: . flg - the result
3355: Notes:
3356: Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm
3357: has a running time of the order of the number of nonzeros; the parallel
3358: test involves parallel copies of the block-offdiagonal parts of the matrix.
3360: Level: intermediate
3362: Concepts: matrices^transposing, matrix^symmetry
3364: .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian()
3365: @*/
3366: PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg)
3367: {
3368: PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*);
3374: PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);
3375: PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);
3376: if (f && g) {
3377: if (f==g) {
3378: (*f)(A,B,tol,flg);
3379: } else {
3380: SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test");
3381: }
3382: }
3383: return(0);
3384: }
3388: /*@C
3389: MatPermute - Creates a new matrix with rows and columns permuted from the
3390: original.
3392: Collective on Mat
3394: Input Parameters:
3395: + mat - the matrix to permute
3396: . row - row permutation, each processor supplies only the permutation for its rows
3397: - col - column permutation, each processor needs the entire column permutation, that is
3398: this is the same size as the total number of columns in the matrix
3400: Output Parameters:
3401: . B - the permuted matrix
3403: Level: advanced
3405: Concepts: matrices^permuting
3407: .seealso: MatGetOrdering()
3408: @*/
3409: PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B)
3410: {
3419: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3420: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3421: if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"MatPermute not available for Mat type %s",mat->type_name);
3422: MatPreallocated(mat);
3424: (*mat->ops->permute)(mat,row,col,B);
3425: PetscObjectStateIncrease((PetscObject)*B);
3426: return(0);
3427: }
3431: /*@C
3432: MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the
3433: original and sparsified to the prescribed tolerance.
3435: Collective on Mat
3437: Input Parameters:
3438: + A - The matrix to permute
3439: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
3440: . frac - The half-bandwidth as a fraction of the total size, or 0.0
3441: . tol - The drop tolerance
3442: . rowp - The row permutation
3443: - colp - The column permutation
3445: Output Parameter:
3446: . B - The permuted, sparsified matrix
3448: Level: advanced
3450: Note:
3451: The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
3452: restrict the half-bandwidth of the resulting matrix to 5% of the
3453: total matrix size.
3455: .keywords: matrix, permute, sparsify
3457: .seealso: MatGetOrdering(), MatPermute()
3458: @*/
3459: PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
3460: {
3461: IS irowp, icolp;
3462: PetscInt *rows, *cols;
3463: PetscInt M, N, locRowStart, locRowEnd;
3464: PetscInt nz, newNz;
3465: const PetscInt *cwork;
3466: PetscInt *cnew;
3467: const PetscScalar *vwork;
3468: PetscScalar *vnew;
3469: PetscInt bw, issize;
3470: PetscInt row, locRow, newRow, col, newCol;
3471: PetscErrorCode ierr;
3478: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
3479: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
3480: if (!A->ops->permutesparsify) {
3481: MatGetSize(A, &M, &N);
3482: MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
3483: ISGetSize(rowp, &issize);
3484: if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M);
3485: ISGetSize(colp, &issize);
3486: if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N);
3487: ISInvertPermutation(rowp, 0, &irowp);
3488: ISGetIndices(irowp, &rows);
3489: ISInvertPermutation(colp, 0, &icolp);
3490: ISGetIndices(icolp, &cols);
3491: PetscMalloc(N * sizeof(PetscInt), &cnew);
3492: PetscMalloc(N * sizeof(PetscScalar), &vnew);
3494: /* Setup bandwidth to include */
3495: if (band == PETSC_DECIDE) {
3496: if (frac <= 0.0)
3497: bw = (PetscInt) (M * 0.05);
3498: else
3499: bw = (PetscInt) (M * frac);
3500: } else {
3501: if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
3502: bw = band;
3503: }
3505: /* Put values into new matrix */
3506: MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
3507: for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
3508: MatGetRow(A, row, &nz, &cwork, &vwork);
3509: newRow = rows[locRow]+locRowStart;
3510: for(col = 0, newNz = 0; col < nz; col++) {
3511: newCol = cols[cwork[col]];
3512: if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
3513: cnew[newNz] = newCol;
3514: vnew[newNz] = vwork[col];
3515: newNz++;
3516: }
3517: }
3518: MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
3519: MatRestoreRow(A, row, &nz, &cwork, &vwork);
3520: }
3521: PetscFree(cnew);
3522: PetscFree(vnew);
3523: MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
3524: MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
3525: ISRestoreIndices(irowp, &rows);
3526: ISRestoreIndices(icolp, &cols);
3527: ISDestroy(irowp);
3528: ISDestroy(icolp);
3529: } else {
3530: (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
3531: }
3532: PetscObjectStateIncrease((PetscObject)*B);
3533: return(0);
3534: }
3538: /*@
3539: MatEqual - Compares two matrices.
3541: Collective on Mat
3543: Input Parameters:
3544: + A - the first matrix
3545: - B - the second matrix
3547: Output Parameter:
3548: . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.
3550: Level: intermediate
3552: Concepts: matrices^equality between
3553: @*/
3554: PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg)
3555: {
3563: MatPreallocated(B);
3566: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3567: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3568: if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3569: if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
3570: if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
3571: if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name);
3572: MatPreallocated(A);
3574: (*A->ops->equal)(A,B,flg);
3575: return(0);
3576: }
3580: /*@
3581: MatDiagonalScale - Scales a matrix on the left and right by diagonal
3582: matrices that are stored as vectors. Either of the two scaling
3583: matrices can be PETSC_NULL.
3585: Collective on Mat
3587: Input Parameters:
3588: + mat - the matrix to be scaled
3589: . l - the left scaling vector (or PETSC_NULL)
3590: - r - the right scaling vector (or PETSC_NULL)
3592: Notes:
3593: MatDiagonalScale() computes A = LAR, where
3594: L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector)
3596: Level: intermediate
3598: Concepts: matrices^diagonal scaling
3599: Concepts: diagonal scaling of matrices
3601: .seealso: MatScale()
3602: @*/
3603: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r)
3604: {
3610: if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3613: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3614: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3615: MatPreallocated(mat);
3617: PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3618: (*mat->ops->diagonalscale)(mat,l,r);
3619: PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3620: PetscObjectStateIncrease((PetscObject)mat);
3621: return(0);
3622: }
3626: /*@
3627: MatScale - Scales all elements of a matrix by a given number.
3629: Collective on Mat
3631: Input Parameters:
3632: + mat - the matrix to be scaled
3633: - a - the scaling value
3635: Output Parameter:
3636: . mat - the scaled matrix
3638: Level: intermediate
3640: Concepts: matrices^scaling all entries
3642: .seealso: MatDiagonalScale()
3643: @*/
3644: PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a)
3645: {
3651: if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3652: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3653: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3654: MatPreallocated(mat);
3656: PetscLogEventBegin(MAT_Scale,mat,0,0,0);
3657: (*mat->ops->scale)(mat,a);
3658: PetscLogEventEnd(MAT_Scale,mat,0,0,0);
3659: PetscObjectStateIncrease((PetscObject)mat);
3660: return(0);
3661: }
3665: /*@
3666: MatNorm - Calculates various norms of a matrix.
3668: Collective on Mat
3670: Input Parameters:
3671: + mat - the matrix
3672: - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY
3674: Output Parameters:
3675: . nrm - the resulting norm
3677: Level: intermediate
3679: Concepts: matrices^norm
3680: Concepts: norm^of matrix
3681: @*/
3682: PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm)
3683: {
3691: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3692: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3693: if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3694: MatPreallocated(mat);
3696: (*mat->ops->norm)(mat,type,nrm);
3697: return(0);
3698: }
3700: /*
3701: This variable is used to prevent counting of MatAssemblyBegin() that
3702: are called from within a MatAssemblyEnd().
3703: */
3704: static PetscInt MatAssemblyEnd_InUse = 0;
3707: /*@
3708: MatAssemblyBegin - Begins assembling the matrix. This routine should
3709: be called after completing all calls to MatSetValues().
3711: Collective on Mat
3713: Input Parameters:
3714: + mat - the matrix
3715: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3716:
3717: Notes:
3718: MatSetValues() generally caches the values. The matrix is ready to
3719: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3720: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3721: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3722: using the matrix.
3724: Level: beginner
3726: Concepts: matrices^assembling
3728: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3729: @*/
3730: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type)
3731: {
3737: MatPreallocated(mat);
3738: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3739: if (mat->assembled) {
3740: mat->was_assembled = PETSC_TRUE;
3741: mat->assembled = PETSC_FALSE;
3742: }
3743: if (!MatAssemblyEnd_InUse) {
3744: PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
3745: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3746: PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
3747: } else {
3748: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3749: }
3750: return(0);
3751: }
3755: /*@
3756: MatAssembled - Indicates if a matrix has been assembled and is ready for
3757: use; for example, in matrix-vector product.
3759: Collective on Mat
3761: Input Parameter:
3762: . mat - the matrix
3764: Output Parameter:
3765: . assembled - PETSC_TRUE or PETSC_FALSE
3767: Level: advanced
3769: Concepts: matrices^assembled?
3771: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3772: @*/
3773: PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled)
3774: {
3779: *assembled = mat->assembled;
3780: return(0);
3781: }
3785: /*
3786: Processes command line options to determine if/how a matrix
3787: is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3788: */
3789: PetscErrorCode MatView_Private(Mat mat)
3790: {
3791: PetscErrorCode ierr;
3792: PetscTruth flg;
3793: static PetscTruth incall = PETSC_FALSE;
3796: if (incall) return(0);
3797: incall = PETSC_TRUE;
3798: PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3799: PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);
3800: if (flg) {
3801: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3802: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3803: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3804: }
3805: PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);
3806: if (flg) {
3807: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3808: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3809: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3810: }
3811: PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);
3812: if (flg) {
3813: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3814: }
3815: PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);
3816: if (flg) {
3817: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3818: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3819: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3820: }
3821: #if defined(PETSC_USE_SOCKET_VIEWER)
3822: PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);
3823: if (flg) {
3824: MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3825: PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3826: }
3827: #endif
3828: PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);
3829: if (flg) {
3830: MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3831: PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3832: }
3833: PetscOptionsEnd();
3834: /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */
3835: PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
3836: if (flg) {
3837: PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
3838: if (flg) {
3839: PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3840: }
3841: MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3842: PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3843: if (flg) {
3844: PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3845: }
3846: }
3847: incall = PETSC_FALSE;
3848: return(0);
3849: }
3853: /*@
3854: MatAssemblyEnd - Completes assembling the matrix. This routine should
3855: be called after MatAssemblyBegin().
3857: Collective on Mat
3859: Input Parameters:
3860: + mat - the matrix
3861: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3863: Options Database Keys:
3864: + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3865: . -mat_view_info_detailed - Prints more detailed info
3866: . -mat_view - Prints matrix in ASCII format
3867: . -mat_view_matlab - Prints matrix in Matlab format
3868: . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3869: . -display <name> - Sets display name (default is host)
3870: . -draw_pause <sec> - Sets number of seconds to pause after display
3871: . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3872: . -viewer_socket_machine <machine>
3873: . -viewer_socket_port <port>
3874: . -mat_view_binary - save matrix to file in binary format
3875: - -viewer_binary_filename <name>
3877: Notes:
3878: MatSetValues() generally caches the values. The matrix is ready to
3879: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3880: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3881: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3882: using the matrix.
3884: Level: beginner
3886: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3887: @*/
3888: PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type)
3889: {
3890: PetscErrorCode ierr;
3891: static PetscInt inassm = 0;
3892: PetscTruth flg;
3898: inassm++;
3899: MatAssemblyEnd_InUse++;
3900: if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3901: PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
3902: if (mat->ops->assemblyend) {
3903: (*mat->ops->assemblyend)(mat,type);
3904: }
3905: PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
3906: } else {
3907: if (mat->ops->assemblyend) {
3908: (*mat->ops->assemblyend)(mat,type);
3909: }
3910: }
3912: /* Flush assembly is not a true assembly */
3913: if (type != MAT_FLUSH_ASSEMBLY) {
3914: mat->assembled = PETSC_TRUE; mat->num_ass++;
3915: }
3916: mat->insertmode = NOT_SET_VALUES;
3917: MatAssemblyEnd_InUse--;
3918: PetscObjectStateIncrease((PetscObject)mat);
3919: if (!mat->symmetric_eternal) {
3920: mat->symmetric_set = PETSC_FALSE;
3921: mat->hermitian_set = PETSC_FALSE;
3922: mat->structurally_symmetric_set = PETSC_FALSE;
3923: }
3924: if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3925: MatView_Private(mat);
3926: PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);
3927: if (flg) {
3928: PetscReal tol = 0.0;
3929: PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);
3930: MatIsSymmetric(mat,tol,&flg);
3931: if (flg) {
3932: PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);
3933: } else {
3934: PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);
3935: }
3936: }
3937: }
3938: inassm--;
3939: PetscOptionsHasName(mat->prefix,"-help",&flg);
3940: if (flg) {
3941: MatPrintHelp(mat);
3942: }
3943: return(0);
3944: }
3949: /*@
3950: MatCompress - Tries to store the matrix in as little space as
3951: possible. May fail if memory is already fully used, since it
3952: tries to allocate new space.
3954: Collective on Mat
3956: Input Parameters:
3957: . mat - the matrix
3959: Level: advanced
3961: @*/
3962: PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat)
3963: {
3969: MatPreallocated(mat);
3970: if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3971: return(0);
3972: }
3976: /*@
3977: MatSetOption - Sets a parameter option for a matrix. Some options
3978: may be specific to certain storage formats. Some options
3979: determine how values will be inserted (or added). Sorted,
3980: row-oriented input will generally assemble the fastest. The default
3981: is row-oriented, nonsorted input.
3983: Collective on Mat
3985: Input Parameters:
3986: + mat - the matrix
3987: - option - the option, one of those listed below (and possibly others),
3988: e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR
3990: Options Describing Matrix Structure:
3991: + MAT_SYMMETRIC - symmetric in terms of both structure and value
3992: . MAT_HERMITIAN - transpose is the complex conjugation
3993: . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
3994: . MAT_NOT_SYMMETRIC - not symmetric in value
3995: . MAT_NOT_HERMITIAN - transpose is not the complex conjugation
3996: . MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure
3997: . MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag
3998: you set to be kept with all future use of the matrix
3999: including after MatAssemblyBegin/End() which could
4000: potentially change the symmetry structure, i.e. you
4001: KNOW the matrix will ALWAYS have the property you set.
4002: - MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the
4003: flags you set will be dropped (in case potentially
4004: the symmetry etc was lost).
4006: Options For Use with MatSetValues():
4007: Insert a logically dense subblock, which can be
4008: + MAT_ROW_ORIENTED - row-oriented (default)
4009: . MAT_COLUMN_ORIENTED - column-oriented
4010: . MAT_ROWS_SORTED - sorted by row
4011: . MAT_ROWS_UNSORTED - not sorted by row (default)
4012: . MAT_COLUMNS_SORTED - sorted by column
4013: - MAT_COLUMNS_UNSORTED - not sorted by column (default)
4015: Not these options reflect the data you pass in with MatSetValues(); it has
4016: nothing to do with how the data is stored internally in the matrix
4017: data structure.
4019: When (re)assembling a matrix, we can restrict the input for
4020: efficiency/debugging purposes. These options include
4021: + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
4022: allowed if they generate a new nonzero
4023: . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
4024: . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
4025: they generate a nonzero in a new diagonal (for block diagonal format only)
4026: . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
4027: . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
4028: . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
4029: - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly
4031: Notes:
4032: Some options are relevant only for particular matrix types and
4033: are thus ignored by others. Other options are not supported by
4034: certain matrix types and will generate an error message if set.
4036: If using a Fortran 77 module to compute a matrix, one may need to
4037: use the column-oriented option (or convert to the row-oriented
4038: format).
4040: MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion
4041: that would generate a new entry in the nonzero structure is instead
4042: ignored. Thus, if memory has not alredy been allocated for this particular
4043: data, then the insertion is ignored. For dense matrices, in which
4044: the entire array is allocated, no entries are ever ignored.
4045: Set after the first MatAssemblyEnd()
4047: MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion
4048: that would generate a new entry in the nonzero structure instead produces
4049: an error. (Currently supported for AIJ and BAIJ formats only.)
4050: This is a useful flag when using SAME_NONZERO_PATTERN in calling
4051: KSPSetOperators() to ensure that the nonzero pattern truely does
4052: remain unchanged. Set after the first MatAssemblyEnd()
4054: MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion
4055: that would generate a new entry that has not been preallocated will
4056: instead produce an error. (Currently supported for AIJ and BAIJ formats
4057: only.) This is a useful flag when debugging matrix memory preallocation.
4059: MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for
4060: other processors should be dropped, rather than stashed.
4061: This is useful if you know that the "owning" processor is also
4062: always generating the correct matrix entries, so that PETSc need
4063: not transfer duplicate entries generated on another processor.
4064:
4065: MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
4066: searches during matrix assembly. When this flag is set, the hash table
4067: is created during the first Matrix Assembly. This hash table is
4068: used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
4069: to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag
4070: should be used with MAT_USE_HASH_TABLE flag. This option is currently
4071: supported by MATMPIBAIJ format only.
4073: MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries
4074: are kept in the nonzero structure
4076: MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating
4077: a zero location in the matrix
4079: MAT_USE_INODES - indicates using inode version of the code - works with AIJ and
4080: ROWBS matrix types
4082: MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
4083: with AIJ and ROWBS matrix types (database option "-mat_no_inode")
4085: Level: intermediate
4087: Concepts: matrices^setting options
4089: @*/
4090: PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op)
4091: {
4097: MatPreallocated(mat);
4098: switch (op) {
4099: case MAT_SYMMETRIC:
4100: mat->symmetric = PETSC_TRUE;
4101: mat->structurally_symmetric = PETSC_TRUE;
4102: mat->symmetric_set = PETSC_TRUE;
4103: mat->structurally_symmetric_set = PETSC_TRUE;
4104: break;
4105: case MAT_HERMITIAN:
4106: mat->hermitian = PETSC_TRUE;
4107: mat->structurally_symmetric = PETSC_TRUE;
4108: mat->hermitian_set = PETSC_TRUE;
4109: mat->structurally_symmetric_set = PETSC_TRUE;
4110: break;
4111: case MAT_STRUCTURALLY_SYMMETRIC:
4112: mat->structurally_symmetric = PETSC_TRUE;
4113: mat->structurally_symmetric_set = PETSC_TRUE;
4114: break;
4115: case MAT_NOT_SYMMETRIC:
4116: mat->symmetric = PETSC_FALSE;
4117: mat->symmetric_set = PETSC_TRUE;
4118: break;
4119: case MAT_NOT_HERMITIAN:
4120: mat->hermitian = PETSC_FALSE;
4121: mat->hermitian_set = PETSC_TRUE;
4122: break;
4123: case MAT_NOT_STRUCTURALLY_SYMMETRIC:
4124: mat->structurally_symmetric = PETSC_FALSE;
4125: mat->structurally_symmetric_set = PETSC_TRUE;
4126: break;
4127: case MAT_SYMMETRY_ETERNAL:
4128: mat->symmetric_eternal = PETSC_TRUE;
4129: break;
4130: case MAT_NOT_SYMMETRY_ETERNAL:
4131: mat->symmetric_eternal = PETSC_FALSE;
4132: break;
4133: default:
4134: break;
4135: }
4136: if (mat->ops->setoption) {
4137: (*mat->ops->setoption)(mat,op);
4138: }
4139: return(0);
4140: }
4144: /*@
4145: MatZeroEntries - Zeros all entries of a matrix. For sparse matrices
4146: this routine retains the old nonzero structure.
4148: Collective on Mat
4150: Input Parameters:
4151: . mat - the matrix
4153: Level: intermediate
4155: Concepts: matrices^zeroing
4157: .seealso: MatZeroRows()
4158: @*/
4159: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat)
4160: {
4166: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4167: if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled");
4168: if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4169: MatPreallocated(mat);
4171: PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
4172: (*mat->ops->zeroentries)(mat);
4173: PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
4174: PetscObjectStateIncrease((PetscObject)mat);
4175: return(0);
4176: }
4180: /*@C
4181: MatZeroRows - Zeros all entries (except possibly the main diagonal)
4182: of a set of rows of a matrix.
4184: Collective on Mat
4186: Input Parameters:
4187: + mat - the matrix
4188: . numRows - the number of rows to remove
4189: . rows - the global row indices
4190: - diag - value put in all diagonals of eliminated rows
4192: Notes:
4193: For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4194: but does not release memory. For the dense and block diagonal
4195: formats this does not alter the nonzero structure.
4197: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4198: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4199: merely zeroed.
4201: The user can set a value in the diagonal entry (or for the AIJ and
4202: row formats can optionally remove the main diagonal entry from the
4203: nonzero structure as well, by passing 0.0 as the final argument).
4205: For the parallel case, all processes that share the matrix (i.e.,
4206: those in the communicator used for matrix creation) MUST call this
4207: routine, regardless of whether any rows being zeroed are owned by
4208: them.
4210: Each processor should list the rows that IT wants zeroed
4212: Level: intermediate
4214: Concepts: matrices^zeroing rows
4216: .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4217: @*/
4218: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4219: {
4226: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4227: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4228: if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4229: MatPreallocated(mat);
4231: (*mat->ops->zerorows)(mat,numRows,rows,diag);
4232: MatView_Private(mat);
4233: PetscObjectStateIncrease((PetscObject)mat);
4234: return(0);
4235: }
4239: /*@C
4240: MatZeroRowsIS - Zeros all entries (except possibly the main diagonal)
4241: of a set of rows of a matrix.
4243: Collective on Mat
4245: Input Parameters:
4246: + mat - the matrix
4247: . is - index set of rows to remove
4248: - diag - value put in all diagonals of eliminated rows
4250: Notes:
4251: For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4252: but does not release memory. For the dense and block diagonal
4253: formats this does not alter the nonzero structure.
4255: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4256: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4257: merely zeroed.
4259: The user can set a value in the diagonal entry (or for the AIJ and
4260: row formats can optionally remove the main diagonal entry from the
4261: nonzero structure as well, by passing 0.0 as the final argument).
4263: For the parallel case, all processes that share the matrix (i.e.,
4264: those in the communicator used for matrix creation) MUST call this
4265: routine, regardless of whether any rows being zeroed are owned by
4266: them.
4268: Each processor should list the rows that IT wants zeroed
4270: Level: intermediate
4272: Concepts: matrices^zeroing rows
4274: .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4275: @*/
4276: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag)
4277: {
4278: PetscInt numRows;
4279: PetscInt *rows;
4286: ISGetLocalSize(is,&numRows);
4287: ISGetIndices(is,&rows);
4288: MatZeroRows(mat,numRows,rows,diag);
4289: ISRestoreIndices(is,&rows);
4290: return(0);
4291: }
4295: /*@C
4296: MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
4297: of a set of rows of a matrix; using local numbering of rows.
4299: Collective on Mat
4301: Input Parameters:
4302: + mat - the matrix
4303: . numRows - the number of rows to remove
4304: . rows - the global row indices
4305: - diag - value put in all diagonals of eliminated rows
4307: Notes:
4308: Before calling MatZeroRowsLocal(), the user must first set the
4309: local-to-global mapping by calling MatSetLocalToGlobalMapping().
4311: For the AIJ matrix formats this removes the old nonzero structure,
4312: but does not release memory. For the dense and block diagonal
4313: formats this does not alter the nonzero structure.
4315: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4316: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4317: merely zeroed.
4319: The user can set a value in the diagonal entry (or for the AIJ and
4320: row formats can optionally remove the main diagonal entry from the
4321: nonzero structure as well, by passing 0.0 as the final argument).
4323: Level: intermediate
4325: Concepts: matrices^zeroing
4327: .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4328: @*/
4329: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4330: {
4337: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4338: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4339: MatPreallocated(mat);
4341: if (mat->ops->zerorowslocal) {
4342: (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);
4343: } else {
4344: IS is, newis;
4345: PetscInt *newRows;
4347: if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
4348: ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);
4349: ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
4350: ISGetIndices(newis,&newRows);
4351: (*mat->ops->zerorows)(mat,numRows,newRows,diag);
4352: ISRestoreIndices(newis,&newRows);
4353: ISDestroy(newis);
4354: ISDestroy(is);
4355: }
4356: PetscObjectStateIncrease((PetscObject)mat);
4357: return(0);
4358: }
4362: /*@C
4363: MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
4364: of a set of rows of a matrix; using local numbering of rows.
4366: Collective on Mat
4368: Input Parameters:
4369: + mat - the matrix
4370: . is - index set of rows to remove
4371: - diag - value put in all diagonals of eliminated rows
4373: Notes:
4374: Before calling MatZeroRowsLocal(), the user must first set the
4375: local-to-global mapping by calling MatSetLocalToGlobalMapping().
4377: For the AIJ matrix formats this removes the old nonzero structure,
4378: but does not release memory. For the dense and block diagonal
4379: formats this does not alter the nonzero structure.
4381: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4382: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4383: merely zeroed.
4385: The user can set a value in the diagonal entry (or for the AIJ and
4386: row formats can optionally remove the main diagonal entry from the
4387: nonzero structure as well, by passing 0.0 as the final argument).
4389: Level: intermediate
4391: Concepts: matrices^zeroing
4393: .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4394: @*/
4395: PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag)
4396: {
4398: PetscInt numRows;
4399: PetscInt *rows;
4405: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4406: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4407: MatPreallocated(mat);
4409: ISGetLocalSize(is,&numRows);
4410: ISGetIndices(is,&rows);
4411: MatZeroRowsLocal(mat,numRows,rows,diag);
4412: ISRestoreIndices(is,&rows);
4413: return(0);
4414: }
4418: /*@
4419: MatGetSize - Returns the numbers of rows and columns in a matrix.
4421: Not Collective
4423: Input Parameter:
4424: . mat - the matrix
4426: Output Parameters:
4427: + m - the number of global rows
4428: - n - the number of global columns
4430: Note: both output parameters can be PETSC_NULL on input.
4432: Level: beginner
4434: Concepts: matrices^size
4436: .seealso: MatGetLocalSize()
4437: @*/
4438: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n)
4439: {
4442: if (m) *m = mat->rmap.N;
4443: if (n) *n = mat->cmap.N;
4444: return(0);
4445: }
4449: /*@
4450: MatGetLocalSize - Returns the number of rows and columns in a matrix
4451: stored locally. This information may be implementation dependent, so
4452: use with care.
4454: Not Collective
4456: Input Parameters:
4457: . mat - the matrix
4459: Output Parameters:
4460: + m - the number of local rows
4461: - n - the number of local columns
4463: Note: both output parameters can be PETSC_NULL on input.
4465: Level: beginner
4467: Concepts: matrices^local size
4469: .seealso: MatGetSize()
4470: @*/
4471: PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n)
4472: {
4477: if (m) *m = mat->rmap.n;
4478: if (n) *n = mat->cmap.n;
4479: return(0);
4480: }
4484: /*@
4485: MatGetOwnershipRange - Returns the range of matrix rows owned by
4486: this processor, assuming that the matrix is laid out with the first
4487: n1 rows on the first processor, the next n2 rows on the second, etc.
4488: For certain parallel layouts this range may not be well defined.
4490: Not Collective
4492: Input Parameters:
4493: . mat - the matrix
4495: Output Parameters:
4496: + m - the global index of the first local row
4497: - n - one more than the global index of the last local row
4499: Note: both output parameters can be PETSC_NULL on input.
4501: Level: beginner
4503: Concepts: matrices^row ownership
4504: @*/
4505: PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n)
4506: {
4514: MatPreallocated(mat);
4515: if (m) *m = mat->rmap.rstart;
4516: if (n) *n = mat->rmap.rend;
4517: return(0);
4518: }
4522: /*@
4523: MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
4524: Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric()
4525: to complete the factorization.
4527: Collective on Mat
4529: Input Parameters:
4530: + mat - the matrix
4531: . row - row permutation
4532: . column - column permutation
4533: - info - structure containing
4534: $ levels - number of levels of fill.
4535: $ expected fill - as ratio of original fill.
4536: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
4537: missing diagonal entries)
4539: Output Parameters:
4540: . fact - new matrix that has been symbolically factored
4542: Notes:
4543: See the users manual for additional information about
4544: choosing the fill factor for better efficiency.
4546: Most users should employ the simplified KSP interface for linear solvers
4547: instead of working directly with matrix algebra routines such as this.
4548: See, e.g., KSPCreate().
4550: Level: developer
4552: Concepts: matrices^symbolic LU factorization
4553: Concepts: matrices^factorization
4554: Concepts: LU^symbolic factorization
4556: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4557: MatGetOrdering(), MatFactorInfo
4559: @*/
4560: PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
4561: {
4571: if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels);
4572: if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4573: if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name);
4574: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4575: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4576: MatPreallocated(mat);
4578: PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
4579: (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
4580: PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
4581: return(0);
4582: }
4586: /*@
4587: MatICCFactorSymbolic - Performs symbolic incomplete
4588: Cholesky factorization for a symmetric matrix. Use
4589: MatCholeskyFactorNumeric() to complete the factorization.
4591: Collective on Mat
4593: Input Parameters:
4594: + mat - the matrix
4595: . perm - row and column permutation
4596: - info - structure containing
4597: $ levels - number of levels of fill.
4598: $ expected fill - as ratio of original fill.
4600: Output Parameter:
4601: . fact - the factored matrix
4603: Notes:
4604: Currently only no-fill factorization is supported.
4606: Most users should employ the simplified KSP interface for linear solvers
4607: instead of working directly with matrix algebra routines such as this.
4608: See, e.g., KSPCreate().
4610: Level: developer
4612: Concepts: matrices^symbolic incomplete Cholesky factorization
4613: Concepts: matrices^factorization
4614: Concepts: Cholsky^symbolic factorization
4616: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
4617: @*/
4618: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
4619: {
4628: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4629: if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels);
4630: if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4631: if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name);
4632: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4633: MatPreallocated(mat);
4635: PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
4636: (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
4637: PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
4638: return(0);
4639: }
4643: /*@C
4644: MatGetArray - Returns a pointer to the element values in the matrix.
4645: The result of this routine is dependent on the underlying matrix data
4646: structure, and may not even work for certain matrix types. You MUST
4647: call MatRestoreArray() when you no longer need to access the array.
4649: Not Collective
4651: Input Parameter:
4652: . mat - the matrix
4654: Output Parameter:
4655: . v - the location of the values
4658: Fortran Note:
4659: This routine is used differently from Fortran, e.g.,
4660: .vb
4661: Mat mat
4662: PetscScalar mat_array(1)
4663: PetscOffset i_mat
4664: PetscErrorCode ierr
4665: call MatGetArray(mat,mat_array,i_mat,ierr)
4667: C Access first local entry in matrix; note that array is
4668: C treated as one dimensional
4669: value = mat_array(i_mat + 1)
4671: [... other code ...]
4672: call MatRestoreArray(mat,mat_array,i_mat,ierr)
4673: .ve
4675: See the Fortran chapter of the users manual and
4676: petsc/src/mat/examples/tests for details.
4678: Level: advanced
4680: Concepts: matrices^access array
4682: .seealso: MatRestoreArray(), MatGetArrayF90()
4683: @*/
4684: PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[])
4685: {
4692: if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4693: MatPreallocated(mat);
4694: (*mat->ops->getarray)(mat,v);
4695: return(0);
4696: }
4700: /*@C
4701: MatRestoreArray - Restores the matrix after MatGetArray() has been called.
4703: Not Collective
4705: Input Parameter:
4706: + mat - the matrix
4707: - v - the location of the values
4709: Fortran Note:
4710: This routine is used differently from Fortran, e.g.,
4711: .vb
4712: Mat mat
4713: PetscScalar mat_array(1)
4714: PetscOffset i_mat
4715: PetscErrorCode ierr
4716: call MatGetArray(mat,mat_array,i_mat,ierr)
4718: C Access first local entry in matrix; note that array is
4719: C treated as one dimensional
4720: value = mat_array(i_mat + 1)
4722: [... other code ...]
4723: call MatRestoreArray(mat,mat_array,i_mat,ierr)
4724: .ve
4726: See the Fortran chapter of the users manual and
4727: petsc/src/mat/examples/tests for details
4729: Level: advanced
4731: .seealso: MatGetArray(), MatRestoreArrayF90()
4732: @*/
4733: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[])
4734: {
4741: #if defined(PETSC_USE_DEBUG)
4742: CHKMEMQ;
4743: #endif
4744: if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4745: (*mat->ops->restorearray)(mat,v);
4746: PetscObjectStateIncrease((PetscObject)mat);
4747: return(0);
4748: }
4752: /*@C
4753: MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
4754: points to an array of valid matrices, they may be reused to store the new
4755: submatrices.
4757: Collective on Mat
4759: Input Parameters:
4760: + mat - the matrix
4761: . n - the number of submatrixes to be extracted (on this processor, may be zero)
4762: . irow, icol - index sets of rows and columns to extract
4763: - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
4765: Output Parameter:
4766: . submat - the array of submatrices
4768: Notes:
4769: MatGetSubMatrices() can extract only sequential submatrices
4770: (from both sequential and parallel matrices). Use MatGetSubMatrix()
4771: to extract a parallel submatrix.
4773: When extracting submatrices from a parallel matrix, each processor can
4774: form a different submatrix by setting the rows and columns of its
4775: individual index sets according to the local submatrix desired.
4777: When finished using the submatrices, the user should destroy
4778: them with MatDestroyMatrices().
4780: MAT_REUSE_MATRIX can only be used when the nonzero structure of the
4781: original matrix has not changed from that last call to MatGetSubMatrices().
4783: This routine creates the matrices in submat; you should NOT create them before
4784: calling it. It also allocates the array of matrix pointers submat.
4786: For BAIJ matrices the index sets must respect the block structure, that is if they
4787: request one row/column in a block, they must request all rows/columns that are in
4788: that block. For example, if the block size is 2 you cannot request just row 0 and
4789: column 0.
4791: Fortran Note:
4792: The Fortran interface is slightly different from that given below; it
4793: requires one to pass in as submat a Mat (integer) array of size at least m.
4795: Level: advanced
4797: Concepts: matrices^accessing submatrices
4798: Concepts: submatrices
4800: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
4801: @*/
4802: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
4803: {
4805: PetscInt i;
4806: PetscTruth eq;
4811: if (n) {
4816: }
4818: if (n && scall == MAT_REUSE_MATRIX) {
4821: }
4822: if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4823: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4824: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4825: MatPreallocated(mat);
4827: PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
4828: (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
4829: PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
4830: for (i=0; i<n; i++) {
4831: if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) {
4832: ISEqual(irow[i],icol[i],&eq);
4833: if (eq) {
4834: if (mat->symmetric){
4835: MatSetOption((*submat)[i],MAT_SYMMETRIC);
4836: } else if (mat->hermitian) {
4837: MatSetOption((*submat)[i],MAT_HERMITIAN);
4838: } else if (mat->structurally_symmetric) {
4839: MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);
4840: }
4841: }
4842: }
4843: }
4844: return(0);
4845: }
4849: /*@C
4850: MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices().
4852: Collective on Mat
4854: Input Parameters:
4855: + n - the number of local matrices
4856: - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
4857: sequence of MatGetSubMatrices())
4859: Level: advanced
4861: Notes: Frees not only the matrices, but also the array that contains the matrices
4863: .seealso: MatGetSubMatrices()
4864: @*/
4865: PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[])
4866: {
4868: PetscInt i;
4871: if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n);
4873: for (i=0; i<n; i++) {
4874: MatDestroy((*mat)[i]);
4875: }
4876: /* memory is allocated even if n = 0 */
4877: PetscFree(*mat);
4878: return(0);
4879: }
4883: /*@
4884: MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4885: replaces the index sets by larger ones that represent submatrices with
4886: additional overlap.
4888: Collective on Mat
4890: Input Parameters:
4891: + mat - the matrix
4892: . n - the number of index sets
4893: . is - the array of index sets (these index sets will changed during the call)
4894: - ov - the additional overlap requested
4896: Level: developer
4898: Concepts: overlap
4899: Concepts: ASM^computing overlap
4901: .seealso: MatGetSubMatrices()
4902: @*/
4903: PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov)
4904: {
4910: if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n);
4911: if (n) {
4914: }
4915: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4916: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4917: MatPreallocated(mat);
4919: if (!ov) return(0);
4920: if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4921: PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
4922: (*mat->ops->increaseoverlap)(mat,n,is,ov);
4923: PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
4924: return(0);
4925: }
4929: /*@
4930: MatPrintHelp - Prints all the options for the matrix.
4932: Collective on Mat
4934: Input Parameter:
4935: . mat - the matrix
4937: Options Database Keys:
4938: + -help - Prints matrix options
4939: - -h - Prints matrix options
4941: Level: developer
4943: .seealso: MatCreate(), MatCreateXXX()
4944: @*/
4945: PetscErrorCode PETSCMAT_DLLEXPORT MatPrintHelp(Mat mat)
4946: {
4947: static PetscTruth called = PETSC_FALSE;
4948: PetscErrorCode ierr;
4953: MatPreallocated(mat);
4955: if (!called) {
4956: if (mat->ops->printhelp) {
4957: (*mat->ops->printhelp)(mat);
4958: }
4959: called = PETSC_TRUE;
4960: }
4961: return(0);
4962: }
4966: /*@
4967: MatGetBlockSize - Returns the matrix block size; useful especially for the
4968: block row and block diagonal formats.
4969:
4970: Not Collective
4972: Input Parameter:
4973: . mat - the matrix
4975: Output Parameter:
4976: . bs - block size
4978: Notes:
4979: Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4980: Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ
4982: Level: intermediate
4984: Concepts: matrices^block size
4986: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4987: @*/
4988: PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs)
4989: {
4996: MatPreallocated(mat);
4997: *bs = mat->rmap.bs;
4998: return(0);
4999: }
5003: /*@
5004: MatSetBlockSize - Sets the matrix block size; for many matrix types you
5005: cannot use this and MUST set the blocksize when you preallocate the matrix
5006:
5007: Not Collective
5009: Input Parameters:
5010: + mat - the matrix
5011: - bs - block size
5013: Notes:
5014: Only works for shell and AIJ matrices
5016: Level: intermediate
5018: Concepts: matrices^block size
5020: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize()
5021: @*/
5022: PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs)
5023: {
5029: MatPreallocated(mat);
5030: if (mat->ops->setblocksize) {
5031: mat->rmap.bs = bs;
5032: (*mat->ops->setblocksize)(mat,bs);
5033: } else {
5034: SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name);
5035: }
5036: return(0);
5037: }
5041: /*@C
5042: MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices.
5044: Collective on Mat
5046: Input Parameters:
5047: + mat - the matrix
5048: . shift - 0 or 1 indicating we want the indices starting at 0 or 1
5049: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5050: symmetrized
5052: Output Parameters:
5053: + n - number of rows in the (possibly compressed) matrix
5054: . ia - the row pointers
5055: . ja - the column indices
5056: - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers
5057: are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set
5059: Level: developer
5061: Notes: You CANNOT change any of the ia[] or ja[] values.
5063: Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values
5065: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5066: @*/
5067: PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5068: {
5078: MatPreallocated(mat);
5079: if (!mat->ops->getrowij) *done = PETSC_FALSE;
5080: else {
5081: *done = PETSC_TRUE;
5082: (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
5083: }
5084: return(0);
5085: }
5089: /*@C
5090: MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices.
5092: Collective on Mat
5094: Input Parameters:
5095: + mat - the matrix
5096: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5097: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5098: symmetrized
5100: Output Parameters:
5101: + n - number of columns in the (possibly compressed) matrix
5102: . ia - the column pointers
5103: . ja - the row indices
5104: - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned
5106: Level: developer
5108: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5109: @*/
5110: PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5111: {
5121: MatPreallocated(mat);
5122: if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
5123: else {
5124: *done = PETSC_TRUE;
5125: (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
5126: }
5127: return(0);
5128: }
5132: /*@C
5133: MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
5134: MatGetRowIJ().
5136: Collective on Mat
5138: Input Parameters:
5139: + mat - the matrix
5140: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5141: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5142: symmetrized
5144: Output Parameters:
5145: + n - size of (possibly compressed) matrix
5146: . ia - the row pointers
5147: . ja - the column indices
5148: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
5150: Level: developer
5152: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5153: @*/
5154: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5155: {
5164: MatPreallocated(mat);
5166: if (!mat->ops->restorerowij) *done = PETSC_FALSE;
5167: else {
5168: *done = PETSC_TRUE;
5169: (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
5170: }
5171: return(0);
5172: }
5176: /*@C
5177: MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
5178: MatGetColumnIJ().
5180: Collective on Mat
5182: Input Parameters:
5183: + mat - the matrix
5184: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5185: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5186: symmetrized
5188: Output Parameters:
5189: + n - size of (possibly compressed) matrix
5190: . ia - the column pointers
5191: . ja - the row indices
5192: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
5194: Level: developer
5196: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5197: @*/
5198: PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5199: {
5208: MatPreallocated(mat);
5210: if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
5211: else {
5212: *done = PETSC_TRUE;
5213: (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
5214: }
5215: return(0);
5216: }
5220: /*@C
5221: MatColoringPatch -Used inside matrix coloring routines that
5222: use MatGetRowIJ() and/or MatGetColumnIJ().
5224: Collective on Mat
5226: Input Parameters:
5227: + mat - the matrix
5228: . ncolors - max color value
5229: . n - number of entries in colorarray
5230: - colorarray - array indicating color for each column
5232: Output Parameters:
5233: . iscoloring - coloring generated using colorarray information
5235: Level: developer
5237: .seealso: MatGetRowIJ(), MatGetColumnIJ()
5239: @*/
5240: PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring)
5241: {
5249: MatPreallocated(mat);
5251: if (!mat->ops->coloringpatch){
5252: ISColoringCreate(mat->comm,ncolors,n,colorarray,iscoloring);
5253: } else {
5254: (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);
5255: }
5256: return(0);
5257: }
5262: /*@
5263: MatSetUnfactored - Resets a factored matrix to be treated as unfactored.
5265: Collective on Mat
5267: Input Parameter:
5268: . mat - the factored matrix to be reset
5270: Notes:
5271: This routine should be used only with factored matrices formed by in-place
5272: factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE
5273: format). This option can save memory, for example, when solving nonlinear
5274: systems with a matrix-free Newton-Krylov method and a matrix-based, in-place
5275: ILU(0) preconditioner.
5277: Note that one can specify in-place ILU(0) factorization by calling
5278: .vb
5279: PCType(pc,PCILU);
5280: PCFactorSeUseInPlace(pc);
5281: .ve
5282: or by using the options -pc_type ilu -pc_factor_in_place
5284: In-place factorization ILU(0) can also be used as a local
5285: solver for the blocks within the block Jacobi or additive Schwarz
5286: methods (runtime option: -sub_pc_factor_in_place). See the discussion
5287: of these preconditioners in the users manual for details on setting
5288: local solver options.
5290: Most users should employ the simplified KSP interface for linear solvers
5291: instead of working directly with matrix algebra routines such as this.
5292: See, e.g., KSPCreate().
5294: Level: developer
5296: .seealso: PCFactorSetUseInPlace()
5298: Concepts: matrices^unfactored
5300: @*/
5301: PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat)
5302: {
5308: MatPreallocated(mat);
5309: mat->factor = 0;
5310: if (!mat->ops->setunfactored) return(0);
5311: (*mat->ops->setunfactored)(mat);
5312: return(0);
5313: }
5315: /*MC
5316: MatGetArrayF90 - Accesses a matrix array from Fortran90.
5318: Synopsis:
5319: MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
5321: Not collective
5323: Input Parameter:
5324: . x - matrix
5326: Output Parameters:
5327: + xx_v - the Fortran90 pointer to the array
5328: - ierr - error code
5330: Example of Usage:
5331: .vb
5332: PetscScalar, pointer xx_v(:)
5333: ....
5334: call MatGetArrayF90(x,xx_v,ierr)
5335: a = xx_v(3)
5336: call MatRestoreArrayF90(x,xx_v,ierr)
5337: .ve
5339: Notes:
5340: Not yet supported for all F90 compilers
5342: Level: advanced
5344: .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray()
5346: Concepts: matrices^accessing array
5348: M*/
5350: /*MC
5351: MatRestoreArrayF90 - Restores a matrix array that has been
5352: accessed with MatGetArrayF90().
5354: Synopsis:
5355: MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
5357: Not collective
5359: Input Parameters:
5360: + x - matrix
5361: - xx_v - the Fortran90 pointer to the array
5363: Output Parameter:
5364: . ierr - error code
5366: Example of Usage:
5367: .vb
5368: PetscScalar, pointer xx_v(:)
5369: ....
5370: call MatGetArrayF90(x,xx_v,ierr)
5371: a = xx_v(3)
5372: call MatRestoreArrayF90(x,xx_v,ierr)
5373: .ve
5374:
5375: Notes:
5376: Not yet supported for all F90 compilers
5378: Level: advanced
5380: .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray()
5382: M*/
5387: /*@
5388: MatGetSubMatrix - Gets a single submatrix on the same number of processors
5389: as the original matrix.
5391: Collective on Mat
5393: Input Parameters:
5394: + mat - the original matrix
5395: . isrow - rows this processor should obtain
5396: . iscol - columns for all processors you wish to keep
5397: . csize - number of columns "local" to this processor (does nothing for sequential
5398: matrices). This should match the result from VecGetLocalSize(x,...) if you
5399: plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5400: - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
5402: Output Parameter:
5403: . newmat - the new submatrix, of the same type as the old
5405: Level: advanced
5407: Notes: the iscol argument MUST be the same on each processor. You might be
5408: able to create the iscol argument with ISAllGather().
5410: The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5411: the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5412: to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX
5413: will reuse the matrix generated the first time.
5415: Concepts: matrices^submatrices
5417: .seealso: MatGetSubMatrices(), ISAllGather()
5418: @*/
5419: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat)
5420: {
5422: PetscMPIInt size;
5423: Mat *local;
5432: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5433: MatPreallocated(mat);
5434: MPI_Comm_size(mat->comm,&size);
5436: /* if original matrix is on just one processor then use submatrix generated */
5437: if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
5438: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
5439: return(0);
5440: } else if (!mat->ops->getsubmatrix && size == 1) {
5441: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
5442: *newmat = *local;
5443: PetscFree(local);
5444: return(0);
5445: }
5447: if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5448: (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
5449: PetscObjectStateIncrease((PetscObject)*newmat);
5450: return(0);
5451: }
5455: /*@
5456: MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors
5457: as the original matrix.
5459: Collective on Mat
5461: Input Parameters:
5462: + mat - the original matrix
5463: . nrows - the number of rows this processor should obtain
5464: . rows - rows this processor should obtain
5465: . ncols - the number of columns for all processors you wish to keep
5466: . cols - columns for all processors you wish to keep
5467: . csize - number of columns "local" to this processor (does nothing for sequential
5468: matrices). This should match the result from VecGetLocalSize(x,...) if you
5469: plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5470: - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
5472: Output Parameter:
5473: . newmat - the new submatrix, of the same type as the old
5475: Level: advanced
5477: Notes: the iscol argument MUST be the same on each processor. You might be
5478: able to create the iscol argument with ISAllGather().
5480: The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5481: the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5482: to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX
5483: will reuse the matrix generated the first time.
5485: Concepts: matrices^submatrices
5487: .seealso: MatGetSubMatrices(), ISAllGather()
5488: @*/
5489: PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat)
5490: {
5491: IS isrow, iscol;
5501: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5502: MatPreallocated(mat);
5503: ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);
5504: ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);
5505: MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);
5506: ISDestroy(isrow);
5507: ISDestroy(iscol);
5508: return(0);
5509: }
5513: /*@
5514: MatStashSetInitialSize - sets the sizes of the matrix stash, that is
5515: used during the assembly process to store values that belong to
5516: other processors.
5518: Not Collective
5520: Input Parameters:
5521: + mat - the matrix
5522: . size - the initial size of the stash.
5523: - bsize - the initial size of the block-stash(if used).
5525: Options Database Keys:
5526: + -matstash_initial_size <size> or <size0,size1,...sizep-1>
5527: - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
5529: Level: intermediate
5531: Notes:
5532: The block-stash is used for values set with MatSetValuesBlocked() while
5533: the stash is used for values set with MatSetValues()
5535: Run with the option -info and look for output of the form
5536: MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
5537: to determine the appropriate value, MM, to use for size and
5538: MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
5539: to determine the value, BMM to use for bsize
5541: Concepts: stash^setting matrix size
5542: Concepts: matrices^stash
5544: @*/
5545: PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize)
5546: {
5552: MatStashSetInitialSize_Private(&mat->stash,size);
5553: MatStashSetInitialSize_Private(&mat->bstash,bsize);
5554: return(0);
5555: }
5559: /*@
5560: MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of
5561: the matrix
5563: Collective on Mat
5565: Input Parameters:
5566: + mat - the matrix
5567: . x,y - the vectors
5568: - w - where the result is stored
5570: Level: intermediate
5572: Notes:
5573: w may be the same vector as y.
5575: This allows one to use either the restriction or interpolation (its transpose)
5576: matrix to do the interpolation
5578: Concepts: interpolation
5580: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
5582: @*/
5583: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
5584: {
5586: PetscInt M,N;
5594: MatPreallocated(A);
5595: MatGetSize(A,&M,&N);
5596: if (N > M) {
5597: MatMultTransposeAdd(A,x,y,w);
5598: } else {
5599: MatMultAdd(A,x,y,w);
5600: }
5601: return(0);
5602: }
5606: /*@
5607: MatInterpolate - y = A*x or A'*x depending on the shape of
5608: the matrix
5610: Collective on Mat
5612: Input Parameters:
5613: + mat - the matrix
5614: - x,y - the vectors
5616: Level: intermediate
5618: Notes:
5619: This allows one to use either the restriction or interpolation (its transpose)
5620: matrix to do the interpolation
5622: Concepts: matrices^interpolation
5624: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
5626: @*/
5627: PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y)
5628: {
5630: PetscInt M,N;
5637: MatPreallocated(A);
5638: MatGetSize(A,&M,&N);
5639: if (N > M) {
5640: MatMultTranspose(A,x,y);
5641: } else {
5642: MatMult(A,x,y);
5643: }
5644: return(0);
5645: }
5649: /*@
5650: MatRestrict - y = A*x or A'*x
5652: Collective on Mat
5654: Input Parameters:
5655: + mat - the matrix
5656: - x,y - the vectors
5658: Level: intermediate
5660: Notes:
5661: This allows one to use either the restriction or interpolation (its transpose)
5662: matrix to do the restriction
5664: Concepts: matrices^restriction
5666: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate()
5668: @*/
5669: PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y)
5670: {
5672: PetscInt M,N;
5679: MatPreallocated(A);
5681: MatGetSize(A,&M,&N);
5682: if (N > M) {
5683: MatMult(A,x,y);
5684: } else {
5685: MatMultTranspose(A,x,y);
5686: }
5687: return(0);
5688: }
5692: /*@C
5693: MatNullSpaceAttach - attaches a null space to a matrix.
5694: This null space will be removed from the resulting vector whenever
5695: MatMult() is called
5697: Collective on Mat
5699: Input Parameters:
5700: + mat - the matrix
5701: - nullsp - the null space object
5703: Level: developer
5705: Notes:
5706: Overwrites any previous null space that may have been attached
5708: Concepts: null space^attaching to matrix
5710: .seealso: MatCreate(), MatNullSpaceCreate()
5711: @*/
5712: PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
5713: {
5720: MatPreallocated(mat);
5722: if (mat->nullsp) {
5723: MatNullSpaceDestroy(mat->nullsp);
5724: }
5725: mat->nullsp = nullsp;
5726: PetscObjectReference((PetscObject)nullsp);
5727: return(0);
5728: }
5732: /*@
5733: MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.
5735: Collective on Mat
5737: Input Parameters:
5738: + mat - the matrix
5739: . row - row/column permutation
5740: . fill - expected fill factor >= 1.0
5741: - level - level of fill, for ICC(k)
5743: Notes:
5744: Probably really in-place only when level of fill is zero, otherwise allocates
5745: new space to store factored matrix and deletes previous memory.
5747: Most users should employ the simplified KSP interface for linear solvers
5748: instead of working directly with matrix algebra routines such as this.
5749: See, e.g., KSPCreate().
5751: Level: developer
5753: Concepts: matrices^incomplete Cholesky factorization
5754: Concepts: Cholesky factorization
5756: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
5757: @*/
5758: PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
5759: {
5767: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
5768: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
5769: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5770: if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5771: MatPreallocated(mat);
5772: (*mat->ops->iccfactor)(mat,row,info);
5773: PetscObjectStateIncrease((PetscObject)mat);
5774: return(0);
5775: }
5779: /*@
5780: MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix.
5782: Not Collective
5784: Input Parameters:
5785: + mat - the matrix
5786: - v - the values compute with ADIC
5788: Level: developer
5790: Notes:
5791: Must call MatSetColoring() before using this routine. Also this matrix must already
5792: have its nonzero pattern determined.
5794: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5795: MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
5796: @*/
5797: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v)
5798: {
5806: if (!mat->assembled) {
5807: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5808: }
5809: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5810: if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5811: (*mat->ops->setvaluesadic)(mat,v);
5812: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5813: MatView_Private(mat);
5814: PetscObjectStateIncrease((PetscObject)mat);
5815: return(0);
5816: }
5821: /*@
5822: MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic()
5824: Not Collective
5826: Input Parameters:
5827: + mat - the matrix
5828: - coloring - the coloring
5830: Level: developer
5832: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5833: MatSetValues(), MatSetValuesAdic()
5834: @*/
5835: PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring)
5836: {
5844: if (!mat->assembled) {
5845: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5846: }
5847: if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5848: (*mat->ops->setcoloring)(mat,coloring);
5849: return(0);
5850: }
5854: /*@
5855: MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix.
5857: Not Collective
5859: Input Parameters:
5860: + mat - the matrix
5861: . nl - leading dimension of v
5862: - v - the values compute with ADIFOR
5864: Level: developer
5866: Notes:
5867: Must call MatSetColoring() before using this routine. Also this matrix must already
5868: have its nonzero pattern determined.
5870: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5871: MatSetValues(), MatSetColoring()
5872: @*/
5873: PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v)
5874: {
5882: if (!mat->assembled) {
5883: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5884: }
5885: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
5886: if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5887: (*mat->ops->setvaluesadifor)(mat,nl,v);
5888: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
5889: PetscObjectStateIncrease((PetscObject)mat);
5890: return(0);
5891: }
5895: /*@
5896: MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the
5897: ghosted ones.
5899: Not Collective
5901: Input Parameters:
5902: + mat - the matrix
5903: - diag = the diagonal values, including ghost ones
5905: Level: developer
5907: Notes: Works only for MPIAIJ and MPIBAIJ matrices
5908:
5909: .seealso: MatDiagonalScale()
5910: @*/
5911: PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag)
5912: {
5914: PetscMPIInt size;
5921: if (!mat->assembled) {
5922: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5923: }
5924: PetscLogEventBegin(MAT_Scale,mat,0,0,0);
5925: MPI_Comm_size(mat->comm,&size);
5926: if (size == 1) {
5927: PetscInt n,m;
5928: VecGetSize(diag,&n);
5929: MatGetSize(mat,0,&m);
5930: if (m == n) {
5931: MatDiagonalScale(mat,0,diag);
5932: } else {
5933: SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions");
5934: }
5935: } else {
5936: PetscErrorCode (*f)(Mat,Vec);
5937: PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
5938: if (f) {
5939: (*f)(mat,diag);
5940: } else {
5941: SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
5942: }
5943: }
5944: PetscLogEventEnd(MAT_Scale,mat,0,0,0);
5945: PetscObjectStateIncrease((PetscObject)mat);
5946: return(0);
5947: }
5951: /*@
5952: MatGetInertia - Gets the inertia from a factored matrix
5954: Collective on Mat
5956: Input Parameter:
5957: . mat - the matrix
5959: Output Parameters:
5960: + nneg - number of negative eigenvalues
5961: . nzero - number of zero eigenvalues
5962: - npos - number of positive eigenvalues
5964: Level: advanced
5966: Notes: Matrix must have been factored by MatCholeskyFactor()
5969: @*/
5970: PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos)
5971: {
5977: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5978: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5979: if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5980: (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5981: return(0);
5982: }
5984: /* ----------------------------------------------------------------*/
5987: /*@
5988: MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors
5990: Collective on Mat and Vecs
5992: Input Parameters:
5993: + mat - the factored matrix
5994: - b - the right-hand-side vectors
5996: Output Parameter:
5997: . x - the result vectors
5999: Notes:
6000: The vectors b and x cannot be the same. I.e., one cannot
6001: call MatSolves(A,x,x).
6003: Notes:
6004: Most users should employ the simplified KSP interface for linear solvers
6005: instead of working directly with matrix algebra routines such as this.
6006: See, e.g., KSPCreate().
6008: Level: developer
6010: Concepts: matrices^triangular solves
6012: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
6013: @*/
6014: PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x)
6015: {
6021: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
6022: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
6023: if (!mat->rmap.N && !mat->cmap.N) return(0);
6025: if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
6026: MatPreallocated(mat);
6027: PetscLogEventBegin(MAT_Solves,mat,0,0,0);
6028: (*mat->ops->solves)(mat,b,x);
6029: PetscLogEventEnd(MAT_Solves,mat,0,0,0);
6030: return(0);
6031: }
6035: /*@
6036: MatIsSymmetric - Test whether a matrix is symmetric
6038: Collective on Mat
6040: Input Parameter:
6041: + A - the matrix to test
6042: - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose)
6044: Output Parameters:
6045: . flg - the result
6047: Level: intermediate
6049: Concepts: matrix^symmetry
6051: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown()
6052: @*/
6053: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg)
6054: {
6060: if (!A->symmetric_set) {
6061: if (!A->ops->issymmetric) {
6062: MatType mattype;
6063: MatGetType(A,&mattype);
6064: SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype);
6065: }
6066: (*A->ops->issymmetric)(A,tol,&A->symmetric);
6067: A->symmetric_set = PETSC_TRUE;
6068: if (A->symmetric) {
6069: A->structurally_symmetric_set = PETSC_TRUE;
6070: A->structurally_symmetric = PETSC_TRUE;
6071: }
6072: }
6073: *flg = A->symmetric;
6074: return(0);
6075: }
6079: /*@
6080: MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric.
6082: Collective on Mat
6084: Input Parameter:
6085: . A - the matrix to check
6087: Output Parameters:
6088: + set - if the symmetric flag is set (this tells you if the next flag is valid)
6089: - flg - the result
6091: Level: advanced
6093: Concepts: matrix^symmetry
6095: Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric()
6096: if you want it explicitly checked
6098: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6099: @*/
6100: PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6101: {
6106: if (A->symmetric_set) {
6107: *set = PETSC_TRUE;
6108: *flg = A->symmetric;
6109: } else {
6110: *set = PETSC_FALSE;
6111: }
6112: return(0);
6113: }
6117: /*@
6118: MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian.
6120: Collective on Mat
6122: Input Parameter:
6123: . A - the matrix to check
6125: Output Parameters:
6126: + set - if the hermitian flag is set (this tells you if the next flag is valid)
6127: - flg - the result
6129: Level: advanced
6131: Concepts: matrix^symmetry
6133: Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian()
6134: if you want it explicitly checked
6136: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6137: @*/
6138: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6139: {
6144: if (A->hermitian_set) {
6145: *set = PETSC_TRUE;
6146: *flg = A->hermitian;
6147: } else {
6148: *set = PETSC_FALSE;
6149: }
6150: return(0);
6151: }
6155: /*@
6156: MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric
6158: Collective on Mat
6160: Input Parameter:
6161: . A - the matrix to test
6163: Output Parameters:
6164: . flg - the result
6166: Level: intermediate
6168: Concepts: matrix^symmetry
6170: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption()
6171: @*/
6172: PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg)
6173: {
6179: if (!A->structurally_symmetric_set) {
6180: if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric");
6181: (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);
6182: A->structurally_symmetric_set = PETSC_TRUE;
6183: }
6184: *flg = A->structurally_symmetric;
6185: return(0);
6186: }
6190: /*@
6191: MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose.
6193: Collective on Mat
6195: Input Parameter:
6196: . A - the matrix to test
6198: Output Parameters:
6199: . flg - the result
6201: Level: intermediate
6203: Concepts: matrix^symmetry
6205: .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption()
6206: @*/
6207: PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg)
6208: {
6214: if (!A->hermitian_set) {
6215: if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian");
6216: (*A->ops->ishermitian)(A,&A->hermitian);
6217: A->hermitian_set = PETSC_TRUE;
6218: if (A->hermitian) {
6219: A->structurally_symmetric_set = PETSC_TRUE;
6220: A->structurally_symmetric = PETSC_TRUE;
6221: }
6222: }
6223: *flg = A->hermitian;
6224: return(0);
6225: }
6230: /*@
6231: MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
6232: to be communicated to other processors during the MatAssemblyBegin/End() process
6234: Not collective
6236: Input Parameter:
6237: . vec - the vector
6239: Output Parameters:
6240: + nstash - the size of the stash
6241: . reallocs - the number of additional mallocs incurred.
6242: . bnstash - the size of the block stash
6243: - breallocs - the number of additional mallocs incurred.in the block stash
6244:
6245: Level: advanced
6247: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize()
6248:
6249: @*/
6250: PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
6251: {
6254: MatStashGetInfo_Private(&mat->stash,nstash,reallocs);
6255: MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);
6256: return(0);
6257: }
6261: /*@
6262: MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same
6263: parallel layout
6264:
6265: Collective on Mat
6267: Input Parameter:
6268: . mat - the matrix
6270: Output Parameter:
6271: + right - (optional) vector that the matrix can be multiplied against
6272: - left - (optional) vector that the matrix vector product can be stored in
6274: Level: advanced
6276: .seealso: MatCreate()
6277: @*/
6278: PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left)
6279: {
6285: MatPreallocated(mat);
6286: if (mat->ops->getvecs) {
6287: (*mat->ops->getvecs)(mat,right,left);
6288: } else {
6289: PetscMPIInt size;
6290: MPI_Comm_size(mat->comm, &size);
6291: if (right) {
6292: VecCreate(mat->comm,right);
6293: VecSetSizes(*right,mat->cmap.n,PETSC_DETERMINE);
6294: if (size > 1) {VecSetType(*right,VECMPI);}
6295: else {VecSetType(*right,VECSEQ);}
6296: }
6297: if (left) {
6298: VecCreate(mat->comm,left);
6299: VecSetSizes(*left,mat->rmap.n,PETSC_DETERMINE);
6300: if (size > 1) {VecSetType(*left,VECMPI);}
6301: else {VecSetType(*left,VECSEQ);}
6302: }
6303: }
6304: if (right) {VecSetBlockSize(*right,mat->rmap.bs);}
6305: if (left) {VecSetBlockSize(*left,mat->rmap.bs);}
6306: return(0);
6307: }
6311: /*@
6312: MatFactorInfoInitialize - Initializes a MatFactorInfo data structure
6313: with default values.
6315: Not Collective
6317: Input Parameters:
6318: . info - the MatFactorInfo data structure
6321: Notes: The solvers are generally used through the KSP and PC objects, for example
6322: PCLU, PCILU, PCCHOLESKY, PCICC
6324: Level: developer
6326: .seealso: MatFactorInfo
6327: @*/
6329: PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info)
6330: {
6334: PetscMemzero(info,sizeof(MatFactorInfo));
6335: return(0);
6336: }
6340: /*@
6341: MatPtAP - Creates the matrix projection C = P^T * A * P
6343: Collective on Mat
6345: Input Parameters:
6346: + A - the matrix
6347: . P - the projection matrix
6348: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6349: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P))
6351: Output Parameters:
6352: . C - the product matrix
6354: Notes:
6355: C will be created and must be destroyed by the user with MatDestroy().
6357: This routine is currently only implemented for pairs of AIJ matrices and classes
6358: which inherit from AIJ.
6360: Level: intermediate
6362: .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult()
6363: @*/
6364: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C)
6365: {
6371: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6372: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6375: MatPreallocated(P);
6376: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6377: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6379: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6380: if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6381: MatPreallocated(A);
6383: PetscLogEventBegin(MAT_PtAP,A,P,0,0);
6384: (*A->ops->ptap)(A,P,scall,fill,C);
6385: PetscLogEventEnd(MAT_PtAP,A,P,0,0);
6387: return(0);
6388: }
6392: /*@
6393: MatPtAPNumeric - Computes the matrix projection C = P^T * A * P
6395: Collective on Mat
6397: Input Parameters:
6398: + A - the matrix
6399: - P - the projection matrix
6401: Output Parameters:
6402: . C - the product matrix
6404: Notes:
6405: C must have been created by calling MatPtAPSymbolic and must be destroyed by
6406: the user using MatDeatroy().
6408: This routine is currently only implemented for pairs of AIJ matrices and classes
6409: which inherit from AIJ. C will be of type MATAIJ.
6411: Level: intermediate
6413: .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric()
6414: @*/
6415: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C)
6416: {
6422: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6423: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6426: MatPreallocated(P);
6427: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6428: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6431: MatPreallocated(C);
6432: if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6433: if (P->cmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->rmap.N);
6434: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6435: if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6436: if (P->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->cmap.N);
6437: MatPreallocated(A);
6439: PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);
6440: (*A->ops->ptapnumeric)(A,P,C);
6441: PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);
6442: return(0);
6443: }
6447: /*@
6448: MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P
6450: Collective on Mat
6452: Input Parameters:
6453: + A - the matrix
6454: - P - the projection matrix
6456: Output Parameters:
6457: . C - the (i,j) structure of the product matrix
6459: Notes:
6460: C will be created and must be destroyed by the user with MatDestroy().
6462: This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6463: which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using
6464: this (i,j) structure by calling MatPtAPNumeric().
6466: Level: intermediate
6468: .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic()
6469: @*/
6470: PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C)
6471: {
6477: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6478: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6481: MatPreallocated(P);
6482: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6483: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6486: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6487: if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6488: MatPreallocated(A);
6489: PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);
6490: (*A->ops->ptapsymbolic)(A,P,fill,C);
6491: PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);
6493: MatSetBlockSize(*C,A->rmap.bs);
6495: return(0);
6496: }
6500: /*@
6501: MatMatMult - Performs Matrix-Matrix Multiplication C=A*B.
6503: Collective on Mat
6505: Input Parameters:
6506: + A - the left matrix
6507: . B - the right matrix
6508: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6509: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6511: Output Parameters:
6512: . C - the product matrix
6514: Notes:
6515: C will be created and must be destroyed by the user with MatDestroy().
6516: Unless scall is MAT_REUSE_MATRIX
6518: This routine is currently only implemented for pairs of AIJ matrices and classes
6519: which inherit from AIJ. C will be of type MATAIJ.
6521: Level: intermediate
6523: .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP()
6524: @*/
6525: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6526: {
6528: PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6529: PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);
6534: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6535: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6538: MatPreallocated(B);
6539: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6540: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6542: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6543: if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6544: MatPreallocated(A);
6546: /* For now, we do not dispatch based on the type of A and B */
6547: /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6548: fA = A->ops->matmult;
6549: if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for A of type %s",A->type_name);
6550: fB = B->ops->matmult;
6551: if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name);
6552: if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6554: PetscLogEventBegin(MAT_MatMult,A,B,0,0);
6555: (*A->ops->matmult)(A,B,scall,fill,C);
6556: PetscLogEventEnd(MAT_MatMult,A,B,0,0);
6557:
6558: return(0);
6559: }
6563: /*@
6564: MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure
6565: of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric().
6567: Collective on Mat
6569: Input Parameters:
6570: + A - the left matrix
6571: . B - the right matrix
6572: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6574: Output Parameters:
6575: . C - the matrix containing the ij structure of product matrix
6577: Notes:
6578: C will be created as a MATSEQAIJ matrix and must be destroyed by the user with MatDestroy().
6580: This routine is currently only implemented for SeqAIJ matrices and classes which inherit from SeqAIJ.
6582: Level: intermediate
6584: .seealso: MatMatMult(), MatMatMultNumeric()
6585: @*/
6586: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C)
6587: {
6589: PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *);
6590: PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *);
6595: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6596: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6600: MatPreallocated(B);
6601: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6602: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6605: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6606: if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6607: MatPreallocated(A);
6609: /* For now, we do not dispatch based on the type of A and P */
6610: /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6611: Asymbolic = A->ops->matmultsymbolic;
6612: if (!Asymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for A of type %s",A->type_name);
6613: Bsymbolic = B->ops->matmultsymbolic;
6614: if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name);
6615: if (Bsymbolic!=Asymbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6617: PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);
6618: (*Asymbolic)(A,B,fill,C);
6619: PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);
6621: return(0);
6622: }
6626: /*@
6627: MatMatMultNumeric - Performs the numeric matrix-matrix product.
6628: Call this routine after first calling MatMatMultSymbolic().
6630: Collective on Mat
6632: Input Parameters:
6633: + A - the left matrix
6634: - B - the right matrix
6636: Output Parameters:
6637: . C - the product matrix, whose ij structure was defined from MatMatMultSymbolic().
6639: Notes:
6640: C must have been created with MatMatMultSymbolic.
6642: This routine is currently only implemented for SeqAIJ type matrices.
6644: Level: intermediate
6646: .seealso: MatMatMult(), MatMatMultSymbolic()
6647: @*/
6648: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C)
6649: {
6651: PetscErrorCode (*Anumeric)(Mat,Mat,Mat);
6652: PetscErrorCode (*Bnumeric)(Mat,Mat,Mat);
6658: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6659: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6663: MatPreallocated(B);
6664: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6665: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6669: MatPreallocated(C);
6670: if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6671: if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6673: if (B->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap.N,C->cmap.N);
6674: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6675: if (A->rmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap.N,C->rmap.N);
6676: MatPreallocated(A);
6678: /* For now, we do not dispatch based on the type of A and B */
6679: /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */
6680: Anumeric = A->ops->matmultnumeric;
6681: if (!Anumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for A of type %s",A->type_name);
6682: Bnumeric = B->ops->matmultnumeric;
6683: if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name);
6684: if (Bnumeric!=Anumeric) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6686: PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);
6687: (*Anumeric)(A,B,C);
6688: PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);
6690: return(0);
6691: }
6695: /*@
6696: MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B.
6698: Collective on Mat
6700: Input Parameters:
6701: + A - the left matrix
6702: . B - the right matrix
6703: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6704: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6706: Output Parameters:
6707: . C - the product matrix
6709: Notes:
6710: C will be created and must be destroyed by the user with MatDestroy().
6712: This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6713: which inherit from SeqAIJ. C will be of type MATSEQAIJ.
6715: Level: intermediate
6717: .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP()
6718: @*/
6719: PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6720: {
6722: PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6723: PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);
6728: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6729: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6732: MatPreallocated(B);
6733: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6734: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6736: if (B->rmap.N!=A->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->rmap.N);
6737: if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill);
6738: MatPreallocated(A);
6740: fA = A->ops->matmulttranspose;
6741: if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name);
6742: fB = B->ops->matmulttranspose;
6743: if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name);
6744: if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6746: PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);
6747: (*A->ops->matmulttranspose)(A,B,scall,fill,C);
6748: PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);
6749:
6750: return(0);
6751: }