Actual source code: matrix.c
1: /*$Id: matrix.c,v 1.402 2001/04/10 22:35:02 balay Exp $*/
3: /*
4: This is where the abstract matrix operations are defined
5: */
7: #include "src/mat/matimpl.h" /*I "petscmat.h" I*/
8: #include "src/vec/vecimpl.h"
10: /*@C
11: MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow()
12: for each row that you get to ensure that your application does
13: not bleed memory.
15: Not Collective
17: Input Parameters:
18: + mat - the matrix
19: - row - the row to get
21: Output Parameters:
22: + ncols - the number of nonzeros in the row
23: . cols - if not NULL, the column numbers
24: - vals - if not NULL, the values
26: Notes:
27: This routine is provided for people who need to have direct access
28: to the structure of a matrix. We hope that we provide enough
29: high-level matrix routines that few users will need it.
31: MatGetRow() always returns 0-based column indices, regardless of
32: whether the internal representation is 0-based (default) or 1-based.
34: For better efficiency, set cols and/or vals to PETSC_NULL if you do
35: not wish to extract these quantities.
37: The user can only examine the values extracted with MatGetRow();
38: the values cannot be altered. To change the matrix entries, one
39: must use MatSetValues().
41: You can only have one call to MatGetRow() outstanding for a particular
42: matrix at a time, per processor. MatGetRow() can only obtained rows
43: associated with the given processor, it cannot get rows from the
44: other processors; for that we suggest using MatGetSubMatrices(), then
45: MatGetRow() on the submatrix. The row indix passed to MatGetRows()
46: is in the global number of rows.
48: Fortran Notes:
49: The calling sequence from Fortran is
50: .vb
51: MatGetRow(matrix,row,ncols,cols,values,ierr)
52: Mat matrix (input)
53: integer row (input)
54: integer ncols (output)
55: integer cols(maxcols) (output)
56: double precision (or double complex) values(maxcols) output
57: .ve
58: where maxcols >= maximum nonzeros in any row of the matrix.
60: Caution:
61: Do not try to change the contents of the output arrays (cols and vals).
62: In some cases, this may corrupt the matrix.
64: Level: advanced
66: Concepts: matrices^row access
68: .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal()
69: @*/
70: int MatGetRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals)
71: {
72: int ierr;
78: MatPreallocated(mat);
79: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
80: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
81: if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
82: PetscLogEventBegin(MAT_GetRow,mat,0,0,0);
83: (*mat->ops->getrow)(mat,row,ncols,cols,vals);
84: PetscLogEventEnd(MAT_GetRow,mat,0,0,0);
85: return(0);
86: }
88: /*@C
89: MatRestoreRow - Frees any temporary space allocated by MatGetRow().
91: Not Collective
93: Input Parameters:
94: + mat - the matrix
95: . row - the row to get
96: . ncols, cols - the number of nonzeros and their columns
97: - vals - if nonzero the column values
99: Notes:
100: This routine should be called after you have finished examining the entries.
102: Fortran Notes:
103: The calling sequence from Fortran is
104: .vb
105: MatRestoreRow(matrix,row,ncols,cols,values,ierr)
106: Mat matrix (input)
107: integer row (input)
108: integer ncols (output)
109: integer cols(maxcols) (output)
110: double precision (or double complex) values(maxcols) output
111: .ve
112: Where maxcols >= maximum nonzeros in any row of the matrix.
114: In Fortran MatRestoreRow() MUST be called after MatGetRow()
115: before another call to MatGetRow() can be made.
117: Level: advanced
119: .seealso: MatGetRow()
120: @*/
121: int MatRestoreRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals)
122: {
128: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
129: if (!mat->ops->restorerow) return(0);
130: (*mat->ops->restorerow)(mat,row,ncols,cols,vals);
131: return(0);
132: }
134: /*@C
135: MatView - Visualizes a matrix object.
137: Collective on Mat
139: Input Parameters:
140: + mat - the matrix
141: - ptr - visualization context
143: Notes:
144: The available visualization contexts include
145: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
146: . PETSC_VIEWER_STDOUT_WORLD - synchronized standard
147: output where only the first processor opens
148: the file. All other processors send their
149: data to the first processor to print.
150: - PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure
152: The user can open alternative visualization contexts with
153: + PetscViewerASCIIOpen() - Outputs matrix to a specified file
154: . PetscViewerBinaryOpen() - Outputs matrix in binary to a
155: specified file; corresponding input uses MatLoad()
156: . PetscViewerDrawOpen() - Outputs nonzero matrix structure to
157: an X window display
158: - PetscViewerSocketOpen() - Outputs matrix to Socket viewer.
159: Currently only the sequential dense and AIJ
160: matrix types support the Socket viewer.
162: The user can call PetscViewerSetFormat() to specify the output
163: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
164: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
165: + PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents
166: . PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format
167: . PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros
168: . PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse
169: format common among all matrix types
170: . PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific
171: format (which is in many cases the same as the default)
172: . PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix
173: size and structure (not the matrix entries)
174: - PETSC_VIEWER_ASCII_INFO_LONG - prints more detailed information about
175: the matrix structure
177: Level: beginner
179: Concepts: matrices^viewing
180: Concepts: matrices^plotting
181: Concepts: matrices^printing
183: .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(),
184: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad()
185: @*/
186: int MatView(Mat mat,PetscViewer viewer)
187: {
188: int ierr,rows,cols;
189: PetscTruth isascii;
190: char *cstr;
191: PetscViewerFormat format;
196: MatPreallocated(mat);
197: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm);
200: if (!mat->assembled) SETERRQ(1,"Must call MatAssemblyBegin/End() before viewing matrix");
202: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);
203: if (isascii) {
204: PetscViewerGetFormat(viewer,&format);
205: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_LONG) {
206: PetscViewerASCIIPrintf(viewer,"Matrix Object:n");
207: PetscViewerASCIIPushTab(viewer);
208: MatGetType(mat,&cstr);
209: MatGetSize(mat,&rows,&cols);
210: PetscViewerASCIIPrintf(viewer,"type=%s, rows=%d, cols=%dn",cstr,rows,cols);
211: if (mat->ops->getinfo) {
212: MatInfo info;
213: MatGetInfo(mat,MAT_GLOBAL_SUM,&info);
214: PetscViewerASCIIPrintf(viewer,"total: nonzeros=%d, allocated nonzeros=%dn",
215: (int)info.nz_used,(int)info.nz_allocated);
216: }
217: }
218: }
219: if (mat->ops->view) {
220: PetscViewerASCIIPushTab(viewer);
221: (*mat->ops->view)(mat,viewer);
222: PetscViewerASCIIPopTab(viewer);
223: } else if (!isascii) {
224: SETERRQ1(1,"Viewer type %s not supported",((PetscObject)viewer)->type_name);
225: }
226: if (isascii) {
227: PetscViewerGetFormat(viewer,&format);
228: if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_LONG) {
229: PetscViewerASCIIPopTab(viewer);
230: }
231: }
232: return(0);
233: }
235: /*@C
236: MatScaleSystem - Scale a vector solution and right hand side to
237: match the scaling of a scaled matrix.
238:
239: Collective on Mat
241: Input Parameter:
242: + mat - the matrix
243: . x - solution vector (or PETSC_NULL)
244: + b - right hand side vector (or PETSC_NULL)
247: Notes:
248: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
249: internally scaled, so this does nothing. For MPIROWBS it
250: permutes and diagonally scales.
252: The SLES methods automatically call this routine when required
253: (via PCPreSolve()) so it is rarely used directly.
255: Level: Developer
257: Concepts: matrices^scaling
259: .seealso: MatUseScaledForm(), MatUnScaleSystem()
260: @*/
261: int MatScaleSystem(Mat mat,Vec x,Vec b)
262: {
268: MatPreallocated(mat);
272: if (mat->ops->scalesystem) {
273: (*mat->ops->scalesystem)(mat,x,b);
274: }
275: return(0);
276: }
278: /*@C
279: MatUnScaleSystem - Unscales a vector solution and right hand side to
280: match the original scaling of a scaled matrix.
281:
282: Collective on Mat
284: Input Parameter:
285: + mat - the matrix
286: . x - solution vector (or PETSC_NULL)
287: + b - right hand side vector (or PETSC_NULL)
290: Notes:
291: For AIJ, BAIJ, and BDiag matrix formats, the matrices are not
292: internally scaled, so this does nothing. For MPIROWBS it
293: permutes and diagonally scales.
295: The SLES methods automatically call this routine when required
296: (via PCPreSolve()) so it is rarely used directly.
298: Level: Developer
300: .seealso: MatUseScaledForm(), MatScaleSystem()
301: @*/
302: int MatUnScaleSystem(Mat mat,Vec x,Vec b)
303: {
309: MatPreallocated(mat);
312: if (mat->ops->unscalesystem) {
313: (*mat->ops->unscalesystem)(mat,x,b);
314: }
315: return(0);
316: }
318: /*@C
319: MatUseScaledForm - For matrix storage formats that scale the
320: matrix (for example MPIRowBS matrices are diagonally scaled on
321: assembly) indicates matrix operations (MatMult() etc) are
322: applied using the scaled matrix.
323:
324: Collective on Mat
326: Input Parameter:
327: + mat - the matrix
328: - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for
329: applying the original matrix
331: Notes:
332: For scaled matrix formats, applying the original, unscaled matrix
333: will be slightly more expensive
335: Level: Developer
337: .seealso: MatScaleSystem(), MatUnScaleSystem()
338: @*/
339: int MatUseScaledForm(Mat mat,PetscTruth scaled)
340: {
346: MatPreallocated(mat);
347: if (mat->ops->usescaledform) {
348: (*mat->ops->usescaledform)(mat,scaled);
349: }
350: return(0);
351: }
353: /*@C
354: MatDestroy - Frees space taken by a matrix.
355:
356: Collective on Mat
358: Input Parameter:
359: . A - the matrix
361: Level: beginner
363: @*/
364: int MatDestroy(Mat A)
365: {
371: MatPreallocated(A);
372: if (--A->refct > 0) return(0);
374: /* if memory was published with AMS then destroy it */
375: PetscObjectDepublish(A);
376: if (A->mapping) {
377: ISLocalToGlobalMappingDestroy(A->mapping);
378: }
379: if (A->bmapping) {
380: ISLocalToGlobalMappingDestroy(A->bmapping);
381: }
382: if (A->rmap) {
383: MapDestroy(A->rmap);
384: }
385: if (A->cmap) {
386: MapDestroy(A->cmap);
387: }
389: (*A->ops->destroy)(A);
390: PetscLogObjectDestroy(A);
391: PetscHeaderDestroy(A);
392: return(0);
393: }
395: /*@
396: MatValid - Checks whether a matrix object is valid.
398: Collective on Mat
400: Input Parameter:
401: . m - the matrix to check
403: Output Parameter:
404: flg - flag indicating matrix status, either
405: PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise.
407: Level: developer
409: Concepts: matrices^validity
410: @*/
411: int MatValid(Mat m,PetscTruth *flg)
412: {
415: if (!m) *flg = PETSC_FALSE;
416: else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE;
417: else *flg = PETSC_TRUE;
418: return(0);
419: }
421: /*@
422: MatSetValues - Inserts or adds a block of values into a matrix.
423: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
424: MUST be called after all calls to MatSetValues() have been completed.
426: Not Collective
428: Input Parameters:
429: + mat - the matrix
430: . v - a logically two-dimensional array of values
431: . m, idxm - the number of rows and their global indices
432: . n, idxn - the number of columns and their global indices
433: - addv - either ADD_VALUES or INSERT_VALUES, where
434: ADD_VALUES adds values to any existing entries, and
435: INSERT_VALUES replaces existing entries with new values
437: Notes:
438: By default the values, v, are row-oriented and unsorted.
439: See MatSetOption() for other options.
441: Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES
442: options cannot be mixed without intervening calls to the assembly
443: routines.
445: MatSetValues() uses 0-based row and column numbers in Fortran
446: as well as in C.
448: Negative indices may be passed in idxm and idxn, these rows and columns are
449: simply ignored. This allows easily inserting element stiffness matrices
450: with homogeneous Dirchlet boundary conditions that you don't want represented
451: in the matrix.
453: Efficiency Alert:
454: The routine MatSetValuesBlocked() may offer much better efficiency
455: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
457: Level: beginner
459: Concepts: matrices^putting entries in
461: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
462: @*/
463: int MatSetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv)
464: {
468: if (!m || !n) return(0); /* no values to insert */
471: MatPreallocated(mat);
475: if (mat->insertmode == NOT_SET_VALUES) {
476: mat->insertmode = addv;
477: }
478: #if defined(PETSC_USE_BOPT_g)
479: else if (mat->insertmode != addv) {
480: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
481: }
482: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
483: #endif
485: if (mat->assembled) {
486: mat->was_assembled = PETSC_TRUE;
487: mat->assembled = PETSC_FALSE;
488: }
489: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
490: if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
491: (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);
492: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
493: return(0);
494: }
496: /*@C
497: MatSetValuesStencil - Inserts or adds a block of values into a matrix.
498: Using structured grid indexing
500: Not Collective
502: Input Parameters:
503: + mat - the matrix
504: . v - a logically two-dimensional array of values
505: . m - number of rows being entered
506: . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered
507: . n - number of columns being entered
508: . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered
509: - addv - either ADD_VALUES or INSERT_VALUES, where
510: ADD_VALUES adds values to any existing entries, and
511: INSERT_VALUES replaces existing entries with new values
513: Notes:
514: By default the values, v, are row-oriented and unsorted.
515: See MatSetOption() for other options.
517: Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES
518: options cannot be mixed without intervening calls to the assembly
519: routines.
521: MatSetValuesStencil() uses 0-based row and column numbers in Fortran
522: as well as in C.
524: In Fortran idxm and idxn should be declared as
525: $ MatStencil idxm(4,m),idxn(4,n)
526: and the values inserted using
527: $ idxm(MatStencil_i,1) = i
528: $ idxm(MatStencil_j,1) = j
529: $ idxm(MatStencil_k,1) = k
530: etc
532: Negative indices may be passed in idxm and idxn, these rows and columns are
533: simply ignored. This allows easily inserting element stiffness matrices
534: with homogeneous Dirchlet boundary conditions that you don't want represented
535: in the matrix.
537: Inspired by the structured grid interface to the HYPRE package
538: (www.llnl.gov/CASC/hyper)
540: Efficiency Alert:
541: The routine MatSetValuesBlockedStencil() may offer much better efficiency
542: for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ).
544: Level: beginner
546: Concepts: matrices^putting entries in
548: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
549: MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil()
550: @*/
551: int MatSetValuesStencil(Mat mat,int m,MatStencil *idxm,int n,MatStencil *idxn,Scalar *v,InsertMode addv)
552: {
553: int j,i,ierr,jdxm[128],jdxn[128],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp;
554: int *starts = mat->stencil.starts,*dxm = (int*)idxm,*dxn = (int*)idxn,sdim = dim - (1 - (int)mat->stencil.noc);
557: if (!m || !n) return(0); /* no values to insert */
564: for (i=0; i<m; i++) {
565: for (j=0; j<3-sdim; j++) dxm++;
566: tmp = *dxm++ - starts[0];
567: for (j=0; j<dim-1; j++) {
568: tmp = tmp*dims[j] + *dxm++ - starts[j+1];
569: }
570: if (mat->stencil.noc) dxm++;
571: jdxm[i] = tmp;
572: }
573: for (i=0; i<n; i++) {
574: for (j=0; j<3-sdim; j++) dxn++;
575: tmp = *dxn++ - starts[0];
576: for (j=0; j<dim-1; j++) {
577: tmp = tmp*dims[j] + *dxn++ - starts[j+1];
578: }
579: if (mat->stencil.noc) dxn++;
580: jdxn[i] = tmp;
581: }
582: MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);
583: return(0);
584: }
586: /*@
587: MatSetStencil - Sets the grid information for setting values into a matrix via
588: MatSetStencil()
590: Not Collective
592: Input Parameters:
593: + mat - the matrix
594: . dim - dimension of the grid 1,2, or 3
595: . dims - number of grid points in x, y, and z direction, including ghost points on your processor
596: . starts - starting point of ghost nodes on your processor in x, y, and z direction
597: - dof - number of degrees of freedom per node
600: Inspired by the structured grid interface to the HYPRE package
601: (www.llnl.gov/CASC/hyper)
603: Level: beginner
605: Concepts: matrices^putting entries in
607: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal()
608: MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil()
609: @*/
610: int MatSetStencil(Mat mat,int dim,int *dims,int *starts,int dof)
611: {
612: int i;
619: mat->stencil.dim = dim + (dof > 1);
620: for (i=0; i<dim; i++) {
621: mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */
622: mat->stencil.starts[i] = starts[dim-i-1];
623: }
624: mat->stencil.dims[dim] = dof;
625: mat->stencil.starts[dim] = 0;
626: mat->stencil.noc = (PetscTruth)(dof == 1);
627: return(0);
628: }
630: /*@
631: MatSetValuesBlocked - Inserts or adds a block of values into a matrix.
633: Not Collective
635: Input Parameters:
636: + mat - the matrix
637: . v - a logically two-dimensional array of values
638: . m, idxm - the number of block rows and their global block indices
639: . n, idxn - the number of block columns and their global block indices
640: - addv - either ADD_VALUES or INSERT_VALUES, where
641: ADD_VALUES adds values to any existing entries, and
642: INSERT_VALUES replaces existing entries with new values
644: Notes:
645: By default the values, v, are row-oriented and unsorted. So the layout of
646: v is the same as for MatSetValues(). See MatSetOption() for other options.
648: Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
649: options cannot be mixed without intervening calls to the assembly
650: routines.
652: MatSetValuesBlocked() uses 0-based row and column numbers in Fortran
653: as well as in C.
655: Negative indices may be passed in idxm and idxn, these rows and columns are
656: simply ignored. This allows easily inserting element stiffness matrices
657: with homogeneous Dirchlet boundary conditions that you don't want represented
658: in the matrix.
660: Each time an entry is set within a sparse matrix via MatSetValues(),
661: internal searching must be done to determine where to place the the
662: data in the matrix storage space. By instead inserting blocks of
663: entries via MatSetValuesBlocked(), the overhead of matrix assembly is
664: reduced.
666: Restrictions:
667: MatSetValuesBlocked() is currently supported only for the block AIJ
668: matrix format (MATSEQBAIJ and MATMPIBAIJ, which are created via
669: MatCreateSeqBAIJ() and MatCreateMPIBAIJ()).
671: Level: intermediate
673: Concepts: matrices^putting entries in blocked
675: .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal()
676: @*/
677: int MatSetValuesBlocked(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv)
678: {
682: if (!m || !n) return(0); /* no values to insert */
685: MatPreallocated(mat);
689: if (mat->insertmode == NOT_SET_VALUES) {
690: mat->insertmode = addv;
691: }
692: #if defined(PETSC_USE_BOPT_g)
693: else if (mat->insertmode != addv) {
694: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
695: }
696: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
697: #endif
699: if (mat->assembled) {
700: mat->was_assembled = PETSC_TRUE;
701: mat->assembled = PETSC_FALSE;
702: }
703: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
704: if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
705: (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);
706: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
707: return(0);
708: }
710: /*MC
711: MatSetValue - Set a single entry into a matrix.
713: Synopsis:
714: void MatSetValue(Mat m,int row,int col,Scalar value,InsertMode mode);
716: Not collective
718: Input Parameters:
719: + m - the matrix
720: . row - the row location of the entry
721: . col - the column location of the entry
722: . value - the value to insert
723: - mode - either INSERT_VALUES or ADD_VALUES
725: Notes:
726: For efficiency one should use MatSetValues() and set several or many
727: values simultaneously if possible.
729: Note that VecSetValue() does NOT return an error code (since this
730: is checked internally).
732: Level: beginner
734: .seealso: MatSetValues()
735: M*/
737: /*@
738: MatGetValues - Gets a block of values from a matrix.
740: Not Collective; currently only returns a local block
742: Input Parameters:
743: + mat - the matrix
744: . v - a logically two-dimensional array for storing the values
745: . m, idxm - the number of rows and their global indices
746: - n, idxn - the number of columns and their global indices
748: Notes:
749: The user must allocate space (m*n Scalars) for the values, v.
750: The values, v, are then returned in a row-oriented format,
751: analogous to that used by default in MatSetValues().
753: MatGetValues() uses 0-based row and column numbers in
754: Fortran as well as in C.
756: MatGetValues() requires that the matrix has been assembled
757: with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to
758: MatSetValues() and MatGetValues() CANNOT be made in succession
759: without intermediate matrix assembly.
761: Level: advanced
763: Concepts: matrices^accessing values
765: .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues()
766: @*/
767: int MatGetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v)
768: {
774: MatPreallocated(mat);
778: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
779: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
780: if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
782: PetscLogEventBegin(MAT_GetValues,mat,0,0,0);
783: (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);
784: PetscLogEventEnd(MAT_GetValues,mat,0,0,0);
785: return(0);
786: }
788: /*@
789: MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by
790: the routine MatSetValuesLocal() to allow users to insert matrix entries
791: using a local (per-processor) numbering.
793: Not Collective
795: Input Parameters:
796: + x - the matrix
797: - mapping - mapping created with ISLocalToGlobalMappingCreate()
798: or ISLocalToGlobalMappingCreateIS()
800: Level: intermediate
802: Concepts: matrices^local to global mapping
803: Concepts: local to global mapping^for matrices
805: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal()
806: @*/
807: int MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping)
808: {
813: MatPreallocated(x);
815: if (x->mapping) {
816: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
817: }
819: if (x->ops->setlocaltoglobalmapping) {
820: (*x->ops->setlocaltoglobalmapping)(x,mapping);
821: } else {
822: x->mapping = mapping;
823: PetscObjectReference((PetscObject)mapping);
824: }
825: return(0);
826: }
828: /*@
829: MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use
830: by the routine MatSetValuesBlockedLocal() to allow users to insert matrix
831: entries using a local (per-processor) numbering.
833: Not Collective
835: Input Parameters:
836: + x - the matrix
837: - mapping - mapping created with ISLocalToGlobalMappingCreate() or
838: ISLocalToGlobalMappingCreateIS()
840: Level: intermediate
842: Concepts: matrices^local to global mapping blocked
843: Concepts: local to global mapping^for matrices, blocked
845: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(),
846: MatSetValuesBlocked(), MatSetValuesLocal()
847: @*/
848: int MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping)
849: {
854: MatPreallocated(x);
856: if (x->bmapping) {
857: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix");
858: }
859:
860: x->bmapping = mapping;
861: PetscObjectReference((PetscObject)mapping);
862: return(0);
863: }
865: /*@
866: MatSetValuesLocal - Inserts or adds values into certain locations of a matrix,
867: using a local ordering of the nodes.
869: Not Collective
871: Input Parameters:
872: + x - the matrix
873: . nrow, irow - number of rows and their local indices
874: . ncol, icol - number of columns and their local indices
875: . y - a logically two-dimensional array of values
876: - addv - either INSERT_VALUES or ADD_VALUES, where
877: ADD_VALUES adds values to any existing entries, and
878: INSERT_VALUES replaces existing entries with new values
880: Notes:
881: Before calling MatSetValuesLocal(), the user must first set the
882: local-to-global mapping by calling MatSetLocalToGlobalMapping().
884: Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES
885: options cannot be mixed without intervening calls to the assembly
886: routines.
888: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
889: MUST be called after all calls to MatSetValuesLocal() have been completed.
891: Level: intermediate
893: Concepts: matrices^putting entries in with local numbering
895: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(),
896: MatSetValueLocal()
897: @*/
898: int MatSetValuesLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv)
899: {
900: int ierr,irowm[2048],icolm[2048];
905: MatPreallocated(mat);
910: if (mat->insertmode == NOT_SET_VALUES) {
911: mat->insertmode = addv;
912: }
913: #if defined(PETSC_USE_BOPT_g)
914: else if (mat->insertmode != addv) {
915: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
916: }
917: if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) {
918: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
919: }
920: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
921: #endif
923: if (mat->assembled) {
924: mat->was_assembled = PETSC_TRUE;
925: mat->assembled = PETSC_FALSE;
926: }
927: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
928: if (!mat->ops->setvalueslocal) {
929: ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);
930: ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);
931: (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);
932: } else {
933: (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);
934: }
935: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
936: return(0);
937: }
939: /*@
940: MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix,
941: using a local ordering of the nodes a block at a time.
943: Not Collective
945: Input Parameters:
946: + x - the matrix
947: . nrow, irow - number of rows and their local indices
948: . ncol, icol - number of columns and their local indices
949: . y - a logically two-dimensional array of values
950: - addv - either INSERT_VALUES or ADD_VALUES, where
951: ADD_VALUES adds values to any existing entries, and
952: INSERT_VALUES replaces existing entries with new values
954: Notes:
955: Before calling MatSetValuesBlockedLocal(), the user must first set the
956: local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(),
957: where the mapping MUST be set for matrix blocks, not for matrix elements.
959: Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
960: options cannot be mixed without intervening calls to the assembly
961: routines.
963: These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd()
964: MUST be called after all calls to MatSetValuesBlockedLocal() have been completed.
966: Level: intermediate
968: Concepts: matrices^putting blocked values in with local numbering
970: .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked()
971: @*/
972: int MatSetValuesBlockedLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv)
973: {
974: int ierr,irowm[2048],icolm[2048];
979: MatPreallocated(mat);
983: if (mat->insertmode == NOT_SET_VALUES) {
984: mat->insertmode = addv;
985: }
986: #if defined(PETSC_USE_BOPT_g)
987: else if (mat->insertmode != addv) {
988: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values");
989: }
990: if (!mat->bmapping) {
991: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()");
992: }
993: if (nrow > 2048 || ncol > 2048) {
994: SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol);
995: }
996: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
997: #endif
999: if (mat->assembled) {
1000: mat->was_assembled = PETSC_TRUE;
1001: mat->assembled = PETSC_FALSE;
1002: }
1003: PetscLogEventBegin(MAT_SetValues,mat,0,0,0);
1004: ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);
1005: ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);
1006: (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);
1007: PetscLogEventEnd(MAT_SetValues,mat,0,0,0);
1008: return(0);
1009: }
1011: /* --------------------------------------------------------*/
1012: /*@
1013: MatMult - Computes the matrix-vector product, y = Ax.
1015: Collective on Mat and Vec
1017: Input Parameters:
1018: + mat - the matrix
1019: - x - the vector to be multilplied
1021: Output Parameters:
1022: . y - the result
1024: Notes:
1025: The vectors x and y cannot be the same. I.e., one cannot
1026: call MatMult(A,y,y).
1028: Level: beginner
1030: Concepts: matrix-vector product
1032: .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd()
1033: @*/
1034: int MatMult(Mat mat,Vec x,Vec y)
1035: {
1041: MatPreallocated(mat);
1045: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1046: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1047: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1048: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1049: if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1050: if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %d %d",mat->m,y->n);
1052: if (mat->nullsp) {
1053: MatNullSpaceRemove(mat->nullsp,x,&x);
1054: }
1056: PetscLogEventBegin(MAT_Mult,mat,x,y,0);
1057: (*mat->ops->mult)(mat,x,y);
1058: PetscLogEventEnd(MAT_Mult,mat,x,y,0);
1060: if (mat->nullsp) {
1061: MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);
1062: }
1063: return(0);
1064: }
1066: /*@
1067: MatMultTranspose - Computes matrix transpose times a vector.
1069: Collective on Mat and Vec
1071: Input Parameters:
1072: + mat - the matrix
1073: - x - the vector to be multilplied
1075: Output Parameters:
1076: . y - the result
1078: Notes:
1079: The vectors x and y cannot be the same. I.e., one cannot
1080: call MatMultTranspose(A,y,y).
1082: Level: beginner
1084: Concepts: matrix vector product^transpose
1086: .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd()
1087: @*/
1088: int MatMultTranspose(Mat mat,Vec x,Vec y)
1089: {
1095: MatPreallocated(mat);
1099: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1100: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1101: if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors");
1102: if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
1103: if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
1104:
1105: PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);
1106: (*mat->ops->multtranspose)(mat,x,y);
1107: PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);
1108: return(0);
1109: }
1111: /*@
1112: MatMultAdd - Computes v3 = v2 + A * v1.
1114: Collective on Mat and Vec
1116: Input Parameters:
1117: + mat - the matrix
1118: - v1, v2 - the vectors
1120: Output Parameters:
1121: . v3 - the result
1123: Notes:
1124: The vectors v1 and v3 cannot be the same. I.e., one cannot
1125: call MatMultAdd(A,v1,v2,v1).
1127: Level: beginner
1129: Concepts: matrix vector product^addition
1131: .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd()
1132: @*/
1133: int MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1134: {
1140: MatPreallocated(mat);
1145: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1146: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1147: if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->N,v1->N);
1148: if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->M,v2->N);
1149: if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->M,v3->N);
1150: if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %d %d",mat->m,v3->n);
1151: if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %d %d",mat->m,v2->n);
1152: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1154: PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);
1155: (*mat->ops->multadd)(mat,v1,v2,v3);
1156: PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);
1157: return(0);
1158: }
1160: /*@
1161: MatMultTransposeAdd - Computes v3 = v2 + A' * v1.
1163: Collective on Mat and Vec
1165: Input Parameters:
1166: + mat - the matrix
1167: - v1, v2 - the vectors
1169: Output Parameters:
1170: . v3 - the result
1172: Notes:
1173: The vectors v1 and v3 cannot be the same. I.e., one cannot
1174: call MatMultTransposeAdd(A,v1,v2,v1).
1176: Level: beginner
1178: Concepts: matrix vector product^transpose and addition
1180: .seealso: MatMultTranspose(), MatMultAdd(), MatMult()
1181: @*/
1182: int MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3)
1183: {
1189: MatPreallocated(mat);
1194: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1195: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1196: if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1197: if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors");
1198: if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->M,v1->N);
1199: if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->N,v2->N);
1200: if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->N,v3->N);
1202: PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);
1203: (*mat->ops->multtransposeadd)(mat,v1,v2,v3);
1204: PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);
1205: return(0);
1206: }
1207: /* ------------------------------------------------------------*/
1208: /*@C
1209: MatGetInfo - Returns information about matrix storage (number of
1210: nonzeros, memory, etc.).
1212: Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used
1213: as the flag
1215: Input Parameters:
1216: . mat - the matrix
1218: Output Parameters:
1219: + flag - flag indicating the type of parameters to be returned
1220: (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors,
1221: MAT_GLOBAL_SUM - sum over all processors)
1222: - info - matrix information context
1224: Notes:
1225: The MatInfo context contains a variety of matrix data, including
1226: number of nonzeros allocated and used, number of mallocs during
1227: matrix assembly, etc. Additional information for factored matrices
1228: is provided (such as the fill ratio, number of mallocs during
1229: factorization, etc.). Much of this info is printed to STDOUT
1230: when using the runtime options
1231: $ -log_info -mat_view_info
1233: Example for C/C++ Users:
1234: See the file ${PETSC_DIR}/include/petscmat.h for a complete list of
1235: data within the MatInfo context. For example,
1236: .vb
1237: MatInfo info;
1238: Mat A;
1239: double mal, nz_a, nz_u;
1241: MatGetInfo(A,MAT_LOCAL,&info);
1242: mal = info.mallocs;
1243: nz_a = info.nz_allocated;
1244: .ve
1246: Example for Fortran Users:
1247: Fortran users should declare info as a double precision
1248: array of dimension MAT_INFO_SIZE, and then extract the parameters
1249: of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h
1250: a complete list of parameter names.
1251: .vb
1252: double precision info(MAT_INFO_SIZE)
1253: double precision mal, nz_a
1254: Mat A
1255: integer ierr
1257: call MatGetInfo(A,MAT_LOCAL,info,ierr)
1258: mal = info(MAT_INFO_MALLOCS)
1259: nz_a = info(MAT_INFO_NZ_ALLOCATED)
1260: .ve
1262: Level: intermediate
1264: Concepts: matrices^getting information on
1265:
1266: @*/
1267: int MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info)
1268: {
1274: MatPreallocated(mat);
1276: if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1277: (*mat->ops->getinfo)(mat,flag,info);
1278: return(0);
1279: }
1281: /* ----------------------------------------------------------*/
1282: /*@C
1283: MatILUDTFactor - Performs a drop tolerance ILU factorization.
1285: Collective on Mat
1287: Input Parameters:
1288: + mat - the matrix
1289: . info - information about the factorization to be done
1290: . row - row permutation
1291: - col - column permutation
1293: Output Parameters:
1294: . fact - the factored matrix
1296: Level: developer
1298: Notes:
1299: Most users should employ the simplified SLES interface for linear solvers
1300: instead of working directly with matrix algebra routines such as this.
1301: See, e.g., SLESCreate().
1303: This is currently only supported for the SeqAIJ matrix format using code
1304: from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or
1305: Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright
1306: and thus can be distributed with PETSc.
1308: Concepts: matrices^ILUDT factorization
1310: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
1311: @*/
1312: int MatILUDTFactor(Mat mat,MatILUInfo *info,IS row,IS col,Mat *fact)
1313: {
1319: MatPreallocated(mat);
1321: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1322: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1323: if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1325: PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1326: (*mat->ops->iludtfactor)(mat,info,row,col,fact);
1327: PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1329: return(0);
1330: }
1332: /*@
1333: MatLUFactor - Performs in-place LU factorization of matrix.
1335: Collective on Mat
1337: Input Parameters:
1338: + mat - the matrix
1339: . row - row permutation
1340: . col - column permutation
1341: - info - options for factorization, includes
1342: $ fill - expected fill as ratio of original fill.
1343: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1344: $ Run with the option -log_info to determine an optimal value to use
1346: Notes:
1347: Most users should employ the simplified SLES interface for linear solvers
1348: instead of working directly with matrix algebra routines such as this.
1349: See, e.g., SLESCreate().
1351: This changes the state of the matrix to a factored matrix; it cannot be used
1352: for example with MatSetValues() unless one first calls MatSetUnfactored().
1354: Level: developer
1356: Concepts: matrices^LU factorization
1358: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(),
1359: MatGetOrdering(), MatSetUnfactored()
1361: @*/
1362: int MatLUFactor(Mat mat,IS row,IS col,MatLUInfo *info)
1363: {
1369: MatPreallocated(mat);
1370: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1371: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1372: if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1374: PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);
1375: (*mat->ops->lufactor)(mat,row,col,info);
1376: PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);
1377: return(0);
1378: }
1380: /*@
1381: MatILUFactor - Performs in-place ILU factorization of matrix.
1383: Collective on Mat
1385: Input Parameters:
1386: + mat - the matrix
1387: . row - row permutation
1388: . col - column permutation
1389: - info - structure containing
1390: $ levels - number of levels of fill.
1391: $ expected fill - as ratio of original fill.
1392: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
1393: missing diagonal entries)
1395: Notes:
1396: Probably really in-place only when level of fill is zero, otherwise allocates
1397: new space to store factored matrix and deletes previous memory.
1399: Most users should employ the simplified SLES interface for linear solvers
1400: instead of working directly with matrix algebra routines such as this.
1401: See, e.g., SLESCreate().
1403: Level: developer
1405: Concepts: matrices^ILU factorization
1407: .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
1408: @*/
1409: int MatILUFactor(Mat mat,IS row,IS col,MatILUInfo *info)
1410: {
1416: MatPreallocated(mat);
1417: if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
1418: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1419: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1420: if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1422: PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);
1423: (*mat->ops->ilufactor)(mat,row,col,info);
1424: PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);
1425: return(0);
1426: }
1428: /*@
1429: MatLUFactorSymbolic - Performs symbolic LU factorization of matrix.
1430: Call this routine before calling MatLUFactorNumeric().
1432: Collective on Mat
1434: Input Parameters:
1435: + mat - the matrix
1436: . row, col - row and column permutations
1437: - info - options for factorization, includes
1438: $ fill - expected fill as ratio of original fill.
1439: $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting)
1440: $ Run with the option -log_info to determine an optimal value to use
1442: Output Parameter:
1443: . fact - new matrix that has been symbolically factored
1445: Notes:
1446: See the users manual for additional information about
1447: choosing the fill factor for better efficiency.
1449: Most users should employ the simplified SLES interface for linear solvers
1450: instead of working directly with matrix algebra routines such as this.
1451: See, e.g., SLESCreate().
1453: Level: developer
1455: Concepts: matrices^LU symbolic factorization
1457: .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor()
1458: @*/
1459: int MatLUFactorSymbolic(Mat mat,IS row,IS col,MatLUInfo *info,Mat *fact)
1460: {
1466: MatPreallocated(mat);
1468: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1469: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1470: if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic LU",mat->type_name);
1472: PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);
1473: (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);
1474: PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);
1475: return(0);
1476: }
1478: /*@
1479: MatLUFactorNumeric - Performs numeric LU factorization of a matrix.
1480: Call this routine after first calling MatLUFactorSymbolic().
1482: Collective on Mat
1484: Input Parameters:
1485: + mat - the matrix
1486: - fact - the matrix generated for the factor, from MatLUFactorSymbolic()
1488: Notes:
1489: See MatLUFactor() for in-place factorization. See
1490: MatCholeskyFactorNumeric() for the symmetric, positive definite case.
1492: Most users should employ the simplified SLES interface for linear solvers
1493: instead of working directly with matrix algebra routines such as this.
1494: See, e.g., SLESCreate().
1496: Level: developer
1498: Concepts: matrices^LU numeric factorization
1500: .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor()
1501: @*/
1502: int MatLUFactorNumeric(Mat mat,Mat *fact)
1503: {
1504: int ierr;
1505: PetscTruth flg;
1510: MatPreallocated(mat);
1513: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1514: if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1515: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %d should = %d %d should = %d",
1516: mat->M,(*fact)->M,mat->N,(*fact)->N);
1517: }
1518: if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1520: PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);
1521: (*(*fact)->ops->lufactornumeric)(mat,fact);
1522: PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);
1523: PetscOptionsHasName(PETSC_NULL,"-mat_view_draw",&flg);
1524: if (flg) {
1525: PetscOptionsHasName(PETSC_NULL,"-mat_view_contour",&flg);
1526: if (flg) {
1527: PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
1528: }
1529: MatView(*fact,PETSC_VIEWER_DRAW_(mat->comm));
1530: PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
1531: if (flg) {
1532: PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
1533: }
1534: }
1535: return(0);
1536: }
1538: /*@
1539: MatCholeskyFactor - Performs in-place Cholesky factorization of a
1540: symmetric matrix.
1542: Collective on Mat
1544: Input Parameters:
1545: + mat - the matrix
1546: . perm - row and column permutations
1547: - f - expected fill as ratio of original fill
1549: Notes:
1550: See MatLUFactor() for the nonsymmetric case. See also
1551: MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric().
1553: Most users should employ the simplified SLES interface for linear solvers
1554: instead of working directly with matrix algebra routines such as this.
1555: See, e.g., SLESCreate().
1557: Level: developer
1559: Concepts: matrices^Cholesky factorization
1561: .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric()
1562: MatGetOrdering()
1564: @*/
1565: int MatCholeskyFactor(Mat mat,IS perm,PetscReal f)
1566: {
1572: MatPreallocated(mat);
1573: if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1574: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1575: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1576: if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1578: PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);
1579: (*mat->ops->choleskyfactor)(mat,perm,f);
1580: PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);
1581: return(0);
1582: }
1584: /*@
1585: MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization
1586: of a symmetric matrix.
1588: Collective on Mat
1590: Input Parameters:
1591: + mat - the matrix
1592: . perm - row and column permutations
1593: - f - expected fill as ratio of original
1595: Output Parameter:
1596: . fact - the factored matrix
1598: Notes:
1599: See MatLUFactorSymbolic() for the nonsymmetric case. See also
1600: MatCholeskyFactor() and MatCholeskyFactorNumeric().
1602: Most users should employ the simplified SLES interface for linear solvers
1603: instead of working directly with matrix algebra routines such as this.
1604: See, e.g., SLESCreate().
1606: Level: developer
1608: Concepts: matrices^Cholesky symbolic factorization
1610: .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric()
1611: MatGetOrdering()
1613: @*/
1614: int MatCholeskyFactorSymbolic(Mat mat,IS perm,PetscReal f,Mat *fact)
1615: {
1621: MatPreallocated(mat);
1623: if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square");
1624: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1625: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
1626: if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1628: PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1629: (*mat->ops->choleskyfactorsymbolic)(mat,perm,f,fact);
1630: PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);
1631: return(0);
1632: }
1634: /*@
1635: MatCholeskyFactorNumeric - Performs numeric Cholesky factorization
1636: of a symmetric matrix. Call this routine after first calling
1637: MatCholeskyFactorSymbolic().
1639: Collective on Mat
1641: Input Parameter:
1642: . mat - the initial matrix
1644: Output Parameter:
1645: . fact - the factored matrix
1647: Notes:
1648: Most users should employ the simplified SLES interface for linear solvers
1649: instead of working directly with matrix algebra routines such as this.
1650: See, e.g., SLESCreate().
1652: Level: developer
1654: Concepts: matrices^Cholesky numeric factorization
1656: .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric()
1657: @*/
1658: int MatCholeskyFactorNumeric(Mat mat,Mat *fact)
1659: {
1665: MatPreallocated(mat);
1667: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
1668: if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1669: if (mat->M != (*fact)->M || mat->N != (*fact)->N) {
1670: SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %d should = %d %d should = %d",
1671: mat->M,(*fact)->M,mat->N,(*fact)->N);
1672: }
1674: PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1675: (*(*fact)->ops->choleskyfactornumeric)(mat,fact);
1676: PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);
1677: return(0);
1678: }
1680: /* ----------------------------------------------------------------*/
1681: /*@
1682: MatSolve - Solves A x = b, given a factored matrix.
1684: Collective on Mat and Vec
1686: Input Parameters:
1687: + mat - the factored matrix
1688: - b - the right-hand-side vector
1690: Output Parameter:
1691: . x - the result vector
1693: Notes:
1694: The vectors b and x cannot be the same. I.e., one cannot
1695: call MatSolve(A,x,x).
1697: Notes:
1698: Most users should employ the simplified SLES interface for linear solvers
1699: instead of working directly with matrix algebra routines such as this.
1700: See, e.g., SLESCreate().
1702: Level: developer
1704: Concepts: matrices^triangular solves
1706: .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd()
1707: @*/
1708: int MatSolve(Mat mat,Vec b,Vec x)
1709: {
1715: MatPreallocated(mat);
1720: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1721: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1722: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1723: if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1724: if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1725: if (mat->M == 0 && mat->N == 0) return(0);
1727: if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1728: PetscLogEventBegin(MAT_Solve,mat,b,x,0);
1729: (*mat->ops->solve)(mat,b,x);
1730: PetscLogEventEnd(MAT_Solve,mat,b,x,0);
1731: return(0);
1732: }
1734: /* @
1735: MatForwardSolve - Solves L x = b, given a factored matrix, A = LU.
1737: Collective on Mat and Vec
1739: Input Parameters:
1740: + mat - the factored matrix
1741: - b - the right-hand-side vector
1743: Output Parameter:
1744: . x - the result vector
1746: Notes:
1747: MatSolve() should be used for most applications, as it performs
1748: a forward solve followed by a backward solve.
1750: The vectors b and x cannot be the same. I.e., one cannot
1751: call MatForwardSolve(A,x,x).
1753: Most users should employ the simplified SLES interface for linear solvers
1754: instead of working directly with matrix algebra routines such as this.
1755: See, e.g., SLESCreate().
1757: Level: developer
1759: Concepts: matrices^forward solves
1761: .seealso: MatSolve(), MatBackwardSolve()
1762: @ */
1763: int MatForwardSolve(Mat mat,Vec b,Vec x)
1764: {
1770: MatPreallocated(mat);
1775: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1776: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1777: if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1778: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1779: if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1780: if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1782: PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);
1783: (*mat->ops->forwardsolve)(mat,b,x);
1784: PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);
1785: return(0);
1786: }
1788: /* @
1789: MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU.
1791: Collective on Mat and Vec
1793: Input Parameters:
1794: + mat - the factored matrix
1795: - b - the right-hand-side vector
1797: Output Parameter:
1798: . x - the result vector
1800: Notes:
1801: MatSolve() should be used for most applications, as it performs
1802: a forward solve followed by a backward solve.
1804: The vectors b and x cannot be the same. I.e., one cannot
1805: call MatBackwardSolve(A,x,x).
1807: Most users should employ the simplified SLES interface for linear solvers
1808: instead of working directly with matrix algebra routines such as this.
1809: See, e.g., SLESCreate().
1811: Level: developer
1813: Concepts: matrices^backward solves
1815: .seealso: MatSolve(), MatForwardSolve()
1816: @ */
1817: int MatBackwardSolve(Mat mat,Vec b,Vec x)
1818: {
1824: MatPreallocated(mat);
1829: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1830: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1831: if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
1832: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1833: if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1834: if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1836: PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);
1837: (*mat->ops->backwardsolve)(mat,b,x);
1838: PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);
1839: return(0);
1840: }
1842: /*@
1843: MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix.
1845: Collective on Mat and Vec
1847: Input Parameters:
1848: + mat - the factored matrix
1849: . b - the right-hand-side vector
1850: - y - the vector to be added to
1852: Output Parameter:
1853: . x - the result vector
1855: Notes:
1856: The vectors b and x cannot be the same. I.e., one cannot
1857: call MatSolveAdd(A,x,y,x).
1859: Most users should employ the simplified SLES interface for linear solvers
1860: instead of working directly with matrix algebra routines such as this.
1861: See, e.g., SLESCreate().
1863: Level: developer
1865: Concepts: matrices^triangular solves
1867: .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd()
1868: @*/
1869: int MatSolveAdd(Mat mat,Vec b,Vec y,Vec x)
1870: {
1871: Scalar one = 1.0;
1872: Vec tmp;
1873: int ierr;
1878: MatPreallocated(mat);
1885: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1886: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1887: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
1888: if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
1889: if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N);
1890: if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
1891: if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);
1893: PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);
1894: if (mat->ops->solveadd) {
1895: (*mat->ops->solveadd)(mat,b,y,x);
1896: } else {
1897: /* do the solve then the add manually */
1898: if (x != y) {
1899: MatSolve(mat,b,x);
1900: VecAXPY(&one,y,x);
1901: } else {
1902: VecDuplicate(x,&tmp);
1903: PetscLogObjectParent(mat,tmp);
1904: VecCopy(x,tmp);
1905: MatSolve(mat,b,x);
1906: VecAXPY(&one,tmp,x);
1907: VecDestroy(tmp);
1908: }
1909: }
1910: PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);
1911: return(0);
1912: }
1914: /*@
1915: MatSolveTranspose - Solves A' x = b, given a factored matrix.
1917: Collective on Mat and Vec
1919: Input Parameters:
1920: + mat - the factored matrix
1921: - b - the right-hand-side vector
1923: Output Parameter:
1924: . x - the result vector
1926: Notes:
1927: The vectors b and x cannot be the same. I.e., one cannot
1928: call MatSolveTranspose(A,x,x).
1930: Most users should employ the simplified SLES interface for linear solvers
1931: instead of working directly with matrix algebra routines such as this.
1932: See, e.g., SLESCreate().
1934: Level: developer
1936: Concepts: matrices^triangular solves
1938: .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd()
1939: @*/
1940: int MatSolveTranspose(Mat mat,Vec b,Vec x)
1941: {
1947: MatPreallocated(mat);
1952: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
1953: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
1954: if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name);
1955: if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
1956: if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);
1958: PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);
1959: (*mat->ops->solvetranspose)(mat,b,x);
1960: PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);
1961: return(0);
1962: }
1964: /*@
1965: MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a
1966: factored matrix.
1968: Collective on Mat and Vec
1970: Input Parameters:
1971: + mat - the factored matrix
1972: . b - the right-hand-side vector
1973: - y - the vector to be added to
1975: Output Parameter:
1976: . x - the result vector
1978: Notes:
1979: The vectors b and x cannot be the same. I.e., one cannot
1980: call MatSolveTransposeAdd(A,x,y,x).
1982: Most users should employ the simplified SLES interface for linear solvers
1983: instead of working directly with matrix algebra routines such as this.
1984: See, e.g., SLESCreate().
1986: Level: developer
1988: Concepts: matrices^triangular solves
1990: .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose()
1991: @*/
1992: int MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x)
1993: {
1994: Scalar one = 1.0;
1995: int ierr;
1996: Vec tmp;
2001: MatPreallocated(mat);
2008: if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors");
2009: if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix");
2010: if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N);
2011: if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N);
2012: if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N);
2013: if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n);
2015: PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);
2016: if (mat->ops->solvetransposeadd) {
2017: (*mat->ops->solvetransposeadd)(mat,b,y,x);
2018: } else {
2019: /* do the solve then the add manually */
2020: if (x != y) {
2021: MatSolveTranspose(mat,b,x);
2022: VecAXPY(&one,y,x);
2023: } else {
2024: VecDuplicate(x,&tmp);
2025: PetscLogObjectParent(mat,tmp);
2026: VecCopy(x,tmp);
2027: MatSolveTranspose(mat,b,x);
2028: VecAXPY(&one,tmp,x);
2029: VecDestroy(tmp);
2030: }
2031: }
2032: PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);
2033: return(0);
2034: }
2035: /* ----------------------------------------------------------------*/
2037: /*@
2038: MatRelax - Computes one relaxation sweep.
2040: Collective on Mat and Vec
2042: Input Parameters:
2043: + mat - the matrix
2044: . b - the right hand side
2045: . omega - the relaxation factor
2046: . flag - flag indicating the type of SOR (see below)
2047: . shift - diagonal shift
2048: - its - the number of iterations
2050: Output Parameters:
2051: . x - the solution (can contain an initial guess)
2053: SOR Flags:
2054: . SOR_FORWARD_SWEEP - forward SOR
2055: . SOR_BACKWARD_SWEEP - backward SOR
2056: . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR)
2057: . SOR_LOCAL_FORWARD_SWEEP - local forward SOR
2058: . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR
2059: . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR
2060: . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies
2061: upper/lower triangular part of matrix to
2062: vector (with omega)
2063: . SOR_ZERO_INITIAL_GUESS - zero initial guess
2065: Notes:
2066: SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and
2067: SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings
2068: on each processor.
2070: Application programmers will not generally use MatRelax() directly,
2071: but instead will employ the SLES/PC interface.
2073: Notes for Advanced Users:
2074: The flags are implemented as bitwise inclusive or operations.
2075: For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP)
2076: to specify a zero initial guess for SSOR.
2078: Most users should employ the simplified SLES interface for linear solvers
2079: instead of working directly with matrix algebra routines such as this.
2080: See, e.g., SLESCreate().
2082: Level: developer
2084: Concepts: matrices^relaxation
2085: Concepts: matrices^SOR
2086: Concepts: matrices^Gauss-Seidel
2088: @*/
2089: int MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,int its,Vec x)
2090: {
2096: MatPreallocated(mat);
2101: if (!mat->ops->relax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2102: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2103: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2104: if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N);
2105: if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N);
2106: if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n);
2108: PetscLogEventBegin(MAT_Relax,mat,b,x,0);
2109: ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,x);
2110: PetscLogEventEnd(MAT_Relax,mat,b,x,0);
2111: return(0);
2112: }
2114: /*
2115: Default matrix copy routine.
2116: */
2117: int MatCopy_Basic(Mat A,Mat B,MatStructure str)
2118: {
2119: int ierr,i,rstart,rend,nz,*cwork;
2120: Scalar *vwork;
2123: MatZeroEntries(B);
2124: MatGetOwnershipRange(A,&rstart,&rend);
2125: for (i=rstart; i<rend; i++) {
2126: MatGetRow(A,i,&nz,&cwork,&vwork);
2127: MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);
2128: MatRestoreRow(A,i,&nz,&cwork,&vwork);
2129: }
2130: MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);
2131: MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);
2132: return(0);
2133: }
2135: /*@C
2136: MatCopy - Copys a matrix to another matrix.
2138: Collective on Mat
2140: Input Parameters:
2141: + A - the matrix
2142: - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN
2144: Output Parameter:
2145: . B - where the copy is put
2147: Notes:
2148: If you use SAME_NONZERO_PATTERN then the zero matrices had better have the
2149: same nonzero pattern or the routine will crash.
2151: MatCopy() copies the matrix entries of a matrix to another existing
2152: matrix (after first zeroing the second matrix). A related routine is
2153: MatConvert(), which first creates a new matrix and then copies the data.
2155: Level: intermediate
2156:
2157: Concepts: matrices^copying
2159: .seealso: MatConvert()
2160: @*/
2161: int MatCopy(Mat A,Mat B,MatStructure str)
2162: {
2169: MatPreallocated(A);
2171: MatPreallocated(B);
2173: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2174: if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2175: if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d",A->M,B->M,
2176: A->N,B->N);
2178: PetscLogEventBegin(MAT_Copy,A,B,0,0);
2179: if (A->ops->copy) {
2180: (*A->ops->copy)(A,B,str);
2181: } else { /* generic conversion */
2182: MatCopy_Basic(A,B,str);
2183: }
2184: PetscLogEventEnd(MAT_Copy,A,B,0,0);
2185: return(0);
2186: }
2188: #include "petscsys.h"
2189: PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE;
2190: PetscFList MatConvertList = 0;
2192: /*@C
2193: MatConvertRegister - Allows one to register a routine that reads matrices
2194: from a binary file for a particular matrix type.
2196: Not Collective
2198: Input Parameters:
2199: + type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ.
2200: - Converter - the function that reads the matrix from the binary file.
2202: Level: developer
2204: .seealso: MatConvertRegisterAll(), MatConvert()
2206: @*/
2207: int MatConvertRegister(char *sname,char *path,char *name,int (*function)(Mat,MatType,Mat*))
2208: {
2209: int ierr;
2210: char fullname[256];
2213: PetscFListConcat(path,name,fullname);
2214: PetscFListAdd(&MatConvertList,sname,fullname,(void (*)())function);
2215: return(0);
2216: }
2218: /*@C
2219: MatConvert - Converts a matrix to another matrix, either of the same
2220: or different type.
2222: Collective on Mat
2224: Input Parameters:
2225: + mat - the matrix
2226: - newtype - new matrix type. Use MATSAME to create a new matrix of the
2227: same type as the original matrix.
2229: Output Parameter:
2230: . M - pointer to place new matrix
2232: Notes:
2233: MatConvert() first creates a new matrix and then copies the data from
2234: the first matrix. A related routine is MatCopy(), which copies the matrix
2235: entries of one matrix to another already existing matrix context.
2237: Level: intermediate
2239: Concepts: matrices^converting between storage formats
2241: .seealso: MatCopy(), MatDuplicate()
2242: @*/
2243: int MatConvert(Mat mat,MatType newtype,Mat *M)
2244: {
2245: int ierr;
2246: PetscTruth sametype,issame,flg;
2247: char convname[256],mtype[256];
2252: MatPreallocated(mat);
2254: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2255: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2257: PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);
2258: if (flg) {
2259: newtype = mtype;
2260: }
2261: PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2262:
2263: PetscTypeCompare((PetscObject)mat,newtype,&sametype);
2264: PetscStrcmp(newtype,"same",&issame);
2265: if ((sametype || issame) && mat->ops->duplicate) {
2266: (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);
2267: } else {
2268: int (*conv)(Mat,MatType,Mat*);
2269: PetscStrcpy(convname,"MatConvertTo_");
2270: PetscStrcat(convname,newtype);
2271: PetscFListFind(mat->comm,MatConvertList,convname,(void(**)())&conv);
2272: if (conv) {
2273: (*conv)(mat,newtype,M);
2274: } else {
2275: PetscStrcpy(convname,"MatConvert_");
2276: PetscStrcat(convname,mat->type_name);
2277: PetscStrcat(convname,"_");
2278: PetscStrcat(convname,newtype);
2279: PetscStrcat(convname,"_C");
2280: PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)())&conv);
2281: if (conv) {
2282: (*conv)(mat,newtype,M);
2283: } else {
2284: if (mat->ops->convert) {
2285: (*mat->ops->convert)(mat,newtype,M);
2286: } else {
2287: MatConvert_Basic(mat,newtype,M);
2288: }
2289: }
2290: }
2291: }
2292: PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2293: return(0);
2294: }
2297: /*@C
2298: MatDuplicate - Duplicates a matrix including the non-zero structure.
2300: Collective on Mat
2302: Input Parameters:
2303: + mat - the matrix
2304: - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero
2305: values as well or not
2307: Output Parameter:
2308: . M - pointer to place new matrix
2310: Level: intermediate
2312: Concepts: matrices^duplicating
2314: .seealso: MatCopy(), MatConvert()
2315: @*/
2316: int MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M)
2317: {
2323: MatPreallocated(mat);
2325: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2326: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2328: *M = 0;
2329: PetscLogEventBegin(MAT_Convert,mat,0,0,0);
2330: if (!mat->ops->duplicate) {
2331: SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type");
2332: }
2333: (*mat->ops->duplicate)(mat,op,M);
2334: PetscLogEventEnd(MAT_Convert,mat,0,0,0);
2335: return(0);
2336: }
2338: /*@
2339: MatGetDiagonal - Gets the diagonal of a matrix.
2341: Collective on Mat and Vec
2343: Input Parameters:
2344: + mat - the matrix
2345: - v - the vector for storing the diagonal
2347: Output Parameter:
2348: . v - the diagonal of the matrix
2350: Notes:
2351: For the SeqAIJ matrix format, this routine may also be called
2352: on a LU factored matrix; in that case it routines the reciprocal of
2353: the diagonal entries in U. It returns the entries permuted by the
2354: row and column permutation used during the symbolic factorization.
2356: Level: intermediate
2358: Concepts: matrices^accessing diagonals
2360: .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax()
2361: @*/
2362: int MatGetDiagonal(Mat mat,Vec v)
2363: {
2369: MatPreallocated(mat);
2372: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2373: if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2375: (*mat->ops->getdiagonal)(mat,v);
2376: return(0);
2377: }
2379: /*@
2380: MatGetRowMax - Gets the maximum value (in absolute value) of each
2381: row of the matrix
2383: Collective on Mat and Vec
2385: Input Parameters:
2386: . mat - the matrix
2388: Output Parameter:
2389: . v - the vector for storing the maximums
2391: Level: intermediate
2393: Concepts: matrices^getting row maximums
2395: .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix()
2396: @*/
2397: int MatGetRowMax(Mat mat,Vec v)
2398: {
2404: MatPreallocated(mat);
2407: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2408: if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2410: (*mat->ops->getrowmax)(mat,v);
2411: return(0);
2412: }
2414: /*@C
2415: MatTranspose - Computes an in-place or out-of-place transpose of a matrix.
2417: Collective on Mat
2419: Input Parameter:
2420: . mat - the matrix to transpose
2422: Output Parameters:
2423: . B - the transpose (or pass in PETSC_NULL for an in-place transpose)
2425: Level: intermediate
2427: Concepts: matrices^transposing
2429: .seealso: MatMultTranspose(), MatMultTransposeAdd()
2430: @*/
2431: int MatTranspose(Mat mat,Mat *B)
2432: {
2438: MatPreallocated(mat);
2439: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2440: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2441: if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2442: (*mat->ops->transpose)(mat,B);
2443: return(0);
2444: }
2446: /*@C
2447: MatPermute - Creates a new matrix with rows and columns permuted from the
2448: original.
2450: Collective on Mat
2452: Input Parameters:
2453: + mat - the matrix to permute
2454: . row - row permutation, each processor supplies only the permutation for its rows
2455: - col - column permutation, each processor needs the entire column permutation, that is
2456: this is the same size as the total number of columns in the matrix
2458: Output Parameters:
2459: . B - the permuted matrix
2461: Level: advanced
2463: Concepts: matrices^permuting
2465: .seealso: MatGetOrdering()
2466: @*/
2467: int MatPermute(Mat mat,IS row,IS col,Mat *B)
2468: {
2474: MatPreallocated(mat);
2477: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2478: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2479: if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2480: (*mat->ops->permute)(mat,row,col,B);
2481: return(0);
2482: }
2484: /*@
2485: MatEqual - Compares two matrices.
2487: Collective on Mat
2489: Input Parameters:
2490: + A - the first matrix
2491: - B - the second matrix
2493: Output Parameter:
2494: . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise.
2496: Level: intermediate
2498: Concepts: matrices^equality between
2499: @*/
2500: int MatEqual(Mat A,Mat B,PetscTruth *flg)
2501: {
2508: MatPreallocated(A);
2510: MatPreallocated(B);
2513: if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2514: if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2515: if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d %d %d",A->M,B->M,A->N,B->N);
2516: if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name);
2517: (*A->ops->equal)(A,B,flg);
2518: return(0);
2519: }
2521: /*@
2522: MatDiagonalScale - Scales a matrix on the left and right by diagonal
2523: matrices that are stored as vectors. Either of the two scaling
2524: matrices can be PETSC_NULL.
2526: Collective on Mat
2528: Input Parameters:
2529: + mat - the matrix to be scaled
2530: . l - the left scaling vector (or PETSC_NULL)
2531: - r - the right scaling vector (or PETSC_NULL)
2533: Notes:
2534: MatDiagonalScale() computes A = LAR, where
2535: L = a diagonal matrix, R = a diagonal matrix
2537: Level: intermediate
2539: Concepts: matrices^diagonal scaling
2540: Concepts: diagonal scaling of matrices
2542: .seealso: MatScale()
2543: @*/
2544: int MatDiagonalScale(Mat mat,Vec l,Vec r)
2545: {
2551: MatPreallocated(mat);
2552: if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2555: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2556: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2558: PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2559: (*mat->ops->diagonalscale)(mat,l,r);
2560: PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2561: return(0);
2562: }
2564: /*@
2565: MatScale - Scales all elements of a matrix by a given number.
2567: Collective on Mat
2569: Input Parameters:
2570: + mat - the matrix to be scaled
2571: - a - the scaling value
2573: Output Parameter:
2574: . mat - the scaled matrix
2576: Level: intermediate
2578: Concepts: matrices^scaling all entries
2580: .seealso: MatDiagonalScale()
2581: @*/
2582: int MatScale(Scalar *a,Mat mat)
2583: {
2589: MatPreallocated(mat);
2591: if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2592: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2593: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2595: PetscLogEventBegin(MAT_Scale,mat,0,0,0);
2596: (*mat->ops->scale)(a,mat);
2597: PetscLogEventEnd(MAT_Scale,mat,0,0,0);
2598: return(0);
2599: }
2601: /*@
2602: MatNorm - Calculates various norms of a matrix.
2604: Collective on Mat
2606: Input Parameters:
2607: + mat - the matrix
2608: - type - the type of norm, NORM_1, NORM_2, NORM_FROBENIUS, NORM_INFINITY
2610: Output Parameters:
2611: . norm - the resulting norm
2613: Level: intermediate
2615: Concepts: matrices^norm
2616: Concepts: norm^of matrix
2617: @*/
2618: int MatNorm(Mat mat,NormType type,PetscReal *norm)
2619: {
2625: MatPreallocated(mat);
2628: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
2629: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
2630: if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
2631: (*mat->ops->norm)(mat,type,norm);
2632: return(0);
2633: }
2635: /*
2636: This variable is used to prevent counting of MatAssemblyBegin() that
2637: are called from within a MatAssemblyEnd().
2638: */
2639: static int MatAssemblyEnd_InUse = 0;
2640: /*@
2641: MatAssemblyBegin - Begins assembling the matrix. This routine should
2642: be called after completing all calls to MatSetValues().
2644: Collective on Mat
2646: Input Parameters:
2647: + mat - the matrix
2648: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
2649:
2650: Notes:
2651: MatSetValues() generally caches the values. The matrix is ready to
2652: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
2653: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
2654: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
2655: using the matrix.
2657: Level: beginner
2659: Concepts: matrices^assembling
2661: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled()
2662: @*/
2663: int MatAssemblyBegin(Mat mat,MatAssemblyType type)
2664: {
2670: MatPreallocated(mat);
2671: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.nDid you forget to call MatSetUnfactored()?");
2672: if (mat->assembled) {
2673: mat->was_assembled = PETSC_TRUE;
2674: mat->assembled = PETSC_FALSE;
2675: }
2676: if (!MatAssemblyEnd_InUse) {
2677: PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);
2678: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
2679: PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);
2680: } else {
2681: if (mat->ops->assemblybegin){(*mat->ops->assemblybegin)(mat,type);}
2682: }
2683: return(0);
2684: }
2686: /*@
2687: MatAssembled - Indicates if a matrix has been assembled and is ready for
2688: use; for example, in matrix-vector product.
2690: Collective on Mat
2692: Input Parameter:
2693: . mat - the matrix
2695: Output Parameter:
2696: . assembled - PETSC_TRUE or PETSC_FALSE
2698: Level: advanced
2700: Concepts: matrices^assembled?
2702: .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin()
2703: @*/
2704: int MatAssembled(Mat mat,PetscTruth *assembled)
2705: {
2709: MatPreallocated(mat);
2710: *assembled = mat->assembled;
2711: return(0);
2712: }
2714: /*
2715: Processes command line options to determine if/how a matrix
2716: is to be viewed. Called by MatAssemblyEnd() and MatLoad().
2717: */
2718: int MatView_Private(Mat mat)
2719: {
2720: int ierr;
2721: PetscTruth flg;
2724: PetscOptionsHasName(mat->prefix,"-mat_view_info",&flg);
2725: if (flg) {
2726: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);
2727: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2728: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2729: }
2730: PetscOptionsHasName(mat->prefix,"-mat_view_info_detailed",&flg);
2731: if (flg) {
2732: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_LONG);
2733: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2734: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2735: }
2736: PetscOptionsHasName(mat->prefix,"-mat_view",&flg);
2737: if (flg) {
2738: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2739: }
2740: PetscOptionsHasName(mat->prefix,"-mat_view_matlab",&flg);
2741: if (flg) {
2742: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);
2743: MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));
2744: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));
2745: }
2746: PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);
2747: if (flg) {
2748: PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);
2749: if (flg) {
2750: PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);
2751: }
2752: MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));
2753: PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));
2754: if (flg) {
2755: PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));
2756: }
2757: }
2758: PetscOptionsHasName(mat->prefix,"-mat_view_socket",&flg);
2759: if (flg) {
2760: MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));
2761: PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));
2762: }
2763: PetscOptionsHasName(mat->prefix,"-mat_view_binary",&flg);
2764: if (flg) {
2765: MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));
2766: PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));
2767: }
2768: return(0);
2769: }
2771: /*@
2772: MatAssemblyEnd - Completes assembling the matrix. This routine should
2773: be called after MatAssemblyBegin().
2775: Collective on Mat
2777: Input Parameters:
2778: + mat - the matrix
2779: - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY
2781: Options Database Keys:
2782: + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly()
2783: . -mat_view_info_detailed - Prints more detailed info
2784: . -mat_view - Prints matrix in ASCII format
2785: . -mat_view_matlab - Prints matrix in Matlab format
2786: . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX().
2787: . -display <name> - Sets display name (default is host)
2788: - -draw_pause <sec> - Sets number of seconds to pause after display
2790: Notes:
2791: MatSetValues() generally caches the values. The matrix is ready to
2792: use only after MatAssemblyBegin() and MatAssemblyEnd() have been called.
2793: Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES
2794: in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before
2795: using the matrix.
2797: Level: beginner
2799: .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled()
2800: @*/
2801: int MatAssemblyEnd(Mat mat,MatAssemblyType type)
2802: {
2803: int ierr;
2804: static int inassm = 0;
2809: MatPreallocated(mat);
2811: inassm++;
2812: MatAssemblyEnd_InUse++;
2813: if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */
2814: PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);
2815: if (mat->ops->assemblyend) {
2816: (*mat->ops->assemblyend)(mat,type);
2817: }
2818: PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);
2819: } else {
2820: if (mat->ops->assemblyend) {
2821: (*mat->ops->assemblyend)(mat,type);
2822: }
2823: }
2825: /* Flush assembly is not a true assembly */
2826: if (type != MAT_FLUSH_ASSEMBLY) {
2827: mat->assembled = PETSC_TRUE; mat->num_ass++;
2828: }
2829: mat->insertmode = NOT_SET_VALUES;
2830: MatAssemblyEnd_InUse--;
2832: if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) {
2833: MatView_Private(mat);
2834: }
2835: inassm--;
2836: return(0);
2837: }
2840: /*@
2841: MatCompress - Tries to store the matrix in as little space as
2842: possible. May fail if memory is already fully used, since it
2843: tries to allocate new space.
2845: Collective on Mat
2847: Input Parameters:
2848: . mat - the matrix
2850: Level: advanced
2852: @*/
2853: int MatCompress(Mat mat)
2854: {
2860: MatPreallocated(mat);
2861: if (mat->ops->compress) {(*mat->ops->compress)(mat);}
2862: return(0);
2863: }
2865: /*@
2866: MatSetOption - Sets a parameter option for a matrix. Some options
2867: may be specific to certain storage formats. Some options
2868: determine how values will be inserted (or added). Sorted,
2869: row-oriented input will generally assemble the fastest. The default
2870: is row-oriented, nonsorted input.
2872: Collective on Mat
2874: Input Parameters:
2875: + mat - the matrix
2876: - option - the option, one of those listed below (and possibly others),
2877: e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR
2879: Options Describing Matrix Structure:
2880: + MAT_SYMMETRIC - symmetric in terms of both structure and value
2881: - MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure
2883: Options For Use with MatSetValues():
2884: Insert a logically dense subblock, which can be
2885: + MAT_ROW_ORIENTED - row-oriented
2886: . MAT_COLUMN_ORIENTED - column-oriented
2887: . MAT_ROWS_SORTED - sorted by row
2888: . MAT_ROWS_UNSORTED - not sorted by row
2889: . MAT_COLUMNS_SORTED - sorted by column
2890: - MAT_COLUMNS_UNSORTED - not sorted by column
2892: Not these options reflect the data you pass in with MatSetValues(); it has
2893: nothing to do with how the data is stored internally in the matrix
2894: data structure.
2896: When (re)assembling a matrix, we can restrict the input for
2897: efficiency/debugging purposes. These options include
2898: + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be
2899: allowed if they generate a new nonzero
2900: . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
2901: . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if
2902: they generate a nonzero in a new diagonal (for block diagonal format only)
2903: . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only)
2904: . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries
2905: . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry
2906: - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly
2908: Notes:
2909: Some options are relevant only for particular matrix types and
2910: are thus ignored by others. Other options are not supported by
2911: certain matrix types and will generate an error message if set.
2913: If using a Fortran 77 module to compute a matrix, one may need to
2914: use the column-oriented option (or convert to the row-oriented
2915: format).
2917: MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion
2918: that would generate a new entry in the nonzero structure is instead
2919: ignored. Thus, if memory has not alredy been allocated for this particular
2920: data, then the insertion is ignored. For dense matrices, in which
2921: the entire array is allocated, no entries are ever ignored.
2923: MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion
2924: that would generate a new entry in the nonzero structure instead produces
2925: an error. (Currently supported for AIJ and BAIJ formats only.)
2926: This is a useful flag when using SAME_NONZERO_PATTERN in calling
2927: SLESSetOperators() to ensure that the nonzero pattern truely does
2928: remain unchanged.
2930: MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion
2931: that would generate a new entry that has not been preallocated will
2932: instead produce an error. (Currently supported for AIJ and BAIJ formats
2933: only.) This is a useful flag when debugging matrix memory preallocation.
2935: MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for
2936: other processors should be dropped, rather than stashed.
2937: This is useful if you know that the "owning" processor is also
2938: always generating the correct matrix entries, so that PETSc need
2939: not transfer duplicate entries generated on another processor.
2940:
2941: MAT_USE_HASH_TABLE indicates that a hash table be used to improve the
2942: searches during matrix assembly. When this flag is set, the hash table
2943: is created during the first Matrix Assembly. This hash table is
2944: used the next time through, during MatSetVaules()/MatSetVaulesBlocked()
2945: to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag
2946: should be used with MAT_USE_HASH_TABLE flag. This option is currently
2947: supported by MATMPIBAIJ format only.
2949: MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries
2950: are kept in the nonzero structure
2952: MAT_IGNORE_ZERO_ENTRIES - when using ADD_VALUES for AIJ matrices this will stop
2953: zero values from creating a zero location in the matrix
2955: MAT_USE_INODES - indicates using inode version of the code - works with AIJ and
2956: ROWBS matrix types
2958: MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
2959: with AIJ and ROWBS matrix types
2961: Level: intermediate
2963: Concepts: matrices^setting options
2965: @*/
2966: int MatSetOption(Mat mat,MatOption op)
2967: {
2973: MatPreallocated(mat);
2974: if (op == MAT_SYMMETRIC) {
2975: mat->symmetric = PETSC_TRUE;
2976: mat->structurally_symmetric = PETSC_TRUE;
2977: } else if (op == MAT_STRUCTURALLY_SYMMETRIC) {
2978: mat->structurally_symmetric = PETSC_TRUE;
2979: } else {
2980: if (mat->ops->setoption) {(*mat->ops->setoption)(mat,op);}
2981: }
2982: return(0);
2983: }
2985: /*@
2986: MatZeroEntries - Zeros all entries of a matrix. For sparse matrices
2987: this routine retains the old nonzero structure.
2989: Collective on Mat
2991: Input Parameters:
2992: . mat - the matrix
2994: Level: intermediate
2996: Concepts: matrices^zeroing
2998: .seealso: MatZeroRows()
2999: @*/
3000: int MatZeroEntries(Mat mat)
3001: {
3007: MatPreallocated(mat);
3008: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3009: if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3011: PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);
3012: (*mat->ops->zeroentries)(mat);
3013: PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);
3014: return(0);
3015: }
3017: /*@C
3018: MatZeroRows - Zeros all entries (except possibly the main diagonal)
3019: of a set of rows of a matrix.
3021: Collective on Mat
3023: Input Parameters:
3024: + mat - the matrix
3025: . is - index set of rows to remove
3026: - diag - pointer to value put in all diagonals of eliminated rows.
3027: Note that diag is not a pointer to an array, but merely a
3028: pointer to a single value.
3030: Notes:
3031: For the AIJ and BAIJ matrix formats this removes the old nonzero structure,
3032: but does not release memory. For the dense and block diagonal
3033: formats this does not alter the nonzero structure.
3035: If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure
3036: of the matrix is not changed (even for AIJ and BAIJ matrices) the values are
3037: merely zeroed.
3039: The user can set a value in the diagonal entry (or for the AIJ and
3040: row formats can optionally remove the main diagonal entry from the
3041: nonzero structure as well, by passing a null pointer (PETSC_NULL
3042: in C or PETSC_NULL_SCALAR in Fortran) as the final argument).
3044: For the parallel case, all processes that share the matrix (i.e.,
3045: those in the communicator used for matrix creation) MUST call this
3046: routine, regardless of whether any rows being zeroed are owned by
3047: them.
3049:
3050: Level: intermediate
3052: Concepts: matrices^zeroing rows
3054: .seealso: MatZeroEntries(), MatZeroRowsLocal(), MatSetOption()
3055: @*/
3056: int MatZeroRows(Mat mat,IS is,Scalar *diag)
3057: {
3063: MatPreallocated(mat);
3066: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3067: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3068: if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3070: (*mat->ops->zerorows)(mat,is,diag);
3071: MatView_Private(mat);
3072: return(0);
3073: }
3075: /*@C
3076: MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal)
3077: of a set of rows of a matrix; using local numbering of rows.
3079: Collective on Mat
3081: Input Parameters:
3082: + mat - the matrix
3083: . is - index set of rows to remove
3084: - diag - pointer to value put in all diagonals of eliminated rows.
3085: Note that diag is not a pointer to an array, but merely a
3086: pointer to a single value.
3088: Notes:
3089: Before calling MatZeroRowsLocal(), the user must first set the
3090: local-to-global mapping by calling MatSetLocalToGlobalMapping().
3092: For the AIJ matrix formats this removes the old nonzero structure,
3093: but does not release memory. For the dense and block diagonal
3094: formats this does not alter the nonzero structure.
3096: The user can set a value in the diagonal entry (or for the AIJ and
3097: row formats can optionally remove the main diagonal entry from the
3098: nonzero structure as well, by passing a null pointer (PETSC_NULL
3099: in C or PETSC_NULL_SCALAR in Fortran) as the final argument).
3101: Level: intermediate
3103: Concepts: matrices^zeroing
3105: .seealso: MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping
3106: @*/
3107: int MatZeroRowsLocal(Mat mat,IS is,Scalar *diag)
3108: {
3110: IS newis;
3115: MatPreallocated(mat);
3118: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3119: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3121: if (mat->ops->zerorowslocal) {
3122: (*mat->ops->zerorowslocal)(mat,is,diag);
3123: } else {
3124: if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first");
3125: ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);
3126: (*mat->ops->zerorows)(mat,newis,diag);
3127: ISDestroy(newis);
3128: }
3129: return(0);
3130: }
3132: /*@
3133: MatGetSize - Returns the numbers of rows and columns in a matrix.
3135: Not Collective
3137: Input Parameter:
3138: . mat - the matrix
3140: Output Parameters:
3141: + m - the number of global rows
3142: - n - the number of global columns
3144: Level: beginner
3146: Concepts: matrices^size
3148: .seealso: MatGetLocalSize()
3149: @*/
3150: int MatGetSize(Mat mat,int *m,int* n)
3151: {
3154: if (m) *m = mat->M;
3155: if (n) *n = mat->N;
3156: return(0);
3157: }
3159: /*@
3160: MatGetLocalSize - Returns the number of rows and columns in a matrix
3161: stored locally. This information may be implementation dependent, so
3162: use with care.
3164: Not Collective
3166: Input Parameters:
3167: . mat - the matrix
3169: Output Parameters:
3170: + m - the number of local rows
3171: - n - the number of local columns
3173: Level: beginner
3175: Concepts: matrices^local size
3177: .seealso: MatGetSize()
3178: @*/
3179: int MatGetLocalSize(Mat mat,int *m,int* n)
3180: {
3183: if (m) *m = mat->m;
3184: if (n) *n = mat->n;
3185: return(0);
3186: }
3188: /*@
3189: MatGetOwnershipRange - Returns the range of matrix rows owned by
3190: this processor, assuming that the matrix is laid out with the first
3191: n1 rows on the first processor, the next n2 rows on the second, etc.
3192: For certain parallel layouts this range may not be well defined.
3194: Not Collective
3196: Input Parameters:
3197: . mat - the matrix
3199: Output Parameters:
3200: + m - the global index of the first local row
3201: - n - one more than the global index of the last local row
3203: Level: beginner
3205: Concepts: matrices^row ownership
3206: @*/
3207: int MatGetOwnershipRange(Mat mat,int *m,int* n)
3208: {
3214: MatPreallocated(mat);
3217: if (!mat->ops->getownershiprange) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3218: (*mat->ops->getownershiprange)(mat,m,n);
3219: return(0);
3220: }
3222: /*@
3223: MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix.
3224: Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric()
3225: to complete the factorization.
3227: Collective on Mat
3229: Input Parameters:
3230: + mat - the matrix
3231: . row - row permutation
3232: . column - column permutation
3233: - info - structure containing
3234: $ levels - number of levels of fill.
3235: $ expected fill - as ratio of original fill.
3236: $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices
3237: missing diagonal entries)
3239: Output Parameters:
3240: . fact - new matrix that has been symbolically factored
3242: Notes:
3243: See the users manual for additional information about
3244: choosing the fill factor for better efficiency.
3246: Most users should employ the simplified SLES interface for linear solvers
3247: instead of working directly with matrix algebra routines such as this.
3248: See, e.g., SLESCreate().
3250: Level: developer
3252: Concepts: matrices^symbolic LU factorization
3253: Concepts: matrices^factorization
3254: Concepts: LU^symbolic factorization
3256: .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
3257: MatGetOrdering()
3259: @*/
3260: int MatILUFactorSymbolic(Mat mat,IS row,IS col,MatILUInfo *info,Mat *fact)
3261: {
3267: MatPreallocated(mat);
3269: if (info && info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %d",info->levels);
3270: if (info && info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill);
3271: if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name);
3272: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3273: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3275: PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);
3276: (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);
3277: PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);
3278: return(0);
3279: }
3281: /*@
3282: MatICCFactorSymbolic - Performs symbolic incomplete
3283: Cholesky factorization for a symmetric matrix. Use
3284: MatCholeskyFactorNumeric() to complete the factorization.
3286: Collective on Mat
3288: Input Parameters:
3289: + mat - the matrix
3290: . perm - row and column permutation
3291: . fill - levels of fill
3292: - f - expected fill as ratio of original fill
3294: Output Parameter:
3295: . fact - the factored matrix
3297: Notes:
3298: Currently only no-fill factorization is supported.
3300: Most users should employ the simplified SLES interface for linear solvers
3301: instead of working directly with matrix algebra routines such as this.
3302: See, e.g., SLESCreate().
3304: Level: developer
3306: Concepts: matrices^symbolic incomplete Cholesky factorization
3307: Concepts: matrices^factorization
3308: Concepts: Cholsky^symbolic factorization
3310: .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor()
3311: @*/
3312: int MatICCFactorSymbolic(Mat mat,IS perm,PetscReal f,int fill,Mat *fact)
3313: {
3319: MatPreallocated(mat);
3321: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3322: if (fill < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Fill negative %d",fill);
3323: if (f < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",f);
3324: if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name);
3325: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3327: PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);
3328: (*mat->ops->iccfactorsymbolic)(mat,perm,f,fill,fact);
3329: PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);
3330: return(0);
3331: }
3333: /*@C
3334: MatGetArray - Returns a pointer to the element values in the matrix.
3335: The result of this routine is dependent on the underlying matrix data
3336: structure, and may not even work for certain matrix types. You MUST
3337: call MatRestoreArray() when you no longer need to access the array.
3339: Not Collective
3341: Input Parameter:
3342: . mat - the matrix
3344: Output Parameter:
3345: . v - the location of the values
3348: Fortran Note:
3349: This routine is used differently from Fortran, e.g.,
3350: .vb
3351: Mat mat
3352: Scalar mat_array(1)
3353: PetscOffset i_mat
3354: int ierr
3355: call MatGetArray(mat,mat_array,i_mat,ierr)
3357: C Access first local entry in matrix; note that array is
3358: C treated as one dimensional
3359: value = mat_array(i_mat + 1)
3361: [... other code ...]
3362: call MatRestoreArray(mat,mat_array,i_mat,ierr)
3363: .ve
3365: See the Fortran chapter of the users manual and
3366: petsc/src/mat/examples/tests for details.
3368: Level: advanced
3370: Concepts: matrices^access array
3372: .seealso: MatRestoreArray(), MatGetArrayF90()
3373: @*/
3374: int MatGetArray(Mat mat,Scalar **v)
3375: {
3381: MatPreallocated(mat);
3383: if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3384: (*mat->ops->getarray)(mat,v);
3385: return(0);
3386: }
3388: /*@C
3389: MatRestoreArray - Restores the matrix after MatGetArray() has been called.
3391: Not Collective
3393: Input Parameter:
3394: + mat - the matrix
3395: - v - the location of the values
3397: Fortran Note:
3398: This routine is used differently from Fortran, e.g.,
3399: .vb
3400: Mat mat
3401: Scalar mat_array(1)
3402: PetscOffset i_mat
3403: int ierr
3404: call MatGetArray(mat,mat_array,i_mat,ierr)
3406: C Access first local entry in matrix; note that array is
3407: C treated as one dimensional
3408: value = mat_array(i_mat + 1)
3410: [... other code ...]
3411: call MatRestoreArray(mat,mat_array,i_mat,ierr)
3412: .ve
3414: See the Fortran chapter of the users manual and
3415: petsc/src/mat/examples/tests for details
3417: Level: advanced
3419: .seealso: MatGetArray(), MatRestoreArrayF90()
3420: @*/
3421: int MatRestoreArray(Mat mat,Scalar **v)
3422: {
3428: MatPreallocated(mat);
3430: if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3431: (*mat->ops->restorearray)(mat,v);
3432: return(0);
3433: }
3435: /*@C
3436: MatGetSubMatrices - Extracts several submatrices from a matrix. If submat
3437: points to an array of valid matrices, they may be reused to store the new
3438: submatrices.
3440: Collective on Mat
3442: Input Parameters:
3443: + mat - the matrix
3444: . n - the number of submatrixes to be extracted (on this processor, may be zero)
3445: . irow, icol - index sets of rows and columns to extract
3446: - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
3448: Output Parameter:
3449: . submat - the array of submatrices
3451: Notes:
3452: MatGetSubMatrices() can extract only sequential submatrices
3453: (from both sequential and parallel matrices). Use MatGetSubMatrix()
3454: to extract a parallel submatrix.
3456: When extracting submatrices from a parallel matrix, each processor can
3457: form a different submatrix by setting the rows and columns of its
3458: individual index sets according to the local submatrix desired.
3460: When finished using the submatrices, the user should destroy
3461: them with MatDestroySubMatrices().
3463: MAT_REUSE_MATRIX can only be used when the nonzero structure of the
3464: original matrix has not changed from that last call to MatGetSubMatrices().
3466: This routine creates the matrices submat; you should NOT create them before
3467: calling it.
3469: Fortran Note:
3470: The Fortran interface is slightly different from that given below; it
3471: requires one to pass in as submat a Mat (integer) array of size at least m.
3473: Level: advanced
3475: Concepts: matrices^accessing submatrices
3476: Concepts: submatrices
3478: .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal()
3479: @*/
3480: int MatGetSubMatrices(Mat mat,int n,IS *irow,IS *icol,MatReuse scall,Mat **submat)
3481: {
3482: int ierr;
3487: MatPreallocated(mat);
3488: if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3489: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3491: PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);
3492: (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);
3493: PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);
3494: return(0);
3495: }
3497: /*@C
3498: MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices().
3500: Collective on Mat
3502: Input Parameters:
3503: + n - the number of local matrices
3504: - mat - the matrices
3506: Level: advanced
3508: .seealso: MatGetSubMatrices()
3509: @*/
3510: int MatDestroyMatrices(int n,Mat **mat)
3511: {
3512: int ierr,i;
3515: if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %d",n);
3517: for (i=0; i<n; i++) {
3518: MatDestroy((*mat)[i]);
3519: }
3520: /* memory is allocated even if n = 0 */
3521: PetscFree(*mat);
3522: return(0);
3523: }
3525: /*@
3526: MatIncreaseOverlap - Given a set of submatrices indicated by index sets,
3527: replaces the index sets by larger ones that represent submatrices with
3528: additional overlap.
3530: Collective on Mat
3532: Input Parameters:
3533: + mat - the matrix
3534: . n - the number of index sets
3535: . is - the array of pointers to index sets
3536: - ov - the additional overlap requested
3538: Level: developer
3540: Concepts: overlap
3541: Concepts: ASM^computing overlap
3543: .seealso: MatGetSubMatrices()
3544: @*/
3545: int MatIncreaseOverlap(Mat mat,int n,IS *is,int ov)
3546: {
3552: MatPreallocated(mat);
3553: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
3554: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
3556: if (!ov) return(0);
3557: if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3558: PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);
3559: (*mat->ops->increaseoverlap)(mat,n,is,ov);
3560: PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);
3561: return(0);
3562: }
3564: /*@
3565: MatPrintHelp - Prints all the options for the matrix.
3567: Collective on Mat
3569: Input Parameter:
3570: . mat - the matrix
3572: Options Database Keys:
3573: + -help - Prints matrix options
3574: - -h - Prints matrix options
3576: Level: developer
3578: .seealso: MatCreate(), MatCreateXXX()
3579: @*/
3580: int MatPrintHelp(Mat mat)
3581: {
3582: static PetscTruth called = PETSC_FALSE;
3583: int ierr;
3584: MPI_Comm comm;
3589: MatPreallocated(mat);
3591: comm = mat->comm;
3592: if (!called) {
3593: (*PetscHelpPrintf)(comm,"General matrix options:n");
3594: (*PetscHelpPrintf)(comm," -mat_view_info: view basic matrix info during MatAssemblyEnd()n");
3595: (*PetscHelpPrintf)(comm," -mat_view_info_detailed: view detailed matrix info during MatAssemblyEnd()n");
3596: (*PetscHelpPrintf)(comm," -mat_view_draw: draw nonzero matrix structure during MatAssemblyEnd()n");
3597: (*PetscHelpPrintf)(comm," -draw_pause <sec>: set seconds of display pausen");
3598: (*PetscHelpPrintf)(comm," -display <name>: set alternate displayn");
3599: called = PETSC_TRUE;
3600: }
3601: if (mat->ops->printhelp) {
3602: (*mat->ops->printhelp)(mat);
3603: }
3604: return(0);
3605: }
3607: /*@
3608: MatGetBlockSize - Returns the matrix block size; useful especially for the
3609: block row and block diagonal formats.
3610:
3611: Not Collective
3613: Input Parameter:
3614: . mat - the matrix
3616: Output Parameter:
3617: . bs - block size
3619: Notes:
3620: Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG.
3621: Block row formats are MATSEQBAIJ, MATMPIBAIJ
3623: Level: intermediate
3625: Concepts: matrices^block size
3627: .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag()
3628: @*/
3629: int MatGetBlockSize(Mat mat,int *bs)
3630: {
3636: MatPreallocated(mat);
3638: if (!mat->ops->getblocksize) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
3639: (*mat->ops->getblocksize)(mat,bs);
3640: return(0);
3641: }
3643: /*@C
3644: MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices.
3646: Collective on Mat
3648: Input Parameters:
3649: + mat - the matrix
3650: . shift - 0 or 1 indicating we want the indices starting at 0 or 1
3651: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3652: symmetrized
3654: Output Parameters:
3655: + n - number of rows in the (possibly compressed) matrix
3656: . ia - the row pointers
3657: . ja - the column indices
3658: - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned
3660: Level: developer
3662: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
3663: @*/
3664: int MatGetRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3665: {
3671: MatPreallocated(mat);
3675: if (!mat->ops->getrowij) *done = PETSC_FALSE;
3676: else {
3677: *done = PETSC_TRUE;
3678: ierr = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);
3679: }
3680: return(0);
3681: }
3683: /*@C
3684: MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices.
3686: Collective on Mat
3688: Input Parameters:
3689: + mat - the matrix
3690: . shift - 1 or zero indicating we want the indices starting at 0 or 1
3691: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3692: symmetrized
3694: Output Parameters:
3695: + n - number of columns in the (possibly compressed) matrix
3696: . ia - the column pointers
3697: . ja - the row indices
3698: - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned
3700: Level: developer
3702: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
3703: @*/
3704: int MatGetColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3705: {
3711: MatPreallocated(mat);
3716: if (!mat->ops->getcolumnij) *done = PETSC_FALSE;
3717: else {
3718: *done = PETSC_TRUE;
3719: ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);
3720: }
3721: return(0);
3722: }
3724: /*@C
3725: MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with
3726: MatGetRowIJ().
3728: Collective on Mat
3730: Input Parameters:
3731: + mat - the matrix
3732: . shift - 1 or zero indicating we want the indices starting at 0 or 1
3733: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3734: symmetrized
3736: Output Parameters:
3737: + n - size of (possibly compressed) matrix
3738: . ia - the row pointers
3739: . ja - the column indices
3740: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
3742: Level: developer
3744: .seealso: MatGetRowIJ(), MatRestoreColumnIJ()
3745: @*/
3746: int MatRestoreRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3747: {
3753: MatPreallocated(mat);
3758: if (!mat->ops->restorerowij) *done = PETSC_FALSE;
3759: else {
3760: *done = PETSC_TRUE;
3761: ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);
3762: }
3763: return(0);
3764: }
3766: /*@C
3767: MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with
3768: MatGetColumnIJ().
3770: Collective on Mat
3772: Input Parameters:
3773: + mat - the matrix
3774: . shift - 1 or zero indicating we want the indices starting at 0 or 1
3775: - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be
3776: symmetrized
3778: Output Parameters:
3779: + n - size of (possibly compressed) matrix
3780: . ia - the column pointers
3781: . ja - the row indices
3782: - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned
3784: Level: developer
3786: .seealso: MatGetColumnIJ(), MatRestoreRowIJ()
3787: @*/
3788: int MatRestoreColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done)
3789: {
3795: MatPreallocated(mat);
3800: if (!mat->ops->restorecolumnij) *done = PETSC_FALSE;
3801: else {
3802: *done = PETSC_TRUE;
3803: ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);
3804: }
3805: return(0);
3806: }
3808: /*@C
3809: MatColoringPatch -Used inside matrix coloring routines that
3810: use MatGetRowIJ() and/or MatGetColumnIJ().
3812: Collective on Mat
3814: Input Parameters:
3815: + mat - the matrix
3816: . n - number of colors
3817: - colorarray - array indicating color for each column
3819: Output Parameters:
3820: . iscoloring - coloring generated using colorarray information
3822: Level: developer
3824: .seealso: MatGetRowIJ(), MatGetColumnIJ()
3826: @*/
3827: int MatColoringPatch(Mat mat,int n,int ncolors,int *colorarray,ISColoring *iscoloring)
3828: {
3834: MatPreallocated(mat);
3837: if (!mat->ops->coloringpatch){
3838: ISColoringCreate(mat->comm,n,colorarray,iscoloring);
3839: } else {
3840: (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);
3841: }
3842: return(0);
3843: }
3846: /*@
3847: MatSetUnfactored - Resets a factored matrix to be treated as unfactored.
3849: Collective on Mat
3851: Input Parameter:
3852: . mat - the factored matrix to be reset
3854: Notes:
3855: This routine should be used only with factored matrices formed by in-place
3856: factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE
3857: format). This option can save memory, for example, when solving nonlinear
3858: systems with a matrix-free Newton-Krylov method and a matrix-based, in-place
3859: ILU(0) preconditioner.
3861: Note that one can specify in-place ILU(0) factorization by calling
3862: .vb
3863: PCType(pc,PCILU);
3864: PCILUSeUseInPlace(pc);
3865: .ve
3866: or by using the options -pc_type ilu -pc_ilu_in_place
3868: In-place factorization ILU(0) can also be used as a local
3869: solver for the blocks within the block Jacobi or additive Schwarz
3870: methods (runtime option: -sub_pc_ilu_in_place). See the discussion
3871: of these preconditioners in the users manual for details on setting
3872: local solver options.
3874: Most users should employ the simplified SLES interface for linear solvers
3875: instead of working directly with matrix algebra routines such as this.
3876: See, e.g., SLESCreate().
3878: Level: developer
3880: .seealso: PCILUSetUseInPlace(), PCLUSetUseInPlace()
3882: Concepts: matrices^unfactored
3884: @*/
3885: int MatSetUnfactored(Mat mat)
3886: {
3892: MatPreallocated(mat);
3893: mat->factor = 0;
3894: if (!mat->ops->setunfactored) return(0);
3895: (*mat->ops->setunfactored)(mat);
3896: return(0);
3897: }
3899: /*MC
3900: MatGetArrayF90 - Accesses a matrix array from Fortran90.
3902: Synopsis:
3903: MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
3905: Not collective
3907: Input Parameter:
3908: . x - matrix
3910: Output Parameters:
3911: + xx_v - the Fortran90 pointer to the array
3912: - ierr - error code
3914: Example of Usage:
3915: .vb
3916: Scalar, pointer xx_v(:)
3917: ....
3918: call MatGetArrayF90(x,xx_v,ierr)
3919: a = xx_v(3)
3920: call MatRestoreArrayF90(x,xx_v,ierr)
3921: .ve
3923: Notes:
3924: Not yet supported for all F90 compilers
3926: Level: advanced
3928: .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray()
3930: Concepts: matrices^accessing array
3932: M*/
3934: /*MC
3935: MatRestoreArrayF90 - Restores a matrix array that has been
3936: accessed with MatGetArrayF90().
3938: Synopsis:
3939: MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr)
3941: Not collective
3943: Input Parameters:
3944: + x - matrix
3945: - xx_v - the Fortran90 pointer to the array
3947: Output Parameter:
3948: . ierr - error code
3950: Example of Usage:
3951: .vb
3952: Scalar, pointer xx_v(:)
3953: ....
3954: call MatGetArrayF90(x,xx_v,ierr)
3955: a = xx_v(3)
3956: call MatRestoreArrayF90(x,xx_v,ierr)
3957: .ve
3958:
3959: Notes:
3960: Not yet supported for all F90 compilers
3962: Level: advanced
3964: .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray()
3966: M*/
3969: /*@
3970: MatGetSubMatrix - Gets a single submatrix on the same number of processors
3971: as the original matrix.
3973: Collective on Mat
3975: Input Parameters:
3976: + mat - the original matrix
3977: . isrow - rows this processor should obtain
3978: . iscol - columns for all processors you wish to keep
3979: . csize - number of columns "local" to this processor (does nothing for sequential
3980: matrices). This should match the result from VecGetLocalSize(x,...) if you
3981: plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE
3982: - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX
3984: Output Parameter:
3985: . newmat - the new submatrix, of the same type as the old
3987: Level: advanced
3989: Notes: the iscol argument MUST be the same on each processor.
3991: The first time this is called you should use a cll of MAT_INITIAL_MATRIX,
3992: the MatGetSubMatrix() routine will create the newmat for you. Any additional calls
3993: to this routine with a mat of the same nonzero structure will reuse the matrix
3994: generated the first time.
3996: Concepts: matrices^submatrices
3998: .seealso: MatGetSubMatrices()
3999: @*/
4000: int MatGetSubMatrix(Mat mat,IS isrow,IS iscol,int csize,MatReuse cll,Mat *newmat)
4001: {
4002: int ierr, size;
4003: Mat *local;
4007: MatPreallocated(mat);
4008: MPI_Comm_size(mat->comm,&size);
4010: /* if original matrix is on just one processor then use submatrix generated */
4011: if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) {
4012: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);
4013: return(0);
4014: } else if (!mat->ops->getsubmatrix && size == 1) {
4015: MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);
4016: *newmat = *local;
4017: PetscFree(local);
4018: return(0);
4019: }
4021: if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4022: (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);
4023: return(0);
4024: }
4026: /*@C
4027: MatGetMaps - Returns the maps associated with the matrix.
4029: Not Collective
4031: Input Parameter:
4032: . mat - the matrix
4034: Output Parameters:
4035: + rmap - the row (right) map
4036: - cmap - the column (left) map
4038: Level: developer
4040: Concepts: maps^getting from matrix
4042: @*/
4043: int MatGetMaps(Mat mat,Map *rmap,Map *cmap)
4044: {
4050: MatPreallocated(mat);
4051: (*mat->ops->getmaps)(mat,rmap,cmap);
4052: return(0);
4053: }
4055: /*
4056: Version that works for all PETSc matrices
4057: */
4058: int MatGetMaps_Petsc(Mat mat,Map *rmap,Map *cmap)
4059: {
4061: if (rmap) *rmap = mat->rmap;
4062: if (cmap) *cmap = mat->cmap;
4063: return(0);
4064: }
4066: /*@
4067: MatSetStashInitialSize - sets the sizes of the matrix stash, that is
4068: used during the assembly process to store values that belong to
4069: other processors.
4071: Not Collective
4073: Input Parameters:
4074: + mat - the matrix
4075: . size - the initial size of the stash.
4076: - bsize - the initial size of the block-stash(if used).
4078: Options Database Keys:
4079: + -matstash_initial_size <size> or <size0,size1,...sizep-1>
4080: - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
4082: Level: intermediate
4084: Notes:
4085: The block-stash is used for values set with VecSetValuesBlocked() while
4086: the stash is used for values set with VecSetValues()
4088: Run with the option -log_info and look for output of the form
4089: MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
4090: to determine the appropriate value, MM, to use for size and
4091: MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
4092: to determine the value, BMM to use for bsize
4094: Concepts: stash^setting matrix size
4095: Concepts: matrices^stash
4097: @*/
4098: int MatSetStashInitialSize(Mat mat,int size, int bsize)
4099: {
4105: MatPreallocated(mat);
4106: MatStashSetInitialSize_Private(&mat->stash,size);
4107: MatStashSetInitialSize_Private(&mat->bstash,bsize);
4108: return(0);
4109: }
4111: /*@
4112: MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of
4113: the matrix
4115: Collective on Mat
4117: Input Parameters:
4118: + mat - the matrix
4119: . x,y - the vectors
4120: - w - where the result is stored
4122: Level: intermediate
4124: Notes:
4125: w may be the same vector as y.
4127: This allows one to use either the restriction or interpolation (its transpose)
4128: matrix to do the interpolation
4130: Concepts: interpolation
4132: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
4134: @*/
4135: int MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w)
4136: {
4137: int M,N,ierr;
4141: MatPreallocated(A);
4142: MatGetSize(A,&M,&N);
4143: if (N > M) {
4144: MatMultTransposeAdd(A,x,y,w);
4145: } else {
4146: MatMultAdd(A,x,y,w);
4147: }
4148: return(0);
4149: }
4151: /*@
4152: MatInterpolate - y = A*x or A'*x depending on the shape of
4153: the matrix
4155: Collective on Mat
4157: Input Parameters:
4158: + mat - the matrix
4159: - x,y - the vectors
4161: Level: intermediate
4163: Notes:
4164: This allows one to use either the restriction or interpolation (its transpose)
4165: matrix to do the interpolation
4167: Concepts: matrices^interpolation
4169: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict()
4171: @*/
4172: int MatInterpolate(Mat A,Vec x,Vec y)
4173: {
4174: int M,N,ierr;
4178: MatPreallocated(A);
4179: MatGetSize(A,&M,&N);
4180: if (N > M) {
4181: MatMultTranspose(A,x,y);
4182: } else {
4183: MatMult(A,x,y);
4184: }
4185: return(0);
4186: }
4188: /*@
4189: MatRestrict - y = A*x or A'*x
4191: Collective on Mat
4193: Input Parameters:
4194: + mat - the matrix
4195: - x,y - the vectors
4197: Level: intermediate
4199: Notes:
4200: This allows one to use either the restriction or interpolation (its transpose)
4201: matrix to do the restriction
4203: Concepts: matrices^restriction
4205: .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate()
4207: @*/
4208: int MatRestrict(Mat A,Vec x,Vec y)
4209: {
4210: int M,N,ierr;
4214: MatPreallocated(A);
4215: MatGetSize(A,&M,&N);
4216: if (N > M) {
4217: MatMult(A,x,y);
4218: } else {
4219: MatMultTranspose(A,x,y);
4220: }
4221: return(0);
4222: }
4224: /*@C
4225: MatNullSpaceAttach - attaches a null space to a matrix.
4226: This null space will be removed from the resulting vector whenever
4227: MatMult() is called
4229: Collective on Mat
4231: Input Parameters:
4232: + mat - the matrix
4233: - nullsp - the null space object
4235: Level: developer
4237: Notes:
4238: Overwrites any previous null space that may have been attached
4240: Concepts: null space^attaching to matrix
4242: .seealso: MatCreate(), MatNullSpaceCreate()
4243: @*/
4244: int MatNullSpaceAttach(Mat mat,MatNullSpace nullsp)
4245: {
4251: MatPreallocated(mat);
4254: if (mat->nullsp) {
4255: MatNullSpaceDestroy(mat->nullsp);
4256: }
4257: mat->nullsp = nullsp;
4258: PetscObjectReference((PetscObject)nullsp);
4259: return(0);
4260: }
4262: /*@
4263: MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix.
4265: Collective on Mat
4267: Input Parameters:
4268: + mat - the matrix
4269: . row - row/column permutation
4270: . fill - expected fill factor >= 1.0
4271: - level - level of fill, for ICC(k)
4273: Notes:
4274: Probably really in-place only when level of fill is zero, otherwise allocates
4275: new space to store factored matrix and deletes previous memory.
4277: Most users should employ the simplified SLES interface for linear solvers
4278: instead of working directly with matrix algebra routines such as this.
4279: See, e.g., SLESCreate().
4281: Level: developer
4283: Concepts: matrices^incomplete Cholesky factorization
4284: Concepts: Cholesky factorization
4286: .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor()
4287: @*/
4288: int MatICCFactor(Mat mat,IS row,PetscReal fill,int level)
4289: {
4295: MatPreallocated(mat);
4296: if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square");
4297: if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
4298: if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
4299: if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name);
4300: (*mat->ops->iccfactor)(mat,row,fill,level);
4301: return(0);
4302: }