Actual source code: matrix.c
1: #define PETSCMAT_DLL
3: /*
4: This is where the abstract matrix operations are defined
5: */
7: #include src/mat/matimpl.h
8: #include private/vecimpl.h
10: /* Logging support */
11: PetscCookie MAT_COOKIE = 0;
12: PetscEvent MAT_Mult = 0, MAT_Mults = 0, MAT_MultConstrained = 0, MAT_MultAdd = 0, MAT_MultTranspose = 0;
13: PetscEvent MAT_MultTransposeConstrained = 0, MAT_MultTransposeAdd = 0, MAT_Solve = 0, MAT_Solves = 0, MAT_SolveAdd = 0, MAT_SolveTranspose = 0, MAT_MatSolve = 0;
14: PetscEvent MAT_SolveTransposeAdd = 0, MAT_Relax = 0, MAT_ForwardSolve = 0, MAT_BackwardSolve = 0, MAT_LUFactor = 0, MAT_LUFactorSymbolic = 0;
15: PetscEvent MAT_LUFactorNumeric = 0, MAT_CholeskyFactor = 0, MAT_CholeskyFactorSymbolic = 0, MAT_CholeskyFactorNumeric = 0, MAT_ILUFactor = 0;
16: PetscEvent MAT_ILUFactorSymbolic = 0, MAT_ICCFactorSymbolic = 0, MAT_Copy = 0, MAT_Convert = 0, MAT_Scale = 0, MAT_AssemblyBegin = 0;
17: PetscEvent MAT_AssemblyEnd = 0, MAT_SetValues = 0, MAT_GetValues = 0, MAT_GetRow = 0, MAT_GetSubMatrices = 0, MAT_GetColoring = 0, MAT_GetOrdering = 0;
18: PetscEvent MAT_IncreaseOverlap = 0, MAT_Partitioning = 0, MAT_ZeroEntries = 0, MAT_Load = 0, MAT_View = 0, MAT_AXPY = 0, MAT_FDColoringCreate = 0;
19: PetscEvent MAT_FDColoringApply = 0,MAT_Transpose = 0,MAT_FDColoringFunction = 0;
20: PetscEvent MAT_MatMult = 0, MAT_MatMultSymbolic = 0, MAT_MatMultNumeric = 0;
21: PetscEvent MAT_PtAP = 0, MAT_PtAPSymbolic = 0, MAT_PtAPNumeric = 0;
22: PetscEvent MAT_MatMultTranspose = 0, MAT_MatMultTransposeSymbolic = 0, MAT_MatMultTransposeNumeric = 0;
24: /* nasty global values for MatSetValue() */
25: PetscInt MatSetValue_Row = 0;
26: PetscInt MatSetValue_Column = 0;
27: PetscScalar MatSetValue_Value = 0.0;
31: /*@
32: MatRealPart - Zeros out the imaginary part of the matrix
34: Collective on Mat
36: Input Parameters:
37: . mat - the matrix
39: Level: advanced
42: .seealso: MatImaginaryPart()
43: @*/
45: PetscErrorCode MatRealPart(Mat mat)
46: {
52: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
53: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
54: if (!mat->ops->realpart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
55: MatPreallocated(mat);
56: (*mat->ops->realpart)(mat);
57: return(0);
58: }
62: /*@
63: MatImaginaryPart - Moves the imaginary part of the matrix to the real part and zeros the imaginary part
65: Collective on Mat
67: Input Parameters:
68: . mat - the matrix
70: Level: advanced
73: .seealso: MatRealPart()
74: @*/
76: PetscErrorCode MatImaginaryPart(Mat mat)
77: {
83: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
84: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
85: if (!mat->ops->imaginarypart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
86: MatPreallocated(mat);
87: (*mat->ops->imaginarypart)(mat);
88: return(0);
89: }
93: /*@C
94: MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow()
95: for each row that you get to ensure that your application does
96: not bleed memory.
98: Not Collective
100: Input Parameters:
101: + mat - the matrix
102: - row - the row to get
104: Output Parameters:
105: + ncols - if not NULL, the number of nonzeros in the row
106: . cols - if not NULL, the column numbers
107: - vals - if not NULL, the values
109: Notes:
110: This routine is provided for people who need to have direct access
111: to the structure of a matrix. We hope that we provide enough
112: high-level matrix routines that few users will need it.
114: MatGetRow() always returns 0-based column indices, regardless of
115: whether the internal representation is 0-based (default) or 1-based.
117: For better efficiency, set cols and/or vals to PETSC_NULL if you do
118: not wish to extract these quantities.
120: The user can only examine the values extracted with MatGetRow();
121: the values cannot be altered. To change the matrix entries, one
122: must use MatSetValues().
124: You can only have one call to MatGetRow() outstanding for a particular
125: matrix at a time, per processor. MatGetRow() can only obtain rows
126: associated with the given processor, it cannot get rows from the
127: other processors; for that we suggest using MatGetSubMatrices(), then
128: MatGetRow() on the submatrix. The row indix passed to MatGetRows()
129: is in the global number of rows.
131: Fortran Notes:
132: The calling sequence from Fortran is
133: .vb
134: MatGetRow(matrix,row,ncols,cols,values,ierr)
135: Mat matrix (input)
136: integer row (input)
137: integer ncols (output)
138: integer cols(maxcols) (output)
139: double precision (or double complex) values(maxcols) output
140: .ve
141: where maxcols >= maximum nonzeros in any row of the matrix.
144: Caution:
145: Do not try to change the contents of the output arrays (cols and vals).
146: In some cases, this may corrupt the matrix.
148: Level: advanced
150: Concepts: matrices^row access
152: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
153: @*/
155: PetscErrorCode MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
156: {
158: PetscInt incols;
163: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
164: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
165: if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
166: MatPreallocated(mat);
168: (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);
169: if (ncols) *ncols = incols;
171: return(0);
172: }
176: /*@
177: MatConjugate - replaces the matrix values with their complex conjugates
179: Collective on Mat
181: Input Parameters:
182: . mat - the matrix
184: Level: advanced
186: .seealso: VecConjugate()
187: @*/
188: PetscErrorCode MatConjugate(Mat mat)
189: {
194: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
195: if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov");
196: (*mat->ops->conjugate)(mat);
197: return(0);
198: }
202: /*@C
203: MatRestoreRow - Frees any temporary space allocated by MatGetRow().
205: Not Collective
207: Input Parameters:
208: + mat - the matrix
209: . row - the row to get
210: . ncols, cols - the number of nonzeros and their columns
211: - vals - if nonzero the column values
213: Notes:
214: This routine should be called after you have finished examining the entries.
216: Fortran Notes:
217: The calling sequence from Fortran is
218: .vb
219: MatRestoreRow(matrix,row,ncols,cols,values,ierr)
220: Mat matrix (input)
221: integer row (input)
222: integer ncols (output)
223: integer cols(maxcols) (output)
224: double precision (or double complex) values(maxcols) output
225: .ve
226: Where maxcols >= maximum nonzeros in any row of the matrix.
228: In Fortran MatRestoreRow() MUST be called after MatGetRow()
229: before another call to MatGetRow() can be made.
231: Level: advanced
233: .seealso: MatGetRow()
234: @*/
235: PetscErrorCode MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[])
236: {
242: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
243: if (!mat->ops->restorerow) return(0);
244: (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);
245: return(0);
246: }
250: /*@C
251: MatGetRowUpperTriangular - Sets a flag to enable calls to MatGetRow() for matrix in MATSBAIJ format.
252: You should call MatRestoreRowUpperTriangular() after calling MatGetRow/MatRestoreRow() to disable the flag.
254: Not Collective
256: Input Parameters:
257: + mat - the matrix
259: Notes:
260: The flag is to ensure that users are aware of MatGetRow() only provides the upper trianglular part of the row for the matrices in MATSBAIJ format.
262: Level: advanced
264: Concepts: matrices^row access
266: .seealso: MatRestoreRowRowUpperTriangular()
267: @*/
269: PetscErrorCode MatGetRowUpperTriangular(Mat mat)
270: {
276: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
277: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
278: if (!mat->ops->getrowuppertriangular) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
279: MatPreallocated(mat);
280: (*mat->ops->getrowuppertriangular)(mat);
281: return(0);
282: }
286: /*@C
287: MatRestoreRowUpperTriangular - Disable calls to MatGetRow() for matrix in MATSBAIJ format.
289: Not Collective
291: Input Parameters:
292: + mat - the matrix
294: Notes:
295: This routine should be called after you have finished MatGetRow/MatRestoreRow().
298: Level: advanced
300: .seealso: MatGetRowUpperTriangular()
301: @*/
302: PetscErrorCode MatRestoreRowUpperTriangular(Mat mat)
303: {
308: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
309: if (!mat->ops->restorerowuppertriangular) return(0);
310: (*mat->ops->restorerowuppertriangular)(mat);
311: return(0);
312: }
316: /*@C
317: MatSetOptionsPrefix - Sets the prefix used for searching for all
318: Mat options in the database.
320: Collective on Mat
322: Input Parameter:
323: + A - the Mat context
324: - prefix - the prefix to prepend to all option names
326: Notes:
327: A hyphen (-) must NOT be given at the beginning of the prefix name.
328: The first character of all runtime options is AUTOMATICALLY the hyphen.
330: Level: advanced
332: .keywords: Mat, set, options, prefix, database
334: .seealso: MatSetFromOptions()
335: @*/
336: PetscErrorCode MatSetOptionsPrefix(Mat A,const char prefix[])
337: {
342: PetscObjectSetOptionsPrefix((PetscObject)A,prefix);
343: return(0);
344: }
348: /*@C
349: MatAppendOptionsPrefix - Appends to the prefix used for searching for all
350: Mat options in the database.
352: Collective on Mat
354: Input Parameters:
355: + A - the Mat context
356: - prefix - the prefix to prepend to all option names
358: Notes:
359: A hyphen (-) must NOT be given at the beginning of the prefix name.
360: The first character of all runtime options is AUTOMATICALLY the hyphen.
362: Level: advanced
364: .keywords: Mat, append, options, prefix, database
366: .seealso: MatGetOptionsPrefix()
367: @*/
368: PetscErrorCode MatAppendOptionsPrefix(Mat A,const char prefix[])
369: {
371:
374: PetscObjectAppendOptionsPrefix((PetscObject)A,prefix);
375: return(0);
376: }
380: /*@C
381: MatGetOptionsPrefix - Sets the prefix used for searching for all
382: Mat options in the database.
384: Not Collective
386: Input Parameter:
387: . A - the Mat context
389: Output Parameter:
390: . prefix - pointer to the prefix string used
392: Notes: On the fortran side, the user should pass in a string 'prefix' of
393: sufficient length to hold the prefix.
395: Level: advanced
397: .keywords: Mat, get, options, prefix, database
399: .seealso: MatAppendOptionsPrefix()
400: @*/
401: PetscErrorCode MatGetOptionsPrefix(Mat A,const char *prefix[])
402: {
407: PetscObjectGetOptionsPrefix((PetscObject)A,prefix);
408: return(0);
409: }
413: /*@
414: MatSetUp - Sets up the internal matrix data structures for the later use.
416: Collective on Mat
418: Input Parameters:
419: . A - the Mat context
421: Notes:
422: For basic use of the Mat classes the user need not explicitly call
423: MatSetUp(), since these actions will happen automatically.
425: Level: advanced
427: .keywords: Mat, setup
429: .seealso: MatCreate(), MatDestroy()
430: @*/
431: PetscErrorCode MatSetUp(Mat A)
432: {
437: MatSetUpPreallocation(A);
438: MatSetFromOptions(A);
439: return(0);
440: }
444: /*@C
445: MatView - Visualizes a matrix object.
447: Collective on Mat
449: Input Parameters:
450: + mat - the matrix
451: - viewer - visualization context
453: Notes:
454: The available visualization contexts include
455: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
456: . PETSC_VIEWER_STDOUT_WORLD - synchronized standard
457: output where only the first processor opens
458: the file. All other processors send their
459: data to the first processor to print.
460: - PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure
462: The user can open alternative visualization contexts with
463: + PetscViewerASCIIOpen() - Outputs matrix to a specified file
464: . PetscViewerBinaryOpen() - Outputs matrix in binary to a
465: specified file; corresponding input uses MatLoad()
466: . PetscViewerDrawOpen() - Outputs nonzero matrix structure to
467: an X window display
468: - PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
469: Currently only the sequential dense and AIJ
470: matrix types support the Socket viewer.
472: The user can call PetscViewerSetFormat() to specify the output
473: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
474: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
475: + PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
476: . PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
477: . PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
478: . PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse
479: format common among all matrix types
480: . PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific
481: format (which is in many cases the same as the default)
482: . PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
483: size and structure (not the matrix entries)
484: . PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about
485: the matrix structure
487: Options Database Keys:
488: + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
489: . -mat_view_info_detailed - Prints more detailed info
490: . -mat_view - Prints matrix in ASCII format
491: . -mat_view_matlab - Prints matrix in Matlab format
492: . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
493: . -display <name> - Sets display name (default is host)
494: . -draw_pause <sec> - Sets number of seconds to pause after display
495: . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
496: . -viewer_socket_machine <machine>
497: . -viewer_socket_port <port>
498: . -mat_view_binary - save matrix to file in binary format
499: - -viewer_binary_filename <name>
500: Level: beginner
502: Concepts: matrices^viewing
503: Concepts: matrices^plotting
504: Concepts: matrices^printing
506: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(),
507: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
508: @*/
509: PetscErrorCode MatView(Mat mat,PetscViewer viewer)
510: {
511: PetscErrorCode ierr;
512: PetscInt rows,cols;
513: PetscTruth iascii;
514: const char *cstr;
515: PetscViewerFormat format;
520: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm);
523: if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix");
524: MatPreallocated(mat);
526: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
527: if (iascii) {
528: PetscViewerGetFormat(viewer,&format);
529: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
530: if (mat->prefix) {
531: PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);
532: } else {
533: PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");
534: }
535: PetscViewerASCIIPushTab(viewer);
536: MatGetType(mat,&cstr);
537: MatGetSize(mat,&rows,&cols);
538: PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);
539: if (mat->ops->getinfo) {
540: MatInfo info;
541: MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
542: PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n",
543: (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);
544: }
545: }
546: }
547: if (mat->ops->view) {
548: PetscViewerASCIIPushTab(viewer);
549: (*mat->ops->view)(mat,viewer);
550: PetscViewerASCIIPopTab(viewer);
551: } else if (!iascii) {
552: SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
553: }
554: if (iascii) {
555: PetscViewerGetFormat(viewer,&format);
556: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
557: PetscViewerASCIIPopTab(viewer);
558: }
559: }
560: return(0);
561: }
565: /*@C
566: MatScaleSystem - Scale a vector solution and right hand side to
567: match the scaling of a scaled matrix.
568:
569: Collective on Mat
571: Input Parameter:
572: + mat - the matrix
573: . b - right hand side vector (or PETSC_NULL)
574: - x - solution vector (or PETSC_NULL)
577: Notes:
578: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
579: internally scaled, so this does nothing. For MPIROWBS it
580: permutes and diagonally scales.
582: The KSP methods automatically call this routine when required
583: (via PCPreSolve()) so it is rarely used directly.
585: Level: Developer
587: Concepts: matrices^scaling
589: .seealso: MatUseScaledForm(), MatUnScaleSystem()
590: @*/
591: PetscErrorCode MatScaleSystem(Mat mat,Vec b,Vec x)
592: {
598: MatPreallocated(mat);
602: if (mat->ops->scalesystem) {
603: (*mat->ops->scalesystem)(mat,b,x);
604: }
605: return(0);
606: }
610: /*@C
611: MatUnScaleSystem - Unscales a vector solution and right hand side to
612: match the original scaling of a scaled matrix.
613:
614: Collective on Mat
616: Input Parameter:
617: + mat - the matrix
618: . b - right hand side vector (or PETSC_NULL)
619: - x - solution vector (or PETSC_NULL)
622: Notes:
623: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
624: internally scaled, so this does nothing. For MPIROWBS it
625: permutes and diagonally scales.
627: The KSP methods automatically call this routine when required
628: (via PCPreSolve()) so it is rarely used directly.
630: Level: Developer
632: .seealso: MatUseScaledForm(), MatScaleSystem()
633: @*/
634: PetscErrorCode MatUnScaleSystem(Mat mat,Vec b,Vec x)
635: {
641: MatPreallocated(mat);
644: if (mat->ops->unscalesystem) {
645: (*mat->ops->unscalesystem)(mat,b,x);
646: }
647: return(0);
648: }
652: /*@C
653: MatUseScaledForm - For matrix storage formats that scale the
654: matrix (for example MPIRowBS matrices are diagonally scaled on
655: assembly) indicates matrix operations (MatMult() etc) are
656: applied using the scaled matrix.
657:
658: Collective on Mat
660: Input Parameter:
661: + mat - the matrix
662: - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for
663: applying the original matrix
665: Notes:
666: For scaled matrix formats, applying the original, unscaled matrix
667: will be slightly more expensive
669: Level: Developer
671: .seealso: MatScaleSystem(), MatUnScaleSystem()
672: @*/
673: PetscErrorCode MatUseScaledForm(Mat mat,PetscTruth scaled)
674: {
680: MatPreallocated(mat);
681: if (mat->ops->usescaledform) {
682: (*mat->ops->usescaledform)(mat,scaled);
683: }
684: return(0);
685: }
689: /*@
690: MatDestroy - Frees space taken by a matrix.
691:
692: Collective on Mat
694: Input Parameter:
695: . A - the matrix
697: Level: beginner
699: @*/
700: PetscErrorCode MatDestroy(Mat A)
701: {
705: if (--A->refct > 0) return(0);
706: MatPreallocated(A);
707: /* if memory was published with AMS then destroy it */
708: PetscObjectDepublish(A);
709: if (A->ops->destroy) {
710: (*A->ops->destroy)(A);
711: }
712: if (A->mapping) {
713: ISLocalToGlobalMappingDestroy(A->mapping);
714: }
715: if (A->bmapping) {
716: ISLocalToGlobalMappingDestroy(A->bmapping);
717: }
718: PetscFree(A->rmap.range);
719: PetscFree(A->cmap.range);
720: PetscFree(A->spptr);
721: PetscHeaderDestroy(A);
722: return(0);
723: }
727: /*@
728: MatValid - Checks whether a matrix object is valid.
730: Collective on Mat
732: Input Parameter:
733: . m - the matrix to check
735: Output Parameter:
736: flg - flag indicating matrix status, either
737: PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.
739: Level: developer
741: Concepts: matrices^validity
742: @*/
743: PetscErrorCode MatValid(Mat m,PetscTruth *flg)
744: {
747: if (!m) *flg = PETSC_FALSE;
748: else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
749: else *flg = PETSC_TRUE;
750: return(0);
751: }
755: /*@
756: MatSetValues - Inserts or adds a block of values into a matrix.
757: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
758: MUST be called after all calls to MatSetValues() have been completed.
760: Not Collective
762: Input Parameters:
763: + mat - the matrix
764: . v - a logically two-dimensional array of values
765: . m, idxm - the number of rows and their global indices
766: . n, idxn - the number of columns and their global indices
767: - addv - either ADD_VALUES or INSERT_VALUES, where
768: ADD_VALUES adds values to any existing entries, and
769: INSERT_VALUES replaces existing entries with new values
771: Notes:
772: By default the values, v, are row-oriented and unsorted.
773: See MatSetOption() for other options.
775: Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES
776: options cannot be mixed without intervening calls to the assembly
777: routines.
779: MatSetValues() uses 0-based row and column numbers in Fortran
780: as well as in C.
782: Negative indices may be passed in idxm and idxn, these rows and columns are
783: simply ignored. This allows easily inserting element stiffness matrices
784: with homogeneous Dirchlet boundary conditions that you don't want represented
785: in the matrix.
787: Efficiency Alert:
788: The routine MatSetValuesBlocked() may offer much better efficiency
789: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
791: Level: beginner
793: Concepts: matrices^putting entries in
795: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
796: InsertMode, INSERT_VALUES, ADD_VALUES
797: @*/
798: PetscErrorCode MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
799: {
803: if (!m || !n) return(0); /* no values to insert */
809: MatPreallocated(mat);
810: if (mat->insertmode == NOT_SET_VALUES) {
811: mat->insertmode = addv;
812: }
813: #if defined(PETSC_USE_DEBUG)
814: else if (mat->insertmode != addv) {
815: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
816: }
817: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
818: #endif
820: if (mat->assembled) {
821: mat->was_assembled = PETSC_TRUE;
822: mat->assembled = PETSC_FALSE;
823: }
825: if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
826: (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
828: return(0);
829: }
834: /*@
835: MatSetValuesRowLocal - Inserts a row (block row for BAIJ matrices) of nonzero
836: values into a matrix
838: Not Collective
840: Input Parameters:
841: + mat - the matrix
842: . row - the (block) row to set
843: - v - a logically two-dimensional array of values
845: Notes:
846: By the values, v, are column-oriented (for the block version) and sorted
848: All the nonzeros in the row must be provided
850: The matrix must have previously had its column indices set
852: The row must belong to this process
854: Level: intermediate
856: Concepts: matrices^putting entries in
858: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
859: InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues(), MatSetValuesRow(), MatSetLocalToGlobalMapping()
860: @*/
861: PetscErrorCode MatSetValuesRowLocal(Mat mat,PetscInt row,const PetscScalar v[])
862: {
869: MatSetValuesRow(mat, mat->mapping->indices[row],v);
870: return(0);
871: }
875: /*@
876: MatSetValuesRow - Inserts a row (block row for BAIJ matrices) of nonzero
877: values into a matrix
879: Not Collective
881: Input Parameters:
882: + mat - the matrix
883: . row - the (block) row to set
884: - v - a logically two-dimensional array of values
886: Notes:
887: By the values, v, are column-oriented (for the block version) and sorted
889: All the nonzeros in the row must be provided
891: The matrix must have previously had its column indices set
893: The row must belong to this process
895: Level: intermediate
897: Concepts: matrices^putting entries in
899: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
900: InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues()
901: @*/
902: PetscErrorCode MatSetValuesRow(Mat mat,PetscInt row,const PetscScalar v[])
903: {
910: #if defined(PETSC_USE_DEBUG)
911: if (mat->insertmode == ADD_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add and insert values");
912: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
913: #endif
914: mat->insertmode = INSERT_VALUES;
916: if (mat->assembled) {
917: mat->was_assembled = PETSC_TRUE;
918: mat->assembled = PETSC_FALSE;
919: }
921: if (!mat->ops->setvaluesrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
922: (*mat->ops->setvaluesrow)(mat,row,v);
924: return(0);
925: }
929: /*@
930: MatSetValuesStencil - Inserts or adds a block of values into a matrix.
931: Using structured grid indexing
933: Not Collective
935: Input Parameters:
936: + mat - the matrix
937: . v - a logically two-dimensional array of values
938: . m - number of rows being entered
939: . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
940: . n - number of columns being entered
941: . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered
942: - addv - either ADD_VALUES or INSERT_VALUES, where
943: ADD_VALUES adds values to any existing entries, and
944: INSERT_VALUES replaces existing entries with new values
946: Notes:
947: By default the values, v, are row-oriented and unsorted.
948: See MatSetOption() for other options.
950: Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES
951: options cannot be mixed without intervening calls to the assembly
952: routines.
954: The grid coordinates are across the entire grid, not just the local portion
956: MatSetValuesStencil() uses 0-based row and column numbers in Fortran
957: as well as in C.
959: For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine
961: In order to use this routine you must either obtain the matrix with DAGetMatrix()
962: or call MatSetLocalToGlobalMapping() and MatSetStencil() first.
964: The columns and rows in the stencil passed in MUST be contained within the
965: ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example,
966: if you create a DA with an overlap of one grid level and on a particular process its first
967: local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the
968: first i index you can use in your column and row indices in MatSetStencil() is 5.
970: In Fortran idxm and idxn should be declared as
971: $ MatStencil idxm(4,m),idxn(4,n)
972: and the values inserted using
973: $ idxm(MatStencil_i,1) = i
974: $ idxm(MatStencil_j,1) = j
975: $ idxm(MatStencil_k,1) = k
976: $ idxm(MatStencil_c,1) = c
977: etc
979: For periodic boundary conditions use negative indices for values to the left (below 0; that are to be
980: obtained by wrapping values from right edge). For values to the right of the last entry using that index plus one
981: etc to obtain values that obtained by wrapping the values from the left edge.
983: For indices that don't mean anything for your case (like the k index when working in 2d) or the c index when you have
984: a single value per point) you can skip filling those indices.
986: Inspired by the structured grid interface to the HYPRE package
987: (http://www.llnl.gov/CASC/hypre)
989: Efficiency Alert:
990: The routine MatSetValuesBlockedStencil() may offer much better efficiency
991: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
993: Level: beginner
995: Concepts: matrices^putting entries in
997: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
998: MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
999: @*/
1000: PetscErrorCode MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1001: {
1003: PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1004: PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);
1007: if (!m || !n) return(0); /* no values to insert */
1014: if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1015: if (n > 256) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);
1017: for (i=0; i<m; i++) {
1018: for (j=0; j<3-sdim; j++) dxm++;
1019: tmp = *dxm++ - starts[0];
1020: for (j=0; j<dim-1; j++) {
1021: if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1022: else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1023: }
1024: if (mat->stencil.noc) dxm++;
1025: jdxm[i] = tmp;
1026: }
1027: for (i=0; i<n; i++) {
1028: for (j=0; j<3-sdim; j++) dxn++;
1029: tmp = *dxn++ - starts[0];
1030: for (j=0; j<dim-1; j++) {
1031: if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1032: else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1033: }
1034: if (mat->stencil.noc) dxn++;
1035: jdxn[i] = tmp;
1036: }
1037: MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
1038: return(0);
1039: }
1043: /*@C
1044: MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix.
1045: Using structured grid indexing
1047: Not Collective
1049: Input Parameters:
1050: + mat - the matrix
1051: . v - a logically two-dimensional array of values
1052: . m - number of rows being entered
1053: . idxm - grid coordinates for matrix rows being entered
1054: . n - number of columns being entered
1055: . idxn - grid coordinates for matrix columns being entered
1056: - addv - either ADD_VALUES or INSERT_VALUES, where
1057: ADD_VALUES adds values to any existing entries, and
1058: INSERT_VALUES replaces existing entries with new values
1060: Notes:
1061: By default the values, v, are row-oriented and unsorted.
1062: See MatSetOption() for other options.
1064: Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES
1065: options cannot be mixed without intervening calls to the assembly
1066: routines.
1068: The grid coordinates are across the entire grid, not just the local portion
1070: MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran
1071: as well as in C.
1073: For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine
1075: In order to use this routine you must either obtain the matrix with DAGetMatrix()
1076: or call MatSetLocalToGlobalMapping() and MatSetStencil() first.
1078: The columns and rows in the stencil passed in MUST be contained within the
1079: ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example,
1080: if you create a DA with an overlap of one grid level and on a particular process its first
1081: local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the
1082: first i index you can use in your column and row indices in MatSetStencil() is 5.
1084: In Fortran idxm and idxn should be declared as
1085: $ MatStencil idxm(4,m),idxn(4,n)
1086: and the values inserted using
1087: $ idxm(MatStencil_i,1) = i
1088: $ idxm(MatStencil_j,1) = j
1089: $ idxm(MatStencil_k,1) = k
1090: etc
1092: Negative indices may be passed in idxm and idxn, these rows and columns are
1093: simply ignored. This allows easily inserting element stiffness matrices
1094: with homogeneous Dirchlet boundary conditions that you don't want represented
1095: in the matrix.
1097: Inspired by the structured grid interface to the HYPRE package
1098: (http://www.llnl.gov/CASC/hypre)
1100: Level: beginner
1102: Concepts: matrices^putting entries in
1104: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1105: MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil
1106: @*/
1107: PetscErrorCode MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv)
1108: {
1110: PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
1111: PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc);
1114: if (!m || !n) return(0); /* no values to insert */
1121: if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m);
1122: if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n);
1124: for (i=0; i<m; i++) {
1125: for (j=0; j<3-sdim; j++) dxm++;
1126: tmp = *dxm++ - starts[0];
1127: for (j=0; j<sdim-1; j++) {
1128: if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1129: else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1];
1130: }
1131: dxm++;
1132: jdxm[i] = tmp;
1133: }
1134: for (i=0; i<n; i++) {
1135: for (j=0; j<3-sdim; j++) dxn++;
1136: tmp = *dxn++ - starts[0];
1137: for (j=0; j<sdim-1; j++) {
1138: if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT;
1139: else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1];
1140: }
1141: dxn++;
1142: jdxn[i] = tmp;
1143: }
1144: MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);
1145: return(0);
1146: }
1150: /*@
1151: MatSetStencil - Sets the grid information for setting values into a matrix via
1152: MatSetValuesStencil()
1154: Not Collective
1156: Input Parameters:
1157: + mat - the matrix
1158: . dim - dimension of the grid 1, 2, or 3
1159: . dims - number of grid points in x, y, and z direction, including ghost points on your processor
1160: . starts - starting point of ghost nodes on your processor in x, y, and z direction
1161: - dof - number of degrees of freedom per node
1164: Inspired by the structured grid interface to the HYPRE package
1165: (www.llnl.gov/CASC/hyper)
1167: For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the
1168: user.
1169:
1170: Level: beginner
1172: Concepts: matrices^putting entries in
1174: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
1175: MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
1176: @*/
1177: PetscErrorCode MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof)
1178: {
1179: PetscInt i;
1186: mat->stencil.dim = dim + (dof > 1);
1187: for (i=0; i<dim; i++) {
1188: mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */
1189: mat->stencil.starts[i] = starts[dim-i-1];
1190: }
1191: mat->stencil.dims[dim] = dof;
1192: mat->stencil.starts[dim] = 0;
1193: mat->stencil.noc = (PetscTruth)(dof == 1);
1194: return(0);
1195: }
1199: /*@
1200: MatSetValuesBlocked - Inserts or adds a block of values into a matrix.
1202: Not Collective
1204: Input Parameters:
1205: + mat - the matrix
1206: . v - a logically two-dimensional array of values
1207: . m, idxm - the number of block rows and their global block indices
1208: . n, idxn - the number of block columns and their global block indices
1209: - addv - either ADD_VALUES or INSERT_VALUES, where
1210: ADD_VALUES adds values to any existing entries, and
1211: INSERT_VALUES replaces existing entries with new values
1213: Notes:
1214: The m and n count the NUMBER of blocks in the row direction and column direction,
1215: NOT the total number of rows/columns; for example, if the block size is 2 and
1216: you are passing in values for rows 2,3,4,5 then m would be 2 (not 4).
1218: By default the values, v, are row-oriented and unsorted. So the layout of
1219: v is the same as for MatSetValues(). See MatSetOption() for other options.
1221: Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1222: options cannot be mixed without intervening calls to the assembly
1223: routines.
1225: MatSetValuesBlocked() uses 0-based row and column numbers in Fortran
1226: as well as in C.
1228: Negative indices may be passed in idxm and idxn, these rows and columns are
1229: simply ignored. This allows easily inserting element stiffness matrices
1230: with homogeneous Dirchlet boundary conditions that you don't want represented
1231: in the matrix.
1233: Each time an entry is set within a sparse matrix via MatSetValues(),
1234: internal searching must be done to determine where to place the the
1235: data in the matrix storage space. By instead inserting blocks of
1236: entries via MatSetValuesBlocked(), the overhead of matrix assembly is
1237: reduced.
1239: Restrictions:
1240: MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats
1242: Level: intermediate
1244: Concepts: matrices^putting entries in blocked
1246: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
1247: @*/
1248: PetscErrorCode MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv)
1249: {
1253: if (!m || !n) return(0); /* no values to insert */
1259: MatPreallocated(mat);
1260: if (mat->insertmode == NOT_SET_VALUES) {
1261: mat->insertmode = addv;
1262: }
1263: #if defined(PETSC_USE_DEBUG)
1264: else if (mat->insertmode != addv) {
1265: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1266: }
1267: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1268: #endif
1270: if (mat->assembled) {
1271: mat->was_assembled = PETSC_TRUE;
1272: mat->assembled = PETSC_FALSE;
1273: }
1275: if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1276: (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
1278: return(0);
1279: }
1283: /*@
1284: MatGetValues - Gets a block of values from a matrix.
1286: Not Collective; currently only returns a local block
1288: Input Parameters:
1289: + mat - the matrix
1290: . v - a logically two-dimensional array for storing the values
1291: . m, idxm - the number of rows and their global indices
1292: - n, idxn - the number of columns and their global indices
1294: Notes:
1295: The user must allocate space (m*n PetscScalars) for the values, v.
1296: The values, v, are then returned in a row-oriented format,
1297: analogous to that used by default in MatSetValues().
1299: MatGetValues() uses 0-based row and column numbers in
1300: Fortran as well as in C.
1302: MatGetValues() requires that the matrix has been assembled
1303: with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to
1304: MatSetValues() and MatGetValues() CANNOT be made in succession
1305: without intermediate matrix assembly.
1307: Level: advanced
1309: Concepts: matrices^accessing values
1311: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
1312: @*/
1313: PetscErrorCode MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[])
1314: {
1323: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1324: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1325: if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1326: MatPreallocated(mat);
1329: (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
1331: return(0);
1332: }
1336: /*@
1337: MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
1338: the routine MatSetValuesLocal() to allow users to insert matrix entries
1339: using a local (per-processor) numbering.
1341: Not Collective
1343: Input Parameters:
1344: + x - the matrix
1345: - mapping - mapping created with ISLocalToGlobalMappingCreate()
1346: or ISLocalToGlobalMappingCreateIS()
1348: Level: intermediate
1350: Concepts: matrices^local to global mapping
1351: Concepts: local to global mapping^for matrices
1353: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
1354: @*/
1355: PetscErrorCode MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
1356: {
1362: if (x->mapping) {
1363: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1364: }
1365: MatPreallocated(x);
1367: if (x->ops->setlocaltoglobalmapping) {
1368: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1369: } else {
1370: x->mapping = mapping;
1371: PetscObjectReference((PetscObject)mapping);
1372: }
1373: return(0);
1374: }
1378: /*@
1379: MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
1380: by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
1381: entries using a local (per-processor) numbering.
1383: Not Collective
1385: Input Parameters:
1386: + x - the matrix
1387: - mapping - mapping created with ISLocalToGlobalMappingCreate() or
1388: ISLocalToGlobalMappingCreateIS()
1390: Level: intermediate
1392: Concepts: matrices^local to global mapping blocked
1393: Concepts: local to global mapping^for matrices, blocked
1395: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
1396: MatSetValuesBlocked(), MatSetValuesLocal()
1397: @*/
1398: PetscErrorCode MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
1399: {
1405: if (x->bmapping) {
1406: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
1407: }
1408: x->bmapping = mapping;
1409: PetscObjectReference((PetscObject)mapping);
1410: return(0);
1411: }
1415: /*@
1416: MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
1417: using a local ordering of the nodes.
1419: Not Collective
1421: Input Parameters:
1422: + x - the matrix
1423: . nrow, irow - number of rows and their local indices
1424: . ncol, icol - number of columns and their local indices
1425: . y - a logically two-dimensional array of values
1426: - addv - either INSERT_VALUES or ADD_VALUES, where
1427: ADD_VALUES adds values to any existing entries, and
1428: INSERT_VALUES replaces existing entries with new values
1430: Notes:
1431: Before calling MatSetValuesLocal(), the user must first set the
1432: local-to-global mapping by calling MatSetLocalToGlobalMapping().
1434: Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES
1435: options cannot be mixed without intervening calls to the assembly
1436: routines.
1438: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
1439: MUST be called after all calls to MatSetValuesLocal() have been completed.
1441: Level: intermediate
1443: Concepts: matrices^putting entries in with local numbering
1445: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
1446: MatSetValueLocal()
1447: @*/
1448: PetscErrorCode MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1449: {
1451: PetscInt irowm[2048],icolm[2048];
1459: MatPreallocated(mat);
1460: if (mat->insertmode == NOT_SET_VALUES) {
1461: mat->insertmode = addv;
1462: }
1463: #if defined(PETSC_USE_DEBUG)
1464: else if (mat->insertmode != addv) {
1465: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1466: }
1467: if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
1468: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1469: }
1470: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1471: #endif
1473: if (mat->assembled) {
1474: mat->was_assembled = PETSC_TRUE;
1475: mat->assembled = PETSC_FALSE;
1476: }
1478: if (!mat->ops->setvalueslocal) {
1479: ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
1480: ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
1481: (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
1482: } else {
1483: (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
1484: }
1485: mat->same_nonzero = PETSC_FALSE;
1487: return(0);
1488: }
1492: /*@
1493: MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix,
1494: using a local ordering of the nodes a block at a time.
1496: Not Collective
1498: Input Parameters:
1499: + x - the matrix
1500: . nrow, irow - number of rows and their local indices
1501: . ncol, icol - number of columns and their local indices
1502: . y - a logically two-dimensional array of values
1503: - addv - either INSERT_VALUES or ADD_VALUES, where
1504: ADD_VALUES adds values to any existing entries, and
1505: INSERT_VALUES replaces existing entries with new values
1507: Notes:
1508: Before calling MatSetValuesBlockedLocal(), the user must first set the
1509: local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
1510: where the mapping MUST be set for matrix blocks, not for matrix elements.
1512: Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1513: options cannot be mixed without intervening calls to the assembly
1514: routines.
1516: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
1517: MUST be called after all calls to MatSetValuesBlockedLocal() have been completed.
1519: Level: intermediate
1521: Concepts: matrices^putting blocked values in with local numbering
1523: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
1524: @*/
1525: PetscErrorCode MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv)
1526: {
1528: PetscInt irowm[2048],icolm[2048];
1536: MatPreallocated(mat);
1537: if (mat->insertmode == NOT_SET_VALUES) {
1538: mat->insertmode = addv;
1539: }
1540: #if defined(PETSC_USE_DEBUG)
1541: else if (mat->insertmode != addv) {
1542: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
1543: }
1544: if (!mat->bmapping) {
1545: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
1546: }
1547: if (nrow > 2048 || ncol > 2048) {
1548: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol);
1549: }
1550: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1551: #endif
1553: if (mat->assembled) {
1554: mat->was_assembled = PETSC_TRUE;
1555: mat->assembled = PETSC_FALSE;
1556: }
1558: ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1559: ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1560: (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1562: return(0);
1563: }
1565: /* --------------------------------------------------------*/
1568: /*@
1569: MatMult - Computes the matrix-vector product, y = Ax.
1571: Collective on Mat and Vec
1573: Input Parameters:
1574: + mat - the matrix
1575: - x - the vector to be multiplied
1577: Output Parameters:
1578: . y - the result
1580: Notes:
1581: The vectors x and y cannot be the same. I.e., one cannot
1582: call MatMult(A,y,y).
1584: Level: beginner
1586: Concepts: matrix-vector product
1588: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1589: @*/
1590: PetscErrorCode MatMult(Mat mat,Vec x,Vec y)
1591: {
1600: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1601: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1602: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1603: #ifndef PETSC_HAVE_CONSTRAINTS
1604: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1605: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1606: if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);
1607: #endif
1608: MatPreallocated(mat);
1610: if (mat->nullsp) {
1611: MatNullSpaceRemove(mat->nullsp,x,&x);
1612: }
1614: if (!mat->ops->mult) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply defined");
1616: (*mat->ops->mult)(mat,x,y);
1619: if (mat->nullsp) {
1620: MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1621: }
1622: PetscObjectStateIncrease((PetscObject)y);
1623: return(0);
1624: }
1628: /*@
1629: MatMultTranspose - Computes matrix transpose times a vector.
1631: Collective on Mat and Vec
1633: Input Parameters:
1634: + mat - the matrix
1635: - x - the vector to be multilplied
1637: Output Parameters:
1638: . y - the result
1640: Notes:
1641: The vectors x and y cannot be the same. I.e., one cannot
1642: call MatMultTranspose(A,y,y).
1644: Level: beginner
1646: Concepts: matrix vector product^transpose
1648: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1649: @*/
1650: PetscErrorCode MatMultTranspose(Mat mat,Vec x,Vec y)
1651: {
1660: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1661: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1662: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1663: #ifndef PETSC_HAVE_CONSTRAINTS
1664: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
1665: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
1666: #endif
1667: MatPreallocated(mat);
1669: if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined");
1671: (*mat->ops->multtranspose)(mat,x,y);
1673: PetscObjectStateIncrease((PetscObject)y);
1674: return(0);
1675: }
1679: /*@
1680: MatMultAdd - Computes v3 = v2 + A * v1.
1682: Collective on Mat and Vec
1684: Input Parameters:
1685: + mat - the matrix
1686: - v1, v2 - the vectors
1688: Output Parameters:
1689: . v3 - the result
1691: Notes:
1692: The vectors v1 and v3 cannot be the same. I.e., one cannot
1693: call MatMultAdd(A,v1,v2,v1).
1695: Level: beginner
1697: Concepts: matrix vector product^addition
1699: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1700: @*/
1701: PetscErrorCode MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1702: {
1712: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1713: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1714: if (mat->cmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->cmap.N,v1->map.N);
1715: if (mat->rmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->rmap.N,v2->map.N);
1716: if (mat->rmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->rmap.N,v3->map.N);
1717: if (mat->rmap.n != v3->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->rmap.n,v3->map.n);
1718: if (mat->rmap.n != v2->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->rmap.n,v2->map.n);
1719: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1720: MatPreallocated(mat);
1723: (*mat->ops->multadd)(mat,v1,v2,v3);
1725: PetscObjectStateIncrease((PetscObject)v3);
1726: return(0);
1727: }
1731: /*@
1732: MatMultTransposeAdd - Computes v3 = v2 + A' * v1.
1734: Collective on Mat and Vec
1736: Input Parameters:
1737: + mat - the matrix
1738: - v1, v2 - the vectors
1740: Output Parameters:
1741: . v3 - the result
1743: Notes:
1744: The vectors v1 and v3 cannot be the same. I.e., one cannot
1745: call MatMultTransposeAdd(A,v1,v2,v1).
1747: Level: beginner
1749: Concepts: matrix vector product^transpose and addition
1751: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1752: @*/
1753: PetscErrorCode MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1754: {
1764: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1765: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1766: if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1767: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1768: if (mat->rmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->rmap.N,v1->map.N);
1769: if (mat->cmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->cmap.N,v2->map.N);
1770: if (mat->cmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->cmap.N,v3->map.N);
1771: MatPreallocated(mat);
1774: (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1776: PetscObjectStateIncrease((PetscObject)v3);
1777: return(0);
1778: }
1782: /*@
1783: MatMultConstrained - The inner multiplication routine for a
1784: constrained matrix P^T A P.
1786: Collective on Mat and Vec
1788: Input Parameters:
1789: + mat - the matrix
1790: - x - the vector to be multilplied
1792: Output Parameters:
1793: . y - the result
1795: Notes:
1796: The vectors x and y cannot be the same. I.e., one cannot
1797: call MatMult(A,y,y).
1799: Level: beginner
1801: .keywords: matrix, multiply, matrix-vector product, constraint
1802: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1803: @*/
1804: PetscErrorCode MatMultConstrained(Mat mat,Vec x,Vec y)
1805: {
1812: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1813: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1814: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1815: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1816: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1817: if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n);
1820: (*mat->ops->multconstrained)(mat,x,y);
1822: PetscObjectStateIncrease((PetscObject)y);
1824: return(0);
1825: }
1829: /*@
1830: MatMultTransposeConstrained - The inner multiplication routine for a
1831: constrained matrix P^T A^T P.
1833: Collective on Mat and Vec
1835: Input Parameters:
1836: + mat - the matrix
1837: - x - the vector to be multilplied
1839: Output Parameters:
1840: . y - the result
1842: Notes:
1843: The vectors x and y cannot be the same. I.e., one cannot
1844: call MatMult(A,y,y).
1846: Level: beginner
1848: .keywords: matrix, multiply, matrix-vector product, constraint
1849: .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd()
1850: @*/
1851: PetscErrorCode MatMultTransposeConstrained(Mat mat,Vec x,Vec y)
1852: {
1859: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1860: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1861: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1862: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
1863: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
1866: (*mat->ops->multtransposeconstrained)(mat,x,y);
1868: PetscObjectStateIncrease((PetscObject)y);
1870: return(0);
1871: }
1872: /* ------------------------------------------------------------*/
1875: /*@
1876: MatGetInfo - Returns information about matrix storage (number of
1877: nonzeros, memory, etc.).
1879: Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1880: as the flag
1882: Input Parameters:
1883: . mat - the matrix
1885: Output Parameters:
1886: + flag - flag indicating the type of parameters to be returned
1887: (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1888: MAT_GLOBAL_SUM - sum over all processors)
1889: - info - matrix information context
1891: Notes:
1892: The MatInfo context contains a variety of matrix data, including
1893: number of nonzeros allocated and used, number of mallocs during
1894: matrix assembly, etc. Additional information for factored matrices
1895: is provided (such as the fill ratio, number of mallocs during
1896: factorization, etc.). Much of this info is printed to STDOUT
1897: when using the runtime options
1898: $ -info -mat_view_info
1900: Example for C/C++ Users:
1901: See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1902: data within the MatInfo context. For example,
1903: .vb
1904: MatInfo info;
1905: Mat A;
1906: double mal, nz_a, nz_u;
1908: MatGetInfo(A,MAT_LOCAL,&info);
1909: mal = info.mallocs;
1910: nz_a = info.nz_allocated;
1911: .ve
1913: Example for Fortran Users:
1914: Fortran users should declare info as a double precision
1915: array of dimension MAT_INFO_SIZE, and then extract the parameters
1916: of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h
1917: a complete list of parameter names.
1918: .vb
1919: double precision info(MAT_INFO_SIZE)
1920: double precision mal, nz_a
1921: Mat A
1922: integer ierr
1924: call MatGetInfo(A,MAT_LOCAL,info,ierr)
1925: mal = info(MAT_INFO_MALLOCS)
1926: nz_a = info(MAT_INFO_NZ_ALLOCATED)
1927: .ve
1929: Level: intermediate
1931: Concepts: matrices^getting information on
1932:
1933: @*/
1934: PetscErrorCode MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1935: {
1942: if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1943: MatPreallocated(mat);
1944: (*mat->ops->getinfo)(mat,flag,info);
1945: return(0);
1946: }
1948: /* ----------------------------------------------------------*/
1951: /*@C
1952: MatILUDTFactor - Performs a drop tolerance ILU factorization.
1954: Collective on Mat
1956: Input Parameters:
1957: + mat - the matrix
1958: . row - row permutation
1959: . col - column permutation
1960: - info - information about the factorization to be done
1962: Output Parameters:
1963: . fact - the factored matrix
1965: Level: developer
1967: Notes:
1968: Most users should employ the simplified KSP interface for linear solvers
1969: instead of working directly with matrix algebra routines such as this.
1970: See, e.g., KSPCreate().
1972: This is currently only supported for the SeqAIJ matrix format using code
1973: from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or
1974: Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright
1975: and thus can be distributed with PETSc.
1977: Concepts: matrices^ILUDT factorization
1979: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
1980: @*/
1981: PetscErrorCode MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
1982: {
1992: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1993: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1994: if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1995: MatPreallocated(mat);
1997: (*mat->ops->iludtfactor)(mat,row,col,info,fact);
1999: PetscObjectStateIncrease((PetscObject)*fact);
2001: return(0);
2002: }
2006: /*@
2007: MatLUFactor - Performs in-place LU factorization of matrix.
2009: Collective on Mat
2011: Input Parameters:
2012: + mat - the matrix
2013: . row - row permutation
2014: . col - column permutation
2015: - info - options for factorization, includes
2016: $ fill - expected fill as ratio of original fill.
2017: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2018: $ Run with the option -info to determine an optimal value to use
2020: Notes:
2021: Most users should employ the simplified KSP interface for linear solvers
2022: instead of working directly with matrix algebra routines such as this.
2023: See, e.g., KSPCreate().
2025: This changes the state of the matrix to a factored matrix; it cannot be used
2026: for example with MatSetValues() unless one first calls MatSetUnfactored().
2028: Level: developer
2030: Concepts: matrices^LU factorization
2032: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
2033: MatGetOrdering(), MatSetUnfactored(), MatFactorInfo
2035: @*/
2036: PetscErrorCode MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2037: {
2046: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2047: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2048: if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2049: MatPreallocated(mat);
2052: (*mat->ops->lufactor)(mat,row,col,info);
2054: PetscObjectStateIncrease((PetscObject)mat);
2055: return(0);
2056: }
2060: /*@
2061: MatILUFactor - Performs in-place ILU factorization of matrix.
2063: Collective on Mat
2065: Input Parameters:
2066: + mat - the matrix
2067: . row - row permutation
2068: . col - column permutation
2069: - info - structure containing
2070: $ levels - number of levels of fill.
2071: $ expected fill - as ratio of original fill.
2072: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
2073: missing diagonal entries)
2075: Notes:
2076: Probably really in-place only when level of fill is zero, otherwise allocates
2077: new space to store factored matrix and deletes previous memory.
2079: Most users should employ the simplified KSP interface for linear solvers
2080: instead of working directly with matrix algebra routines such as this.
2081: See, e.g., KSPCreate().
2083: Level: developer
2085: Concepts: matrices^ILU factorization
2087: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2088: @*/
2089: PetscErrorCode MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info)
2090: {
2099: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
2100: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2101: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2102: if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2103: MatPreallocated(mat);
2106: (*mat->ops->ilufactor)(mat,row,col,info);
2108: PetscObjectStateIncrease((PetscObject)mat);
2109: return(0);
2110: }
2114: /*@
2115: MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
2116: Call this routine before calling MatLUFactorNumeric().
2118: Collective on Mat
2120: Input Parameters:
2121: + mat - the matrix
2122: . row, col - row and column permutations
2123: - info - options for factorization, includes
2124: $ fill - expected fill as ratio of original fill.
2125: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2126: $ Run with the option -info to determine an optimal value to use
2128: Output Parameter:
2129: . fact - new matrix that has been symbolically factored
2131: Notes:
2132: See the users manual for additional information about
2133: choosing the fill factor for better efficiency.
2135: Most users should employ the simplified KSP interface for linear solvers
2136: instead of working directly with matrix algebra routines such as this.
2137: See, e.g., KSPCreate().
2139: Level: developer
2141: Concepts: matrices^LU symbolic factorization
2143: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
2144: @*/
2145: PetscErrorCode MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
2146: {
2156: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2157: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2158: if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic LU",mat->type_name);
2159: MatPreallocated(mat);
2162: (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
2164: PetscObjectStateIncrease((PetscObject)*fact);
2165: return(0);
2166: }
2170: /*@
2171: MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
2172: Call this routine after first calling MatLUFactorSymbolic().
2174: Collective on Mat
2176: Input Parameters:
2177: + mat - the matrix
2178: . info - options for factorization
2179: - fact - the matrix generated for the factor, from MatLUFactorSymbolic()
2181: Notes:
2182: See MatLUFactor() for in-place factorization. See
2183: MatCholeskyFactorNumeric() for the symmetric, positive definite case.
2185: Most users should employ the simplified KSP interface for linear solvers
2186: instead of working directly with matrix algebra routines such as this.
2187: See, e.g., KSPCreate().
2189: Level: developer
2191: Concepts: matrices^LU numeric factorization
2193: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
2194: @*/
2195: PetscErrorCode MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2196: {
2204: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2205: if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2206: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2207: }
2208: if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2209: MatPreallocated(mat);
2211: (*(*fact)->ops->lufactornumeric)(mat,info,fact);
2214: MatView_Private(*fact);
2215: PetscObjectStateIncrease((PetscObject)*fact);
2216: return(0);
2217: }
2221: /*@
2222: MatCholeskyFactor - Performs in-place Cholesky factorization of a
2223: symmetric matrix.
2225: Collective on Mat
2227: Input Parameters:
2228: + mat - the matrix
2229: . perm - row and column permutations
2230: - f - expected fill as ratio of original fill
2232: Notes:
2233: See MatLUFactor() for the nonsymmetric case. See also
2234: MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().
2236: Most users should employ the simplified KSP interface for linear solvers
2237: instead of working directly with matrix algebra routines such as this.
2238: See, e.g., KSPCreate().
2240: Level: developer
2242: Concepts: matrices^Cholesky factorization
2244: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
2245: MatGetOrdering()
2247: @*/
2248: PetscErrorCode MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info)
2249: {
2257: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2258: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2259: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2260: if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2261: MatPreallocated(mat);
2264: (*mat->ops->choleskyfactor)(mat,perm,info);
2266: PetscObjectStateIncrease((PetscObject)mat);
2267: return(0);
2268: }
2272: /*@
2273: MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
2274: of a symmetric matrix.
2276: Collective on Mat
2278: Input Parameters:
2279: + mat - the matrix
2280: . perm - row and column permutations
2281: - info - options for factorization, includes
2282: $ fill - expected fill as ratio of original fill.
2283: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
2284: $ Run with the option -info to determine an optimal value to use
2286: Output Parameter:
2287: . fact - the factored matrix
2289: Notes:
2290: See MatLUFactorSymbolic() for the nonsymmetric case. See also
2291: MatCholeskyFactor() and MatCholeskyFactorNumeric().
2293: Most users should employ the simplified KSP interface for linear solvers
2294: instead of working directly with matrix algebra routines such as this.
2295: See, e.g., KSPCreate().
2297: Level: developer
2299: Concepts: matrices^Cholesky symbolic factorization
2301: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
2302: MatGetOrdering()
2304: @*/
2305: PetscErrorCode MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
2306: {
2315: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
2316: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2317: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2318: if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2319: MatPreallocated(mat);
2322: (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);
2324: PetscObjectStateIncrease((PetscObject)*fact);
2325: return(0);
2326: }
2330: /*@
2331: MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
2332: of a symmetric matrix. Call this routine after first calling
2333: MatCholeskyFactorSymbolic().
2335: Collective on Mat
2337: Input Parameter:
2338: . mat - the initial matrix
2339: . info - options for factorization
2340: - fact - the symbolic factor of mat
2342: Output Parameter:
2343: . fact - the factored matrix
2345: Notes:
2346: Most users should employ the simplified KSP interface for linear solvers
2347: instead of working directly with matrix algebra routines such as this.
2348: See, e.g., KSPCreate().
2350: Level: developer
2352: Concepts: matrices^Cholesky numeric factorization
2354: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
2355: @*/
2356: PetscErrorCode MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact)
2357: {
2364: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2365: if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2366: if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) {
2367: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N);
2368: }
2369: MatPreallocated(mat);
2372: (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);
2374: PetscObjectStateIncrease((PetscObject)*fact);
2375: return(0);
2376: }
2378: /* ----------------------------------------------------------------*/
2381: /*@
2382: MatSolve - Solves A x = b, given a factored matrix.
2384: Collective on Mat and Vec
2386: Input Parameters:
2387: + mat - the factored matrix
2388: - b - the right-hand-side vector
2390: Output Parameter:
2391: . x - the result vector
2393: Notes:
2394: The vectors b and x cannot be the same. I.e., one cannot
2395: call MatSolve(A,x,x).
2397: Notes:
2398: Most users should employ the simplified KSP interface for linear solvers
2399: instead of working directly with matrix algebra routines such as this.
2400: See, e.g., KSPCreate().
2402: Level: developer
2404: Concepts: matrices^triangular solves
2406: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
2407: @*/
2408: PetscErrorCode MatSolve(Mat mat,Vec b,Vec x)
2409: {
2419: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2420: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2421: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2422: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2423: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2424: if (!mat->rmap.N && !mat->cmap.N) return(0);
2425: if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2426: MatPreallocated(mat);
2429: (*mat->ops->solve)(mat,b,x);
2431: PetscObjectStateIncrease((PetscObject)x);
2432: return(0);
2433: }
2437: /*@
2438: MatMatSolve - Solves A X = B, given a factored matrix.
2440: Collective on Mat
2442: Input Parameters:
2443: + mat - the factored matrix
2444: - b - the right-hand-side vector
2446: Output Parameter:
2447: . x - the result vector
2449: Notes:
2450: The vectors b and x cannot be the same. I.e., one cannot
2451: call MatMatSolve(A,x,x).
2453: Notes:
2454: Most users should employ the simplified KSP interface for linear solvers
2455: instead of working directly with matrix algebra routines such as this.
2456: See, e.g., KSPCreate().
2458: Level: developer
2460: Concepts: matrices^triangular solves
2462: .seealso: MatMatSolveAdd(), MatMatSolveTranspose(), MatMatSolveTransposeAdd()
2463: @*/
2464: PetscErrorCode MatMatSolve(Mat A,Mat B,Mat X)
2465: {
2475: if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices");
2476: if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2477: if (A->cmap.N != X->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat X: global dim %D %D",A->cmap.N,X->rmap.N);
2478: if (A->rmap.N != B->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D",A->rmap.N,B->rmap.N);
2479: if (A->rmap.n != B->rmap.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: local dim %D %D",A->rmap.n,B->rmap.n);
2480: if (!A->rmap.N && !A->cmap.N) return(0);
2481: if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2482: MatPreallocated(A);
2485: (*A->ops->matsolve)(A,B,X);
2487: PetscObjectStateIncrease((PetscObject)X);
2488: return(0);
2489: }
2494: /* @
2495: MatForwardSolve - Solves L x = b, given a factored matrix, A = LU.
2497: Collective on Mat and Vec
2499: Input Parameters:
2500: + mat - the factored matrix
2501: - b - the right-hand-side vector
2503: Output Parameter:
2504: . x - the result vector
2506: Notes:
2507: MatSolve() should be used for most applications, as it performs
2508: a forward solve followed by a backward solve.
2510: The vectors b and x cannot be the same. I.e., one cannot
2511: call MatForwardSolve(A,x,x).
2513: Most users should employ the simplified KSP interface for linear solvers
2514: instead of working directly with matrix algebra routines such as this.
2515: See, e.g., KSPCreate().
2517: Level: developer
2519: Concepts: matrices^forward solves
2521: .seealso: MatSolve(), MatBackwardSolve()
2522: @ */
2523: PetscErrorCode MatForwardSolve(Mat mat,Vec b,Vec x)
2524: {
2534: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2535: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2536: if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2537: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2538: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2539: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2540: MatPreallocated(mat);
2542: (*mat->ops->forwardsolve)(mat,b,x);
2544: PetscObjectStateIncrease((PetscObject)x);
2545: return(0);
2546: }
2550: /* @
2551: MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU.
2553: Collective on Mat and Vec
2555: Input Parameters:
2556: + mat - the factored matrix
2557: - b - the right-hand-side vector
2559: Output Parameter:
2560: . x - the result vector
2562: Notes:
2563: MatSolve() should be used for most applications, as it performs
2564: a forward solve followed by a backward solve.
2566: The vectors b and x cannot be the same. I.e., one cannot
2567: call MatBackwardSolve(A,x,x).
2569: Most users should employ the simplified KSP interface for linear solvers
2570: instead of working directly with matrix algebra routines such as this.
2571: See, e.g., KSPCreate().
2573: Level: developer
2575: Concepts: matrices^backward solves
2577: .seealso: MatSolve(), MatForwardSolve()
2578: @ */
2579: PetscErrorCode MatBackwardSolve(Mat mat,Vec b,Vec x)
2580: {
2590: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2591: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2592: if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2593: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2594: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2595: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2596: MatPreallocated(mat);
2599: (*mat->ops->backwardsolve)(mat,b,x);
2601: PetscObjectStateIncrease((PetscObject)x);
2602: return(0);
2603: }
2607: /*@
2608: MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix.
2610: Collective on Mat and Vec
2612: Input Parameters:
2613: + mat - the factored matrix
2614: . b - the right-hand-side vector
2615: - y - the vector to be added to
2617: Output Parameter:
2618: . x - the result vector
2620: Notes:
2621: The vectors b and x cannot be the same. I.e., one cannot
2622: call MatSolveAdd(A,x,y,x).
2624: Most users should employ the simplified KSP interface for linear solvers
2625: instead of working directly with matrix algebra routines such as this.
2626: See, e.g., KSPCreate().
2628: Level: developer
2630: Concepts: matrices^triangular solves
2632: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
2633: @*/
2634: PetscErrorCode MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
2635: {
2636: PetscScalar one = 1.0;
2637: Vec tmp;
2649: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2650: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2651: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2652: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2653: if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N);
2654: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2655: if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2656: MatPreallocated(mat);
2659: if (mat->ops->solveadd) {
2660: (*mat->ops->solveadd)(mat,b,y,x);
2661: } else {
2662: /* do the solve then the add manually */
2663: if (x != y) {
2664: MatSolve(mat,b,x);
2665: VecAXPY(x,one,y);
2666: } else {
2667: VecDuplicate(x,&tmp);
2668: PetscLogObjectParent(mat,tmp);
2669: VecCopy(x,tmp);
2670: MatSolve(mat,b,x);
2671: VecAXPY(x,one,tmp);
2672: VecDestroy(tmp);
2673: }
2674: }
2676: PetscObjectStateIncrease((PetscObject)x);
2677: return(0);
2678: }
2682: /*@
2683: MatSolveTranspose - Solves A' x = b, given a factored matrix.
2685: Collective on Mat and Vec
2687: Input Parameters:
2688: + mat - the factored matrix
2689: - b - the right-hand-side vector
2691: Output Parameter:
2692: . x - the result vector
2694: Notes:
2695: The vectors b and x cannot be the same. I.e., one cannot
2696: call MatSolveTranspose(A,x,x).
2698: Most users should employ the simplified KSP interface for linear solvers
2699: instead of working directly with matrix algebra routines such as this.
2700: See, e.g., KSPCreate().
2702: Level: developer
2704: Concepts: matrices^triangular solves
2706: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
2707: @*/
2708: PetscErrorCode MatSolveTranspose(Mat mat,Vec b,Vec x)
2709: {
2719: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2720: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2721: if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
2722: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2723: if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2724: MatPreallocated(mat);
2726: (*mat->ops->solvetranspose)(mat,b,x);
2728: PetscObjectStateIncrease((PetscObject)x);
2729: return(0);
2730: }
2734: /*@
2735: MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a
2736: factored matrix.
2738: Collective on Mat and Vec
2740: Input Parameters:
2741: + mat - the factored matrix
2742: . b - the right-hand-side vector
2743: - y - the vector to be added to
2745: Output Parameter:
2746: . x - the result vector
2748: Notes:
2749: The vectors b and x cannot be the same. I.e., one cannot
2750: call MatSolveTransposeAdd(A,x,y,x).
2752: Most users should employ the simplified KSP interface for linear solvers
2753: instead of working directly with matrix algebra routines such as this.
2754: See, e.g., KSPCreate().
2756: Level: developer
2758: Concepts: matrices^triangular solves
2760: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
2761: @*/
2762: PetscErrorCode MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
2763: {
2764: PetscScalar one = 1.0;
2766: Vec tmp;
2777: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2778: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2779: if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N);
2780: if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N);
2781: if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N);
2782: if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n);
2783: MatPreallocated(mat);
2786: if (mat->ops->solvetransposeadd) {
2787: (*mat->ops->solvetransposeadd)(mat,b,y,x);
2788: } else {
2789: /* do the solve then the add manually */
2790: if (x != y) {
2791: MatSolveTranspose(mat,b,x);
2792: VecAXPY(x,one,y);
2793: } else {
2794: VecDuplicate(x,&tmp);
2795: PetscLogObjectParent(mat,tmp);
2796: VecCopy(x,tmp);
2797: MatSolveTranspose(mat,b,x);
2798: VecAXPY(x,one,tmp);
2799: VecDestroy(tmp);
2800: }
2801: }
2803: PetscObjectStateIncrease((PetscObject)x);
2804: return(0);
2805: }
2806: /* ----------------------------------------------------------------*/
2810: /*@
2811: MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.
2813: Collective on Mat and Vec
2815: Input Parameters:
2816: + mat - the matrix
2817: . b - the right hand side
2818: . omega - the relaxation factor
2819: . flag - flag indicating the type of SOR (see below)
2820: . shift - diagonal shift
2821: - its - the number of iterations
2822: - lits - the number of local iterations
2824: Output Parameters:
2825: . x - the solution (can contain an initial guess)
2827: SOR Flags:
2828: . SOR_FORWARD_SWEEP - forward SOR
2829: . SOR_BACKWARD_SWEEP - backward SOR
2830: . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2831: . SOR_LOCAL_FORWARD_SWEEP - local forward SOR
2832: . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR
2833: . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2834: . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies
2835: upper/lower triangular part of matrix to
2836: vector (with omega)
2837: . SOR_ZERO_INITIAL_GUESS - zero initial guess
2839: Notes:
2840: SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2841: SOR_LOCAL_SYMMETRIC_SWEEP perform separate independent smoothings
2842: on each processor.
2844: Application programmers will not generally use MatRelax() directly,
2845: but instead will employ the KSP/PC interface.
2847: Notes for Advanced Users:
2848: The flags are implemented as bitwise inclusive or operations.
2849: For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2850: to specify a zero initial guess for SSOR.
2852: Most users should employ the simplified KSP interface for linear solvers
2853: instead of working directly with matrix algebra routines such as this.
2854: See, e.g., KSPCreate().
2856: See also, MatPBRelax(). This routine will automatically call the point block
2857: version if the point version is not available.
2859: Level: developer
2861: Concepts: matrices^relaxation
2862: Concepts: matrices^SOR
2863: Concepts: matrices^Gauss-Seidel
2865: @*/
2866: PetscErrorCode MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2867: {
2877: if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2878: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2879: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2880: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2881: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2882: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2883: MatPreallocated(mat);
2885: if (mat->ops->relax) {
2886: ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);
2887: } else {
2888: ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2889: }
2891: PetscObjectStateIncrease((PetscObject)x);
2892: return(0);
2893: }
2897: /*@
2898: MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps.
2900: Collective on Mat and Vec
2902: See MatRelax() for usage
2904: For multi-component PDEs where the Jacobian is stored in a point block format
2905: (with the PETSc BAIJ matrix formats) the relaxation is done one point block at
2906: a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved
2907: simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point.
2909: Level: developer
2911: @*/
2912: PetscErrorCode MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x)
2913: {
2923: if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2924: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2925: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2926: if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N);
2927: if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N);
2928: if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n);
2929: MatPreallocated(mat);
2932: ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);
2934: PetscObjectStateIncrease((PetscObject)x);
2935: return(0);
2936: }
2940: /*
2941: Default matrix copy routine.
2942: */
2943: PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str)
2944: {
2945: PetscErrorCode ierr;
2946: PetscInt i,rstart,rend,nz;
2947: const PetscInt *cwork;
2948: const PetscScalar *vwork;
2951: if (B->assembled) {
2952: MatZeroEntries(B);
2953: }
2954: MatGetOwnershipRange(A,&rstart,&rend);
2955: for (i=rstart; i<rend; i++) {
2956: MatGetRow(A,i,&nz,&cwork,&vwork);
2957: MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2958: MatRestoreRow(A,i,&nz,&cwork,&vwork);
2959: }
2960: MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2961: MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2962: PetscObjectStateIncrease((PetscObject)B);
2963: return(0);
2964: }
2968: /*@
2969: MatCopy - Copys a matrix to another matrix.
2971: Collective on Mat
2973: Input Parameters:
2974: + A - the matrix
2975: - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN
2977: Output Parameter:
2978: . B - where the copy is put
2980: Notes:
2981: If you use SAME_NONZERO_PATTERN then the two matrices had better have the
2982: same nonzero pattern or the routine will crash.
2984: MatCopy() copies the matrix entries of a matrix to another existing
2985: matrix (after first zeroing the second matrix). A related routine is
2986: MatConvert(), which first creates a new matrix and then copies the data.
2988: Level: intermediate
2989:
2990: Concepts: matrices^copying
2992: .seealso: MatConvert(), MatDuplicate()
2994: @*/
2995: PetscErrorCode MatCopy(Mat A,Mat B,MatStructure str)
2996: {
3004: MatPreallocated(B);
3006: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3007: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3008: if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3009: MatPreallocated(A);
3012: if (A->ops->copy) {
3013: (*A->ops->copy)(A,B,str);
3014: } else { /* generic conversion */
3015: MatCopy_Basic(A,B,str);
3016: }
3017: if (A->mapping) {
3018: if (B->mapping) {ISLocalToGlobalMappingDestroy(B->mapping);B->mapping = 0;}
3019: MatSetLocalToGlobalMapping(B,A->mapping);
3020: }
3021: if (A->bmapping) {
3022: if (B->bmapping) {ISLocalToGlobalMappingDestroy(B->bmapping);B->bmapping = 0;}
3023: MatSetLocalToGlobalMappingBlock(B,A->mapping);
3024: }
3026: PetscObjectStateIncrease((PetscObject)B);
3027: return(0);
3028: }
3032: /*@C
3033: MatConvert - Converts a matrix to another matrix, either of the same
3034: or different type.
3036: Collective on Mat
3038: Input Parameters:
3039: + mat - the matrix
3040: . newtype - new matrix type. Use MATSAME to create a new matrix of the
3041: same type as the original matrix.
3042: - reuse - denotes if the destination matrix is to be created or reused. Currently
3043: MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use
3044: MAT_INITIAL_MATRIX.
3045: Output Parameter:
3046: . M - pointer to place new matrix
3048: Notes:
3049: MatConvert() first creates a new matrix and then copies the data from
3050: the first matrix. A related routine is MatCopy(), which copies the matrix
3051: entries of one matrix to another already existing matrix context.
3053: Level: intermediate
3055: Concepts: matrices^converting between storage formats
3057: .seealso: MatCopy(), MatDuplicate()
3058: @*/
3059: PetscErrorCode MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M)
3060: {
3061: PetscErrorCode ierr;
3062: PetscTruth sametype,issame,flg;
3063: char convname[256],mtype[256];
3064: Mat B;
3070: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3071: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3072: MatPreallocated(mat);
3074: PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
3075: if (flg) {
3076: newtype = mtype;
3077: }
3079:
3080: PetscTypeCompare((PetscObject)mat,newtype,&sametype);
3081: PetscStrcmp(newtype,"same",&issame);
3082: if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) {
3083: SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for in-place conversion currently");
3084: }
3085: if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) {
3086: (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
3087: } else {
3088: PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL;
3089: const char *prefix[3] = {"seq","mpi",""};
3090: PetscInt i;
3092: /*
3093: Order of precedence:
3094: 1) See if a specialized converter is known to the current matrix.
3095: 2) See if a specialized converter is known to the desired matrix class.
3096: 3) See if a good general converter is registered for the desired class
3097: (as of 6/27/03 only MATMPIADJ falls into this category).
3098: 4) See if a good general converter is known for the current matrix.
3099: 5) Use a really basic converter.
3100: */
3101: for (i=0; i<3; i++) {
3102: /* 1) See if a specialized converter is known to the current matrix and the desired class */
3103: PetscStrcpy(convname,"MatConvert_");
3104: PetscStrcat(convname,mat->type_name);
3105: PetscStrcat(convname,"_");
3106: PetscStrcat(convname,prefix[i]);
3107: PetscStrcat(convname,newtype);
3108: PetscStrcat(convname,"_C");
3109: PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);
3110: if (conv) goto foundconv;
3111: }
3113: /* 2) See if a specialized converter is known to the desired matrix class. */
3114: MatCreate(mat->comm,&B);
3115: MatSetSizes(B,mat->rmap.n,mat->cmap.n,mat->rmap.N,mat->cmap.N);
3116: MatSetType(B,newtype);
3117: PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);
3119: /* 3) See if a good general converter is registered for the desired class */
3120: if (!conv) conv = B->ops->convert;
3121: MatDestroy(B);
3122: if (conv) goto foundconv;
3124: /* 4) See if a good general converter is known for the current matrix */
3125: if (mat->ops->convert) {
3126: conv = mat->ops->convert;
3127: }
3128: if (conv) goto foundconv;
3130: /* 5) Use a really basic converter. */
3131: conv = MatConvert_Basic;
3133: foundconv:
3134: (*conv)(mat,newtype,reuse,M);
3135: }
3136: B = *M;
3138: PetscObjectStateIncrease((PetscObject)B);
3139: return(0);
3140: }
3145: /*@
3146: MatDuplicate - Duplicates a matrix including the non-zero structure.
3148: Collective on Mat
3150: Input Parameters:
3151: + mat - the matrix
3152: - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
3153: values as well or not
3155: Output Parameter:
3156: . M - pointer to place new matrix
3158: Level: intermediate
3160: Concepts: matrices^duplicating
3162: .seealso: MatCopy(), MatConvert()
3163: @*/
3164: PetscErrorCode MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
3165: {
3167: Mat B;
3173: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3174: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3175: MatPreallocated(mat);
3177: *M = 0;
3179: if (!mat->ops->duplicate) {
3180: SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
3181: }
3182: (*mat->ops->duplicate)(mat,op,M);
3183: B = *M;
3184: if (mat->mapping) {
3185: MatSetLocalToGlobalMapping(B,mat->mapping);
3186: }
3187: if (mat->bmapping) {
3188: MatSetLocalToGlobalMappingBlock(B,mat->bmapping);
3189: }
3190: PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);
3191: PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);
3192:
3194: PetscObjectStateIncrease((PetscObject)B);
3195: return(0);
3196: }
3200: /*@
3201: MatGetDiagonal - Gets the diagonal of a matrix.
3203: Collective on Mat and Vec
3205: Input Parameters:
3206: + mat - the matrix
3207: - v - the vector for storing the diagonal
3209: Output Parameter:
3210: . v - the diagonal of the matrix
3212: Notes:
3213: For the SeqAIJ matrix format, this routine may also be called
3214: on a LU factored matrix; in that case it routines the reciprocal of
3215: the diagonal entries in U. It returns the entries permuted by the
3216: row and column permutation used during the symbolic factorization.
3218: Level: intermediate
3220: Concepts: matrices^accessing diagonals
3222: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
3223: @*/
3224: PetscErrorCode MatGetDiagonal(Mat mat,Vec v)
3225: {
3232: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3233: if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3234: MatPreallocated(mat);
3236: (*mat->ops->getdiagonal)(mat,v);
3237: PetscObjectStateIncrease((PetscObject)v);
3238: return(0);
3239: }
3243: /*@
3244: MatGetRowMax - Gets the maximum value (in absolute value) of each
3245: row of the matrix
3247: Collective on Mat and Vec
3249: Input Parameters:
3250: . mat - the matrix
3252: Output Parameter:
3253: . v - the vector for storing the maximums
3255: Level: intermediate
3257: Concepts: matrices^getting row maximums
3259: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
3260: @*/
3261: PetscErrorCode MatGetRowMax(Mat mat,Vec v)
3262: {
3269: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3270: if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3271: MatPreallocated(mat);
3273: (*mat->ops->getrowmax)(mat,v);
3274: PetscObjectStateIncrease((PetscObject)v);
3275: return(0);
3276: }
3280: /*@C
3281: MatTranspose - Computes an in-place or out-of-place transpose of a matrix.
3283: Collective on Mat
3285: Input Parameter:
3286: . mat - the matrix to transpose
3288: Output Parameters:
3289: . B - the transpose (or pass in PETSC_NULL for an in-place transpose)
3291: Level: intermediate
3293: Concepts: matrices^transposing
3295: .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose()
3296: @*/
3297: PetscErrorCode MatTranspose(Mat mat,Mat *B)
3298: {
3304: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3305: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3306: if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3307: MatPreallocated(mat);
3310: (*mat->ops->transpose)(mat,B);
3312: if (B) {PetscObjectStateIncrease((PetscObject)*B);}
3313: return(0);
3314: }
3318: /*@C
3319: MatIsTranspose - Test whether a matrix is another one's transpose,
3320: or its own, in which case it tests symmetry.
3322: Collective on Mat
3324: Input Parameter:
3325: + A - the matrix to test
3326: - B - the matrix to test against, this can equal the first parameter
3328: Output Parameters:
3329: . flg - the result
3331: Notes:
3332: Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm
3333: has a running time of the order of the number of nonzeros; the parallel
3334: test involves parallel copies of the block-offdiagonal parts of the matrix.
3336: Level: intermediate
3338: Concepts: matrices^transposing, matrix^symmetry
3340: .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian()
3341: @*/
3342: PetscErrorCode MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg)
3343: {
3344: PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*);
3350: PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);
3351: PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);
3352: if (f && g) {
3353: if (f==g) {
3354: (*f)(A,B,tol,flg);
3355: } else {
3356: SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test");
3357: }
3358: }
3359: return(0);
3360: }
3364: /*@C
3365: MatPermute - Creates a new matrix with rows and columns permuted from the
3366: original.
3368: Collective on Mat
3370: Input Parameters:
3371: + mat - the matrix to permute
3372: . row - row permutation, each processor supplies only the permutation for its rows
3373: - col - column permutation, each processor needs the entire column permutation, that is
3374: this is the same size as the total number of columns in the matrix
3376: Output Parameters:
3377: . B - the permuted matrix
3379: Level: advanced
3381: Concepts: matrices^permuting
3383: .seealso: MatGetOrdering()
3384: @*/
3385: PetscErrorCode MatPermute(Mat mat,IS row,IS col,Mat *B)
3386: {
3395: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3396: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3397: if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"MatPermute not available for Mat type %s",mat->type_name);
3398: MatPreallocated(mat);
3400: (*mat->ops->permute)(mat,row,col,B);
3401: PetscObjectStateIncrease((PetscObject)*B);
3402: return(0);
3403: }
3407: /*@C
3408: MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the
3409: original and sparsified to the prescribed tolerance.
3411: Collective on Mat
3413: Input Parameters:
3414: + A - The matrix to permute
3415: . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE
3416: . frac - The half-bandwidth as a fraction of the total size, or 0.0
3417: . tol - The drop tolerance
3418: . rowp - The row permutation
3419: - colp - The column permutation
3421: Output Parameter:
3422: . B - The permuted, sparsified matrix
3424: Level: advanced
3426: Note:
3427: The default behavior (band = PETSC_DECIDE and frac = 0.0) is to
3428: restrict the half-bandwidth of the resulting matrix to 5% of the
3429: total matrix size.
3431: .keywords: matrix, permute, sparsify
3433: .seealso: MatGetOrdering(), MatPermute()
3434: @*/
3435: PetscErrorCode MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B)
3436: {
3437: IS irowp, icolp;
3438: PetscInt *rows, *cols;
3439: PetscInt M, N, locRowStart, locRowEnd;
3440: PetscInt nz, newNz;
3441: const PetscInt *cwork;
3442: PetscInt *cnew;
3443: const PetscScalar *vwork;
3444: PetscScalar *vnew;
3445: PetscInt bw, issize;
3446: PetscInt row, locRow, newRow, col, newCol;
3447: PetscErrorCode ierr;
3454: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix");
3455: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix");
3456: if (!A->ops->permutesparsify) {
3457: MatGetSize(A, &M, &N);
3458: MatGetOwnershipRange(A, &locRowStart, &locRowEnd);
3459: ISGetSize(rowp, &issize);
3460: if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M);
3461: ISGetSize(colp, &issize);
3462: if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N);
3463: ISInvertPermutation(rowp, 0, &irowp);
3464: ISGetIndices(irowp, &rows);
3465: ISInvertPermutation(colp, 0, &icolp);
3466: ISGetIndices(icolp, &cols);
3467: PetscMalloc(N * sizeof(PetscInt), &cnew);
3468: PetscMalloc(N * sizeof(PetscScalar), &vnew);
3470: /* Setup bandwidth to include */
3471: if (band == PETSC_DECIDE) {
3472: if (frac <= 0.0)
3473: bw = (PetscInt) (M * 0.05);
3474: else
3475: bw = (PetscInt) (M * frac);
3476: } else {
3477: if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer");
3478: bw = band;
3479: }
3481: /* Put values into new matrix */
3482: MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);
3483: for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) {
3484: MatGetRow(A, row, &nz, &cwork, &vwork);
3485: newRow = rows[locRow]+locRowStart;
3486: for(col = 0, newNz = 0; col < nz; col++) {
3487: newCol = cols[cwork[col]];
3488: if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) {
3489: cnew[newNz] = newCol;
3490: vnew[newNz] = vwork[col];
3491: newNz++;
3492: }
3493: }
3494: MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);
3495: MatRestoreRow(A, row, &nz, &cwork, &vwork);
3496: }
3497: PetscFree(cnew);
3498: PetscFree(vnew);
3499: MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);
3500: MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);
3501: ISRestoreIndices(irowp, &rows);
3502: ISRestoreIndices(icolp, &cols);
3503: ISDestroy(irowp);
3504: ISDestroy(icolp);
3505: } else {
3506: (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);
3507: }
3508: PetscObjectStateIncrease((PetscObject)*B);
3509: return(0);
3510: }
3514: /*@
3515: MatEqual - Compares two matrices.
3517: Collective on Mat
3519: Input Parameters:
3520: + A - the first matrix
3521: - B - the second matrix
3523: Output Parameter:
3524: . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.
3526: Level: intermediate
3528: Concepts: matrices^equality between
3529: @*/
3530: PetscErrorCode MatEqual(Mat A,Mat B,PetscTruth *flg)
3531: {
3539: MatPreallocated(B);
3542: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3543: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3544: if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N);
3545: if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
3546: if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name);
3547: if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name);
3548: MatPreallocated(A);
3550: (*A->ops->equal)(A,B,flg);
3551: return(0);
3552: }
3556: /*@
3557: MatDiagonalScale - Scales a matrix on the left and right by diagonal
3558: matrices that are stored as vectors. Either of the two scaling
3559: matrices can be PETSC_NULL.
3561: Collective on Mat
3563: Input Parameters:
3564: + mat - the matrix to be scaled
3565: . l - the left scaling vector (or PETSC_NULL)
3566: - r - the right scaling vector (or PETSC_NULL)
3568: Notes:
3569: MatDiagonalScale() computes A = LAR, where
3570: L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector)
3572: Level: intermediate
3574: Concepts: matrices^diagonal scaling
3575: Concepts: diagonal scaling of matrices
3577: .seealso: MatScale()
3578: @*/
3579: PetscErrorCode MatDiagonalScale(Mat mat,Vec l,Vec r)
3580: {
3586: if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3589: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3590: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3591: MatPreallocated(mat);
3594: (*mat->ops->diagonalscale)(mat,l,r);
3596: PetscObjectStateIncrease((PetscObject)mat);
3597: return(0);
3598: }
3602: /*@
3603: MatScale - Scales all elements of a matrix by a given number.
3605: Collective on Mat
3607: Input Parameters:
3608: + mat - the matrix to be scaled
3609: - a - the scaling value
3611: Output Parameter:
3612: . mat - the scaled matrix
3614: Level: intermediate
3616: Concepts: matrices^scaling all entries
3618: .seealso: MatDiagonalScale()
3619: @*/
3620: PetscErrorCode MatScale(Mat mat,PetscScalar a)
3621: {
3627: if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3628: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3629: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3630: MatPreallocated(mat);
3633: (*mat->ops->scale)(mat,a);
3635: PetscObjectStateIncrease((PetscObject)mat);
3636: return(0);
3637: }
3641: /*@
3642: MatNorm - Calculates various norms of a matrix.
3644: Collective on Mat
3646: Input Parameters:
3647: + mat - the matrix
3648: - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY
3650: Output Parameters:
3651: . nrm - the resulting norm
3653: Level: intermediate
3655: Concepts: matrices^norm
3656: Concepts: norm^of matrix
3657: @*/
3658: PetscErrorCode MatNorm(Mat mat,NormType type,PetscReal *nrm)
3659: {
3667: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3668: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3669: if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3670: MatPreallocated(mat);
3672: (*mat->ops->norm)(mat,type,nrm);
3673: return(0);
3674: }
3676: /*
3677: This variable is used to prevent counting of MatAssemblyBegin() that
3678: are called from within a MatAssemblyEnd().
3679: */
3680: static PetscInt MatAssemblyEnd_InUse = 0;
3683: /*@
3684: MatAssemblyBegin - Begins assembling the matrix. This routine should
3685: be called after completing all calls to MatSetValues().
3687: Collective on Mat
3689: Input Parameters:
3690: + mat - the matrix
3691: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3692:
3693: Notes:
3694: MatSetValues() generally caches the values. The matrix is ready to
3695: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3696: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3697: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3698: using the matrix.
3700: Level: beginner
3702: Concepts: matrices^assembling
3704: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
3705: @*/
3706: PetscErrorCode MatAssemblyBegin(Mat mat,MatAssemblyType type)
3707: {
3713: MatPreallocated(mat);
3714: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?");
3715: if (mat->assembled) {
3716: mat->was_assembled = PETSC_TRUE;
3717: mat->assembled = PETSC_FALSE;
3718: }
3719: if (!MatAssemblyEnd_InUse) {
3721: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3723: } else {
3724: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
3725: }
3726: return(0);
3727: }
3731: /*@
3732: MatAssembled - Indicates if a matrix has been assembled and is ready for
3733: use; for example, in matrix-vector product.
3735: Collective on Mat
3737: Input Parameter:
3738: . mat - the matrix
3740: Output Parameter:
3741: . assembled - PETSC_TRUE or PETSC_FALSE
3743: Level: advanced
3745: Concepts: matrices^assembled?
3747: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
3748: @*/
3749: PetscErrorCode MatAssembled(Mat mat,PetscTruth *assembled)
3750: {
3755: *assembled = mat->assembled;
3756: return(0);
3757: }
3761: /*
3762: Processes command line options to determine if/how a matrix
3763: is to be viewed. Called by MatAssemblyEnd() and MatLoad().
3764: */
3765: PetscErrorCode MatView_Private(Mat mat)
3766: {
3767: PetscErrorCode ierr;
3768: PetscTruth flg1,flg2,flg3,flg4,flg6,flg7,flg8;
3769: static PetscTruth incall = PETSC_FALSE;
3770: #if defined(PETSC_USE_SOCKET_VIEWER)
3771: PetscTruth flg5;
3772: #endif
3775: if (incall) return(0);
3776: incall = PETSC_TRUE;
3777: PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");
3778: PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg1);
3779: PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg2);
3780: PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg3);
3781: PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg4);
3782: #if defined(PETSC_USE_SOCKET_VIEWER)
3783: PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg5);
3784: #endif
3785: PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg6);
3786: PetscOptionsName("-mat_view_draw","Draw the matrix nonzero structure","MatView",&flg7);
3787: PetscOptionsEnd();
3789: if (flg1) {
3790: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
3791: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3792: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3793: }
3794: if (flg2) {
3795: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);
3796: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3797: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3798: }
3799: if (flg3) {
3800: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3801: }
3802: if (flg4) {
3803: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
3804: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
3805: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
3806: }
3807: #if defined(PETSC_USE_SOCKET_VIEWER)
3808: if (flg5) {
3809: MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
3810: PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
3811: }
3812: #endif
3813: if (flg6) {
3814: MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
3815: PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
3816: }
3817: if (flg7) {
3818: PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg8);
3819: if (flg8) {
3820: PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
3821: }
3822: MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
3823: PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
3824: if (flg8) {
3825: PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
3826: }
3827: }
3828: incall = PETSC_FALSE;
3829: return(0);
3830: }
3834: /*@
3835: MatAssemblyEnd - Completes assembling the matrix. This routine should
3836: be called after MatAssemblyBegin().
3838: Collective on Mat
3840: Input Parameters:
3841: + mat - the matrix
3842: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
3844: Options Database Keys:
3845: + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
3846: . -mat_view_info_detailed - Prints more detailed info
3847: . -mat_view - Prints matrix in ASCII format
3848: . -mat_view_matlab - Prints matrix in Matlab format
3849: . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
3850: . -display <name> - Sets display name (default is host)
3851: . -draw_pause <sec> - Sets number of seconds to pause after display
3852: . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual)
3853: . -viewer_socket_machine <machine>
3854: . -viewer_socket_port <port>
3855: . -mat_view_binary - save matrix to file in binary format
3856: - -viewer_binary_filename <name>
3858: Notes:
3859: MatSetValues() generally caches the values. The matrix is ready to
3860: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
3861: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
3862: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
3863: using the matrix.
3865: Level: beginner
3867: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen()
3868: @*/
3869: PetscErrorCode MatAssemblyEnd(Mat mat,MatAssemblyType type)
3870: {
3871: PetscErrorCode ierr;
3872: static PetscInt inassm = 0;
3873: PetscTruth flg;
3879: inassm++;
3880: MatAssemblyEnd_InUse++;
3881: if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
3883: if (mat->ops->assemblyend) {
3884: (*mat->ops->assemblyend)(mat,type);
3885: }
3887: } else {
3888: if (mat->ops->assemblyend) {
3889: (*mat->ops->assemblyend)(mat,type);
3890: }
3891: }
3893: /* Flush assembly is not a true assembly */
3894: if (type != MAT_FLUSH_ASSEMBLY) {
3895: mat->assembled = PETSC_TRUE; mat->num_ass++;
3896: }
3897: mat->insertmode = NOT_SET_VALUES;
3898: MatAssemblyEnd_InUse--;
3899: PetscObjectStateIncrease((PetscObject)mat);
3900: if (!mat->symmetric_eternal) {
3901: mat->symmetric_set = PETSC_FALSE;
3902: mat->hermitian_set = PETSC_FALSE;
3903: mat->structurally_symmetric_set = PETSC_FALSE;
3904: }
3905: if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
3906: MatView_Private(mat);
3907: PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);
3908: if (flg) {
3909: PetscReal tol = 0.0;
3910: PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);
3911: MatIsSymmetric(mat,tol,&flg);
3912: if (flg) {
3913: PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);
3914: } else {
3915: PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);
3916: }
3917: }
3918: }
3919: inassm--;
3920: return(0);
3921: }
3926: /*@
3927: MatCompress - Tries to store the matrix in as little space as
3928: possible. May fail if memory is already fully used, since it
3929: tries to allocate new space.
3931: Collective on Mat
3933: Input Parameters:
3934: . mat - the matrix
3936: Level: advanced
3938: @*/
3939: PetscErrorCode MatCompress(Mat mat)
3940: {
3946: MatPreallocated(mat);
3947: if (mat->ops->compress) {(*mat->ops->compress)(mat);}
3948: return(0);
3949: }
3953: /*@
3954: MatSetOption - Sets a parameter option for a matrix. Some options
3955: may be specific to certain storage formats. Some options
3956: determine how values will be inserted (or added). Sorted,
3957: row-oriented input will generally assemble the fastest. The default
3958: is row-oriented, nonsorted input.
3960: Collective on Mat
3962: Input Parameters:
3963: + mat - the matrix
3964: - option - the option, one of those listed below (and possibly others),
3965: e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR
3967: Options Describing Matrix Structure:
3968: + MAT_SYMMETRIC - symmetric in terms of both structure and value
3969: . MAT_HERMITIAN - transpose is the complex conjugation
3970: . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
3971: . MAT_NOT_SYMMETRIC - not symmetric in value
3972: . MAT_NOT_HERMITIAN - transpose is not the complex conjugation
3973: . MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure
3974: . MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag
3975: you set to be kept with all future use of the matrix
3976: including after MatAssemblyBegin/End() which could
3977: potentially change the symmetry structure, i.e. you
3978: KNOW the matrix will ALWAYS have the property you set.
3979: - MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the
3980: flags you set will be dropped (in case potentially
3981: the symmetry etc was lost).
3983: Options For Use with MatSetValues():
3984: Insert a logically dense subblock, which can be
3985: + MAT_ROW_ORIENTED - row-oriented (default)
3986: . MAT_COLUMN_ORIENTED - column-oriented
3987: . MAT_ROWS_SORTED - sorted by row
3988: . MAT_ROWS_UNSORTED - not sorted by row (default)
3989: . MAT_COLUMNS_SORTED - sorted by column
3990: - MAT_COLUMNS_UNSORTED - not sorted by column (default)
3992: Not these options reflect the data you pass in with MatSetValues(); it has
3993: nothing to do with how the data is stored internally in the matrix
3994: data structure.
3996: When (re)assembling a matrix, we can restrict the input for
3997: efficiency/debugging purposes. These options include
3998: + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
3999: allowed if they generate a new nonzero
4000: . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
4001: . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
4002: they generate a nonzero in a new diagonal (for block diagonal format only)
4003: . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
4004: . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
4005: . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
4006: - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly
4008: Notes:
4009: Some options are relevant only for particular matrix types and
4010: are thus ignored by others. Other options are not supported by
4011: certain matrix types and will generate an error message if set.
4013: If using a Fortran 77 module to compute a matrix, one may need to
4014: use the column-oriented option (or convert to the row-oriented
4015: format).
4017: MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion
4018: that would generate a new entry in the nonzero structure is instead
4019: ignored. Thus, if memory has not alredy been allocated for this particular
4020: data, then the insertion is ignored. For dense matrices, in which
4021: the entire array is allocated, no entries are ever ignored.
4022: Set after the first MatAssemblyEnd()
4024: MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion
4025: that would generate a new entry in the nonzero structure instead produces
4026: an error. (Currently supported for AIJ and BAIJ formats only.)
4027: This is a useful flag when using SAME_NONZERO_PATTERN in calling
4028: KSPSetOperators() to ensure that the nonzero pattern truely does
4029: remain unchanged. Set after the first MatAssemblyEnd()
4031: MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion
4032: that would generate a new entry that has not been preallocated will
4033: instead produce an error. (Currently supported for AIJ and BAIJ formats
4034: only.) This is a useful flag when debugging matrix memory preallocation.
4036: MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for
4037: other processors should be dropped, rather than stashed.
4038: This is useful if you know that the "owning" processor is also
4039: always generating the correct matrix entries, so that PETSc need
4040: not transfer duplicate entries generated on another processor.
4041:
4042: MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
4043: searches during matrix assembly. When this flag is set, the hash table
4044: is created during the first Matrix Assembly. This hash table is
4045: used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
4046: to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag
4047: should be used with MAT_USE_HASH_TABLE flag. This option is currently
4048: supported by MATMPIBAIJ format only.
4050: MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries
4051: are kept in the nonzero structure
4053: MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating
4054: a zero location in the matrix
4056: MAT_USE_INODES - indicates using inode version of the code - works with AIJ and
4057: ROWBS matrix types
4059: MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
4060: with AIJ and ROWBS matrix types (database option "-mat_no_inode")
4062: Level: intermediate
4064: Concepts: matrices^setting options
4066: @*/
4067: PetscErrorCode MatSetOption(Mat mat,MatOption op)
4068: {
4074: MatPreallocated(mat);
4075: switch (op) {
4076: case MAT_SYMMETRIC:
4077: mat->symmetric = PETSC_TRUE;
4078: mat->structurally_symmetric = PETSC_TRUE;
4079: mat->symmetric_set = PETSC_TRUE;
4080: mat->structurally_symmetric_set = PETSC_TRUE;
4081: break;
4082: case MAT_HERMITIAN:
4083: mat->hermitian = PETSC_TRUE;
4084: mat->structurally_symmetric = PETSC_TRUE;
4085: mat->hermitian_set = PETSC_TRUE;
4086: mat->structurally_symmetric_set = PETSC_TRUE;
4087: break;
4088: case MAT_STRUCTURALLY_SYMMETRIC:
4089: mat->structurally_symmetric = PETSC_TRUE;
4090: mat->structurally_symmetric_set = PETSC_TRUE;
4091: break;
4092: case MAT_NOT_SYMMETRIC:
4093: mat->symmetric = PETSC_FALSE;
4094: mat->symmetric_set = PETSC_TRUE;
4095: break;
4096: case MAT_NOT_HERMITIAN:
4097: mat->hermitian = PETSC_FALSE;
4098: mat->hermitian_set = PETSC_TRUE;
4099: break;
4100: case MAT_NOT_STRUCTURALLY_SYMMETRIC:
4101: mat->structurally_symmetric = PETSC_FALSE;
4102: mat->structurally_symmetric_set = PETSC_TRUE;
4103: break;
4104: case MAT_SYMMETRY_ETERNAL:
4105: mat->symmetric_eternal = PETSC_TRUE;
4106: break;
4107: case MAT_NOT_SYMMETRY_ETERNAL:
4108: mat->symmetric_eternal = PETSC_FALSE;
4109: break;
4110: default:
4111: break;
4112: }
4113: if (mat->ops->setoption) {
4114: (*mat->ops->setoption)(mat,op);
4115: }
4116: return(0);
4117: }
4121: /*@
4122: MatZeroEntries - Zeros all entries of a matrix. For sparse matrices
4123: this routine retains the old nonzero structure.
4125: Collective on Mat
4127: Input Parameters:
4128: . mat - the matrix
4130: Level: intermediate
4132: Concepts: matrices^zeroing
4134: .seealso: MatZeroRows()
4135: @*/
4136: PetscErrorCode MatZeroEntries(Mat mat)
4137: {
4143: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4144: if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled");
4145: if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4146: MatPreallocated(mat);
4149: (*mat->ops->zeroentries)(mat);
4151: PetscObjectStateIncrease((PetscObject)mat);
4152: return(0);
4153: }
4157: /*@C
4158: MatZeroRows - Zeros all entries (except possibly the main diagonal)
4159: of a set of rows of a matrix.
4161: Collective on Mat
4163: Input Parameters:
4164: + mat - the matrix
4165: . numRows - the number of rows to remove
4166: . rows - the global row indices
4167: - diag - value put in all diagonals of eliminated rows
4169: Notes:
4170: For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4171: but does not release memory. For the dense and block diagonal
4172: formats this does not alter the nonzero structure.
4174: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4175: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4176: merely zeroed.
4178: The user can set a value in the diagonal entry (or for the AIJ and
4179: row formats can optionally remove the main diagonal entry from the
4180: nonzero structure as well, by passing 0.0 as the final argument).
4182: For the parallel case, all processes that share the matrix (i.e.,
4183: those in the communicator used for matrix creation) MUST call this
4184: routine, regardless of whether any rows being zeroed are owned by
4185: them.
4187: Each processor should list the rows that IT wants zeroed
4189: Level: intermediate
4191: Concepts: matrices^zeroing rows
4193: .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4194: @*/
4195: PetscErrorCode MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4196: {
4203: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4204: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4205: if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4206: MatPreallocated(mat);
4208: (*mat->ops->zerorows)(mat,numRows,rows,diag);
4209: MatView_Private(mat);
4210: PetscObjectStateIncrease((PetscObject)mat);
4211: return(0);
4212: }
4216: /*@C
4217: MatZeroRowsIS - Zeros all entries (except possibly the main diagonal)
4218: of a set of rows of a matrix.
4220: Collective on Mat
4222: Input Parameters:
4223: + mat - the matrix
4224: . is - index set of rows to remove
4225: - diag - value put in all diagonals of eliminated rows
4227: Notes:
4228: For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
4229: but does not release memory. For the dense and block diagonal
4230: formats this does not alter the nonzero structure.
4232: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4233: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4234: merely zeroed.
4236: The user can set a value in the diagonal entry (or for the AIJ and
4237: row formats can optionally remove the main diagonal entry from the
4238: nonzero structure as well, by passing 0.0 as the final argument).
4240: For the parallel case, all processes that share the matrix (i.e.,
4241: those in the communicator used for matrix creation) MUST call this
4242: routine, regardless of whether any rows being zeroed are owned by
4243: them.
4245: Each processor should list the rows that IT wants zeroed
4247: Level: intermediate
4249: Concepts: matrices^zeroing rows
4251: .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
4252: @*/
4253: PetscErrorCode MatZeroRowsIS(Mat mat,IS is,PetscScalar diag)
4254: {
4255: PetscInt numRows;
4256: PetscInt *rows;
4263: ISGetLocalSize(is,&numRows);
4264: ISGetIndices(is,&rows);
4265: MatZeroRows(mat,numRows,rows,diag);
4266: ISRestoreIndices(is,&rows);
4267: return(0);
4268: }
4272: /*@C
4273: MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
4274: of a set of rows of a matrix; using local numbering of rows.
4276: Collective on Mat
4278: Input Parameters:
4279: + mat - the matrix
4280: . numRows - the number of rows to remove
4281: . rows - the global row indices
4282: - diag - value put in all diagonals of eliminated rows
4284: Notes:
4285: Before calling MatZeroRowsLocal(), the user must first set the
4286: local-to-global mapping by calling MatSetLocalToGlobalMapping().
4288: For the AIJ matrix formats this removes the old nonzero structure,
4289: but does not release memory. For the dense and block diagonal
4290: formats this does not alter the nonzero structure.
4292: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4293: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4294: merely zeroed.
4296: The user can set a value in the diagonal entry (or for the AIJ and
4297: row formats can optionally remove the main diagonal entry from the
4298: nonzero structure as well, by passing 0.0 as the final argument).
4300: Level: intermediate
4302: Concepts: matrices^zeroing
4304: .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4305: @*/
4306: PetscErrorCode MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag)
4307: {
4314: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4315: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4316: MatPreallocated(mat);
4318: if (mat->ops->zerorowslocal) {
4319: (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);
4320: } else {
4321: IS is, newis;
4322: PetscInt *newRows;
4324: if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
4325: ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);
4326: ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
4327: ISGetIndices(newis,&newRows);
4328: (*mat->ops->zerorows)(mat,numRows,newRows,diag);
4329: ISRestoreIndices(newis,&newRows);
4330: ISDestroy(newis);
4331: ISDestroy(is);
4332: }
4333: PetscObjectStateIncrease((PetscObject)mat);
4334: return(0);
4335: }
4339: /*@C
4340: MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
4341: of a set of rows of a matrix; using local numbering of rows.
4343: Collective on Mat
4345: Input Parameters:
4346: + mat - the matrix
4347: . is - index set of rows to remove
4348: - diag - value put in all diagonals of eliminated rows
4350: Notes:
4351: Before calling MatZeroRowsLocal(), the user must first set the
4352: local-to-global mapping by calling MatSetLocalToGlobalMapping().
4354: For the AIJ matrix formats this removes the old nonzero structure,
4355: but does not release memory. For the dense and block diagonal
4356: formats this does not alter the nonzero structure.
4358: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
4359: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
4360: merely zeroed.
4362: The user can set a value in the diagonal entry (or for the AIJ and
4363: row formats can optionally remove the main diagonal entry from the
4364: nonzero structure as well, by passing 0.0 as the final argument).
4366: Level: intermediate
4368: Concepts: matrices^zeroing
4370: .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
4371: @*/
4372: PetscErrorCode MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag)
4373: {
4375: PetscInt numRows;
4376: PetscInt *rows;
4382: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4383: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4384: MatPreallocated(mat);
4386: ISGetLocalSize(is,&numRows);
4387: ISGetIndices(is,&rows);
4388: MatZeroRowsLocal(mat,numRows,rows,diag);
4389: ISRestoreIndices(is,&rows);
4390: return(0);
4391: }
4395: /*@
4396: MatGetSize - Returns the numbers of rows and columns in a matrix.
4398: Not Collective
4400: Input Parameter:
4401: . mat - the matrix
4403: Output Parameters:
4404: + m - the number of global rows
4405: - n - the number of global columns
4407: Note: both output parameters can be PETSC_NULL on input.
4409: Level: beginner
4411: Concepts: matrices^size
4413: .seealso: MatGetLocalSize()
4414: @*/
4415: PetscErrorCode MatGetSize(Mat mat,PetscInt *m,PetscInt* n)
4416: {
4419: if (m) *m = mat->rmap.N;
4420: if (n) *n = mat->cmap.N;
4421: return(0);
4422: }
4426: /*@
4427: MatGetLocalSize - Returns the number of rows and columns in a matrix
4428: stored locally. This information may be implementation dependent, so
4429: use with care.
4431: Not Collective
4433: Input Parameters:
4434: . mat - the matrix
4436: Output Parameters:
4437: + m - the number of local rows
4438: - n - the number of local columns
4440: Note: both output parameters can be PETSC_NULL on input.
4442: Level: beginner
4444: Concepts: matrices^local size
4446: .seealso: MatGetSize()
4447: @*/
4448: PetscErrorCode MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n)
4449: {
4454: if (m) *m = mat->rmap.n;
4455: if (n) *n = mat->cmap.n;
4456: return(0);
4457: }
4461: /*@
4462: MatGetOwnershipRange - Returns the range of matrix rows owned by
4463: this processor, assuming that the matrix is laid out with the first
4464: n1 rows on the first processor, the next n2 rows on the second, etc.
4465: For certain parallel layouts this range may not be well defined.
4467: Not Collective
4469: Input Parameters:
4470: . mat - the matrix
4472: Output Parameters:
4473: + m - the global index of the first local row
4474: - n - one more than the global index of the last local row
4476: Note: both output parameters can be PETSC_NULL on input.
4478: Level: beginner
4480: Concepts: matrices^row ownership
4481: @*/
4482: PetscErrorCode MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n)
4483: {
4491: MatPreallocated(mat);
4492: if (m) *m = mat->rmap.rstart;
4493: if (n) *n = mat->rmap.rend;
4494: return(0);
4495: }
4499: /*@
4500: MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
4501: Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric()
4502: to complete the factorization.
4504: Collective on Mat
4506: Input Parameters:
4507: + mat - the matrix
4508: . row - row permutation
4509: . column - column permutation
4510: - info - structure containing
4511: $ levels - number of levels of fill.
4512: $ expected fill - as ratio of original fill.
4513: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
4514: missing diagonal entries)
4516: Output Parameters:
4517: . fact - new matrix that has been symbolically factored
4519: Notes:
4520: See the users manual for additional information about
4521: choosing the fill factor for better efficiency.
4523: Most users should employ the simplified KSP interface for linear solvers
4524: instead of working directly with matrix algebra routines such as this.
4525: See, e.g., KSPCreate().
4527: Level: developer
4529: Concepts: matrices^symbolic LU factorization
4530: Concepts: matrices^factorization
4531: Concepts: LU^symbolic factorization
4533: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4534: MatGetOrdering(), MatFactorInfo
4536: @*/
4537: PetscErrorCode MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact)
4538: {
4548: if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels);
4549: if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4550: if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name);
4551: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4552: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4553: MatPreallocated(mat);
4556: (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
4558: return(0);
4559: }
4563: /*@
4564: MatICCFactorSymbolic - Performs symbolic incomplete
4565: Cholesky factorization for a symmetric matrix. Use
4566: MatCholeskyFactorNumeric() to complete the factorization.
4568: Collective on Mat
4570: Input Parameters:
4571: + mat - the matrix
4572: . perm - row and column permutation
4573: - info - structure containing
4574: $ levels - number of levels of fill.
4575: $ expected fill - as ratio of original fill.
4577: Output Parameter:
4578: . fact - the factored matrix
4580: Notes:
4581: Most users should employ the KSP interface for linear solvers
4582: instead of working directly with matrix algebra routines such as this.
4583: See, e.g., KSPCreate().
4585: Level: developer
4587: Concepts: matrices^symbolic incomplete Cholesky factorization
4588: Concepts: matrices^factorization
4589: Concepts: Cholsky^symbolic factorization
4591: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo
4592: @*/
4593: PetscErrorCode MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact)
4594: {
4603: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4604: if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels);
4605: if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill);
4606: if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name);
4607: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4608: MatPreallocated(mat);
4611: (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);
4613: return(0);
4614: }
4618: /*@C
4619: MatGetArray - Returns a pointer to the element values in the matrix.
4620: The result of this routine is dependent on the underlying matrix data
4621: structure, and may not even work for certain matrix types. You MUST
4622: call MatRestoreArray() when you no longer need to access the array.
4624: Not Collective
4626: Input Parameter:
4627: . mat - the matrix
4629: Output Parameter:
4630: . v - the location of the values
4633: Fortran Note:
4634: This routine is used differently from Fortran, e.g.,
4635: .vb
4636: Mat mat
4637: PetscScalar mat_array(1)
4638: PetscOffset i_mat
4639: PetscErrorCode ierr
4640: call MatGetArray(mat,mat_array,i_mat,ierr)
4642: C Access first local entry in matrix; note that array is
4643: C treated as one dimensional
4644: value = mat_array(i_mat + 1)
4646: [... other code ...]
4647: call MatRestoreArray(mat,mat_array,i_mat,ierr)
4648: .ve
4650: See the Fortran chapter of the users manual and
4651: petsc/src/mat/examples/tests for details.
4653: Level: advanced
4655: Concepts: matrices^access array
4657: .seealso: MatRestoreArray(), MatGetArrayF90()
4658: @*/
4659: PetscErrorCode MatGetArray(Mat mat,PetscScalar *v[])
4660: {
4667: if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4668: MatPreallocated(mat);
4669: (*mat->ops->getarray)(mat,v);
4670: CHKMEMQ;
4671: return(0);
4672: }
4676: /*@C
4677: MatRestoreArray - Restores the matrix after MatGetArray() has been called.
4679: Not Collective
4681: Input Parameter:
4682: + mat - the matrix
4683: - v - the location of the values
4685: Fortran Note:
4686: This routine is used differently from Fortran, e.g.,
4687: .vb
4688: Mat mat
4689: PetscScalar mat_array(1)
4690: PetscOffset i_mat
4691: PetscErrorCode ierr
4692: call MatGetArray(mat,mat_array,i_mat,ierr)
4694: C Access first local entry in matrix; note that array is
4695: C treated as one dimensional
4696: value = mat_array(i_mat + 1)
4698: [... other code ...]
4699: call MatRestoreArray(mat,mat_array,i_mat,ierr)
4700: .ve
4702: See the Fortran chapter of the users manual and
4703: petsc/src/mat/examples/tests for details
4705: Level: advanced
4707: .seealso: MatGetArray(), MatRestoreArrayF90()
4708: @*/
4709: PetscErrorCode MatRestoreArray(Mat mat,PetscScalar *v[])
4710: {
4717: #if defined(PETSC_USE_DEBUG)
4718: CHKMEMQ;
4719: #endif
4720: if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4721: (*mat->ops->restorearray)(mat,v);
4722: PetscObjectStateIncrease((PetscObject)mat);
4723: return(0);
4724: }
4728: /*@C
4729: MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
4730: points to an array of valid matrices, they may be reused to store the new
4731: submatrices.
4733: Collective on Mat
4735: Input Parameters:
4736: + mat - the matrix
4737: . n - the number of submatrixes to be extracted (on this processor, may be zero)
4738: . irow, icol - index sets of rows and columns to extract
4739: - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
4741: Output Parameter:
4742: . submat - the array of submatrices
4744: Notes:
4745: MatGetSubMatrices() can extract only sequential submatrices
4746: (from both sequential and parallel matrices). Use MatGetSubMatrix()
4747: to extract a parallel submatrix.
4749: When extracting submatrices from a parallel matrix, each processor can
4750: form a different submatrix by setting the rows and columns of its
4751: individual index sets according to the local submatrix desired.
4753: When finished using the submatrices, the user should destroy
4754: them with MatDestroyMatrices().
4756: MAT_REUSE_MATRIX can only be used when the nonzero structure of the
4757: original matrix has not changed from that last call to MatGetSubMatrices().
4759: This routine creates the matrices in submat; you should NOT create them before
4760: calling it. It also allocates the array of matrix pointers submat.
4762: For BAIJ matrices the index sets must respect the block structure, that is if they
4763: request one row/column in a block, they must request all rows/columns that are in
4764: that block. For example, if the block size is 2 you cannot request just row 0 and
4765: column 0.
4767: Fortran Note:
4768: The Fortran interface is slightly different from that given below; it
4769: requires one to pass in as submat a Mat (integer) array of size at least m.
4771: Level: advanced
4773: Concepts: matrices^accessing submatrices
4774: Concepts: submatrices
4776: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
4777: @*/
4778: PetscErrorCode MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[])
4779: {
4781: PetscInt i;
4782: PetscTruth eq;
4787: if (n) {
4792: }
4794: if (n && scall == MAT_REUSE_MATRIX) {
4797: }
4798: if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4799: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4800: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4801: MatPreallocated(mat);
4804: (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
4806: for (i=0; i<n; i++) {
4807: if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) {
4808: ISEqual(irow[i],icol[i],&eq);
4809: if (eq) {
4810: if (mat->symmetric){
4811: MatSetOption((*submat)[i],MAT_SYMMETRIC);
4812: } else if (mat->hermitian) {
4813: MatSetOption((*submat)[i],MAT_HERMITIAN);
4814: } else if (mat->structurally_symmetric) {
4815: MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);
4816: }
4817: }
4818: }
4819: }
4820: return(0);
4821: }
4825: /*@C
4826: MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices().
4828: Collective on Mat
4830: Input Parameters:
4831: + n - the number of local matrices
4832: - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling
4833: sequence of MatGetSubMatrices())
4835: Level: advanced
4837: Notes: Frees not only the matrices, but also the array that contains the matrices
4839: .seealso: MatGetSubMatrices()
4840: @*/
4841: PetscErrorCode MatDestroyMatrices(PetscInt n,Mat *mat[])
4842: {
4844: PetscInt i;
4847: if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n);
4849: for (i=0; i<n; i++) {
4850: MatDestroy((*mat)[i]);
4851: }
4852: /* memory is allocated even if n = 0 */
4853: PetscFree(*mat);
4854: return(0);
4855: }
4859: /*@
4860: MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
4861: replaces the index sets by larger ones that represent submatrices with
4862: additional overlap.
4864: Collective on Mat
4866: Input Parameters:
4867: + mat - the matrix
4868: . n - the number of index sets
4869: . is - the array of index sets (these index sets will changed during the call)
4870: - ov - the additional overlap requested
4872: Level: developer
4874: Concepts: overlap
4875: Concepts: ASM^computing overlap
4877: .seealso: MatGetSubMatrices()
4878: @*/
4879: PetscErrorCode MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov)
4880: {
4886: if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n);
4887: if (n) {
4890: }
4891: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4892: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4893: MatPreallocated(mat);
4895: if (!ov) return(0);
4896: if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4898: (*mat->ops->increaseoverlap)(mat,n,is,ov);
4900: return(0);
4901: }
4905: /*@
4906: MatGetBlockSize - Returns the matrix block size; useful especially for the
4907: block row and block diagonal formats.
4908:
4909: Not Collective
4911: Input Parameter:
4912: . mat - the matrix
4914: Output Parameter:
4915: . bs - block size
4917: Notes:
4918: Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
4919: Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ
4921: Level: intermediate
4923: Concepts: matrices^block size
4925: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
4926: @*/
4927: PetscErrorCode MatGetBlockSize(Mat mat,PetscInt *bs)
4928: {
4935: MatPreallocated(mat);
4936: *bs = mat->rmap.bs;
4937: return(0);
4938: }
4942: /*@
4943: MatSetBlockSize - Sets the matrix block size; for many matrix types you
4944: cannot use this and MUST set the blocksize when you preallocate the matrix
4945:
4946: Not Collective
4948: Input Parameters:
4949: + mat - the matrix
4950: - bs - block size
4952: Notes:
4953: Only works for shell and AIJ matrices
4955: Level: intermediate
4957: Concepts: matrices^block size
4959: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize()
4960: @*/
4961: PetscErrorCode MatSetBlockSize(Mat mat,PetscInt bs)
4962: {
4968: MatPreallocated(mat);
4969: if (mat->ops->setblocksize) {
4970: mat->rmap.bs = bs;
4971: (*mat->ops->setblocksize)(mat,bs);
4972: } else {
4973: SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name);
4974: }
4975: return(0);
4976: }
4980: /*@C
4981: MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices.
4983: Collective on Mat
4985: Input Parameters:
4986: + mat - the matrix
4987: . shift - 0 or 1 indicating we want the indices starting at 0 or 1
4988: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
4989: symmetrized
4991: Output Parameters:
4992: + n - number of rows in the (possibly compressed) matrix
4993: . ia - the row pointers
4994: . ja - the column indices
4995: - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers
4996: are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set
4998: Level: developer
5000: Notes: You CANNOT change any of the ia[] or ja[] values.
5002: Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values
5004: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5005: @*/
5006: PetscErrorCode MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5007: {
5017: MatPreallocated(mat);
5018: if (!mat->ops->getrowij) *done = PETSC_FALSE;
5019: else {
5020: *done = PETSC_TRUE;
5021: (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
5022: }
5023: return(0);
5024: }
5028: /*@C
5029: MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices.
5031: Collective on Mat
5033: Input Parameters:
5034: + mat - the matrix
5035: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5036: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5037: symmetrized
5039: Output Parameters:
5040: + n - number of columns in the (possibly compressed) matrix
5041: . ia - the column pointers
5042: . ja - the row indices
5043: - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned
5045: Level: developer
5047: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5048: @*/
5049: PetscErrorCode MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5050: {
5060: MatPreallocated(mat);
5061: if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
5062: else {
5063: *done = PETSC_TRUE;
5064: (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
5065: }
5066: return(0);
5067: }
5071: /*@C
5072: MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
5073: MatGetRowIJ().
5075: Collective on Mat
5077: Input Parameters:
5078: + mat - the matrix
5079: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5080: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5081: symmetrized
5083: Output Parameters:
5084: + n - size of (possibly compressed) matrix
5085: . ia - the row pointers
5086: . ja - the column indices
5087: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
5089: Level: developer
5091: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
5092: @*/
5093: PetscErrorCode MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5094: {
5103: MatPreallocated(mat);
5105: if (!mat->ops->restorerowij) *done = PETSC_FALSE;
5106: else {
5107: *done = PETSC_TRUE;
5108: (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
5109: }
5110: return(0);
5111: }
5115: /*@C
5116: MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
5117: MatGetColumnIJ().
5119: Collective on Mat
5121: Input Parameters:
5122: + mat - the matrix
5123: . shift - 1 or zero indicating we want the indices starting at 0 or 1
5124: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
5125: symmetrized
5127: Output Parameters:
5128: + n - size of (possibly compressed) matrix
5129: . ia - the column pointers
5130: . ja - the row indices
5131: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
5133: Level: developer
5135: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
5136: @*/
5137: PetscErrorCode MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done)
5138: {
5147: MatPreallocated(mat);
5149: if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
5150: else {
5151: *done = PETSC_TRUE;
5152: (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
5153: }
5154: return(0);
5155: }
5159: /*@C
5160: MatColoringPatch -Used inside matrix coloring routines that
5161: use MatGetRowIJ() and/or MatGetColumnIJ().
5163: Collective on Mat
5165: Input Parameters:
5166: + mat - the matrix
5167: . ncolors - max color value
5168: . n - number of entries in colorarray
5169: - colorarray - array indicating color for each column
5171: Output Parameters:
5172: . iscoloring - coloring generated using colorarray information
5174: Level: developer
5176: .seealso: MatGetRowIJ(), MatGetColumnIJ()
5178: @*/
5179: PetscErrorCode MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring)
5180: {
5188: MatPreallocated(mat);
5190: if (!mat->ops->coloringpatch){
5191: ISColoringCreate(mat->comm,ncolors,n,colorarray,iscoloring);
5192: } else {
5193: (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);
5194: }
5195: return(0);
5196: }
5201: /*@
5202: MatSetUnfactored - Resets a factored matrix to be treated as unfactored.
5204: Collective on Mat
5206: Input Parameter:
5207: . mat - the factored matrix to be reset
5209: Notes:
5210: This routine should be used only with factored matrices formed by in-place
5211: factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE
5212: format). This option can save memory, for example, when solving nonlinear
5213: systems with a matrix-free Newton-Krylov method and a matrix-based, in-place
5214: ILU(0) preconditioner.
5216: Note that one can specify in-place ILU(0) factorization by calling
5217: .vb
5218: PCType(pc,PCILU);
5219: PCFactorSeUseInPlace(pc);
5220: .ve
5221: or by using the options -pc_type ilu -pc_factor_in_place
5223: In-place factorization ILU(0) can also be used as a local
5224: solver for the blocks within the block Jacobi or additive Schwarz
5225: methods (runtime option: -sub_pc_factor_in_place). See the discussion
5226: of these preconditioners in the users manual for details on setting
5227: local solver options.
5229: Most users should employ the simplified KSP interface for linear solvers
5230: instead of working directly with matrix algebra routines such as this.
5231: See, e.g., KSPCreate().
5233: Level: developer
5235: .seealso: PCFactorSetUseInPlace()
5237: Concepts: matrices^unfactored
5239: @*/
5240: PetscErrorCode MatSetUnfactored(Mat mat)
5241: {
5247: MatPreallocated(mat);
5248: mat->factor = 0;
5249: if (!mat->ops->setunfactored) return(0);
5250: (*mat->ops->setunfactored)(mat);
5251: return(0);
5252: }
5254: /*MC
5255: MatGetArrayF90 - Accesses a matrix array from Fortran90.
5257: Synopsis:
5258: MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
5260: Not collective
5262: Input Parameter:
5263: . x - matrix
5265: Output Parameters:
5266: + xx_v - the Fortran90 pointer to the array
5267: - ierr - error code
5269: Example of Usage:
5270: .vb
5271: PetscScalar, pointer xx_v(:)
5272: ....
5273: call MatGetArrayF90(x,xx_v,ierr)
5274: a = xx_v(3)
5275: call MatRestoreArrayF90(x,xx_v,ierr)
5276: .ve
5278: Notes:
5279: Not yet supported for all F90 compilers
5281: Level: advanced
5283: .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray()
5285: Concepts: matrices^accessing array
5287: M*/
5289: /*MC
5290: MatRestoreArrayF90 - Restores a matrix array that has been
5291: accessed with MatGetArrayF90().
5293: Synopsis:
5294: MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
5296: Not collective
5298: Input Parameters:
5299: + x - matrix
5300: - xx_v - the Fortran90 pointer to the array
5302: Output Parameter:
5303: . ierr - error code
5305: Example of Usage:
5306: .vb
5307: PetscScalar, pointer xx_v(:)
5308: ....
5309: call MatGetArrayF90(x,xx_v,ierr)
5310: a = xx_v(3)
5311: call MatRestoreArrayF90(x,xx_v,ierr)
5312: .ve
5313:
5314: Notes:
5315: Not yet supported for all F90 compilers
5317: Level: advanced
5319: .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray()
5321: M*/
5326: /*@
5327: MatGetSubMatrix - Gets a single submatrix on the same number of processors
5328: as the original matrix.
5330: Collective on Mat
5332: Input Parameters:
5333: + mat - the original matrix
5334: . isrow - rows this processor should obtain
5335: . iscol - columns for all processors you wish to keep
5336: . csize - number of columns "local" to this processor (does nothing for sequential
5337: matrices). This should match the result from VecGetLocalSize(x,...) if you
5338: plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5339: - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
5341: Output Parameter:
5342: . newmat - the new submatrix, of the same type as the old
5344: Level: advanced
5346: Notes: the iscol argument MUST be the same on each processor. You might be
5347: able to create the iscol argument with ISAllGather().
5349: The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5350: the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5351: to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX
5352: will reuse the matrix generated the first time.
5354: Concepts: matrices^submatrices
5356: .seealso: MatGetSubMatrices(), ISAllGather()
5357: @*/
5358: PetscErrorCode MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat)
5359: {
5361: PetscMPIInt size;
5362: Mat *local;
5371: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5372: MatPreallocated(mat);
5373: MPI_Comm_size(mat->comm,&size);
5375: /* if original matrix is on just one processor then use submatrix generated */
5376: if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
5377: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
5378: return(0);
5379: } else if (!mat->ops->getsubmatrix && size == 1) {
5380: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
5381: *newmat = *local;
5382: PetscFree(local);
5383: return(0);
5384: }
5386: if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5387: (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
5388: PetscObjectStateIncrease((PetscObject)*newmat);
5389: return(0);
5390: }
5394: /*@
5395: MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors
5396: as the original matrix.
5398: Collective on Mat
5400: Input Parameters:
5401: + mat - the original matrix
5402: . nrows - the number of rows this processor should obtain
5403: . rows - rows this processor should obtain
5404: . ncols - the number of columns for all processors you wish to keep
5405: . cols - columns for all processors you wish to keep
5406: . csize - number of columns "local" to this processor (does nothing for sequential
5407: matrices). This should match the result from VecGetLocalSize(x,...) if you
5408: plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
5409: - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
5411: Output Parameter:
5412: . newmat - the new submatrix, of the same type as the old
5414: Level: advanced
5416: Notes: the iscol argument MUST be the same on each processor. You might be
5417: able to create the iscol argument with ISAllGather().
5419: The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
5420: the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
5421: to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX
5422: will reuse the matrix generated the first time.
5424: Concepts: matrices^submatrices
5426: .seealso: MatGetSubMatrices(), ISAllGather()
5427: @*/
5428: PetscErrorCode MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat)
5429: {
5430: IS isrow, iscol;
5440: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5441: MatPreallocated(mat);
5442: ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);
5443: ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);
5444: MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);
5445: ISDestroy(isrow);
5446: ISDestroy(iscol);
5447: return(0);
5448: }
5452: /*@
5453: MatStashSetInitialSize - sets the sizes of the matrix stash, that is
5454: used during the assembly process to store values that belong to
5455: other processors.
5457: Not Collective
5459: Input Parameters:
5460: + mat - the matrix
5461: . size - the initial size of the stash.
5462: - bsize - the initial size of the block-stash(if used).
5464: Options Database Keys:
5465: + -matstash_initial_size <size> or <size0,size1,...sizep-1>
5466: - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
5468: Level: intermediate
5470: Notes:
5471: The block-stash is used for values set with MatSetValuesBlocked() while
5472: the stash is used for values set with MatSetValues()
5474: Run with the option -info and look for output of the form
5475: MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
5476: to determine the appropriate value, MM, to use for size and
5477: MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
5478: to determine the value, BMM to use for bsize
5480: Concepts: stash^setting matrix size
5481: Concepts: matrices^stash
5483: @*/
5484: PetscErrorCode MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize)
5485: {
5491: MatStashSetInitialSize_Private(&mat->stash,size);
5492: MatStashSetInitialSize_Private(&mat->bstash,bsize);
5493: return(0);
5494: }
5498: /*@
5499: MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of
5500: the matrix
5502: Collective on Mat
5504: Input Parameters:
5505: + mat - the matrix
5506: . x,y - the vectors
5507: - w - where the result is stored
5509: Level: intermediate
5511: Notes:
5512: w may be the same vector as y.
5514: This allows one to use either the restriction or interpolation (its transpose)
5515: matrix to do the interpolation
5517: Concepts: interpolation
5519: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
5521: @*/
5522: PetscErrorCode MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
5523: {
5525: PetscInt M,N;
5533: MatPreallocated(A);
5534: MatGetSize(A,&M,&N);
5535: if (N > M) {
5536: MatMultTransposeAdd(A,x,y,w);
5537: } else {
5538: MatMultAdd(A,x,y,w);
5539: }
5540: return(0);
5541: }
5545: /*@
5546: MatInterpolate - y = A*x or A'*x depending on the shape of
5547: the matrix
5549: Collective on Mat
5551: Input Parameters:
5552: + mat - the matrix
5553: - x,y - the vectors
5555: Level: intermediate
5557: Notes:
5558: This allows one to use either the restriction or interpolation (its transpose)
5559: matrix to do the interpolation
5561: Concepts: matrices^interpolation
5563: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
5565: @*/
5566: PetscErrorCode MatInterpolate(Mat A,Vec x,Vec y)
5567: {
5569: PetscInt M,N;
5576: MatPreallocated(A);
5577: MatGetSize(A,&M,&N);
5578: if (N > M) {
5579: MatMultTranspose(A,x,y);
5580: } else {
5581: MatMult(A,x,y);
5582: }
5583: return(0);
5584: }
5588: /*@
5589: MatRestrict - y = A*x or A'*x
5591: Collective on Mat
5593: Input Parameters:
5594: + mat - the matrix
5595: - x,y - the vectors
5597: Level: intermediate
5599: Notes:
5600: This allows one to use either the restriction or interpolation (its transpose)
5601: matrix to do the restriction
5603: Concepts: matrices^restriction
5605: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate()
5607: @*/
5608: PetscErrorCode MatRestrict(Mat A,Vec x,Vec y)
5609: {
5611: PetscInt M,N;
5618: MatPreallocated(A);
5620: MatGetSize(A,&M,&N);
5621: if (N > M) {
5622: MatMult(A,x,y);
5623: } else {
5624: MatMultTranspose(A,x,y);
5625: }
5626: return(0);
5627: }
5631: /*@C
5632: MatNullSpaceAttach - attaches a null space to a matrix.
5633: This null space will be removed from the resulting vector whenever
5634: MatMult() is called
5636: Collective on Mat
5638: Input Parameters:
5639: + mat - the matrix
5640: - nullsp - the null space object
5642: Level: developer
5644: Notes:
5645: Overwrites any previous null space that may have been attached
5647: Concepts: null space^attaching to matrix
5649: .seealso: MatCreate(), MatNullSpaceCreate()
5650: @*/
5651: PetscErrorCode MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
5652: {
5659: MatPreallocated(mat);
5661: if (mat->nullsp) {
5662: MatNullSpaceDestroy(mat->nullsp);
5663: }
5664: mat->nullsp = nullsp;
5665: PetscObjectReference((PetscObject)nullsp);
5666: return(0);
5667: }
5671: /*@
5672: MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.
5674: Collective on Mat
5676: Input Parameters:
5677: + mat - the matrix
5678: . row - row/column permutation
5679: . fill - expected fill factor >= 1.0
5680: - level - level of fill, for ICC(k)
5682: Notes:
5683: Probably really in-place only when level of fill is zero, otherwise allocates
5684: new space to store factored matrix and deletes previous memory.
5686: Most users should employ the simplified KSP interface for linear solvers
5687: instead of working directly with matrix algebra routines such as this.
5688: See, e.g., KSPCreate().
5690: Level: developer
5692: Concepts: matrices^incomplete Cholesky factorization
5693: Concepts: Cholesky factorization
5695: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
5696: @*/
5697: PetscErrorCode MatICCFactor(Mat mat,IS row,MatFactorInfo* info)
5698: {
5706: if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
5707: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
5708: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
5709: if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5710: MatPreallocated(mat);
5711: (*mat->ops->iccfactor)(mat,row,info);
5712: PetscObjectStateIncrease((PetscObject)mat);
5713: return(0);
5714: }
5718: /*@
5719: MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix.
5721: Not Collective
5723: Input Parameters:
5724: + mat - the matrix
5725: - v - the values compute with ADIC
5727: Level: developer
5729: Notes:
5730: Must call MatSetColoring() before using this routine. Also this matrix must already
5731: have its nonzero pattern determined.
5733: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5734: MatSetValues(), MatSetColoring(), MatSetValuesAdifor()
5735: @*/
5736: PetscErrorCode MatSetValuesAdic(Mat mat,void *v)
5737: {
5745: if (!mat->assembled) {
5746: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5747: }
5749: if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5750: (*mat->ops->setvaluesadic)(mat,v);
5752: MatView_Private(mat);
5753: PetscObjectStateIncrease((PetscObject)mat);
5754: return(0);
5755: }
5760: /*@
5761: MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic()
5763: Not Collective
5765: Input Parameters:
5766: + mat - the matrix
5767: - coloring - the coloring
5769: Level: developer
5771: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5772: MatSetValues(), MatSetValuesAdic()
5773: @*/
5774: PetscErrorCode MatSetColoring(Mat mat,ISColoring coloring)
5775: {
5783: if (!mat->assembled) {
5784: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5785: }
5786: if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5787: (*mat->ops->setcoloring)(mat,coloring);
5788: return(0);
5789: }
5793: /*@
5794: MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix.
5796: Not Collective
5798: Input Parameters:
5799: + mat - the matrix
5800: . nl - leading dimension of v
5801: - v - the values compute with ADIFOR
5803: Level: developer
5805: Notes:
5806: Must call MatSetColoring() before using this routine. Also this matrix must already
5807: have its nonzero pattern determined.
5809: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(),
5810: MatSetValues(), MatSetColoring()
5811: @*/
5812: PetscErrorCode MatSetValuesAdifor(Mat mat,PetscInt nl,void *v)
5813: {
5821: if (!mat->assembled) {
5822: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5823: }
5825: if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5826: (*mat->ops->setvaluesadifor)(mat,nl,v);
5828: PetscObjectStateIncrease((PetscObject)mat);
5829: return(0);
5830: }
5834: /*@
5835: MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the
5836: ghosted ones.
5838: Not Collective
5840: Input Parameters:
5841: + mat - the matrix
5842: - diag = the diagonal values, including ghost ones
5844: Level: developer
5846: Notes: Works only for MPIAIJ and MPIBAIJ matrices
5847:
5848: .seealso: MatDiagonalScale()
5849: @*/
5850: PetscErrorCode MatDiagonalScaleLocal(Mat mat,Vec diag)
5851: {
5853: PetscMPIInt size;
5860: if (!mat->assembled) {
5861: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled");
5862: }
5864: MPI_Comm_size(mat->comm,&size);
5865: if (size == 1) {
5866: PetscInt n,m;
5867: VecGetSize(diag,&n);
5868: MatGetSize(mat,0,&m);
5869: if (m == n) {
5870: MatDiagonalScale(mat,0,diag);
5871: } else {
5872: SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions");
5873: }
5874: } else {
5875: PetscErrorCode (*f)(Mat,Vec);
5876: PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);
5877: if (f) {
5878: (*f)(mat,diag);
5879: } else {
5880: SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices");
5881: }
5882: }
5884: PetscObjectStateIncrease((PetscObject)mat);
5885: return(0);
5886: }
5890: /*@
5891: MatGetInertia - Gets the inertia from a factored matrix
5893: Collective on Mat
5895: Input Parameter:
5896: . mat - the matrix
5898: Output Parameters:
5899: + nneg - number of negative eigenvalues
5900: . nzero - number of zero eigenvalues
5901: - npos - number of positive eigenvalues
5903: Level: advanced
5905: Notes: Matrix must have been factored by MatCholeskyFactor()
5908: @*/
5909: PetscErrorCode MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos)
5910: {
5916: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5917: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled");
5918: if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5919: (*mat->ops->getinertia)(mat,nneg,nzero,npos);
5920: return(0);
5921: }
5923: /* ----------------------------------------------------------------*/
5926: /*@
5927: MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors
5929: Collective on Mat and Vecs
5931: Input Parameters:
5932: + mat - the factored matrix
5933: - b - the right-hand-side vectors
5935: Output Parameter:
5936: . x - the result vectors
5938: Notes:
5939: The vectors b and x cannot be the same. I.e., one cannot
5940: call MatSolves(A,x,x).
5942: Notes:
5943: Most users should employ the simplified KSP interface for linear solvers
5944: instead of working directly with matrix algebra routines such as this.
5945: See, e.g., KSPCreate().
5947: Level: developer
5949: Concepts: matrices^triangular solves
5951: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve()
5952: @*/
5953: PetscErrorCode MatSolves(Mat mat,Vecs b,Vecs x)
5954: {
5960: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
5961: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
5962: if (!mat->rmap.N && !mat->cmap.N) return(0);
5964: if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
5965: MatPreallocated(mat);
5967: (*mat->ops->solves)(mat,b,x);
5969: return(0);
5970: }
5974: /*@
5975: MatIsSymmetric - Test whether a matrix is symmetric
5977: Collective on Mat
5979: Input Parameter:
5980: + A - the matrix to test
5981: - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose)
5983: Output Parameters:
5984: . flg - the result
5986: Level: intermediate
5988: Concepts: matrix^symmetry
5990: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown()
5991: @*/
5992: PetscErrorCode MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg)
5993: {
5999: if (!A->symmetric_set) {
6000: if (!A->ops->issymmetric) {
6001: MatType mattype;
6002: MatGetType(A,&mattype);
6003: SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype);
6004: }
6005: (*A->ops->issymmetric)(A,tol,&A->symmetric);
6006: A->symmetric_set = PETSC_TRUE;
6007: if (A->symmetric) {
6008: A->structurally_symmetric_set = PETSC_TRUE;
6009: A->structurally_symmetric = PETSC_TRUE;
6010: }
6011: }
6012: *flg = A->symmetric;
6013: return(0);
6014: }
6018: /*@
6019: MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric.
6021: Collective on Mat
6023: Input Parameter:
6024: . A - the matrix to check
6026: Output Parameters:
6027: + set - if the symmetric flag is set (this tells you if the next flag is valid)
6028: - flg - the result
6030: Level: advanced
6032: Concepts: matrix^symmetry
6034: Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric()
6035: if you want it explicitly checked
6037: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6038: @*/
6039: PetscErrorCode MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6040: {
6045: if (A->symmetric_set) {
6046: *set = PETSC_TRUE;
6047: *flg = A->symmetric;
6048: } else {
6049: *set = PETSC_FALSE;
6050: }
6051: return(0);
6052: }
6056: /*@
6057: MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian.
6059: Collective on Mat
6061: Input Parameter:
6062: . A - the matrix to check
6064: Output Parameters:
6065: + set - if the hermitian flag is set (this tells you if the next flag is valid)
6066: - flg - the result
6068: Level: advanced
6070: Concepts: matrix^symmetry
6072: Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian()
6073: if you want it explicitly checked
6075: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric()
6076: @*/
6077: PetscErrorCode MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg)
6078: {
6083: if (A->hermitian_set) {
6084: *set = PETSC_TRUE;
6085: *flg = A->hermitian;
6086: } else {
6087: *set = PETSC_FALSE;
6088: }
6089: return(0);
6090: }
6094: /*@
6095: MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric
6097: Collective on Mat
6099: Input Parameter:
6100: . A - the matrix to test
6102: Output Parameters:
6103: . flg - the result
6105: Level: intermediate
6107: Concepts: matrix^symmetry
6109: .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption()
6110: @*/
6111: PetscErrorCode MatIsStructurallySymmetric(Mat A,PetscTruth *flg)
6112: {
6118: if (!A->structurally_symmetric_set) {
6119: if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric");
6120: (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);
6121: A->structurally_symmetric_set = PETSC_TRUE;
6122: }
6123: *flg = A->structurally_symmetric;
6124: return(0);
6125: }
6129: /*@
6130: MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose.
6132: Collective on Mat
6134: Input Parameter:
6135: . A - the matrix to test
6137: Output Parameters:
6138: . flg - the result
6140: Level: intermediate
6142: Concepts: matrix^symmetry
6144: .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption()
6145: @*/
6146: PetscErrorCode MatIsHermitian(Mat A,PetscTruth *flg)
6147: {
6153: if (!A->hermitian_set) {
6154: if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian");
6155: (*A->ops->ishermitian)(A,&A->hermitian);
6156: A->hermitian_set = PETSC_TRUE;
6157: if (A->hermitian) {
6158: A->structurally_symmetric_set = PETSC_TRUE;
6159: A->structurally_symmetric = PETSC_TRUE;
6160: }
6161: }
6162: *flg = A->hermitian;
6163: return(0);
6164: }
6169: /*@
6170: MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
6171: to be communicated to other processors during the MatAssemblyBegin/End() process
6173: Not collective
6175: Input Parameter:
6176: . vec - the vector
6178: Output Parameters:
6179: + nstash - the size of the stash
6180: . reallocs - the number of additional mallocs incurred.
6181: . bnstash - the size of the block stash
6182: - breallocs - the number of additional mallocs incurred.in the block stash
6183:
6184: Level: advanced
6186: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize()
6187:
6188: @*/
6189: PetscErrorCode MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
6190: {
6193: MatStashGetInfo_Private(&mat->stash,nstash,reallocs);
6194: MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);
6195: return(0);
6196: }
6200: /*@
6201: MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same
6202: parallel layout
6203:
6204: Collective on Mat
6206: Input Parameter:
6207: . mat - the matrix
6209: Output Parameter:
6210: + right - (optional) vector that the matrix can be multiplied against
6211: - left - (optional) vector that the matrix vector product can be stored in
6213: Level: advanced
6215: .seealso: MatCreate()
6216: @*/
6217: PetscErrorCode MatGetVecs(Mat mat,Vec *right,Vec *left)
6218: {
6224: MatPreallocated(mat);
6225: if (mat->ops->getvecs) {
6226: (*mat->ops->getvecs)(mat,right,left);
6227: } else {
6228: PetscMPIInt size;
6229: MPI_Comm_size(mat->comm, &size);
6230: if (right) {
6231: VecCreate(mat->comm,right);
6232: VecSetSizes(*right,mat->cmap.n,PETSC_DETERMINE);
6233: if (size > 1) {VecSetType(*right,VECMPI);}
6234: else {VecSetType(*right,VECSEQ);}
6235: }
6236: if (left) {
6237: VecCreate(mat->comm,left);
6238: VecSetSizes(*left,mat->rmap.n,PETSC_DETERMINE);
6239: if (size > 1) {VecSetType(*left,VECMPI);}
6240: else {VecSetType(*left,VECSEQ);}
6241: }
6242: }
6243: if (right) {VecSetBlockSize(*right,mat->rmap.bs);}
6244: if (left) {VecSetBlockSize(*left,mat->rmap.bs);}
6245: return(0);
6246: }
6250: /*@
6251: MatFactorInfoInitialize - Initializes a MatFactorInfo data structure
6252: with default values.
6254: Not Collective
6256: Input Parameters:
6257: . info - the MatFactorInfo data structure
6260: Notes: The solvers are generally used through the KSP and PC objects, for example
6261: PCLU, PCILU, PCCHOLESKY, PCICC
6263: Level: developer
6265: .seealso: MatFactorInfo
6266: @*/
6268: PetscErrorCode MatFactorInfoInitialize(MatFactorInfo *info)
6269: {
6273: PetscMemzero(info,sizeof(MatFactorInfo));
6274: return(0);
6275: }
6279: /*@
6280: MatPtAP - Creates the matrix projection C = P^T * A * P
6282: Collective on Mat
6284: Input Parameters:
6285: + A - the matrix
6286: . P - the projection matrix
6287: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6288: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P))
6290: Output Parameters:
6291: . C - the product matrix
6293: Notes:
6294: C will be created and must be destroyed by the user with MatDestroy().
6296: This routine is currently only implemented for pairs of AIJ matrices and classes
6297: which inherit from AIJ.
6299: Level: intermediate
6301: .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult()
6302: @*/
6303: PetscErrorCode MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C)
6304: {
6310: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6311: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6314: MatPreallocated(P);
6315: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6316: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6318: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6319: if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6320: MatPreallocated(A);
6323: (*A->ops->ptap)(A,P,scall,fill,C);
6326: return(0);
6327: }
6331: /*@
6332: MatPtAPNumeric - Computes the matrix projection C = P^T * A * P
6334: Collective on Mat
6336: Input Parameters:
6337: + A - the matrix
6338: - P - the projection matrix
6340: Output Parameters:
6341: . C - the product matrix
6343: Notes:
6344: C must have been created by calling MatPtAPSymbolic and must be destroyed by
6345: the user using MatDeatroy().
6347: This routine is currently only implemented for pairs of AIJ matrices and classes
6348: which inherit from AIJ. C will be of type MATAIJ.
6350: Level: intermediate
6352: .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric()
6353: @*/
6354: PetscErrorCode MatPtAPNumeric(Mat A,Mat P,Mat C)
6355: {
6361: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6362: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6365: MatPreallocated(P);
6366: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6367: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6370: MatPreallocated(C);
6371: if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6372: if (P->cmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->rmap.N);
6373: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6374: if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6375: if (P->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->cmap.N);
6376: MatPreallocated(A);
6379: (*A->ops->ptapnumeric)(A,P,C);
6381: return(0);
6382: }
6386: /*@
6387: MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P
6389: Collective on Mat
6391: Input Parameters:
6392: + A - the matrix
6393: - P - the projection matrix
6395: Output Parameters:
6396: . C - the (i,j) structure of the product matrix
6398: Notes:
6399: C will be created and must be destroyed by the user with MatDestroy().
6401: This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6402: which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using
6403: this (i,j) structure by calling MatPtAPNumeric().
6405: Level: intermediate
6407: .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic()
6408: @*/
6409: PetscErrorCode MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C)
6410: {
6416: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6417: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6418: if (fill <1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6421: MatPreallocated(P);
6422: if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6423: if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6426: if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N);
6427: if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N);
6428: MatPreallocated(A);
6430: (*A->ops->ptapsymbolic)(A,P,fill,C);
6433: MatSetBlockSize(*C,A->rmap.bs);
6435: return(0);
6436: }
6440: /*@
6441: MatMatMult - Performs Matrix-Matrix Multiplication C=A*B.
6443: Collective on Mat
6445: Input Parameters:
6446: + A - the left matrix
6447: . B - the right matrix
6448: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6449: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6451: Output Parameters:
6452: . C - the product matrix
6454: Notes:
6455: C will be created and must be destroyed by the user with MatDestroy().
6456: Unless scall is MAT_REUSE_MATRIX
6458: If you have many matrices with the same non-zero structure to multiply, you
6459: should either
6460: $ 1) use MAT_REUSE_MATRIX in all calls but the first or
6461: $ 2) call MatMatMultSymbolic() once and then MatMatMultNumeric() for each product needed
6463: Level: intermediate
6465: .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP()
6466: @*/
6467: PetscErrorCode MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6468: {
6470: PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6471: PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);
6472: PetscErrorCode (*mult)(Mat,Mat,MatReuse,PetscReal,Mat *)=PETSC_NULL;
6477: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6478: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6481: MatPreallocated(B);
6482: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6483: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6485: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6486: if (fill == PETSC_DEFAULT) fill = 2.0;
6487: if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill);
6488: MatPreallocated(A);
6490: fA = A->ops->matmult;
6491: fB = B->ops->matmult;
6492: if (fB == fA) {
6493: if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name);
6494: mult = fB;
6495: } else {
6496: /* dispatch based on the type of A and B */
6497: char multname[256];
6498: PetscStrcpy(multname,"MatMatMult_");
6499: PetscStrcat(multname,A->type_name);
6500: PetscStrcat(multname,"_");
6501: PetscStrcat(multname,B->type_name);
6502: PetscStrcat(multname,"_C"); /* e.g., multname = "MatMatMult_aij_dense_C" */
6503: PetscObjectQueryFunction((PetscObject)B,multname,(void (**)(void))&mult);
6504: if (!mult) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6505: }
6507: (*mult)(A,B,scall,fill,C);
6509: return(0);
6510: }
6514: /*@
6515: MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure
6516: of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric().
6518: Collective on Mat
6520: Input Parameters:
6521: + A - the left matrix
6522: . B - the right matrix
6523: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6525: Output Parameters:
6526: . C - the matrix containing the ij structure of product matrix
6528: Notes:
6529: C will be created and must be destroyed by the user with MatDestroy().
6531: This routine is currently implemented for
6532: - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ.
6533: - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE.
6535: Level: intermediate
6537: .seealso: MatMatMult(), MatMatMultNumeric()
6538: @*/
6539: PetscErrorCode MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C)
6540: {
6542: PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *);
6543: PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *);
6544: PetscErrorCode (*symbolic)(Mat,Mat,PetscReal,Mat *)=PETSC_NULL;
6549: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6550: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6554: MatPreallocated(B);
6555: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6556: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6559: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6560: if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill);
6561: MatPreallocated(A);
6562:
6563: Asymbolic = A->ops->matmultsymbolic;
6564: Bsymbolic = B->ops->matmultsymbolic;
6565: if (Asymbolic == Bsymbolic){
6566: if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name);
6567: symbolic = Bsymbolic;
6568: } else { /* dispatch based on the type of A and B */
6569: char symbolicname[256];
6570: PetscStrcpy(symbolicname,"MatMatMultSymbolic_");
6571: PetscStrcat(symbolicname,A->type_name);
6572: PetscStrcat(symbolicname,"_");
6573: PetscStrcat(symbolicname,B->type_name);
6574: PetscStrcat(symbolicname,"_C");
6575: PetscObjectQueryFunction((PetscObject)B,symbolicname,(void (**)(void))&symbolic);
6576: if (!symbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6577: }
6579: (*symbolic)(A,B,fill,C);
6581: return(0);
6582: }
6586: /*@
6587: MatMatMultNumeric - Performs the numeric matrix-matrix product.
6588: Call this routine after first calling MatMatMultSymbolic().
6590: Collective on Mat
6592: Input Parameters:
6593: + A - the left matrix
6594: - B - the right matrix
6596: Output Parameters:
6597: . C - the product matrix, whose ij structure was defined from MatMatMultSymbolic().
6599: Notes:
6600: C must have been created with MatMatMultSymbolic.
6602: This routine is currently implemented for
6603: - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ.
6604: - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE.
6606: Level: intermediate
6608: .seealso: MatMatMult(), MatMatMultSymbolic()
6609: @*/
6610: PetscErrorCode MatMatMultNumeric(Mat A,Mat B,Mat C)
6611: {
6613: PetscErrorCode (*Anumeric)(Mat,Mat,Mat);
6614: PetscErrorCode (*Bnumeric)(Mat,Mat,Mat);
6615: PetscErrorCode (*numeric)(Mat,Mat,Mat)=PETSC_NULL;
6620: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6621: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6625: MatPreallocated(B);
6626: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6627: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6631: MatPreallocated(C);
6632: if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6633: if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6635: if (B->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap.N,C->cmap.N);
6636: if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N);
6637: if (A->rmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap.N,C->rmap.N);
6638: MatPreallocated(A);
6640: Anumeric = A->ops->matmultnumeric;
6641: Bnumeric = B->ops->matmultnumeric;
6642: if (Anumeric == Bnumeric){
6643: if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name);
6644: numeric = Bnumeric;
6645: } else {
6646: char numericname[256];
6647: PetscStrcpy(numericname,"MatMatMultNumeric_");
6648: PetscStrcat(numericname,A->type_name);
6649: PetscStrcat(numericname,"_");
6650: PetscStrcat(numericname,B->type_name);
6651: PetscStrcat(numericname,"_C");
6652: PetscObjectQueryFunction((PetscObject)B,numericname,(void (**)(void))&numeric);
6653: if (!numeric)
6654: SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6655: }
6657: (*numeric)(A,B,C);
6659: return(0);
6660: }
6664: /*@
6665: MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B.
6667: Collective on Mat
6669: Input Parameters:
6670: + A - the left matrix
6671: . B - the right matrix
6672: . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
6673: - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B))
6675: Output Parameters:
6676: . C - the product matrix
6678: Notes:
6679: C will be created and must be destroyed by the user with MatDestroy().
6681: This routine is currently only implemented for pairs of SeqAIJ matrices and classes
6682: which inherit from SeqAIJ. C will be of type MATSEQAIJ.
6684: Level: intermediate
6686: .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP()
6687: @*/
6688: PetscErrorCode MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C)
6689: {
6691: PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*);
6692: PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*);
6697: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6698: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6701: MatPreallocated(B);
6702: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
6703: if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
6705: if (B->rmap.N!=A->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->rmap.N);
6706: if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill);
6707: MatPreallocated(A);
6709: fA = A->ops->matmulttranspose;
6710: if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name);
6711: fB = B->ops->matmulttranspose;
6712: if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name);
6713: if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name);
6716: (*A->ops->matmulttranspose)(A,B,scall,fill,C);
6718:
6719: return(0);
6720: }