1 #define PETSCMAT_DLL 2 3 /* 4 This is where the abstract matrix operations are defined 5 */ 6 7 #include "src/mat/matimpl.h" /*I "petscmat.h" I*/ 8 #include "private/vecimpl.h" 9 10 /* Logging support */ 11 PetscCookie PETSCMAT_DLLEXPORT MAT_COOKIE = 0; 12 PetscEvent MAT_Mult = 0, MAT_Mults = 0, MAT_MultConstrained = 0, MAT_MultAdd = 0, MAT_MultTranspose = 0; 13 PetscEvent MAT_MultTransposeConstrained = 0, MAT_MultTransposeAdd = 0, MAT_Solve = 0, MAT_Solves = 0, MAT_SolveAdd = 0, MAT_SolveTranspose = 0, MAT_MatSolve = 0; 14 PetscEvent MAT_SolveTransposeAdd = 0, MAT_Relax = 0, MAT_ForwardSolve = 0, MAT_BackwardSolve = 0, MAT_LUFactor = 0, MAT_LUFactorSymbolic = 0; 15 PetscEvent MAT_LUFactorNumeric = 0, MAT_CholeskyFactor = 0, MAT_CholeskyFactorSymbolic = 0, MAT_CholeskyFactorNumeric = 0, MAT_ILUFactor = 0; 16 PetscEvent MAT_ILUFactorSymbolic = 0, MAT_ICCFactorSymbolic = 0, MAT_Copy = 0, MAT_Convert = 0, MAT_Scale = 0, MAT_AssemblyBegin = 0; 17 PetscEvent MAT_AssemblyEnd = 0, MAT_SetValues = 0, MAT_GetValues = 0, MAT_GetRow = 0, MAT_GetSubMatrices = 0, MAT_GetColoring = 0, MAT_GetOrdering = 0; 18 PetscEvent MAT_IncreaseOverlap = 0, MAT_Partitioning = 0, MAT_ZeroEntries = 0, MAT_Load = 0, MAT_View = 0, MAT_AXPY = 0, MAT_FDColoringCreate = 0; 19 PetscEvent MAT_FDColoringApply = 0,MAT_Transpose = 0,MAT_FDColoringFunction = 0; 20 PetscEvent MAT_MatMult = 0, MAT_MatMultSymbolic = 0, MAT_MatMultNumeric = 0; 21 PetscEvent MAT_PtAP = 0, MAT_PtAPSymbolic = 0, MAT_PtAPNumeric = 0; 22 PetscEvent MAT_MatMultTranspose = 0, MAT_MatMultTransposeSymbolic = 0, MAT_MatMultTransposeNumeric = 0; 23 24 /* nasty global values for MatSetValue() */ 25 PetscInt PETSCMAT_DLLEXPORT MatSetValue_Row = 0; 26 PetscInt PETSCMAT_DLLEXPORT MatSetValue_Column = 0; 27 PetscScalar PETSCMAT_DLLEXPORT MatSetValue_Value = 0.0; 28 29 #undef __FUNCT__ 30 #define __FUNCT__ "MatRealPart" 31 /*@ 32 MatRealPart - Zeros out the imaginary part of the matrix 33 34 Collective on Mat 35 36 Input Parameters: 37 . mat - the matrix 38 39 Level: advanced 40 41 42 .seealso: MatImaginaryPart() 43 @*/ 44 45 PetscErrorCode PETSCMAT_DLLEXPORT MatRealPart(Mat mat) 46 { 47 PetscErrorCode ierr; 48 49 PetscFunctionBegin; 50 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 51 PetscValidType(mat,1); 52 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 53 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 54 if (!mat->ops->realpart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 55 ierr = MatPreallocated(mat);CHKERRQ(ierr); 56 ierr = (*mat->ops->realpart)(mat);CHKERRQ(ierr); 57 PetscFunctionReturn(0); 58 } 59 60 #undef __FUNCT__ 61 #define __FUNCT__ "MatImaginaryPart" 62 /*@ 63 MatImaginaryPart - Moves the imaginary part of the matrix to the real part and zeros the imaginary part 64 65 Collective on Mat 66 67 Input Parameters: 68 . mat - the matrix 69 70 Level: advanced 71 72 73 .seealso: MatRealPart() 74 @*/ 75 76 PetscErrorCode PETSCMAT_DLLEXPORT MatImaginaryPart(Mat mat) 77 { 78 PetscErrorCode ierr; 79 80 PetscFunctionBegin; 81 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 82 PetscValidType(mat,1); 83 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 84 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 85 if (!mat->ops->imaginarypart) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 86 ierr = MatPreallocated(mat);CHKERRQ(ierr); 87 ierr = (*mat->ops->imaginarypart)(mat);CHKERRQ(ierr); 88 PetscFunctionReturn(0); 89 } 90 91 #undef __FUNCT__ 92 #define __FUNCT__ "MatGetRow" 93 /*@C 94 MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow() 95 for each row that you get to ensure that your application does 96 not bleed memory. 97 98 Not Collective 99 100 Input Parameters: 101 + mat - the matrix 102 - row - the row to get 103 104 Output Parameters: 105 + ncols - if not NULL, the number of nonzeros in the row 106 . cols - if not NULL, the column numbers 107 - vals - if not NULL, the values 108 109 Notes: 110 This routine is provided for people who need to have direct access 111 to the structure of a matrix. We hope that we provide enough 112 high-level matrix routines that few users will need it. 113 114 MatGetRow() always returns 0-based column indices, regardless of 115 whether the internal representation is 0-based (default) or 1-based. 116 117 For better efficiency, set cols and/or vals to PETSC_NULL if you do 118 not wish to extract these quantities. 119 120 The user can only examine the values extracted with MatGetRow(); 121 the values cannot be altered. To change the matrix entries, one 122 must use MatSetValues(). 123 124 You can only have one call to MatGetRow() outstanding for a particular 125 matrix at a time, per processor. MatGetRow() can only obtain rows 126 associated with the given processor, it cannot get rows from the 127 other processors; for that we suggest using MatGetSubMatrices(), then 128 MatGetRow() on the submatrix. The row indix passed to MatGetRows() 129 is in the global number of rows. 130 131 Fortran Notes: 132 The calling sequence from Fortran is 133 .vb 134 MatGetRow(matrix,row,ncols,cols,values,ierr) 135 Mat matrix (input) 136 integer row (input) 137 integer ncols (output) 138 integer cols(maxcols) (output) 139 double precision (or double complex) values(maxcols) output 140 .ve 141 where maxcols >= maximum nonzeros in any row of the matrix. 142 143 144 Caution: 145 Do not try to change the contents of the output arrays (cols and vals). 146 In some cases, this may corrupt the matrix. 147 148 Level: advanced 149 150 Concepts: matrices^row access 151 152 .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal() 153 @*/ 154 155 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[]) 156 { 157 PetscErrorCode ierr; 158 PetscInt incols; 159 160 PetscFunctionBegin; 161 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 162 PetscValidType(mat,1); 163 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 164 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 165 if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 166 ierr = MatPreallocated(mat);CHKERRQ(ierr); 167 ierr = PetscLogEventBegin(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 168 ierr = (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);CHKERRQ(ierr); 169 if (ncols) *ncols = incols; 170 ierr = PetscLogEventEnd(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 171 PetscFunctionReturn(0); 172 } 173 174 #undef __FUNCT__ 175 #define __FUNCT__ "MatConjugate" 176 /*@ 177 MatConjugate - replaces the matrix values with their complex conjugates 178 179 Collective on Mat 180 181 Input Parameters: 182 . mat - the matrix 183 184 Level: advanced 185 186 .seealso: VecConjugate() 187 @*/ 188 PetscErrorCode PETSCMAT_DLLEXPORT MatConjugate(Mat mat) 189 { 190 PetscErrorCode ierr; 191 192 PetscFunctionBegin; 193 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 194 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 195 if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov"); 196 ierr = (*mat->ops->conjugate)(mat);CHKERRQ(ierr); 197 PetscFunctionReturn(0); 198 } 199 200 #undef __FUNCT__ 201 #define __FUNCT__ "MatRestoreRow" 202 /*@C 203 MatRestoreRow - Frees any temporary space allocated by MatGetRow(). 204 205 Not Collective 206 207 Input Parameters: 208 + mat - the matrix 209 . row - the row to get 210 . ncols, cols - the number of nonzeros and their columns 211 - vals - if nonzero the column values 212 213 Notes: 214 This routine should be called after you have finished examining the entries. 215 216 Fortran Notes: 217 The calling sequence from Fortran is 218 .vb 219 MatRestoreRow(matrix,row,ncols,cols,values,ierr) 220 Mat matrix (input) 221 integer row (input) 222 integer ncols (output) 223 integer cols(maxcols) (output) 224 double precision (or double complex) values(maxcols) output 225 .ve 226 Where maxcols >= maximum nonzeros in any row of the matrix. 227 228 In Fortran MatRestoreRow() MUST be called after MatGetRow() 229 before another call to MatGetRow() can be made. 230 231 Level: advanced 232 233 .seealso: MatGetRow() 234 @*/ 235 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[]) 236 { 237 PetscErrorCode ierr; 238 239 PetscFunctionBegin; 240 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 241 PetscValidIntPointer(ncols,3); 242 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 243 if (!mat->ops->restorerow) PetscFunctionReturn(0); 244 ierr = (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);CHKERRQ(ierr); 245 PetscFunctionReturn(0); 246 } 247 248 #undef __FUNCT__ 249 #define __FUNCT__ "MatGetRowUpperTriangular" 250 /*@C 251 MatGetRowUpperTriangular - Sets a flag to enable calls to MatGetRow() for matrix in MATSBAIJ format. 252 You should call MatRestoreRowUpperTriangular() after calling MatGetRow/MatRestoreRow() to disable the flag. 253 254 Not Collective 255 256 Input Parameters: 257 + mat - the matrix 258 259 Notes: 260 The flag is to ensure that users are aware of MatGetRow() only provides the upper trianglular part of the row for the matrices in MATSBAIJ format. 261 262 Level: advanced 263 264 Concepts: matrices^row access 265 266 .seealso: MatRestoreRowRowUpperTriangular() 267 @*/ 268 269 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowUpperTriangular(Mat mat) 270 { 271 PetscErrorCode ierr; 272 273 PetscFunctionBegin; 274 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 275 PetscValidType(mat,1); 276 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 277 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 278 if (!mat->ops->getrowuppertriangular) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 279 ierr = MatPreallocated(mat);CHKERRQ(ierr); 280 ierr = (*mat->ops->getrowuppertriangular)(mat);CHKERRQ(ierr); 281 PetscFunctionReturn(0); 282 } 283 284 #undef __FUNCT__ 285 #define __FUNCT__ "MatRestoreRowUpperTriangular" 286 /*@C 287 MatRestoreRowUpperTriangular - Disable calls to MatGetRow() for matrix in MATSBAIJ format. 288 289 Not Collective 290 291 Input Parameters: 292 + mat - the matrix 293 294 Notes: 295 This routine should be called after you have finished MatGetRow/MatRestoreRow(). 296 297 298 Level: advanced 299 300 .seealso: MatGetRowUpperTriangular() 301 @*/ 302 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowUpperTriangular(Mat mat) 303 { 304 PetscErrorCode ierr; 305 306 PetscFunctionBegin; 307 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 308 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 309 if (!mat->ops->restorerowuppertriangular) PetscFunctionReturn(0); 310 ierr = (*mat->ops->restorerowuppertriangular)(mat);CHKERRQ(ierr); 311 PetscFunctionReturn(0); 312 } 313 314 #undef __FUNCT__ 315 #define __FUNCT__ "MatSetOptionsPrefix" 316 /*@C 317 MatSetOptionsPrefix - Sets the prefix used for searching for all 318 Mat options in the database. 319 320 Collective on Mat 321 322 Input Parameter: 323 + A - the Mat context 324 - prefix - the prefix to prepend to all option names 325 326 Notes: 327 A hyphen (-) must NOT be given at the beginning of the prefix name. 328 The first character of all runtime options is AUTOMATICALLY the hyphen. 329 330 Level: advanced 331 332 .keywords: Mat, set, options, prefix, database 333 334 .seealso: MatSetFromOptions() 335 @*/ 336 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOptionsPrefix(Mat A,const char prefix[]) 337 { 338 PetscErrorCode ierr; 339 340 PetscFunctionBegin; 341 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 342 ierr = PetscObjectSetOptionsPrefix((PetscObject)A,prefix);CHKERRQ(ierr); 343 PetscFunctionReturn(0); 344 } 345 346 #undef __FUNCT__ 347 #define __FUNCT__ "MatAppendOptionsPrefix" 348 /*@C 349 MatAppendOptionsPrefix - Appends to the prefix used for searching for all 350 Mat options in the database. 351 352 Collective on Mat 353 354 Input Parameters: 355 + A - the Mat context 356 - prefix - the prefix to prepend to all option names 357 358 Notes: 359 A hyphen (-) must NOT be given at the beginning of the prefix name. 360 The first character of all runtime options is AUTOMATICALLY the hyphen. 361 362 Level: advanced 363 364 .keywords: Mat, append, options, prefix, database 365 366 .seealso: MatGetOptionsPrefix() 367 @*/ 368 PetscErrorCode PETSCMAT_DLLEXPORT MatAppendOptionsPrefix(Mat A,const char prefix[]) 369 { 370 PetscErrorCode ierr; 371 372 PetscFunctionBegin; 373 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 374 ierr = PetscObjectAppendOptionsPrefix((PetscObject)A,prefix);CHKERRQ(ierr); 375 PetscFunctionReturn(0); 376 } 377 378 #undef __FUNCT__ 379 #define __FUNCT__ "MatGetOptionsPrefix" 380 /*@C 381 MatGetOptionsPrefix - Sets the prefix used for searching for all 382 Mat options in the database. 383 384 Not Collective 385 386 Input Parameter: 387 . A - the Mat context 388 389 Output Parameter: 390 . prefix - pointer to the prefix string used 391 392 Notes: On the fortran side, the user should pass in a string 'prefix' of 393 sufficient length to hold the prefix. 394 395 Level: advanced 396 397 .keywords: Mat, get, options, prefix, database 398 399 .seealso: MatAppendOptionsPrefix() 400 @*/ 401 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOptionsPrefix(Mat A,const char *prefix[]) 402 { 403 PetscErrorCode ierr; 404 405 PetscFunctionBegin; 406 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 407 ierr = PetscObjectGetOptionsPrefix((PetscObject)A,prefix);CHKERRQ(ierr); 408 PetscFunctionReturn(0); 409 } 410 411 #undef __FUNCT__ 412 #define __FUNCT__ "MatSetUp" 413 /*@ 414 MatSetUp - Sets up the internal matrix data structures for the later use. 415 416 Collective on Mat 417 418 Input Parameters: 419 . A - the Mat context 420 421 Notes: 422 For basic use of the Mat classes the user need not explicitly call 423 MatSetUp(), since these actions will happen automatically. 424 425 Level: advanced 426 427 .keywords: Mat, setup 428 429 .seealso: MatCreate(), MatDestroy() 430 @*/ 431 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUp(Mat A) 432 { 433 PetscErrorCode ierr; 434 435 PetscFunctionBegin; 436 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 437 ierr = MatSetUpPreallocation(A);CHKERRQ(ierr); 438 ierr = MatSetFromOptions(A);CHKERRQ(ierr); 439 PetscFunctionReturn(0); 440 } 441 442 #undef __FUNCT__ 443 #define __FUNCT__ "MatView" 444 /*@C 445 MatView - Visualizes a matrix object. 446 447 Collective on Mat 448 449 Input Parameters: 450 + mat - the matrix 451 - viewer - visualization context 452 453 Notes: 454 The available visualization contexts include 455 + PETSC_VIEWER_STDOUT_SELF - standard output (default) 456 . PETSC_VIEWER_STDOUT_WORLD - synchronized standard 457 output where only the first processor opens 458 the file. All other processors send their 459 data to the first processor to print. 460 - PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure 461 462 The user can open alternative visualization contexts with 463 + PetscViewerASCIIOpen() - Outputs matrix to a specified file 464 . PetscViewerBinaryOpen() - Outputs matrix in binary to a 465 specified file; corresponding input uses MatLoad() 466 . PetscViewerDrawOpen() - Outputs nonzero matrix structure to 467 an X window display 468 - PetscViewerSocketOpen() - Outputs matrix to Socket viewer. 469 Currently only the sequential dense and AIJ 470 matrix types support the Socket viewer. 471 472 The user can call PetscViewerSetFormat() to specify the output 473 format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF, 474 PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include 475 + PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents 476 . PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format 477 . PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros 478 . PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 479 format common among all matrix types 480 . PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 481 format (which is in many cases the same as the default) 482 . PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix 483 size and structure (not the matrix entries) 484 . PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about 485 the matrix structure 486 487 Options Database Keys: 488 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 489 . -mat_view_info_detailed - Prints more detailed info 490 . -mat_view - Prints matrix in ASCII format 491 . -mat_view_matlab - Prints matrix in Matlab format 492 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 493 . -display <name> - Sets display name (default is host) 494 . -draw_pause <sec> - Sets number of seconds to pause after display 495 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 496 . -viewer_socket_machine <machine> 497 . -viewer_socket_port <port> 498 . -mat_view_binary - save matrix to file in binary format 499 - -viewer_binary_filename <name> 500 Level: beginner 501 502 Concepts: matrices^viewing 503 Concepts: matrices^plotting 504 Concepts: matrices^printing 505 506 .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 507 PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad() 508 @*/ 509 PetscErrorCode PETSCMAT_DLLEXPORT MatView(Mat mat,PetscViewer viewer) 510 { 511 PetscErrorCode ierr; 512 PetscInt rows,cols; 513 PetscTruth iascii; 514 const char *cstr; 515 PetscViewerFormat format; 516 517 PetscFunctionBegin; 518 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 519 PetscValidType(mat,1); 520 if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm); 521 PetscValidHeaderSpecific(viewer,PETSC_VIEWER_COOKIE,2); 522 PetscCheckSameComm(mat,1,viewer,2); 523 if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix"); 524 ierr = MatPreallocated(mat);CHKERRQ(ierr); 525 526 ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);CHKERRQ(ierr); 527 if (iascii) { 528 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 529 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 530 if (mat->prefix) { 531 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);CHKERRQ(ierr); 532 } else { 533 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");CHKERRQ(ierr); 534 } 535 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 536 ierr = MatGetType(mat,&cstr);CHKERRQ(ierr); 537 ierr = MatGetSize(mat,&rows,&cols);CHKERRQ(ierr); 538 ierr = PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);CHKERRQ(ierr); 539 if (mat->ops->getinfo) { 540 MatInfo info; 541 ierr = MatGetInfo(mat,MAT_GLOBAL_SUM,&info);CHKERRQ(ierr); 542 ierr = PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n", 543 (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);CHKERRQ(ierr); 544 } 545 } 546 } 547 if (mat->ops->view) { 548 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 549 ierr = (*mat->ops->view)(mat,viewer);CHKERRQ(ierr); 550 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 551 } else if (!iascii) { 552 SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name); 553 } 554 if (iascii) { 555 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 556 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 557 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 558 } 559 } 560 PetscFunctionReturn(0); 561 } 562 563 #undef __FUNCT__ 564 #define __FUNCT__ "MatScaleSystem" 565 /*@C 566 MatScaleSystem - Scale a vector solution and right hand side to 567 match the scaling of a scaled matrix. 568 569 Collective on Mat 570 571 Input Parameter: 572 + mat - the matrix 573 . b - right hand side vector (or PETSC_NULL) 574 - x - solution vector (or PETSC_NULL) 575 576 577 Notes: 578 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 579 internally scaled, so this does nothing. For MPIROWBS it 580 permutes and diagonally scales. 581 582 The KSP methods automatically call this routine when required 583 (via PCPreSolve()) so it is rarely used directly. 584 585 Level: Developer 586 587 Concepts: matrices^scaling 588 589 .seealso: MatUseScaledForm(), MatUnScaleSystem() 590 @*/ 591 PetscErrorCode PETSCMAT_DLLEXPORT MatScaleSystem(Mat mat,Vec b,Vec x) 592 { 593 PetscErrorCode ierr; 594 595 PetscFunctionBegin; 596 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 597 PetscValidType(mat,1); 598 ierr = MatPreallocated(mat);CHKERRQ(ierr); 599 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 600 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 601 602 if (mat->ops->scalesystem) { 603 ierr = (*mat->ops->scalesystem)(mat,b,x);CHKERRQ(ierr); 604 } 605 PetscFunctionReturn(0); 606 } 607 608 #undef __FUNCT__ 609 #define __FUNCT__ "MatUnScaleSystem" 610 /*@C 611 MatUnScaleSystem - Unscales a vector solution and right hand side to 612 match the original scaling of a scaled matrix. 613 614 Collective on Mat 615 616 Input Parameter: 617 + mat - the matrix 618 . b - right hand side vector (or PETSC_NULL) 619 - x - solution vector (or PETSC_NULL) 620 621 622 Notes: 623 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 624 internally scaled, so this does nothing. For MPIROWBS it 625 permutes and diagonally scales. 626 627 The KSP methods automatically call this routine when required 628 (via PCPreSolve()) so it is rarely used directly. 629 630 Level: Developer 631 632 .seealso: MatUseScaledForm(), MatScaleSystem() 633 @*/ 634 PetscErrorCode PETSCMAT_DLLEXPORT MatUnScaleSystem(Mat mat,Vec b,Vec x) 635 { 636 PetscErrorCode ierr; 637 638 PetscFunctionBegin; 639 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 640 PetscValidType(mat,1); 641 ierr = MatPreallocated(mat);CHKERRQ(ierr); 642 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 643 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 644 if (mat->ops->unscalesystem) { 645 ierr = (*mat->ops->unscalesystem)(mat,b,x);CHKERRQ(ierr); 646 } 647 PetscFunctionReturn(0); 648 } 649 650 #undef __FUNCT__ 651 #define __FUNCT__ "MatUseScaledForm" 652 /*@C 653 MatUseScaledForm - For matrix storage formats that scale the 654 matrix (for example MPIRowBS matrices are diagonally scaled on 655 assembly) indicates matrix operations (MatMult() etc) are 656 applied using the scaled matrix. 657 658 Collective on Mat 659 660 Input Parameter: 661 + mat - the matrix 662 - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 663 applying the original matrix 664 665 Notes: 666 For scaled matrix formats, applying the original, unscaled matrix 667 will be slightly more expensive 668 669 Level: Developer 670 671 .seealso: MatScaleSystem(), MatUnScaleSystem() 672 @*/ 673 PetscErrorCode PETSCMAT_DLLEXPORT MatUseScaledForm(Mat mat,PetscTruth scaled) 674 { 675 PetscErrorCode ierr; 676 677 PetscFunctionBegin; 678 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 679 PetscValidType(mat,1); 680 ierr = MatPreallocated(mat);CHKERRQ(ierr); 681 if (mat->ops->usescaledform) { 682 ierr = (*mat->ops->usescaledform)(mat,scaled);CHKERRQ(ierr); 683 } 684 PetscFunctionReturn(0); 685 } 686 687 #undef __FUNCT__ 688 #define __FUNCT__ "MatDestroy" 689 /*@ 690 MatDestroy - Frees space taken by a matrix. 691 692 Collective on Mat 693 694 Input Parameter: 695 . A - the matrix 696 697 Level: beginner 698 699 @*/ 700 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroy(Mat A) 701 { 702 PetscErrorCode ierr; 703 704 PetscFunctionBegin; 705 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 706 if (--A->refct > 0) PetscFunctionReturn(0); 707 708 PetscValidType(A,1); 709 ierr = MatPreallocated(A);CHKERRQ(ierr); 710 /* if memory was published with AMS then destroy it */ 711 ierr = PetscObjectDepublish(A);CHKERRQ(ierr); 712 if (A->mapping) { 713 ierr = ISLocalToGlobalMappingDestroy(A->mapping);CHKERRQ(ierr); 714 } 715 if (A->bmapping) { 716 ierr = ISLocalToGlobalMappingDestroy(A->bmapping);CHKERRQ(ierr); 717 } 718 ierr = (*A->ops->destroy)(A);CHKERRQ(ierr); 719 if (A->rmap.range) { 720 ierr = PetscFree(A->rmap.range);CHKERRQ(ierr); 721 } 722 if (A->cmap.range) { 723 ierr = PetscFree(A->cmap.range);CHKERRQ(ierr); 724 } 725 ierr = PetscHeaderDestroy(A);CHKERRQ(ierr); 726 PetscFunctionReturn(0); 727 } 728 729 #undef __FUNCT__ 730 #define __FUNCT__ "MatValid" 731 /*@ 732 MatValid - Checks whether a matrix object is valid. 733 734 Collective on Mat 735 736 Input Parameter: 737 . m - the matrix to check 738 739 Output Parameter: 740 flg - flag indicating matrix status, either 741 PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise. 742 743 Level: developer 744 745 Concepts: matrices^validity 746 @*/ 747 PetscErrorCode PETSCMAT_DLLEXPORT MatValid(Mat m,PetscTruth *flg) 748 { 749 PetscFunctionBegin; 750 PetscValidIntPointer(flg,1); 751 if (!m) *flg = PETSC_FALSE; 752 else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE; 753 else *flg = PETSC_TRUE; 754 PetscFunctionReturn(0); 755 } 756 757 #undef __FUNCT__ 758 #define __FUNCT__ "MatSetValues" 759 /*@ 760 MatSetValues - Inserts or adds a block of values into a matrix. 761 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 762 MUST be called after all calls to MatSetValues() have been completed. 763 764 Not Collective 765 766 Input Parameters: 767 + mat - the matrix 768 . v - a logically two-dimensional array of values 769 . m, idxm - the number of rows and their global indices 770 . n, idxn - the number of columns and their global indices 771 - addv - either ADD_VALUES or INSERT_VALUES, where 772 ADD_VALUES adds values to any existing entries, and 773 INSERT_VALUES replaces existing entries with new values 774 775 Notes: 776 By default the values, v, are row-oriented and unsorted. 777 See MatSetOption() for other options. 778 779 Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 780 options cannot be mixed without intervening calls to the assembly 781 routines. 782 783 MatSetValues() uses 0-based row and column numbers in Fortran 784 as well as in C. 785 786 Negative indices may be passed in idxm and idxn, these rows and columns are 787 simply ignored. This allows easily inserting element stiffness matrices 788 with homogeneous Dirchlet boundary conditions that you don't want represented 789 in the matrix. 790 791 Efficiency Alert: 792 The routine MatSetValuesBlocked() may offer much better efficiency 793 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 794 795 Level: beginner 796 797 Concepts: matrices^putting entries in 798 799 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 800 InsertMode, INSERT_VALUES, ADD_VALUES 801 @*/ 802 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 803 { 804 PetscErrorCode ierr; 805 806 PetscFunctionBegin; 807 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 808 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 809 PetscValidType(mat,1); 810 PetscValidIntPointer(idxm,3); 811 PetscValidIntPointer(idxn,5); 812 PetscValidScalarPointer(v,6); 813 ierr = MatPreallocated(mat);CHKERRQ(ierr); 814 if (mat->insertmode == NOT_SET_VALUES) { 815 mat->insertmode = addv; 816 } 817 #if defined(PETSC_USE_DEBUG) 818 else if (mat->insertmode != addv) { 819 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 820 } 821 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 822 #endif 823 824 if (mat->assembled) { 825 mat->was_assembled = PETSC_TRUE; 826 mat->assembled = PETSC_FALSE; 827 } 828 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 829 if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 830 ierr = (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 831 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 832 PetscFunctionReturn(0); 833 } 834 835 836 #undef __FUNCT__ 837 #define __FUNCT__ "MatSetValuesRowLocal" 838 /*@ 839 MatSetValuesRowLocal - Inserts a row (block row for BAIJ matrices) of nonzero 840 values into a matrix 841 842 Not Collective 843 844 Input Parameters: 845 + mat - the matrix 846 . row - the (block) row to set 847 - v - a logically two-dimensional array of values 848 849 Notes: 850 By the values, v, are column-oriented (for the block version) and sorted 851 852 All the nonzeros in the row must be provided 853 854 The matrix must have previously had its column indices set 855 856 The row must belong to this process 857 858 Level: intermediate 859 860 Concepts: matrices^putting entries in 861 862 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 863 InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues(), MatSetValuesRow(), MatSetLocalToGlobalMapping() 864 @*/ 865 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRowLocal(Mat mat,PetscInt row,const PetscScalar v[]) 866 { 867 PetscErrorCode ierr; 868 869 PetscFunctionBegin; 870 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 871 PetscValidType(mat,1); 872 PetscValidScalarPointer(v,2); 873 ierr = MatSetValuesRow(mat, mat->mapping->indices[row],v);CHKERRQ(ierr); 874 PetscFunctionReturn(0); 875 } 876 877 #undef __FUNCT__ 878 #define __FUNCT__ "MatSetValuesRow" 879 /*@ 880 MatSetValuesRow - Inserts a row (block row for BAIJ matrices) of nonzero 881 values into a matrix 882 883 Not Collective 884 885 Input Parameters: 886 + mat - the matrix 887 . row - the (block) row to set 888 - v - a logically two-dimensional array of values 889 890 Notes: 891 By the values, v, are column-oriented (for the block version) and sorted 892 893 All the nonzeros in the row must be provided 894 895 The matrix must have previously had its column indices set 896 897 The row must belong to this process 898 899 Level: intermediate 900 901 Concepts: matrices^putting entries in 902 903 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 904 InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues() 905 @*/ 906 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRow(Mat mat,PetscInt row,const PetscScalar v[]) 907 { 908 PetscErrorCode ierr; 909 910 PetscFunctionBegin; 911 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 912 PetscValidType(mat,1); 913 PetscValidScalarPointer(v,2); 914 #if defined(PETSC_USE_DEBUG) 915 if (mat->insertmode == ADD_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add and insert values"); 916 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 917 #endif 918 mat->insertmode = INSERT_VALUES; 919 920 if (mat->assembled) { 921 mat->was_assembled = PETSC_TRUE; 922 mat->assembled = PETSC_FALSE; 923 } 924 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 925 if (!mat->ops->setvaluesrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 926 ierr = (*mat->ops->setvaluesrow)(mat,row,v);CHKERRQ(ierr); 927 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 928 PetscFunctionReturn(0); 929 } 930 931 #undef __FUNCT__ 932 #define __FUNCT__ "MatSetValuesStencil" 933 /*@ 934 MatSetValuesStencil - Inserts or adds a block of values into a matrix. 935 Using structured grid indexing 936 937 Not Collective 938 939 Input Parameters: 940 + mat - the matrix 941 . v - a logically two-dimensional array of values 942 . m - number of rows being entered 943 . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered 944 . n - number of columns being entered 945 . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 946 - addv - either ADD_VALUES or INSERT_VALUES, where 947 ADD_VALUES adds values to any existing entries, and 948 INSERT_VALUES replaces existing entries with new values 949 950 Notes: 951 By default the values, v, are row-oriented and unsorted. 952 See MatSetOption() for other options. 953 954 Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 955 options cannot be mixed without intervening calls to the assembly 956 routines. 957 958 The grid coordinates are across the entire grid, not just the local portion 959 960 MatSetValuesStencil() uses 0-based row and column numbers in Fortran 961 as well as in C. 962 963 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 964 965 In order to use this routine you must either obtain the matrix with DAGetMatrix() 966 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 967 968 The columns and rows in the stencil passed in MUST be contained within the 969 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 970 if you create a DA with an overlap of one grid level and on a particular process its first 971 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 972 first i index you can use in your column and row indices in MatSetStencil() is 5. 973 974 In Fortran idxm and idxn should be declared as 975 $ MatStencil idxm(4,m),idxn(4,n) 976 and the values inserted using 977 $ idxm(MatStencil_i,1) = i 978 $ idxm(MatStencil_j,1) = j 979 $ idxm(MatStencil_k,1) = k 980 $ idxm(MatStencil_c,1) = c 981 etc 982 983 For periodic boundary conditions use negative indices for values to the left (below 0; that are to be 984 obtained by wrapping values from right edge). For values to the right of the last entry using that index plus one 985 etc to obtain values that obtained by wrapping the values from the left edge. 986 987 For indices that don't mean anything for your case (like the k index when working in 2d) or the c index when you have 988 a single value per point) you can skip filling those indices. 989 990 Inspired by the structured grid interface to the HYPRE package 991 (http://www.llnl.gov/CASC/hypre) 992 993 Efficiency Alert: 994 The routine MatSetValuesBlockedStencil() may offer much better efficiency 995 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 996 997 Level: beginner 998 999 Concepts: matrices^putting entries in 1000 1001 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1002 MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 1003 @*/ 1004 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 1005 { 1006 PetscErrorCode ierr; 1007 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 1008 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 1009 1010 PetscFunctionBegin; 1011 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1012 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1013 PetscValidType(mat,1); 1014 PetscValidIntPointer(idxm,3); 1015 PetscValidIntPointer(idxn,5); 1016 PetscValidScalarPointer(v,6); 1017 1018 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 1019 if (n > 256) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 1020 1021 for (i=0; i<m; i++) { 1022 for (j=0; j<3-sdim; j++) dxm++; 1023 tmp = *dxm++ - starts[0]; 1024 for (j=0; j<dim-1; j++) { 1025 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1026 else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1]; 1027 } 1028 if (mat->stencil.noc) dxm++; 1029 jdxm[i] = tmp; 1030 } 1031 for (i=0; i<n; i++) { 1032 for (j=0; j<3-sdim; j++) dxn++; 1033 tmp = *dxn++ - starts[0]; 1034 for (j=0; j<dim-1; j++) { 1035 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1036 else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1]; 1037 } 1038 if (mat->stencil.noc) dxn++; 1039 jdxn[i] = tmp; 1040 } 1041 ierr = MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 1042 PetscFunctionReturn(0); 1043 } 1044 1045 #undef __FUNCT__ 1046 #define __FUNCT__ "MatSetValuesBlockedStencil" 1047 /*@C 1048 MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix. 1049 Using structured grid indexing 1050 1051 Not Collective 1052 1053 Input Parameters: 1054 + mat - the matrix 1055 . v - a logically two-dimensional array of values 1056 . m - number of rows being entered 1057 . idxm - grid coordinates for matrix rows being entered 1058 . n - number of columns being entered 1059 . idxn - grid coordinates for matrix columns being entered 1060 - addv - either ADD_VALUES or INSERT_VALUES, where 1061 ADD_VALUES adds values to any existing entries, and 1062 INSERT_VALUES replaces existing entries with new values 1063 1064 Notes: 1065 By default the values, v, are row-oriented and unsorted. 1066 See MatSetOption() for other options. 1067 1068 Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES 1069 options cannot be mixed without intervening calls to the assembly 1070 routines. 1071 1072 The grid coordinates are across the entire grid, not just the local portion 1073 1074 MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran 1075 as well as in C. 1076 1077 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 1078 1079 In order to use this routine you must either obtain the matrix with DAGetMatrix() 1080 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 1081 1082 The columns and rows in the stencil passed in MUST be contained within the 1083 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 1084 if you create a DA with an overlap of one grid level and on a particular process its first 1085 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 1086 first i index you can use in your column and row indices in MatSetStencil() is 5. 1087 1088 In Fortran idxm and idxn should be declared as 1089 $ MatStencil idxm(4,m),idxn(4,n) 1090 and the values inserted using 1091 $ idxm(MatStencil_i,1) = i 1092 $ idxm(MatStencil_j,1) = j 1093 $ idxm(MatStencil_k,1) = k 1094 etc 1095 1096 Negative indices may be passed in idxm and idxn, these rows and columns are 1097 simply ignored. This allows easily inserting element stiffness matrices 1098 with homogeneous Dirchlet boundary conditions that you don't want represented 1099 in the matrix. 1100 1101 Inspired by the structured grid interface to the HYPRE package 1102 (http://www.llnl.gov/CASC/hypre) 1103 1104 Level: beginner 1105 1106 Concepts: matrices^putting entries in 1107 1108 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1109 MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 1110 @*/ 1111 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 1112 { 1113 PetscErrorCode ierr; 1114 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 1115 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 1116 1117 PetscFunctionBegin; 1118 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1119 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1120 PetscValidType(mat,1); 1121 PetscValidIntPointer(idxm,3); 1122 PetscValidIntPointer(idxn,5); 1123 PetscValidScalarPointer(v,6); 1124 1125 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 1126 if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 1127 1128 for (i=0; i<m; i++) { 1129 for (j=0; j<3-sdim; j++) dxm++; 1130 tmp = *dxm++ - starts[0]; 1131 for (j=0; j<sdim-1; j++) { 1132 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1133 else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1]; 1134 } 1135 dxm++; 1136 jdxm[i] = tmp; 1137 } 1138 for (i=0; i<n; i++) { 1139 for (j=0; j<3-sdim; j++) dxn++; 1140 tmp = *dxn++ - starts[0]; 1141 for (j=0; j<sdim-1; j++) { 1142 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1143 else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1]; 1144 } 1145 dxn++; 1146 jdxn[i] = tmp; 1147 } 1148 ierr = MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 1149 PetscFunctionReturn(0); 1150 } 1151 1152 #undef __FUNCT__ 1153 #define __FUNCT__ "MatSetStencil" 1154 /*@ 1155 MatSetStencil - Sets the grid information for setting values into a matrix via 1156 MatSetValuesStencil() 1157 1158 Not Collective 1159 1160 Input Parameters: 1161 + mat - the matrix 1162 . dim - dimension of the grid 1, 2, or 3 1163 . dims - number of grid points in x, y, and z direction, including ghost points on your processor 1164 . starts - starting point of ghost nodes on your processor in x, y, and z direction 1165 - dof - number of degrees of freedom per node 1166 1167 1168 Inspired by the structured grid interface to the HYPRE package 1169 (www.llnl.gov/CASC/hyper) 1170 1171 For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the 1172 user. 1173 1174 Level: beginner 1175 1176 Concepts: matrices^putting entries in 1177 1178 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1179 MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil() 1180 @*/ 1181 PetscErrorCode PETSCMAT_DLLEXPORT MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof) 1182 { 1183 PetscInt i; 1184 1185 PetscFunctionBegin; 1186 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1187 PetscValidIntPointer(dims,3); 1188 PetscValidIntPointer(starts,4); 1189 1190 mat->stencil.dim = dim + (dof > 1); 1191 for (i=0; i<dim; i++) { 1192 mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */ 1193 mat->stencil.starts[i] = starts[dim-i-1]; 1194 } 1195 mat->stencil.dims[dim] = dof; 1196 mat->stencil.starts[dim] = 0; 1197 mat->stencil.noc = (PetscTruth)(dof == 1); 1198 PetscFunctionReturn(0); 1199 } 1200 1201 #undef __FUNCT__ 1202 #define __FUNCT__ "MatSetValuesBlocked" 1203 /*@ 1204 MatSetValuesBlocked - Inserts or adds a block of values into a matrix. 1205 1206 Not Collective 1207 1208 Input Parameters: 1209 + mat - the matrix 1210 . v - a logically two-dimensional array of values 1211 . m, idxm - the number of block rows and their global block indices 1212 . n, idxn - the number of block columns and their global block indices 1213 - addv - either ADD_VALUES or INSERT_VALUES, where 1214 ADD_VALUES adds values to any existing entries, and 1215 INSERT_VALUES replaces existing entries with new values 1216 1217 Notes: 1218 The m and n count the NUMBER of blocks in the row direction and column direction, 1219 NOT the total number of rows/columns; for example, if the block size is 2 and 1220 you are passing in values for rows 2,3,4,5 then m would be 2 (not 4). 1221 1222 By default the values, v, are row-oriented and unsorted. So the layout of 1223 v is the same as for MatSetValues(). See MatSetOption() for other options. 1224 1225 Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 1226 options cannot be mixed without intervening calls to the assembly 1227 routines. 1228 1229 MatSetValuesBlocked() uses 0-based row and column numbers in Fortran 1230 as well as in C. 1231 1232 Negative indices may be passed in idxm and idxn, these rows and columns are 1233 simply ignored. This allows easily inserting element stiffness matrices 1234 with homogeneous Dirchlet boundary conditions that you don't want represented 1235 in the matrix. 1236 1237 Each time an entry is set within a sparse matrix via MatSetValues(), 1238 internal searching must be done to determine where to place the the 1239 data in the matrix storage space. By instead inserting blocks of 1240 entries via MatSetValuesBlocked(), the overhead of matrix assembly is 1241 reduced. 1242 1243 Restrictions: 1244 MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats 1245 1246 Level: intermediate 1247 1248 Concepts: matrices^putting entries in blocked 1249 1250 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal() 1251 @*/ 1252 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 1253 { 1254 PetscErrorCode ierr; 1255 1256 PetscFunctionBegin; 1257 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1258 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1259 PetscValidType(mat,1); 1260 PetscValidIntPointer(idxm,3); 1261 PetscValidIntPointer(idxn,5); 1262 PetscValidScalarPointer(v,6); 1263 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1264 if (mat->insertmode == NOT_SET_VALUES) { 1265 mat->insertmode = addv; 1266 } 1267 #if defined(PETSC_USE_DEBUG) 1268 else if (mat->insertmode != addv) { 1269 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1270 } 1271 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1272 #endif 1273 1274 if (mat->assembled) { 1275 mat->was_assembled = PETSC_TRUE; 1276 mat->assembled = PETSC_FALSE; 1277 } 1278 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1279 if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1280 ierr = (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 1281 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1282 PetscFunctionReturn(0); 1283 } 1284 1285 #undef __FUNCT__ 1286 #define __FUNCT__ "MatGetValues" 1287 /*@ 1288 MatGetValues - Gets a block of values from a matrix. 1289 1290 Not Collective; currently only returns a local block 1291 1292 Input Parameters: 1293 + mat - the matrix 1294 . v - a logically two-dimensional array for storing the values 1295 . m, idxm - the number of rows and their global indices 1296 - n, idxn - the number of columns and their global indices 1297 1298 Notes: 1299 The user must allocate space (m*n PetscScalars) for the values, v. 1300 The values, v, are then returned in a row-oriented format, 1301 analogous to that used by default in MatSetValues(). 1302 1303 MatGetValues() uses 0-based row and column numbers in 1304 Fortran as well as in C. 1305 1306 MatGetValues() requires that the matrix has been assembled 1307 with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to 1308 MatSetValues() and MatGetValues() CANNOT be made in succession 1309 without intermediate matrix assembly. 1310 1311 Level: advanced 1312 1313 Concepts: matrices^accessing values 1314 1315 .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues() 1316 @*/ 1317 PetscErrorCode PETSCMAT_DLLEXPORT MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[]) 1318 { 1319 PetscErrorCode ierr; 1320 1321 PetscFunctionBegin; 1322 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1323 PetscValidType(mat,1); 1324 PetscValidIntPointer(idxm,3); 1325 PetscValidIntPointer(idxn,5); 1326 PetscValidScalarPointer(v,6); 1327 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1328 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1329 if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1330 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1331 1332 ierr = PetscLogEventBegin(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 1333 ierr = (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);CHKERRQ(ierr); 1334 ierr = PetscLogEventEnd(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 1335 PetscFunctionReturn(0); 1336 } 1337 1338 #undef __FUNCT__ 1339 #define __FUNCT__ "MatSetLocalToGlobalMapping" 1340 /*@ 1341 MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by 1342 the routine MatSetValuesLocal() to allow users to insert matrix entries 1343 using a local (per-processor) numbering. 1344 1345 Not Collective 1346 1347 Input Parameters: 1348 + x - the matrix 1349 - mapping - mapping created with ISLocalToGlobalMappingCreate() 1350 or ISLocalToGlobalMappingCreateIS() 1351 1352 Level: intermediate 1353 1354 Concepts: matrices^local to global mapping 1355 Concepts: local to global mapping^for matrices 1356 1357 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal() 1358 @*/ 1359 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping) 1360 { 1361 PetscErrorCode ierr; 1362 PetscFunctionBegin; 1363 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1364 PetscValidType(x,1); 1365 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1366 if (x->mapping) { 1367 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1368 } 1369 ierr = MatPreallocated(x);CHKERRQ(ierr); 1370 1371 if (x->ops->setlocaltoglobalmapping) { 1372 ierr = (*x->ops->setlocaltoglobalmapping)(x,mapping);CHKERRQ(ierr); 1373 } else { 1374 x->mapping = mapping; 1375 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1376 } 1377 PetscFunctionReturn(0); 1378 } 1379 1380 #undef __FUNCT__ 1381 #define __FUNCT__ "MatSetLocalToGlobalMappingBlock" 1382 /*@ 1383 MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use 1384 by the routine MatSetValuesBlockedLocal() to allow users to insert matrix 1385 entries using a local (per-processor) numbering. 1386 1387 Not Collective 1388 1389 Input Parameters: 1390 + x - the matrix 1391 - mapping - mapping created with ISLocalToGlobalMappingCreate() or 1392 ISLocalToGlobalMappingCreateIS() 1393 1394 Level: intermediate 1395 1396 Concepts: matrices^local to global mapping blocked 1397 Concepts: local to global mapping^for matrices, blocked 1398 1399 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(), 1400 MatSetValuesBlocked(), MatSetValuesLocal() 1401 @*/ 1402 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping) 1403 { 1404 PetscErrorCode ierr; 1405 PetscFunctionBegin; 1406 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1407 PetscValidType(x,1); 1408 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1409 if (x->bmapping) { 1410 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1411 } 1412 x->bmapping = mapping; 1413 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1414 PetscFunctionReturn(0); 1415 } 1416 1417 #undef __FUNCT__ 1418 #define __FUNCT__ "MatSetValuesLocal" 1419 /*@ 1420 MatSetValuesLocal - Inserts or adds values into certain locations of a matrix, 1421 using a local ordering of the nodes. 1422 1423 Not Collective 1424 1425 Input Parameters: 1426 + x - the matrix 1427 . nrow, irow - number of rows and their local indices 1428 . ncol, icol - number of columns and their local indices 1429 . y - a logically two-dimensional array of values 1430 - addv - either INSERT_VALUES or ADD_VALUES, where 1431 ADD_VALUES adds values to any existing entries, and 1432 INSERT_VALUES replaces existing entries with new values 1433 1434 Notes: 1435 Before calling MatSetValuesLocal(), the user must first set the 1436 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 1437 1438 Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 1439 options cannot be mixed without intervening calls to the assembly 1440 routines. 1441 1442 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 1443 MUST be called after all calls to MatSetValuesLocal() have been completed. 1444 1445 Level: intermediate 1446 1447 Concepts: matrices^putting entries in with local numbering 1448 1449 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(), 1450 MatSetValueLocal() 1451 @*/ 1452 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv) 1453 { 1454 PetscErrorCode ierr; 1455 PetscInt irowm[2048],icolm[2048]; 1456 1457 PetscFunctionBegin; 1458 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1459 PetscValidType(mat,1); 1460 PetscValidIntPointer(irow,3); 1461 PetscValidIntPointer(icol,5); 1462 PetscValidScalarPointer(y,6); 1463 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1464 if (mat->insertmode == NOT_SET_VALUES) { 1465 mat->insertmode = addv; 1466 } 1467 #if defined(PETSC_USE_DEBUG) 1468 else if (mat->insertmode != addv) { 1469 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1470 } 1471 if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) { 1472 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol); 1473 } 1474 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1475 #endif 1476 1477 if (mat->assembled) { 1478 mat->was_assembled = PETSC_TRUE; 1479 mat->assembled = PETSC_FALSE; 1480 } 1481 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1482 if (!mat->ops->setvalueslocal) { 1483 ierr = ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);CHKERRQ(ierr); 1484 ierr = ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);CHKERRQ(ierr); 1485 ierr = (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 1486 } else { 1487 ierr = (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);CHKERRQ(ierr); 1488 } 1489 mat->same_nonzero = PETSC_FALSE; 1490 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1491 PetscFunctionReturn(0); 1492 } 1493 1494 #undef __FUNCT__ 1495 #define __FUNCT__ "MatSetValuesBlockedLocal" 1496 /*@ 1497 MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix, 1498 using a local ordering of the nodes a block at a time. 1499 1500 Not Collective 1501 1502 Input Parameters: 1503 + x - the matrix 1504 . nrow, irow - number of rows and their local indices 1505 . ncol, icol - number of columns and their local indices 1506 . y - a logically two-dimensional array of values 1507 - addv - either INSERT_VALUES or ADD_VALUES, where 1508 ADD_VALUES adds values to any existing entries, and 1509 INSERT_VALUES replaces existing entries with new values 1510 1511 Notes: 1512 Before calling MatSetValuesBlockedLocal(), the user must first set the 1513 local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(), 1514 where the mapping MUST be set for matrix blocks, not for matrix elements. 1515 1516 Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 1517 options cannot be mixed without intervening calls to the assembly 1518 routines. 1519 1520 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 1521 MUST be called after all calls to MatSetValuesBlockedLocal() have been completed. 1522 1523 Level: intermediate 1524 1525 Concepts: matrices^putting blocked values in with local numbering 1526 1527 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked() 1528 @*/ 1529 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv) 1530 { 1531 PetscErrorCode ierr; 1532 PetscInt irowm[2048],icolm[2048]; 1533 1534 PetscFunctionBegin; 1535 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1536 PetscValidType(mat,1); 1537 PetscValidIntPointer(irow,3); 1538 PetscValidIntPointer(icol,5); 1539 PetscValidScalarPointer(y,6); 1540 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1541 if (mat->insertmode == NOT_SET_VALUES) { 1542 mat->insertmode = addv; 1543 } 1544 #if defined(PETSC_USE_DEBUG) 1545 else if (mat->insertmode != addv) { 1546 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1547 } 1548 if (!mat->bmapping) { 1549 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()"); 1550 } 1551 if (nrow > 2048 || ncol > 2048) { 1552 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol); 1553 } 1554 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1555 #endif 1556 1557 if (mat->assembled) { 1558 mat->was_assembled = PETSC_TRUE; 1559 mat->assembled = PETSC_FALSE; 1560 } 1561 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1562 ierr = ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);CHKERRQ(ierr); 1563 ierr = ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);CHKERRQ(ierr); 1564 ierr = (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 1565 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1566 PetscFunctionReturn(0); 1567 } 1568 1569 /* --------------------------------------------------------*/ 1570 #undef __FUNCT__ 1571 #define __FUNCT__ "MatMult" 1572 /*@ 1573 MatMult - Computes the matrix-vector product, y = Ax. 1574 1575 Collective on Mat and Vec 1576 1577 Input Parameters: 1578 + mat - the matrix 1579 - x - the vector to be multiplied 1580 1581 Output Parameters: 1582 . y - the result 1583 1584 Notes: 1585 The vectors x and y cannot be the same. I.e., one cannot 1586 call MatMult(A,y,y). 1587 1588 Level: beginner 1589 1590 Concepts: matrix-vector product 1591 1592 .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd() 1593 @*/ 1594 PetscErrorCode PETSCMAT_DLLEXPORT MatMult(Mat mat,Vec x,Vec y) 1595 { 1596 PetscErrorCode ierr; 1597 1598 PetscFunctionBegin; 1599 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1600 PetscValidType(mat,1); 1601 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1602 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1603 1604 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1605 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1606 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1607 #ifndef PETSC_HAVE_CONSTRAINTS 1608 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1609 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1610 if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n); 1611 #endif 1612 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1613 1614 if (mat->nullsp) { 1615 ierr = MatNullSpaceRemove(mat->nullsp,x,&x);CHKERRQ(ierr); 1616 } 1617 1618 if (!mat->ops->mult) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply defined"); 1619 ierr = PetscLogEventBegin(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 1620 ierr = (*mat->ops->mult)(mat,x,y);CHKERRQ(ierr); 1621 ierr = PetscLogEventEnd(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 1622 1623 if (mat->nullsp) { 1624 ierr = MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);CHKERRQ(ierr); 1625 } 1626 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1627 PetscFunctionReturn(0); 1628 } 1629 1630 #undef __FUNCT__ 1631 #define __FUNCT__ "MatMultTranspose" 1632 /*@ 1633 MatMultTranspose - Computes matrix transpose times a vector. 1634 1635 Collective on Mat and Vec 1636 1637 Input Parameters: 1638 + mat - the matrix 1639 - x - the vector to be multilplied 1640 1641 Output Parameters: 1642 . y - the result 1643 1644 Notes: 1645 The vectors x and y cannot be the same. I.e., one cannot 1646 call MatMultTranspose(A,y,y). 1647 1648 Level: beginner 1649 1650 Concepts: matrix vector product^transpose 1651 1652 .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd() 1653 @*/ 1654 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTranspose(Mat mat,Vec x,Vec y) 1655 { 1656 PetscErrorCode ierr; 1657 1658 PetscFunctionBegin; 1659 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1660 PetscValidType(mat,1); 1661 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1662 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1663 1664 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1665 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1666 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1667 #ifndef PETSC_HAVE_CONSTRAINTS 1668 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 1669 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N); 1670 #endif 1671 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1672 1673 if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined"); 1674 ierr = PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1675 ierr = (*mat->ops->multtranspose)(mat,x,y);CHKERRQ(ierr); 1676 ierr = PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1677 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1678 PetscFunctionReturn(0); 1679 } 1680 1681 #undef __FUNCT__ 1682 #define __FUNCT__ "MatMultAdd" 1683 /*@ 1684 MatMultAdd - Computes v3 = v2 + A * v1. 1685 1686 Collective on Mat and Vec 1687 1688 Input Parameters: 1689 + mat - the matrix 1690 - v1, v2 - the vectors 1691 1692 Output Parameters: 1693 . v3 - the result 1694 1695 Notes: 1696 The vectors v1 and v3 cannot be the same. I.e., one cannot 1697 call MatMultAdd(A,v1,v2,v1). 1698 1699 Level: beginner 1700 1701 Concepts: matrix vector product^addition 1702 1703 .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd() 1704 @*/ 1705 PetscErrorCode PETSCMAT_DLLEXPORT MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1706 { 1707 PetscErrorCode ierr; 1708 1709 PetscFunctionBegin; 1710 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1711 PetscValidType(mat,1); 1712 PetscValidHeaderSpecific(v1,VEC_COOKIE,2); 1713 PetscValidHeaderSpecific(v2,VEC_COOKIE,3); 1714 PetscValidHeaderSpecific(v3,VEC_COOKIE,4); 1715 1716 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1717 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1718 if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->N,v1->N); 1719 if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->M,v2->N); 1720 if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->M,v3->N); 1721 if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->m,v3->n); 1722 if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->m,v2->n); 1723 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1724 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1725 1726 ierr = PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1727 ierr = (*mat->ops->multadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1728 ierr = PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1729 ierr = PetscObjectStateIncrease((PetscObject)v3);CHKERRQ(ierr); 1730 PetscFunctionReturn(0); 1731 } 1732 1733 #undef __FUNCT__ 1734 #define __FUNCT__ "MatMultTransposeAdd" 1735 /*@ 1736 MatMultTransposeAdd - Computes v3 = v2 + A' * v1. 1737 1738 Collective on Mat and Vec 1739 1740 Input Parameters: 1741 + mat - the matrix 1742 - v1, v2 - the vectors 1743 1744 Output Parameters: 1745 . v3 - the result 1746 1747 Notes: 1748 The vectors v1 and v3 cannot be the same. I.e., one cannot 1749 call MatMultTransposeAdd(A,v1,v2,v1). 1750 1751 Level: beginner 1752 1753 Concepts: matrix vector product^transpose and addition 1754 1755 .seealso: MatMultTranspose(), MatMultAdd(), MatMult() 1756 @*/ 1757 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1758 { 1759 PetscErrorCode ierr; 1760 1761 PetscFunctionBegin; 1762 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1763 PetscValidType(mat,1); 1764 PetscValidHeaderSpecific(v1,VEC_COOKIE,2); 1765 PetscValidHeaderSpecific(v2,VEC_COOKIE,3); 1766 PetscValidHeaderSpecific(v3,VEC_COOKIE,4); 1767 1768 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1769 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1770 if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1771 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1772 if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->M,v1->N); 1773 if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->N,v2->N); 1774 if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->N,v3->N); 1775 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1776 1777 ierr = PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1778 ierr = (*mat->ops->multtransposeadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1779 ierr = PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1780 ierr = PetscObjectStateIncrease((PetscObject)v3);CHKERRQ(ierr); 1781 PetscFunctionReturn(0); 1782 } 1783 1784 #undef __FUNCT__ 1785 #define __FUNCT__ "MatMultConstrained" 1786 /*@ 1787 MatMultConstrained - The inner multiplication routine for a 1788 constrained matrix P^T A P. 1789 1790 Collective on Mat and Vec 1791 1792 Input Parameters: 1793 + mat - the matrix 1794 - x - the vector to be multilplied 1795 1796 Output Parameters: 1797 . y - the result 1798 1799 Notes: 1800 The vectors x and y cannot be the same. I.e., one cannot 1801 call MatMult(A,y,y). 1802 1803 Level: beginner 1804 1805 .keywords: matrix, multiply, matrix-vector product, constraint 1806 .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd() 1807 @*/ 1808 PetscErrorCode PETSCMAT_DLLEXPORT MatMultConstrained(Mat mat,Vec x,Vec y) 1809 { 1810 PetscErrorCode ierr; 1811 1812 PetscFunctionBegin; 1813 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1814 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1815 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1816 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1817 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1818 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1819 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1820 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1821 if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n); 1822 1823 ierr = PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1824 ierr = (*mat->ops->multconstrained)(mat,x,y);CHKERRQ(ierr); 1825 ierr = PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1826 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1827 1828 PetscFunctionReturn(0); 1829 } 1830 1831 #undef __FUNCT__ 1832 #define __FUNCT__ "MatMultTransposeConstrained" 1833 /*@ 1834 MatMultTransposeConstrained - The inner multiplication routine for a 1835 constrained matrix P^T A^T P. 1836 1837 Collective on Mat and Vec 1838 1839 Input Parameters: 1840 + mat - the matrix 1841 - x - the vector to be multilplied 1842 1843 Output Parameters: 1844 . y - the result 1845 1846 Notes: 1847 The vectors x and y cannot be the same. I.e., one cannot 1848 call MatMult(A,y,y). 1849 1850 Level: beginner 1851 1852 .keywords: matrix, multiply, matrix-vector product, constraint 1853 .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd() 1854 @*/ 1855 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeConstrained(Mat mat,Vec x,Vec y) 1856 { 1857 PetscErrorCode ierr; 1858 1859 PetscFunctionBegin; 1860 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1861 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1862 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1863 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1864 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1865 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1866 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1867 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1868 1869 ierr = PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1870 ierr = (*mat->ops->multtransposeconstrained)(mat,x,y);CHKERRQ(ierr); 1871 ierr = PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1872 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1873 1874 PetscFunctionReturn(0); 1875 } 1876 /* ------------------------------------------------------------*/ 1877 #undef __FUNCT__ 1878 #define __FUNCT__ "MatGetInfo" 1879 /*@ 1880 MatGetInfo - Returns information about matrix storage (number of 1881 nonzeros, memory, etc.). 1882 1883 Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used 1884 as the flag 1885 1886 Input Parameters: 1887 . mat - the matrix 1888 1889 Output Parameters: 1890 + flag - flag indicating the type of parameters to be returned 1891 (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors, 1892 MAT_GLOBAL_SUM - sum over all processors) 1893 - info - matrix information context 1894 1895 Notes: 1896 The MatInfo context contains a variety of matrix data, including 1897 number of nonzeros allocated and used, number of mallocs during 1898 matrix assembly, etc. Additional information for factored matrices 1899 is provided (such as the fill ratio, number of mallocs during 1900 factorization, etc.). Much of this info is printed to STDOUT 1901 when using the runtime options 1902 $ -info -mat_view_info 1903 1904 Example for C/C++ Users: 1905 See the file ${PETSC_DIR}/include/petscmat.h for a complete list of 1906 data within the MatInfo context. For example, 1907 .vb 1908 MatInfo info; 1909 Mat A; 1910 double mal, nz_a, nz_u; 1911 1912 MatGetInfo(A,MAT_LOCAL,&info); 1913 mal = info.mallocs; 1914 nz_a = info.nz_allocated; 1915 .ve 1916 1917 Example for Fortran Users: 1918 Fortran users should declare info as a double precision 1919 array of dimension MAT_INFO_SIZE, and then extract the parameters 1920 of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h 1921 a complete list of parameter names. 1922 .vb 1923 double precision info(MAT_INFO_SIZE) 1924 double precision mal, nz_a 1925 Mat A 1926 integer ierr 1927 1928 call MatGetInfo(A,MAT_LOCAL,info,ierr) 1929 mal = info(MAT_INFO_MALLOCS) 1930 nz_a = info(MAT_INFO_NZ_ALLOCATED) 1931 .ve 1932 1933 Level: intermediate 1934 1935 Concepts: matrices^getting information on 1936 1937 @*/ 1938 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info) 1939 { 1940 PetscErrorCode ierr; 1941 1942 PetscFunctionBegin; 1943 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1944 PetscValidType(mat,1); 1945 PetscValidPointer(info,3); 1946 if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1947 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1948 ierr = (*mat->ops->getinfo)(mat,flag,info);CHKERRQ(ierr); 1949 PetscFunctionReturn(0); 1950 } 1951 1952 /* ----------------------------------------------------------*/ 1953 #undef __FUNCT__ 1954 #define __FUNCT__ "MatILUDTFactor" 1955 /*@C 1956 MatILUDTFactor - Performs a drop tolerance ILU factorization. 1957 1958 Collective on Mat 1959 1960 Input Parameters: 1961 + mat - the matrix 1962 . row - row permutation 1963 . col - column permutation 1964 - info - information about the factorization to be done 1965 1966 Output Parameters: 1967 . fact - the factored matrix 1968 1969 Level: developer 1970 1971 Notes: 1972 Most users should employ the simplified KSP interface for linear solvers 1973 instead of working directly with matrix algebra routines such as this. 1974 See, e.g., KSPCreate(). 1975 1976 This is currently only supported for the SeqAIJ matrix format using code 1977 from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or 1978 Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright 1979 and thus can be distributed with PETSc. 1980 1981 Concepts: matrices^ILUDT factorization 1982 1983 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 1984 @*/ 1985 PetscErrorCode PETSCMAT_DLLEXPORT MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 1986 { 1987 PetscErrorCode ierr; 1988 1989 PetscFunctionBegin; 1990 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1991 PetscValidType(mat,1); 1992 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 1993 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 1994 PetscValidPointer(info,4); 1995 PetscValidPointer(fact,5); 1996 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1997 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1998 if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1999 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2000 ierr = PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 2001 ierr = (*mat->ops->iludtfactor)(mat,row,col,info,fact);CHKERRQ(ierr); 2002 ierr = PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 2003 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2004 2005 PetscFunctionReturn(0); 2006 } 2007 2008 #undef __FUNCT__ 2009 #define __FUNCT__ "MatLUFactor" 2010 /*@ 2011 MatLUFactor - Performs in-place LU factorization of matrix. 2012 2013 Collective on Mat 2014 2015 Input Parameters: 2016 + mat - the matrix 2017 . row - row permutation 2018 . col - column permutation 2019 - info - options for factorization, includes 2020 $ fill - expected fill as ratio of original fill. 2021 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 2022 $ Run with the option -info to determine an optimal value to use 2023 2024 Notes: 2025 Most users should employ the simplified KSP interface for linear solvers 2026 instead of working directly with matrix algebra routines such as this. 2027 See, e.g., KSPCreate(). 2028 2029 This changes the state of the matrix to a factored matrix; it cannot be used 2030 for example with MatSetValues() unless one first calls MatSetUnfactored(). 2031 2032 Level: developer 2033 2034 Concepts: matrices^LU factorization 2035 2036 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), 2037 MatGetOrdering(), MatSetUnfactored(), MatFactorInfo 2038 2039 @*/ 2040 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info) 2041 { 2042 PetscErrorCode ierr; 2043 2044 PetscFunctionBegin; 2045 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2046 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 2047 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 2048 PetscValidPointer(info,4); 2049 PetscValidType(mat,1); 2050 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2051 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2052 if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2053 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2054 2055 ierr = PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 2056 ierr = (*mat->ops->lufactor)(mat,row,col,info);CHKERRQ(ierr); 2057 ierr = PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 2058 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 2059 PetscFunctionReturn(0); 2060 } 2061 2062 #undef __FUNCT__ 2063 #define __FUNCT__ "MatILUFactor" 2064 /*@ 2065 MatILUFactor - Performs in-place ILU factorization of matrix. 2066 2067 Collective on Mat 2068 2069 Input Parameters: 2070 + mat - the matrix 2071 . row - row permutation 2072 . col - column permutation 2073 - info - structure containing 2074 $ levels - number of levels of fill. 2075 $ expected fill - as ratio of original fill. 2076 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 2077 missing diagonal entries) 2078 2079 Notes: 2080 Probably really in-place only when level of fill is zero, otherwise allocates 2081 new space to store factored matrix and deletes previous memory. 2082 2083 Most users should employ the simplified KSP interface for linear solvers 2084 instead of working directly with matrix algebra routines such as this. 2085 See, e.g., KSPCreate(). 2086 2087 Level: developer 2088 2089 Concepts: matrices^ILU factorization 2090 2091 .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 2092 @*/ 2093 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info) 2094 { 2095 PetscErrorCode ierr; 2096 2097 PetscFunctionBegin; 2098 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2099 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 2100 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 2101 PetscValidPointer(info,4); 2102 PetscValidType(mat,1); 2103 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 2104 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2105 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2106 if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2107 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2108 2109 ierr = PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 2110 ierr = (*mat->ops->ilufactor)(mat,row,col,info);CHKERRQ(ierr); 2111 ierr = PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 2112 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 2113 PetscFunctionReturn(0); 2114 } 2115 2116 #undef __FUNCT__ 2117 #define __FUNCT__ "MatLUFactorSymbolic" 2118 /*@ 2119 MatLUFactorSymbolic - Performs symbolic LU factorization of matrix. 2120 Call this routine before calling MatLUFactorNumeric(). 2121 2122 Collective on Mat 2123 2124 Input Parameters: 2125 + mat - the matrix 2126 . row, col - row and column permutations 2127 - info - options for factorization, includes 2128 $ fill - expected fill as ratio of original fill. 2129 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 2130 $ Run with the option -info to determine an optimal value to use 2131 2132 Output Parameter: 2133 . fact - new matrix that has been symbolically factored 2134 2135 Notes: 2136 See the users manual for additional information about 2137 choosing the fill factor for better efficiency. 2138 2139 Most users should employ the simplified KSP interface for linear solvers 2140 instead of working directly with matrix algebra routines such as this. 2141 See, e.g., KSPCreate(). 2142 2143 Level: developer 2144 2145 Concepts: matrices^LU symbolic factorization 2146 2147 .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 2148 @*/ 2149 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 2150 { 2151 PetscErrorCode ierr; 2152 2153 PetscFunctionBegin; 2154 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2155 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 2156 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 2157 PetscValidPointer(info,4); 2158 PetscValidType(mat,1); 2159 PetscValidPointer(fact,5); 2160 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2161 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2162 if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic LU",mat->type_name); 2163 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2164 2165 ierr = PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 2166 ierr = (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 2167 ierr = PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 2168 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2169 PetscFunctionReturn(0); 2170 } 2171 2172 #undef __FUNCT__ 2173 #define __FUNCT__ "MatLUFactorNumeric" 2174 /*@ 2175 MatLUFactorNumeric - Performs numeric LU factorization of a matrix. 2176 Call this routine after first calling MatLUFactorSymbolic(). 2177 2178 Collective on Mat 2179 2180 Input Parameters: 2181 + mat - the matrix 2182 . info - options for factorization 2183 - fact - the matrix generated for the factor, from MatLUFactorSymbolic() 2184 2185 Notes: 2186 See MatLUFactor() for in-place factorization. See 2187 MatCholeskyFactorNumeric() for the symmetric, positive definite case. 2188 2189 Most users should employ the simplified KSP interface for linear solvers 2190 instead of working directly with matrix algebra routines such as this. 2191 See, e.g., KSPCreate(). 2192 2193 Level: developer 2194 2195 Concepts: matrices^LU numeric factorization 2196 2197 .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor() 2198 @*/ 2199 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact) 2200 { 2201 PetscErrorCode ierr; 2202 2203 PetscFunctionBegin; 2204 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2205 PetscValidType(mat,1); 2206 PetscValidPointer(fact,2); 2207 PetscValidHeaderSpecific(*fact,MAT_COOKIE,2); 2208 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2209 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 2210 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",mat->M,(*fact)->M,mat->N,(*fact)->N); 2211 } 2212 if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2213 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2214 ierr = PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2215 ierr = (*(*fact)->ops->lufactornumeric)(mat,info,fact);CHKERRQ(ierr); 2216 ierr = PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2217 2218 ierr = MatView_Private(*fact);CHKERRQ(ierr); 2219 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2220 PetscFunctionReturn(0); 2221 } 2222 2223 #undef __FUNCT__ 2224 #define __FUNCT__ "MatCholeskyFactor" 2225 /*@ 2226 MatCholeskyFactor - Performs in-place Cholesky factorization of a 2227 symmetric matrix. 2228 2229 Collective on Mat 2230 2231 Input Parameters: 2232 + mat - the matrix 2233 . perm - row and column permutations 2234 - f - expected fill as ratio of original fill 2235 2236 Notes: 2237 See MatLUFactor() for the nonsymmetric case. See also 2238 MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric(). 2239 2240 Most users should employ the simplified KSP interface for linear solvers 2241 instead of working directly with matrix algebra routines such as this. 2242 See, e.g., KSPCreate(). 2243 2244 Level: developer 2245 2246 Concepts: matrices^Cholesky factorization 2247 2248 .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric() 2249 MatGetOrdering() 2250 2251 @*/ 2252 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info) 2253 { 2254 PetscErrorCode ierr; 2255 2256 PetscFunctionBegin; 2257 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2258 PetscValidType(mat,1); 2259 PetscValidHeaderSpecific(perm,IS_COOKIE,2); 2260 PetscValidPointer(info,3); 2261 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 2262 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2263 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2264 if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2265 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2266 2267 ierr = PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 2268 ierr = (*mat->ops->choleskyfactor)(mat,perm,info);CHKERRQ(ierr); 2269 ierr = PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 2270 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 2271 PetscFunctionReturn(0); 2272 } 2273 2274 #undef __FUNCT__ 2275 #define __FUNCT__ "MatCholeskyFactorSymbolic" 2276 /*@ 2277 MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization 2278 of a symmetric matrix. 2279 2280 Collective on Mat 2281 2282 Input Parameters: 2283 + mat - the matrix 2284 . perm - row and column permutations 2285 - info - options for factorization, includes 2286 $ fill - expected fill as ratio of original fill. 2287 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 2288 $ Run with the option -info to determine an optimal value to use 2289 2290 Output Parameter: 2291 . fact - the factored matrix 2292 2293 Notes: 2294 See MatLUFactorSymbolic() for the nonsymmetric case. See also 2295 MatCholeskyFactor() and MatCholeskyFactorNumeric(). 2296 2297 Most users should employ the simplified KSP interface for linear solvers 2298 instead of working directly with matrix algebra routines such as this. 2299 See, e.g., KSPCreate(). 2300 2301 Level: developer 2302 2303 Concepts: matrices^Cholesky symbolic factorization 2304 2305 .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric() 2306 MatGetOrdering() 2307 2308 @*/ 2309 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact) 2310 { 2311 PetscErrorCode ierr; 2312 2313 PetscFunctionBegin; 2314 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2315 PetscValidType(mat,1); 2316 if (perm) PetscValidHeaderSpecific(perm,IS_COOKIE,2); 2317 PetscValidPointer(info,3); 2318 PetscValidPointer(fact,4); 2319 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 2320 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2321 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2322 if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2323 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2324 2325 ierr = PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 2326 ierr = (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);CHKERRQ(ierr); 2327 ierr = PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 2328 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2329 PetscFunctionReturn(0); 2330 } 2331 2332 #undef __FUNCT__ 2333 #define __FUNCT__ "MatCholeskyFactorNumeric" 2334 /*@ 2335 MatCholeskyFactorNumeric - Performs numeric Cholesky factorization 2336 of a symmetric matrix. Call this routine after first calling 2337 MatCholeskyFactorSymbolic(). 2338 2339 Collective on Mat 2340 2341 Input Parameter: 2342 . mat - the initial matrix 2343 . info - options for factorization 2344 - fact - the symbolic factor of mat 2345 2346 Output Parameter: 2347 . fact - the factored matrix 2348 2349 Notes: 2350 Most users should employ the simplified KSP interface for linear solvers 2351 instead of working directly with matrix algebra routines such as this. 2352 See, e.g., KSPCreate(). 2353 2354 Level: developer 2355 2356 Concepts: matrices^Cholesky numeric factorization 2357 2358 .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric() 2359 @*/ 2360 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact) 2361 { 2362 PetscErrorCode ierr; 2363 2364 PetscFunctionBegin; 2365 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2366 PetscValidType(mat,1); 2367 PetscValidPointer(fact,2); 2368 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2369 if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2370 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 2371 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->M,(*fact)->M,mat->N,(*fact)->N); 2372 } 2373 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2374 2375 ierr = PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2376 ierr = (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);CHKERRQ(ierr); 2377 ierr = PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2378 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2379 PetscFunctionReturn(0); 2380 } 2381 2382 /* ----------------------------------------------------------------*/ 2383 #undef __FUNCT__ 2384 #define __FUNCT__ "MatSolve" 2385 /*@ 2386 MatSolve - Solves A x = b, given a factored matrix. 2387 2388 Collective on Mat and Vec 2389 2390 Input Parameters: 2391 + mat - the factored matrix 2392 - b - the right-hand-side vector 2393 2394 Output Parameter: 2395 . x - the result vector 2396 2397 Notes: 2398 The vectors b and x cannot be the same. I.e., one cannot 2399 call MatSolve(A,x,x). 2400 2401 Notes: 2402 Most users should employ the simplified KSP interface for linear solvers 2403 instead of working directly with matrix algebra routines such as this. 2404 See, e.g., KSPCreate(). 2405 2406 Level: developer 2407 2408 Concepts: matrices^triangular solves 2409 2410 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd() 2411 @*/ 2412 PetscErrorCode PETSCMAT_DLLEXPORT MatSolve(Mat mat,Vec b,Vec x) 2413 { 2414 PetscErrorCode ierr; 2415 2416 PetscFunctionBegin; 2417 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2418 PetscValidType(mat,1); 2419 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2420 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2421 PetscCheckSameComm(mat,1,b,2); 2422 PetscCheckSameComm(mat,1,x,3); 2423 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2424 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2425 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2426 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2427 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2428 if (!mat->M && !mat->N) PetscFunctionReturn(0); 2429 if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2430 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2431 2432 ierr = PetscLogEventBegin(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2433 ierr = (*mat->ops->solve)(mat,b,x);CHKERRQ(ierr); 2434 ierr = PetscLogEventEnd(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2435 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2436 PetscFunctionReturn(0); 2437 } 2438 2439 #undef __FUNCT__ 2440 #define __FUNCT__ "MatMatSolve" 2441 /*@ 2442 MatMatSolve - Solves A X = B, given a factored matrix. 2443 2444 Collective on Mat 2445 2446 Input Parameters: 2447 + mat - the factored matrix 2448 - b - the right-hand-side vector 2449 2450 Output Parameter: 2451 . x - the result vector 2452 2453 Notes: 2454 The vectors b and x cannot be the same. I.e., one cannot 2455 call MatMatSolve(A,x,x). 2456 2457 Notes: 2458 Most users should employ the simplified KSP interface for linear solvers 2459 instead of working directly with matrix algebra routines such as this. 2460 See, e.g., KSPCreate(). 2461 2462 Level: developer 2463 2464 Concepts: matrices^triangular solves 2465 2466 .seealso: MatMatSolveAdd(), MatMatSolveTranspose(), MatMatSolveTransposeAdd() 2467 @*/ 2468 PetscErrorCode PETSCMAT_DLLEXPORT MatMatSolve(Mat A,Mat B,Mat X) 2469 { 2470 PetscErrorCode ierr; 2471 2472 PetscFunctionBegin; 2473 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 2474 PetscValidType(A,1); 2475 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 2476 PetscValidHeaderSpecific(X,MAT_COOKIE,3); 2477 PetscCheckSameComm(A,1,B,2); 2478 PetscCheckSameComm(A,1,X,3); 2479 if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices"); 2480 if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2481 if (A->N != X->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat X: global dim %D %D",A->N,X->M); 2482 if (A->M != B->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D",A->M,B->M); 2483 if (A->m != B->m) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: local dim %D %D",A->m,B->m); 2484 if (!A->M && !A->N) PetscFunctionReturn(0); 2485 if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name); 2486 ierr = MatPreallocated(A);CHKERRQ(ierr); 2487 2488 ierr = PetscLogEventBegin(MAT_MatSolve,A,B,X,0);CHKERRQ(ierr); 2489 ierr = (*A->ops->matsolve)(A,B,X);CHKERRQ(ierr); 2490 ierr = PetscLogEventEnd(MAT_MatSolve,A,B,X,0);CHKERRQ(ierr); 2491 ierr = PetscObjectStateIncrease((PetscObject)X);CHKERRQ(ierr); 2492 PetscFunctionReturn(0); 2493 } 2494 2495 2496 #undef __FUNCT__ 2497 #define __FUNCT__ "MatForwardSolve" 2498 /* @ 2499 MatForwardSolve - Solves L x = b, given a factored matrix, A = LU. 2500 2501 Collective on Mat and Vec 2502 2503 Input Parameters: 2504 + mat - the factored matrix 2505 - b - the right-hand-side vector 2506 2507 Output Parameter: 2508 . x - the result vector 2509 2510 Notes: 2511 MatSolve() should be used for most applications, as it performs 2512 a forward solve followed by a backward solve. 2513 2514 The vectors b and x cannot be the same. I.e., one cannot 2515 call MatForwardSolve(A,x,x). 2516 2517 Most users should employ the simplified KSP interface for linear solvers 2518 instead of working directly with matrix algebra routines such as this. 2519 See, e.g., KSPCreate(). 2520 2521 Level: developer 2522 2523 Concepts: matrices^forward solves 2524 2525 .seealso: MatSolve(), MatBackwardSolve() 2526 @ */ 2527 PetscErrorCode PETSCMAT_DLLEXPORT MatForwardSolve(Mat mat,Vec b,Vec x) 2528 { 2529 PetscErrorCode ierr; 2530 2531 PetscFunctionBegin; 2532 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2533 PetscValidType(mat,1); 2534 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2535 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2536 PetscCheckSameComm(mat,1,b,2); 2537 PetscCheckSameComm(mat,1,x,3); 2538 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2539 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2540 if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2541 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2542 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2543 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2544 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2545 ierr = PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2546 ierr = (*mat->ops->forwardsolve)(mat,b,x);CHKERRQ(ierr); 2547 ierr = PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2548 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2549 PetscFunctionReturn(0); 2550 } 2551 2552 #undef __FUNCT__ 2553 #define __FUNCT__ "MatBackwardSolve" 2554 /* @ 2555 MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU. 2556 2557 Collective on Mat and Vec 2558 2559 Input Parameters: 2560 + mat - the factored matrix 2561 - b - the right-hand-side vector 2562 2563 Output Parameter: 2564 . x - the result vector 2565 2566 Notes: 2567 MatSolve() should be used for most applications, as it performs 2568 a forward solve followed by a backward solve. 2569 2570 The vectors b and x cannot be the same. I.e., one cannot 2571 call MatBackwardSolve(A,x,x). 2572 2573 Most users should employ the simplified KSP interface for linear solvers 2574 instead of working directly with matrix algebra routines such as this. 2575 See, e.g., KSPCreate(). 2576 2577 Level: developer 2578 2579 Concepts: matrices^backward solves 2580 2581 .seealso: MatSolve(), MatForwardSolve() 2582 @ */ 2583 PetscErrorCode PETSCMAT_DLLEXPORT MatBackwardSolve(Mat mat,Vec b,Vec x) 2584 { 2585 PetscErrorCode ierr; 2586 2587 PetscFunctionBegin; 2588 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2589 PetscValidType(mat,1); 2590 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2591 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2592 PetscCheckSameComm(mat,1,b,2); 2593 PetscCheckSameComm(mat,1,x,3); 2594 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2595 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2596 if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2597 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2598 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2599 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2600 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2601 2602 ierr = PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2603 ierr = (*mat->ops->backwardsolve)(mat,b,x);CHKERRQ(ierr); 2604 ierr = PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2605 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2606 PetscFunctionReturn(0); 2607 } 2608 2609 #undef __FUNCT__ 2610 #define __FUNCT__ "MatSolveAdd" 2611 /*@ 2612 MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix. 2613 2614 Collective on Mat and Vec 2615 2616 Input Parameters: 2617 + mat - the factored matrix 2618 . b - the right-hand-side vector 2619 - y - the vector to be added to 2620 2621 Output Parameter: 2622 . x - the result vector 2623 2624 Notes: 2625 The vectors b and x cannot be the same. I.e., one cannot 2626 call MatSolveAdd(A,x,y,x). 2627 2628 Most users should employ the simplified KSP interface for linear solvers 2629 instead of working directly with matrix algebra routines such as this. 2630 See, e.g., KSPCreate(). 2631 2632 Level: developer 2633 2634 Concepts: matrices^triangular solves 2635 2636 .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd() 2637 @*/ 2638 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveAdd(Mat mat,Vec b,Vec y,Vec x) 2639 { 2640 PetscScalar one = 1.0; 2641 Vec tmp; 2642 PetscErrorCode ierr; 2643 2644 PetscFunctionBegin; 2645 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2646 PetscValidType(mat,1); 2647 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2648 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2649 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2650 PetscCheckSameComm(mat,1,b,2); 2651 PetscCheckSameComm(mat,1,y,2); 2652 PetscCheckSameComm(mat,1,x,3); 2653 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2654 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2655 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2656 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2657 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 2658 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2659 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n); 2660 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2661 2662 ierr = PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2663 if (mat->ops->solveadd) { 2664 ierr = (*mat->ops->solveadd)(mat,b,y,x);CHKERRQ(ierr); 2665 } else { 2666 /* do the solve then the add manually */ 2667 if (x != y) { 2668 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2669 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2670 } else { 2671 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2672 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2673 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2674 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2675 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2676 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2677 } 2678 } 2679 ierr = PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2680 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2681 PetscFunctionReturn(0); 2682 } 2683 2684 #undef __FUNCT__ 2685 #define __FUNCT__ "MatSolveTranspose" 2686 /*@ 2687 MatSolveTranspose - Solves A' x = b, given a factored matrix. 2688 2689 Collective on Mat and Vec 2690 2691 Input Parameters: 2692 + mat - the factored matrix 2693 - b - the right-hand-side vector 2694 2695 Output Parameter: 2696 . x - the result vector 2697 2698 Notes: 2699 The vectors b and x cannot be the same. I.e., one cannot 2700 call MatSolveTranspose(A,x,x). 2701 2702 Most users should employ the simplified KSP interface for linear solvers 2703 instead of working directly with matrix algebra routines such as this. 2704 See, e.g., KSPCreate(). 2705 2706 Level: developer 2707 2708 Concepts: matrices^triangular solves 2709 2710 .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd() 2711 @*/ 2712 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTranspose(Mat mat,Vec b,Vec x) 2713 { 2714 PetscErrorCode ierr; 2715 2716 PetscFunctionBegin; 2717 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2718 PetscValidType(mat,1); 2719 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2720 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2721 PetscCheckSameComm(mat,1,b,2); 2722 PetscCheckSameComm(mat,1,x,3); 2723 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2724 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2725 if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name); 2726 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 2727 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N); 2728 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2729 ierr = PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2730 ierr = (*mat->ops->solvetranspose)(mat,b,x);CHKERRQ(ierr); 2731 ierr = PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2732 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2733 PetscFunctionReturn(0); 2734 } 2735 2736 #undef __FUNCT__ 2737 #define __FUNCT__ "MatSolveTransposeAdd" 2738 /*@ 2739 MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 2740 factored matrix. 2741 2742 Collective on Mat and Vec 2743 2744 Input Parameters: 2745 + mat - the factored matrix 2746 . b - the right-hand-side vector 2747 - y - the vector to be added to 2748 2749 Output Parameter: 2750 . x - the result vector 2751 2752 Notes: 2753 The vectors b and x cannot be the same. I.e., one cannot 2754 call MatSolveTransposeAdd(A,x,y,x). 2755 2756 Most users should employ the simplified KSP interface for linear solvers 2757 instead of working directly with matrix algebra routines such as this. 2758 See, e.g., KSPCreate(). 2759 2760 Level: developer 2761 2762 Concepts: matrices^triangular solves 2763 2764 .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose() 2765 @*/ 2766 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x) 2767 { 2768 PetscScalar one = 1.0; 2769 PetscErrorCode ierr; 2770 Vec tmp; 2771 2772 PetscFunctionBegin; 2773 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2774 PetscValidType(mat,1); 2775 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2776 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2777 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2778 PetscCheckSameComm(mat,1,b,2); 2779 PetscCheckSameComm(mat,1,y,3); 2780 PetscCheckSameComm(mat,1,x,4); 2781 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2782 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2783 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 2784 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N); 2785 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N); 2786 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n); 2787 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2788 2789 ierr = PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2790 if (mat->ops->solvetransposeadd) { 2791 ierr = (*mat->ops->solvetransposeadd)(mat,b,y,x);CHKERRQ(ierr); 2792 } else { 2793 /* do the solve then the add manually */ 2794 if (x != y) { 2795 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2796 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2797 } else { 2798 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2799 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2800 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2801 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2802 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2803 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2804 } 2805 } 2806 ierr = PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2807 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2808 PetscFunctionReturn(0); 2809 } 2810 /* ----------------------------------------------------------------*/ 2811 2812 #undef __FUNCT__ 2813 #define __FUNCT__ "MatRelax" 2814 /*@ 2815 MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2816 2817 Collective on Mat and Vec 2818 2819 Input Parameters: 2820 + mat - the matrix 2821 . b - the right hand side 2822 . omega - the relaxation factor 2823 . flag - flag indicating the type of SOR (see below) 2824 . shift - diagonal shift 2825 - its - the number of iterations 2826 - lits - the number of local iterations 2827 2828 Output Parameters: 2829 . x - the solution (can contain an initial guess) 2830 2831 SOR Flags: 2832 . SOR_FORWARD_SWEEP - forward SOR 2833 . SOR_BACKWARD_SWEEP - backward SOR 2834 . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR) 2835 . SOR_LOCAL_FORWARD_SWEEP - local forward SOR 2836 . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 2837 . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR 2838 . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 2839 upper/lower triangular part of matrix to 2840 vector (with omega) 2841 . SOR_ZERO_INITIAL_GUESS - zero initial guess 2842 2843 Notes: 2844 SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and 2845 SOR_LOCAL_SYMMETRIC_SWEEP perform separate independent smoothings 2846 on each processor. 2847 2848 Application programmers will not generally use MatRelax() directly, 2849 but instead will employ the KSP/PC interface. 2850 2851 Notes for Advanced Users: 2852 The flags are implemented as bitwise inclusive or operations. 2853 For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP) 2854 to specify a zero initial guess for SSOR. 2855 2856 Most users should employ the simplified KSP interface for linear solvers 2857 instead of working directly with matrix algebra routines such as this. 2858 See, e.g., KSPCreate(). 2859 2860 See also, MatPBRelax(). This routine will automatically call the point block 2861 version if the point version is not available. 2862 2863 Level: developer 2864 2865 Concepts: matrices^relaxation 2866 Concepts: matrices^SOR 2867 Concepts: matrices^Gauss-Seidel 2868 2869 @*/ 2870 PetscErrorCode PETSCMAT_DLLEXPORT MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2871 { 2872 PetscErrorCode ierr; 2873 2874 PetscFunctionBegin; 2875 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2876 PetscValidType(mat,1); 2877 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2878 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2879 PetscCheckSameComm(mat,1,b,2); 2880 PetscCheckSameComm(mat,1,x,8); 2881 if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2882 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2883 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2884 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2885 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2886 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2887 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2888 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2889 if (mat->ops->relax) { 2890 ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2891 } else { 2892 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2893 } 2894 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2895 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2896 PetscFunctionReturn(0); 2897 } 2898 2899 #undef __FUNCT__ 2900 #define __FUNCT__ "MatPBRelax" 2901 /*@ 2902 MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2903 2904 Collective on Mat and Vec 2905 2906 See MatRelax() for usage 2907 2908 For multi-component PDEs where the Jacobian is stored in a point block format 2909 (with the PETSc BAIJ matrix formats) the relaxation is done one point block at 2910 a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved 2911 simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point. 2912 2913 Level: developer 2914 2915 @*/ 2916 PetscErrorCode PETSCMAT_DLLEXPORT MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2917 { 2918 PetscErrorCode ierr; 2919 2920 PetscFunctionBegin; 2921 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2922 PetscValidType(mat,1); 2923 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2924 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2925 PetscCheckSameComm(mat,1,b,2); 2926 PetscCheckSameComm(mat,1,x,8); 2927 if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2928 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2929 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2930 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2931 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2932 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2933 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2934 2935 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2936 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2937 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2938 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2939 PetscFunctionReturn(0); 2940 } 2941 2942 #undef __FUNCT__ 2943 #define __FUNCT__ "MatCopy_Basic" 2944 /* 2945 Default matrix copy routine. 2946 */ 2947 PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str) 2948 { 2949 PetscErrorCode ierr; 2950 PetscInt i,rstart,rend,nz; 2951 const PetscInt *cwork; 2952 const PetscScalar *vwork; 2953 2954 PetscFunctionBegin; 2955 if (B->assembled) { 2956 ierr = MatZeroEntries(B);CHKERRQ(ierr); 2957 } 2958 ierr = MatGetOwnershipRange(A,&rstart,&rend);CHKERRQ(ierr); 2959 for (i=rstart; i<rend; i++) { 2960 ierr = MatGetRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2961 ierr = MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);CHKERRQ(ierr); 2962 ierr = MatRestoreRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2963 } 2964 ierr = MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2965 ierr = MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2966 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2967 PetscFunctionReturn(0); 2968 } 2969 2970 #undef __FUNCT__ 2971 #define __FUNCT__ "MatCopy" 2972 /*@ 2973 MatCopy - Copys a matrix to another matrix. 2974 2975 Collective on Mat 2976 2977 Input Parameters: 2978 + A - the matrix 2979 - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN 2980 2981 Output Parameter: 2982 . B - where the copy is put 2983 2984 Notes: 2985 If you use SAME_NONZERO_PATTERN then the two matrices had better have the 2986 same nonzero pattern or the routine will crash. 2987 2988 MatCopy() copies the matrix entries of a matrix to another existing 2989 matrix (after first zeroing the second matrix). A related routine is 2990 MatConvert(), which first creates a new matrix and then copies the data. 2991 2992 Level: intermediate 2993 2994 Concepts: matrices^copying 2995 2996 .seealso: MatConvert(), MatDuplicate() 2997 2998 @*/ 2999 PetscErrorCode PETSCMAT_DLLEXPORT MatCopy(Mat A,Mat B,MatStructure str) 3000 { 3001 PetscErrorCode ierr; 3002 3003 PetscFunctionBegin; 3004 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3005 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3006 PetscValidType(A,1); 3007 PetscValidType(B,2); 3008 MatPreallocated(B); 3009 PetscCheckSameComm(A,1,B,2); 3010 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3011 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3012 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); 3013 ierr = MatPreallocated(A);CHKERRQ(ierr); 3014 3015 ierr = PetscLogEventBegin(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 3016 if (A->ops->copy) { 3017 ierr = (*A->ops->copy)(A,B,str);CHKERRQ(ierr); 3018 } else { /* generic conversion */ 3019 ierr = MatCopy_Basic(A,B,str);CHKERRQ(ierr); 3020 } 3021 if (A->mapping) { 3022 if (B->mapping) {ierr = ISLocalToGlobalMappingDestroy(B->mapping);CHKERRQ(ierr);B->mapping = 0;} 3023 ierr = MatSetLocalToGlobalMapping(B,A->mapping);CHKERRQ(ierr); 3024 } 3025 if (A->bmapping) { 3026 if (B->bmapping) {ierr = ISLocalToGlobalMappingDestroy(B->bmapping);CHKERRQ(ierr);B->bmapping = 0;} 3027 ierr = MatSetLocalToGlobalMappingBlock(B,A->mapping);CHKERRQ(ierr); 3028 } 3029 ierr = PetscLogEventEnd(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 3030 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3031 PetscFunctionReturn(0); 3032 } 3033 3034 #include "petscsys.h" 3035 PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE; 3036 PetscFList MatConvertList = 0; 3037 3038 #undef __FUNCT__ 3039 #define __FUNCT__ "MatConvertRegister" 3040 /*@C 3041 MatConvertRegister - Allows one to register a routine that converts a sparse matrix 3042 from one format to another. 3043 3044 Not Collective 3045 3046 Input Parameters: 3047 + type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ. 3048 - Converter - the function that reads the matrix from the binary file. 3049 3050 Level: developer 3051 3052 .seealso: MatConvertRegisterAll(), MatConvert() 3053 3054 @*/ 3055 PetscErrorCode PETSCMAT_DLLEXPORT MatConvertRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(Mat,MatType,MatReuse,Mat*)) 3056 { 3057 PetscErrorCode ierr; 3058 char fullname[PETSC_MAX_PATH_LEN]; 3059 3060 PetscFunctionBegin; 3061 ierr = PetscFListConcat(path,name,fullname);CHKERRQ(ierr); 3062 ierr = PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);CHKERRQ(ierr); 3063 PetscFunctionReturn(0); 3064 } 3065 3066 #undef __FUNCT__ 3067 #define __FUNCT__ "MatConvert" 3068 /*@C 3069 MatConvert - Converts a matrix to another matrix, either of the same 3070 or different type. 3071 3072 Collective on Mat 3073 3074 Input Parameters: 3075 + mat - the matrix 3076 . newtype - new matrix type. Use MATSAME to create a new matrix of the 3077 same type as the original matrix. 3078 - reuse - denotes if the destination matrix is to be created or reused. Currently 3079 MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use 3080 MAT_INITIAL_MATRIX. 3081 Output Parameter: 3082 . M - pointer to place new matrix 3083 3084 Notes: 3085 MatConvert() first creates a new matrix and then copies the data from 3086 the first matrix. A related routine is MatCopy(), which copies the matrix 3087 entries of one matrix to another already existing matrix context. 3088 3089 Level: intermediate 3090 3091 Concepts: matrices^converting between storage formats 3092 3093 .seealso: MatCopy(), MatDuplicate() 3094 @*/ 3095 PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M) 3096 { 3097 PetscErrorCode ierr; 3098 PetscTruth sametype,issame,flg; 3099 char convname[256],mtype[256]; 3100 Mat B; 3101 3102 PetscFunctionBegin; 3103 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3104 PetscValidType(mat,1); 3105 PetscValidPointer(M,3); 3106 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3107 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3108 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3109 3110 ierr = PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);CHKERRQ(ierr); 3111 if (flg) { 3112 newtype = mtype; 3113 } 3114 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3115 3116 ierr = PetscTypeCompare((PetscObject)mat,newtype,&sametype);CHKERRQ(ierr); 3117 ierr = PetscStrcmp(newtype,"same",&issame);CHKERRQ(ierr); 3118 if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) { 3119 SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for inplace convertion currently"); 3120 } 3121 if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) { 3122 ierr = (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);CHKERRQ(ierr); 3123 } else { 3124 PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL; 3125 /* 3126 Order of precedence: 3127 1) See if a specialized converter is known to the current matrix. 3128 2) See if a specialized converter is known to the desired matrix class. 3129 3) See if a good general converter is registered for the desired class 3130 (as of 6/27/03 only MATMPIADJ falls into this category). 3131 4) See if a good general converter is known for the current matrix. 3132 5) Use a really basic converter. 3133 */ 3134 ierr = PetscStrcpy(convname,"MatConvert_");CHKERRQ(ierr); 3135 ierr = PetscStrcat(convname,mat->type_name);CHKERRQ(ierr); 3136 ierr = PetscStrcat(convname,"_");CHKERRQ(ierr); 3137 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 3138 ierr = PetscStrcat(convname,"_C");CHKERRQ(ierr); 3139 ierr = PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);CHKERRQ(ierr); 3140 3141 if (!conv) { 3142 ierr = MatCreate(mat->comm,&B);CHKERRQ(ierr); 3143 ierr = MatSetSizes(B,0,0,0,0);CHKERRQ(ierr); 3144 ierr = MatSetType(B,newtype);CHKERRQ(ierr); 3145 ierr = PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);CHKERRQ(ierr); 3146 ierr = MatDestroy(B);CHKERRQ(ierr); 3147 if (!conv) { 3148 if (!MatConvertRegisterAllCalled) { 3149 ierr = MatConvertRegisterAll(PETSC_NULL);CHKERRQ(ierr); 3150 } 3151 ierr = PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);CHKERRQ(ierr); 3152 if (!conv) { 3153 if (mat->ops->convert) { 3154 conv = mat->ops->convert; 3155 } else { 3156 conv = MatConvert_Basic; 3157 } 3158 } 3159 } 3160 } 3161 ierr = (*conv)(mat,newtype,reuse,M);CHKERRQ(ierr); 3162 } 3163 B = *M; 3164 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3165 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3166 PetscFunctionReturn(0); 3167 } 3168 3169 3170 #undef __FUNCT__ 3171 #define __FUNCT__ "MatDuplicate" 3172 /*@ 3173 MatDuplicate - Duplicates a matrix including the non-zero structure. 3174 3175 Collective on Mat 3176 3177 Input Parameters: 3178 + mat - the matrix 3179 - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero 3180 values as well or not 3181 3182 Output Parameter: 3183 . M - pointer to place new matrix 3184 3185 Level: intermediate 3186 3187 Concepts: matrices^duplicating 3188 3189 .seealso: MatCopy(), MatConvert() 3190 @*/ 3191 PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M) 3192 { 3193 PetscErrorCode ierr; 3194 Mat B; 3195 3196 PetscFunctionBegin; 3197 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3198 PetscValidType(mat,1); 3199 PetscValidPointer(M,3); 3200 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3201 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3202 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3203 3204 *M = 0; 3205 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3206 if (!mat->ops->duplicate) { 3207 SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type"); 3208 } 3209 ierr = (*mat->ops->duplicate)(mat,op,M);CHKERRQ(ierr); 3210 B = *M; 3211 if (mat->mapping) { 3212 ierr = MatSetLocalToGlobalMapping(B,mat->mapping);CHKERRQ(ierr); 3213 } 3214 if (mat->bmapping) { 3215 ierr = MatSetLocalToGlobalMappingBlock(B,mat->bmapping);CHKERRQ(ierr); 3216 } 3217 ierr = PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);CHKERRQ(ierr); 3218 ierr = PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);CHKERRQ(ierr); 3219 3220 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3221 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3222 PetscFunctionReturn(0); 3223 } 3224 3225 #undef __FUNCT__ 3226 #define __FUNCT__ "MatGetDiagonal" 3227 /*@ 3228 MatGetDiagonal - Gets the diagonal of a matrix. 3229 3230 Collective on Mat and Vec 3231 3232 Input Parameters: 3233 + mat - the matrix 3234 - v - the vector for storing the diagonal 3235 3236 Output Parameter: 3237 . v - the diagonal of the matrix 3238 3239 Notes: 3240 For the SeqAIJ matrix format, this routine may also be called 3241 on a LU factored matrix; in that case it routines the reciprocal of 3242 the diagonal entries in U. It returns the entries permuted by the 3243 row and column permutation used during the symbolic factorization. 3244 3245 Level: intermediate 3246 3247 Concepts: matrices^accessing diagonals 3248 3249 .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax() 3250 @*/ 3251 PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v) 3252 { 3253 PetscErrorCode ierr; 3254 3255 PetscFunctionBegin; 3256 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3257 PetscValidType(mat,1); 3258 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 3259 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3260 if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3261 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3262 3263 ierr = (*mat->ops->getdiagonal)(mat,v);CHKERRQ(ierr); 3264 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 3265 PetscFunctionReturn(0); 3266 } 3267 3268 #undef __FUNCT__ 3269 #define __FUNCT__ "MatGetRowMax" 3270 /*@ 3271 MatGetRowMax - Gets the maximum value (in absolute value) of each 3272 row of the matrix 3273 3274 Collective on Mat and Vec 3275 3276 Input Parameters: 3277 . mat - the matrix 3278 3279 Output Parameter: 3280 . v - the vector for storing the maximums 3281 3282 Level: intermediate 3283 3284 Concepts: matrices^getting row maximums 3285 3286 .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix() 3287 @*/ 3288 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v) 3289 { 3290 PetscErrorCode ierr; 3291 3292 PetscFunctionBegin; 3293 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3294 PetscValidType(mat,1); 3295 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 3296 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3297 if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3298 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3299 3300 ierr = (*mat->ops->getrowmax)(mat,v);CHKERRQ(ierr); 3301 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 3302 PetscFunctionReturn(0); 3303 } 3304 3305 #undef __FUNCT__ 3306 #define __FUNCT__ "MatTranspose" 3307 /*@C 3308 MatTranspose - Computes an in-place or out-of-place transpose of a matrix. 3309 3310 Collective on Mat 3311 3312 Input Parameter: 3313 . mat - the matrix to transpose 3314 3315 Output Parameters: 3316 . B - the transpose (or pass in PETSC_NULL for an in-place transpose) 3317 3318 Level: intermediate 3319 3320 Concepts: matrices^transposing 3321 3322 .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose() 3323 @*/ 3324 PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B) 3325 { 3326 PetscErrorCode ierr; 3327 3328 PetscFunctionBegin; 3329 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3330 PetscValidType(mat,1); 3331 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3332 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3333 if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3334 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3335 3336 ierr = PetscLogEventBegin(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 3337 ierr = (*mat->ops->transpose)(mat,B);CHKERRQ(ierr); 3338 ierr = PetscLogEventEnd(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 3339 if (B) {ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr);} 3340 PetscFunctionReturn(0); 3341 } 3342 3343 #undef __FUNCT__ 3344 #define __FUNCT__ "MatIsTranspose" 3345 /*@C 3346 MatIsTranspose - Test whether a matrix is another one's transpose, 3347 or its own, in which case it tests symmetry. 3348 3349 Collective on Mat 3350 3351 Input Parameter: 3352 + A - the matrix to test 3353 - B - the matrix to test against, this can equal the first parameter 3354 3355 Output Parameters: 3356 . flg - the result 3357 3358 Notes: 3359 Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm 3360 has a running time of the order of the number of nonzeros; the parallel 3361 test involves parallel copies of the block-offdiagonal parts of the matrix. 3362 3363 Level: intermediate 3364 3365 Concepts: matrices^transposing, matrix^symmetry 3366 3367 .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian() 3368 @*/ 3369 PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg) 3370 { 3371 PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*); 3372 3373 PetscFunctionBegin; 3374 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3375 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3376 PetscValidPointer(flg,3); 3377 ierr = PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);CHKERRQ(ierr); 3378 ierr = PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);CHKERRQ(ierr); 3379 if (f && g) { 3380 if (f==g) { 3381 ierr = (*f)(A,B,tol,flg);CHKERRQ(ierr); 3382 } else { 3383 SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test"); 3384 } 3385 } 3386 PetscFunctionReturn(0); 3387 } 3388 3389 #undef __FUNCT__ 3390 #define __FUNCT__ "MatPermute" 3391 /*@C 3392 MatPermute - Creates a new matrix with rows and columns permuted from the 3393 original. 3394 3395 Collective on Mat 3396 3397 Input Parameters: 3398 + mat - the matrix to permute 3399 . row - row permutation, each processor supplies only the permutation for its rows 3400 - col - column permutation, each processor needs the entire column permutation, that is 3401 this is the same size as the total number of columns in the matrix 3402 3403 Output Parameters: 3404 . B - the permuted matrix 3405 3406 Level: advanced 3407 3408 Concepts: matrices^permuting 3409 3410 .seealso: MatGetOrdering() 3411 @*/ 3412 PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B) 3413 { 3414 PetscErrorCode ierr; 3415 3416 PetscFunctionBegin; 3417 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3418 PetscValidType(mat,1); 3419 PetscValidHeaderSpecific(row,IS_COOKIE,2); 3420 PetscValidHeaderSpecific(col,IS_COOKIE,3); 3421 PetscValidPointer(B,4); 3422 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3423 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3424 if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"MatPermute not available for Mat type %s",mat->type_name); 3425 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3426 3427 ierr = (*mat->ops->permute)(mat,row,col,B);CHKERRQ(ierr); 3428 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3429 PetscFunctionReturn(0); 3430 } 3431 3432 #undef __FUNCT__ 3433 #define __FUNCT__ "MatPermuteSparsify" 3434 /*@C 3435 MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the 3436 original and sparsified to the prescribed tolerance. 3437 3438 Collective on Mat 3439 3440 Input Parameters: 3441 + A - The matrix to permute 3442 . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE 3443 . frac - The half-bandwidth as a fraction of the total size, or 0.0 3444 . tol - The drop tolerance 3445 . rowp - The row permutation 3446 - colp - The column permutation 3447 3448 Output Parameter: 3449 . B - The permuted, sparsified matrix 3450 3451 Level: advanced 3452 3453 Note: 3454 The default behavior (band = PETSC_DECIDE and frac = 0.0) is to 3455 restrict the half-bandwidth of the resulting matrix to 5% of the 3456 total matrix size. 3457 3458 .keywords: matrix, permute, sparsify 3459 3460 .seealso: MatGetOrdering(), MatPermute() 3461 @*/ 3462 PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B) 3463 { 3464 IS irowp, icolp; 3465 PetscInt *rows, *cols; 3466 PetscInt M, N, locRowStart, locRowEnd; 3467 PetscInt nz, newNz; 3468 const PetscInt *cwork; 3469 PetscInt *cnew; 3470 const PetscScalar *vwork; 3471 PetscScalar *vnew; 3472 PetscInt bw, issize; 3473 PetscInt row, locRow, newRow, col, newCol; 3474 PetscErrorCode ierr; 3475 3476 PetscFunctionBegin; 3477 PetscValidHeaderSpecific(A, MAT_COOKIE,1); 3478 PetscValidHeaderSpecific(rowp, IS_COOKIE,5); 3479 PetscValidHeaderSpecific(colp, IS_COOKIE,6); 3480 PetscValidPointer(B,7); 3481 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix"); 3482 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix"); 3483 if (!A->ops->permutesparsify) { 3484 ierr = MatGetSize(A, &M, &N);CHKERRQ(ierr); 3485 ierr = MatGetOwnershipRange(A, &locRowStart, &locRowEnd);CHKERRQ(ierr); 3486 ierr = ISGetSize(rowp, &issize);CHKERRQ(ierr); 3487 if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M); 3488 ierr = ISGetSize(colp, &issize);CHKERRQ(ierr); 3489 if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N); 3490 ierr = ISInvertPermutation(rowp, 0, &irowp);CHKERRQ(ierr); 3491 ierr = ISGetIndices(irowp, &rows);CHKERRQ(ierr); 3492 ierr = ISInvertPermutation(colp, 0, &icolp);CHKERRQ(ierr); 3493 ierr = ISGetIndices(icolp, &cols);CHKERRQ(ierr); 3494 ierr = PetscMalloc(N * sizeof(PetscInt), &cnew);CHKERRQ(ierr); 3495 ierr = PetscMalloc(N * sizeof(PetscScalar), &vnew);CHKERRQ(ierr); 3496 3497 /* Setup bandwidth to include */ 3498 if (band == PETSC_DECIDE) { 3499 if (frac <= 0.0) 3500 bw = (PetscInt) (M * 0.05); 3501 else 3502 bw = (PetscInt) (M * frac); 3503 } else { 3504 if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer"); 3505 bw = band; 3506 } 3507 3508 /* Put values into new matrix */ 3509 ierr = MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);CHKERRQ(ierr); 3510 for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) { 3511 ierr = MatGetRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3512 newRow = rows[locRow]+locRowStart; 3513 for(col = 0, newNz = 0; col < nz; col++) { 3514 newCol = cols[cwork[col]]; 3515 if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) { 3516 cnew[newNz] = newCol; 3517 vnew[newNz] = vwork[col]; 3518 newNz++; 3519 } 3520 } 3521 ierr = MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);CHKERRQ(ierr); 3522 ierr = MatRestoreRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3523 } 3524 ierr = PetscFree(cnew);CHKERRQ(ierr); 3525 ierr = PetscFree(vnew);CHKERRQ(ierr); 3526 ierr = MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3527 ierr = MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3528 ierr = ISRestoreIndices(irowp, &rows);CHKERRQ(ierr); 3529 ierr = ISRestoreIndices(icolp, &cols);CHKERRQ(ierr); 3530 ierr = ISDestroy(irowp);CHKERRQ(ierr); 3531 ierr = ISDestroy(icolp);CHKERRQ(ierr); 3532 } else { 3533 ierr = (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);CHKERRQ(ierr); 3534 } 3535 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3536 PetscFunctionReturn(0); 3537 } 3538 3539 #undef __FUNCT__ 3540 #define __FUNCT__ "MatEqual" 3541 /*@ 3542 MatEqual - Compares two matrices. 3543 3544 Collective on Mat 3545 3546 Input Parameters: 3547 + A - the first matrix 3548 - B - the second matrix 3549 3550 Output Parameter: 3551 . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise. 3552 3553 Level: intermediate 3554 3555 Concepts: matrices^equality between 3556 @*/ 3557 PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg) 3558 { 3559 PetscErrorCode ierr; 3560 3561 PetscFunctionBegin; 3562 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3563 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3564 PetscValidType(A,1); 3565 PetscValidType(B,2); 3566 MatPreallocated(B); 3567 PetscValidIntPointer(flg,3); 3568 PetscCheckSameComm(A,1,B,2); 3569 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3570 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3571 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); 3572 if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name); 3573 if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name); 3574 if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name); 3575 ierr = MatPreallocated(A);CHKERRQ(ierr); 3576 3577 ierr = (*A->ops->equal)(A,B,flg);CHKERRQ(ierr); 3578 PetscFunctionReturn(0); 3579 } 3580 3581 #undef __FUNCT__ 3582 #define __FUNCT__ "MatDiagonalScale" 3583 /*@ 3584 MatDiagonalScale - Scales a matrix on the left and right by diagonal 3585 matrices that are stored as vectors. Either of the two scaling 3586 matrices can be PETSC_NULL. 3587 3588 Collective on Mat 3589 3590 Input Parameters: 3591 + mat - the matrix to be scaled 3592 . l - the left scaling vector (or PETSC_NULL) 3593 - r - the right scaling vector (or PETSC_NULL) 3594 3595 Notes: 3596 MatDiagonalScale() computes A = LAR, where 3597 L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector) 3598 3599 Level: intermediate 3600 3601 Concepts: matrices^diagonal scaling 3602 Concepts: diagonal scaling of matrices 3603 3604 .seealso: MatScale() 3605 @*/ 3606 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r) 3607 { 3608 PetscErrorCode ierr; 3609 3610 PetscFunctionBegin; 3611 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3612 PetscValidType(mat,1); 3613 if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3614 if (l) {PetscValidHeaderSpecific(l,VEC_COOKIE,2);PetscCheckSameComm(mat,1,l,2);} 3615 if (r) {PetscValidHeaderSpecific(r,VEC_COOKIE,3);PetscCheckSameComm(mat,1,r,3);} 3616 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3617 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3618 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3619 3620 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3621 ierr = (*mat->ops->diagonalscale)(mat,l,r);CHKERRQ(ierr); 3622 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3623 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3624 PetscFunctionReturn(0); 3625 } 3626 3627 #undef __FUNCT__ 3628 #define __FUNCT__ "MatScale" 3629 /*@ 3630 MatScale - Scales all elements of a matrix by a given number. 3631 3632 Collective on Mat 3633 3634 Input Parameters: 3635 + mat - the matrix to be scaled 3636 - a - the scaling value 3637 3638 Output Parameter: 3639 . mat - the scaled matrix 3640 3641 Level: intermediate 3642 3643 Concepts: matrices^scaling all entries 3644 3645 .seealso: MatDiagonalScale() 3646 @*/ 3647 PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a) 3648 { 3649 PetscErrorCode ierr; 3650 3651 PetscFunctionBegin; 3652 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3653 PetscValidType(mat,1); 3654 if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3655 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3656 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3657 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3658 3659 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3660 ierr = (*mat->ops->scale)(mat,a);CHKERRQ(ierr); 3661 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3662 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3663 PetscFunctionReturn(0); 3664 } 3665 3666 #undef __FUNCT__ 3667 #define __FUNCT__ "MatNorm" 3668 /*@ 3669 MatNorm - Calculates various norms of a matrix. 3670 3671 Collective on Mat 3672 3673 Input Parameters: 3674 + mat - the matrix 3675 - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY 3676 3677 Output Parameters: 3678 . nrm - the resulting norm 3679 3680 Level: intermediate 3681 3682 Concepts: matrices^norm 3683 Concepts: norm^of matrix 3684 @*/ 3685 PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm) 3686 { 3687 PetscErrorCode ierr; 3688 3689 PetscFunctionBegin; 3690 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3691 PetscValidType(mat,1); 3692 PetscValidScalarPointer(nrm,3); 3693 3694 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3695 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3696 if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3697 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3698 3699 ierr = (*mat->ops->norm)(mat,type,nrm);CHKERRQ(ierr); 3700 PetscFunctionReturn(0); 3701 } 3702 3703 /* 3704 This variable is used to prevent counting of MatAssemblyBegin() that 3705 are called from within a MatAssemblyEnd(). 3706 */ 3707 static PetscInt MatAssemblyEnd_InUse = 0; 3708 #undef __FUNCT__ 3709 #define __FUNCT__ "MatAssemblyBegin" 3710 /*@ 3711 MatAssemblyBegin - Begins assembling the matrix. This routine should 3712 be called after completing all calls to MatSetValues(). 3713 3714 Collective on Mat 3715 3716 Input Parameters: 3717 + mat - the matrix 3718 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3719 3720 Notes: 3721 MatSetValues() generally caches the values. The matrix is ready to 3722 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3723 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3724 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3725 using the matrix. 3726 3727 Level: beginner 3728 3729 Concepts: matrices^assembling 3730 3731 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled() 3732 @*/ 3733 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type) 3734 { 3735 PetscErrorCode ierr; 3736 3737 PetscFunctionBegin; 3738 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3739 PetscValidType(mat,1); 3740 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3741 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?"); 3742 if (mat->assembled) { 3743 mat->was_assembled = PETSC_TRUE; 3744 mat->assembled = PETSC_FALSE; 3745 } 3746 if (!MatAssemblyEnd_InUse) { 3747 ierr = PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3748 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3749 ierr = PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3750 } else { 3751 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3752 } 3753 PetscFunctionReturn(0); 3754 } 3755 3756 #undef __FUNCT__ 3757 #define __FUNCT__ "MatAssembed" 3758 /*@ 3759 MatAssembled - Indicates if a matrix has been assembled and is ready for 3760 use; for example, in matrix-vector product. 3761 3762 Collective on Mat 3763 3764 Input Parameter: 3765 . mat - the matrix 3766 3767 Output Parameter: 3768 . assembled - PETSC_TRUE or PETSC_FALSE 3769 3770 Level: advanced 3771 3772 Concepts: matrices^assembled? 3773 3774 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin() 3775 @*/ 3776 PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled) 3777 { 3778 PetscFunctionBegin; 3779 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3780 PetscValidType(mat,1); 3781 PetscValidPointer(assembled,2); 3782 *assembled = mat->assembled; 3783 PetscFunctionReturn(0); 3784 } 3785 3786 #undef __FUNCT__ 3787 #define __FUNCT__ "MatView_Private" 3788 /* 3789 Processes command line options to determine if/how a matrix 3790 is to be viewed. Called by MatAssemblyEnd() and MatLoad(). 3791 */ 3792 PetscErrorCode MatView_Private(Mat mat) 3793 { 3794 PetscErrorCode ierr; 3795 PetscTruth flg; 3796 static PetscTruth incall = PETSC_FALSE; 3797 3798 PetscFunctionBegin; 3799 if (incall) PetscFunctionReturn(0); 3800 incall = PETSC_TRUE; 3801 ierr = PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");CHKERRQ(ierr); 3802 ierr = PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);CHKERRQ(ierr); 3803 if (flg) { 3804 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);CHKERRQ(ierr); 3805 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3806 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3807 } 3808 ierr = PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);CHKERRQ(ierr); 3809 if (flg) { 3810 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);CHKERRQ(ierr); 3811 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3812 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3813 } 3814 ierr = PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);CHKERRQ(ierr); 3815 if (flg) { 3816 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3817 } 3818 ierr = PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);CHKERRQ(ierr); 3819 if (flg) { 3820 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);CHKERRQ(ierr); 3821 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3822 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3823 } 3824 #if defined(PETSC_USE_SOCKET_VIEWER) 3825 ierr = PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);CHKERRQ(ierr); 3826 if (flg) { 3827 ierr = MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3828 ierr = PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3829 } 3830 #endif 3831 ierr = PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);CHKERRQ(ierr); 3832 if (flg) { 3833 ierr = MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3834 ierr = PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3835 } 3836 ierr = PetscOptionsEnd();CHKERRQ(ierr); 3837 /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */ 3838 ierr = PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);CHKERRQ(ierr); 3839 if (flg) { 3840 ierr = PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);CHKERRQ(ierr); 3841 if (flg) { 3842 PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);CHKERRQ(ierr); 3843 } 3844 ierr = MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3845 ierr = PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3846 if (flg) { 3847 PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3848 } 3849 } 3850 incall = PETSC_FALSE; 3851 PetscFunctionReturn(0); 3852 } 3853 3854 #undef __FUNCT__ 3855 #define __FUNCT__ "MatAssemblyEnd" 3856 /*@ 3857 MatAssemblyEnd - Completes assembling the matrix. This routine should 3858 be called after MatAssemblyBegin(). 3859 3860 Collective on Mat 3861 3862 Input Parameters: 3863 + mat - the matrix 3864 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3865 3866 Options Database Keys: 3867 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 3868 . -mat_view_info_detailed - Prints more detailed info 3869 . -mat_view - Prints matrix in ASCII format 3870 . -mat_view_matlab - Prints matrix in Matlab format 3871 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 3872 . -display <name> - Sets display name (default is host) 3873 . -draw_pause <sec> - Sets number of seconds to pause after display 3874 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 3875 . -viewer_socket_machine <machine> 3876 . -viewer_socket_port <port> 3877 . -mat_view_binary - save matrix to file in binary format 3878 - -viewer_binary_filename <name> 3879 3880 Notes: 3881 MatSetValues() generally caches the values. The matrix is ready to 3882 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3883 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3884 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3885 using the matrix. 3886 3887 Level: beginner 3888 3889 .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen() 3890 @*/ 3891 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type) 3892 { 3893 PetscErrorCode ierr; 3894 static PetscInt inassm = 0; 3895 PetscTruth flg; 3896 3897 PetscFunctionBegin; 3898 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3899 PetscValidType(mat,1); 3900 3901 inassm++; 3902 MatAssemblyEnd_InUse++; 3903 if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */ 3904 ierr = PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3905 if (mat->ops->assemblyend) { 3906 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3907 } 3908 ierr = PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3909 } else { 3910 if (mat->ops->assemblyend) { 3911 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3912 } 3913 } 3914 3915 /* Flush assembly is not a true assembly */ 3916 if (type != MAT_FLUSH_ASSEMBLY) { 3917 mat->assembled = PETSC_TRUE; mat->num_ass++; 3918 } 3919 mat->insertmode = NOT_SET_VALUES; 3920 MatAssemblyEnd_InUse--; 3921 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3922 if (!mat->symmetric_eternal) { 3923 mat->symmetric_set = PETSC_FALSE; 3924 mat->hermitian_set = PETSC_FALSE; 3925 mat->structurally_symmetric_set = PETSC_FALSE; 3926 } 3927 if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) { 3928 ierr = MatView_Private(mat);CHKERRQ(ierr); 3929 ierr = PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);CHKERRQ(ierr); 3930 if (flg) { 3931 PetscReal tol = 0.0; 3932 ierr = PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);CHKERRQ(ierr); 3933 ierr = MatIsSymmetric(mat,tol,&flg);CHKERRQ(ierr); 3934 if (flg) { 3935 ierr = PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 3936 } else { 3937 ierr = PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 3938 } 3939 } 3940 } 3941 inassm--; 3942 ierr = PetscOptionsHasName(mat->prefix,"-help",&flg);CHKERRQ(ierr); 3943 if (flg) { 3944 ierr = MatPrintHelp(mat);CHKERRQ(ierr); 3945 } 3946 PetscFunctionReturn(0); 3947 } 3948 3949 3950 #undef __FUNCT__ 3951 #define __FUNCT__ "MatCompress" 3952 /*@ 3953 MatCompress - Tries to store the matrix in as little space as 3954 possible. May fail if memory is already fully used, since it 3955 tries to allocate new space. 3956 3957 Collective on Mat 3958 3959 Input Parameters: 3960 . mat - the matrix 3961 3962 Level: advanced 3963 3964 @*/ 3965 PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat) 3966 { 3967 PetscErrorCode ierr; 3968 3969 PetscFunctionBegin; 3970 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3971 PetscValidType(mat,1); 3972 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3973 if (mat->ops->compress) {ierr = (*mat->ops->compress)(mat);CHKERRQ(ierr);} 3974 PetscFunctionReturn(0); 3975 } 3976 3977 #undef __FUNCT__ 3978 #define __FUNCT__ "MatSetOption" 3979 /*@ 3980 MatSetOption - Sets a parameter option for a matrix. Some options 3981 may be specific to certain storage formats. Some options 3982 determine how values will be inserted (or added). Sorted, 3983 row-oriented input will generally assemble the fastest. The default 3984 is row-oriented, nonsorted input. 3985 3986 Collective on Mat 3987 3988 Input Parameters: 3989 + mat - the matrix 3990 - option - the option, one of those listed below (and possibly others), 3991 e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR 3992 3993 Options Describing Matrix Structure: 3994 + MAT_SYMMETRIC - symmetric in terms of both structure and value 3995 . MAT_HERMITIAN - transpose is the complex conjugation 3996 . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 3997 . MAT_NOT_SYMMETRIC - not symmetric in value 3998 . MAT_NOT_HERMITIAN - transpose is not the complex conjugation 3999 . MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure 4000 . MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag 4001 you set to be kept with all future use of the matrix 4002 including after MatAssemblyBegin/End() which could 4003 potentially change the symmetry structure, i.e. you 4004 KNOW the matrix will ALWAYS have the property you set. 4005 - MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 4006 flags you set will be dropped (in case potentially 4007 the symmetry etc was lost). 4008 4009 Options For Use with MatSetValues(): 4010 Insert a logically dense subblock, which can be 4011 + MAT_ROW_ORIENTED - row-oriented (default) 4012 . MAT_COLUMN_ORIENTED - column-oriented 4013 . MAT_ROWS_SORTED - sorted by row 4014 . MAT_ROWS_UNSORTED - not sorted by row (default) 4015 . MAT_COLUMNS_SORTED - sorted by column 4016 - MAT_COLUMNS_UNSORTED - not sorted by column (default) 4017 4018 Not these options reflect the data you pass in with MatSetValues(); it has 4019 nothing to do with how the data is stored internally in the matrix 4020 data structure. 4021 4022 When (re)assembling a matrix, we can restrict the input for 4023 efficiency/debugging purposes. These options include 4024 + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be 4025 allowed if they generate a new nonzero 4026 . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed 4027 . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if 4028 they generate a nonzero in a new diagonal (for block diagonal format only) 4029 . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 4030 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 4031 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 4032 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 4033 4034 Notes: 4035 Some options are relevant only for particular matrix types and 4036 are thus ignored by others. Other options are not supported by 4037 certain matrix types and will generate an error message if set. 4038 4039 If using a Fortran 77 module to compute a matrix, one may need to 4040 use the column-oriented option (or convert to the row-oriented 4041 format). 4042 4043 MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 4044 that would generate a new entry in the nonzero structure is instead 4045 ignored. Thus, if memory has not alredy been allocated for this particular 4046 data, then the insertion is ignored. For dense matrices, in which 4047 the entire array is allocated, no entries are ever ignored. 4048 Set after the first MatAssemblyEnd() 4049 4050 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 4051 that would generate a new entry in the nonzero structure instead produces 4052 an error. (Currently supported for AIJ and BAIJ formats only.) 4053 This is a useful flag when using SAME_NONZERO_PATTERN in calling 4054 KSPSetOperators() to ensure that the nonzero pattern truely does 4055 remain unchanged. Set after the first MatAssemblyEnd() 4056 4057 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 4058 that would generate a new entry that has not been preallocated will 4059 instead produce an error. (Currently supported for AIJ and BAIJ formats 4060 only.) This is a useful flag when debugging matrix memory preallocation. 4061 4062 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 4063 other processors should be dropped, rather than stashed. 4064 This is useful if you know that the "owning" processor is also 4065 always generating the correct matrix entries, so that PETSc need 4066 not transfer duplicate entries generated on another processor. 4067 4068 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 4069 searches during matrix assembly. When this flag is set, the hash table 4070 is created during the first Matrix Assembly. This hash table is 4071 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 4072 to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 4073 should be used with MAT_USE_HASH_TABLE flag. This option is currently 4074 supported by MATMPIBAIJ format only. 4075 4076 MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries 4077 are kept in the nonzero structure 4078 4079 MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating 4080 a zero location in the matrix 4081 4082 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 4083 ROWBS matrix types 4084 4085 MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works 4086 with AIJ and ROWBS matrix types (database option "-mat_no_inode") 4087 4088 Level: intermediate 4089 4090 Concepts: matrices^setting options 4091 4092 @*/ 4093 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op) 4094 { 4095 PetscErrorCode ierr; 4096 4097 PetscFunctionBegin; 4098 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4099 PetscValidType(mat,1); 4100 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4101 switch (op) { 4102 case MAT_SYMMETRIC: 4103 mat->symmetric = PETSC_TRUE; 4104 mat->structurally_symmetric = PETSC_TRUE; 4105 mat->symmetric_set = PETSC_TRUE; 4106 mat->structurally_symmetric_set = PETSC_TRUE; 4107 break; 4108 case MAT_HERMITIAN: 4109 mat->hermitian = PETSC_TRUE; 4110 mat->structurally_symmetric = PETSC_TRUE; 4111 mat->hermitian_set = PETSC_TRUE; 4112 mat->structurally_symmetric_set = PETSC_TRUE; 4113 break; 4114 case MAT_STRUCTURALLY_SYMMETRIC: 4115 mat->structurally_symmetric = PETSC_TRUE; 4116 mat->structurally_symmetric_set = PETSC_TRUE; 4117 break; 4118 case MAT_NOT_SYMMETRIC: 4119 mat->symmetric = PETSC_FALSE; 4120 mat->symmetric_set = PETSC_TRUE; 4121 break; 4122 case MAT_NOT_HERMITIAN: 4123 mat->hermitian = PETSC_FALSE; 4124 mat->hermitian_set = PETSC_TRUE; 4125 break; 4126 case MAT_NOT_STRUCTURALLY_SYMMETRIC: 4127 mat->structurally_symmetric = PETSC_FALSE; 4128 mat->structurally_symmetric_set = PETSC_TRUE; 4129 break; 4130 case MAT_SYMMETRY_ETERNAL: 4131 mat->symmetric_eternal = PETSC_TRUE; 4132 break; 4133 case MAT_NOT_SYMMETRY_ETERNAL: 4134 mat->symmetric_eternal = PETSC_FALSE; 4135 break; 4136 default: 4137 break; 4138 } 4139 if (mat->ops->setoption) { 4140 ierr = (*mat->ops->setoption)(mat,op);CHKERRQ(ierr); 4141 } 4142 PetscFunctionReturn(0); 4143 } 4144 4145 #undef __FUNCT__ 4146 #define __FUNCT__ "MatZeroEntries" 4147 /*@ 4148 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 4149 this routine retains the old nonzero structure. 4150 4151 Collective on Mat 4152 4153 Input Parameters: 4154 . mat - the matrix 4155 4156 Level: intermediate 4157 4158 Concepts: matrices^zeroing 4159 4160 .seealso: MatZeroRows() 4161 @*/ 4162 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat) 4163 { 4164 PetscErrorCode ierr; 4165 4166 PetscFunctionBegin; 4167 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4168 PetscValidType(mat,1); 4169 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4170 if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled"); 4171 if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4172 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4173 4174 ierr = PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4175 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 4176 ierr = PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4177 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4178 PetscFunctionReturn(0); 4179 } 4180 4181 #undef __FUNCT__ 4182 #define __FUNCT__ "MatZeroRows" 4183 /*@C 4184 MatZeroRows - Zeros all entries (except possibly the main diagonal) 4185 of a set of rows of a matrix. 4186 4187 Collective on Mat 4188 4189 Input Parameters: 4190 + mat - the matrix 4191 . numRows - the number of rows to remove 4192 . rows - the global row indices 4193 - diag - value put in all diagonals of eliminated rows 4194 4195 Notes: 4196 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 4197 but does not release memory. For the dense and block diagonal 4198 formats this does not alter the nonzero structure. 4199 4200 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4201 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4202 merely zeroed. 4203 4204 The user can set a value in the diagonal entry (or for the AIJ and 4205 row formats can optionally remove the main diagonal entry from the 4206 nonzero structure as well, by passing 0.0 as the final argument). 4207 4208 For the parallel case, all processes that share the matrix (i.e., 4209 those in the communicator used for matrix creation) MUST call this 4210 routine, regardless of whether any rows being zeroed are owned by 4211 them. 4212 4213 Each processor should list the rows that IT wants zeroed 4214 4215 Level: intermediate 4216 4217 Concepts: matrices^zeroing rows 4218 4219 .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 4220 @*/ 4221 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 4222 { 4223 PetscErrorCode ierr; 4224 4225 PetscFunctionBegin; 4226 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4227 PetscValidType(mat,1); 4228 if (numRows) PetscValidIntPointer(rows,3); 4229 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4230 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4231 if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4232 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4233 4234 ierr = (*mat->ops->zerorows)(mat,numRows,rows,diag);CHKERRQ(ierr); 4235 ierr = MatView_Private(mat);CHKERRQ(ierr); 4236 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4237 PetscFunctionReturn(0); 4238 } 4239 4240 #undef __FUNCT__ 4241 #define __FUNCT__ "MatZeroRowsIS" 4242 /*@C 4243 MatZeroRowsIS - Zeros all entries (except possibly the main diagonal) 4244 of a set of rows of a matrix. 4245 4246 Collective on Mat 4247 4248 Input Parameters: 4249 + mat - the matrix 4250 . is - index set of rows to remove 4251 - diag - value put in all diagonals of eliminated rows 4252 4253 Notes: 4254 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 4255 but does not release memory. For the dense and block diagonal 4256 formats this does not alter the nonzero structure. 4257 4258 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4259 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4260 merely zeroed. 4261 4262 The user can set a value in the diagonal entry (or for the AIJ and 4263 row formats can optionally remove the main diagonal entry from the 4264 nonzero structure as well, by passing 0.0 as the final argument). 4265 4266 For the parallel case, all processes that share the matrix (i.e., 4267 those in the communicator used for matrix creation) MUST call this 4268 routine, regardless of whether any rows being zeroed are owned by 4269 them. 4270 4271 Each processor should list the rows that IT wants zeroed 4272 4273 Level: intermediate 4274 4275 Concepts: matrices^zeroing rows 4276 4277 .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 4278 @*/ 4279 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag) 4280 { 4281 PetscInt numRows; 4282 PetscInt *rows; 4283 PetscErrorCode ierr; 4284 4285 PetscFunctionBegin; 4286 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4287 PetscValidType(mat,1); 4288 PetscValidHeaderSpecific(is,IS_COOKIE,2); 4289 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 4290 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 4291 ierr = MatZeroRows(mat,numRows,rows,diag);CHKERRQ(ierr); 4292 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 4293 PetscFunctionReturn(0); 4294 } 4295 4296 #undef __FUNCT__ 4297 #define __FUNCT__ "MatZeroRowsLocal" 4298 /*@C 4299 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 4300 of a set of rows of a matrix; using local numbering of rows. 4301 4302 Collective on Mat 4303 4304 Input Parameters: 4305 + mat - the matrix 4306 . numRows - the number of rows to remove 4307 . rows - the global row indices 4308 - diag - value put in all diagonals of eliminated rows 4309 4310 Notes: 4311 Before calling MatZeroRowsLocal(), the user must first set the 4312 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 4313 4314 For the AIJ matrix formats this removes the old nonzero structure, 4315 but does not release memory. For the dense and block diagonal 4316 formats this does not alter the nonzero structure. 4317 4318 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4319 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4320 merely zeroed. 4321 4322 The user can set a value in the diagonal entry (or for the AIJ and 4323 row formats can optionally remove the main diagonal entry from the 4324 nonzero structure as well, by passing 0.0 as the final argument). 4325 4326 Level: intermediate 4327 4328 Concepts: matrices^zeroing 4329 4330 .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 4331 @*/ 4332 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 4333 { 4334 PetscErrorCode ierr; 4335 4336 PetscFunctionBegin; 4337 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4338 PetscValidType(mat,1); 4339 if (numRows) PetscValidIntPointer(rows,3); 4340 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4341 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4342 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4343 4344 if (mat->ops->zerorowslocal) { 4345 ierr = (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);CHKERRQ(ierr); 4346 } else { 4347 IS is, newis; 4348 PetscInt *newRows; 4349 4350 if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 4351 ierr = ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);CHKERRQ(ierr); 4352 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 4353 ierr = ISGetIndices(newis,&newRows);CHKERRQ(ierr); 4354 ierr = (*mat->ops->zerorows)(mat,numRows,newRows,diag);CHKERRQ(ierr); 4355 ierr = ISRestoreIndices(newis,&newRows);CHKERRQ(ierr); 4356 ierr = ISDestroy(newis);CHKERRQ(ierr); 4357 ierr = ISDestroy(is);CHKERRQ(ierr); 4358 } 4359 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4360 PetscFunctionReturn(0); 4361 } 4362 4363 #undef __FUNCT__ 4364 #define __FUNCT__ "MatZeroRowsLocal" 4365 /*@C 4366 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 4367 of a set of rows of a matrix; using local numbering of rows. 4368 4369 Collective on Mat 4370 4371 Input Parameters: 4372 + mat - the matrix 4373 . is - index set of rows to remove 4374 - diag - value put in all diagonals of eliminated rows 4375 4376 Notes: 4377 Before calling MatZeroRowsLocal(), the user must first set the 4378 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 4379 4380 For the AIJ matrix formats this removes the old nonzero structure, 4381 but does not release memory. For the dense and block diagonal 4382 formats this does not alter the nonzero structure. 4383 4384 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4385 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4386 merely zeroed. 4387 4388 The user can set a value in the diagonal entry (or for the AIJ and 4389 row formats can optionally remove the main diagonal entry from the 4390 nonzero structure as well, by passing 0.0 as the final argument). 4391 4392 Level: intermediate 4393 4394 Concepts: matrices^zeroing 4395 4396 .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 4397 @*/ 4398 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag) 4399 { 4400 PetscErrorCode ierr; 4401 PetscInt numRows; 4402 PetscInt *rows; 4403 4404 PetscFunctionBegin; 4405 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4406 PetscValidType(mat,1); 4407 PetscValidHeaderSpecific(is,IS_COOKIE,2); 4408 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4409 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4410 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4411 4412 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 4413 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 4414 ierr = MatZeroRowsLocal(mat,numRows,rows,diag);CHKERRQ(ierr); 4415 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 4416 PetscFunctionReturn(0); 4417 } 4418 4419 #undef __FUNCT__ 4420 #define __FUNCT__ "MatGetSize" 4421 /*@ 4422 MatGetSize - Returns the numbers of rows and columns in a matrix. 4423 4424 Not Collective 4425 4426 Input Parameter: 4427 . mat - the matrix 4428 4429 Output Parameters: 4430 + m - the number of global rows 4431 - n - the number of global columns 4432 4433 Note: both output parameters can be PETSC_NULL on input. 4434 4435 Level: beginner 4436 4437 Concepts: matrices^size 4438 4439 .seealso: MatGetLocalSize() 4440 @*/ 4441 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n) 4442 { 4443 PetscFunctionBegin; 4444 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4445 if (m) *m = mat->M; 4446 if (n) *n = mat->N; 4447 PetscFunctionReturn(0); 4448 } 4449 4450 #undef __FUNCT__ 4451 #define __FUNCT__ "MatGetLocalSize" 4452 /*@ 4453 MatGetLocalSize - Returns the number of rows and columns in a matrix 4454 stored locally. This information may be implementation dependent, so 4455 use with care. 4456 4457 Not Collective 4458 4459 Input Parameters: 4460 . mat - the matrix 4461 4462 Output Parameters: 4463 + m - the number of local rows 4464 - n - the number of local columns 4465 4466 Note: both output parameters can be PETSC_NULL on input. 4467 4468 Level: beginner 4469 4470 Concepts: matrices^local size 4471 4472 .seealso: MatGetSize() 4473 @*/ 4474 PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n) 4475 { 4476 PetscFunctionBegin; 4477 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4478 if (m) PetscValidIntPointer(m,2); 4479 if (n) PetscValidIntPointer(n,3); 4480 if (m) *m = mat->m; 4481 if (n) *n = mat->n; 4482 PetscFunctionReturn(0); 4483 } 4484 4485 #undef __FUNCT__ 4486 #define __FUNCT__ "MatGetOwnershipRange" 4487 /*@ 4488 MatGetOwnershipRange - Returns the range of matrix rows owned by 4489 this processor, assuming that the matrix is laid out with the first 4490 n1 rows on the first processor, the next n2 rows on the second, etc. 4491 For certain parallel layouts this range may not be well defined. 4492 4493 Not Collective 4494 4495 Input Parameters: 4496 . mat - the matrix 4497 4498 Output Parameters: 4499 + m - the global index of the first local row 4500 - n - one more than the global index of the last local row 4501 4502 Note: both output parameters can be PETSC_NULL on input. 4503 4504 Level: beginner 4505 4506 Concepts: matrices^row ownership 4507 @*/ 4508 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n) 4509 { 4510 PetscErrorCode ierr; 4511 4512 PetscFunctionBegin; 4513 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4514 PetscValidType(mat,1); 4515 if (m) PetscValidIntPointer(m,2); 4516 if (n) PetscValidIntPointer(n,3); 4517 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4518 *m = mat->rmap.rstart; 4519 *n = mat->rmap.rend; 4520 PetscFunctionReturn(0); 4521 } 4522 4523 #undef __FUNCT__ 4524 #define __FUNCT__ "MatILUFactorSymbolic" 4525 /*@ 4526 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 4527 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 4528 to complete the factorization. 4529 4530 Collective on Mat 4531 4532 Input Parameters: 4533 + mat - the matrix 4534 . row - row permutation 4535 . column - column permutation 4536 - info - structure containing 4537 $ levels - number of levels of fill. 4538 $ expected fill - as ratio of original fill. 4539 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 4540 missing diagonal entries) 4541 4542 Output Parameters: 4543 . fact - new matrix that has been symbolically factored 4544 4545 Notes: 4546 See the users manual for additional information about 4547 choosing the fill factor for better efficiency. 4548 4549 Most users should employ the simplified KSP interface for linear solvers 4550 instead of working directly with matrix algebra routines such as this. 4551 See, e.g., KSPCreate(). 4552 4553 Level: developer 4554 4555 Concepts: matrices^symbolic LU factorization 4556 Concepts: matrices^factorization 4557 Concepts: LU^symbolic factorization 4558 4559 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 4560 MatGetOrdering(), MatFactorInfo 4561 4562 @*/ 4563 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 4564 { 4565 PetscErrorCode ierr; 4566 4567 PetscFunctionBegin; 4568 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4569 PetscValidType(mat,1); 4570 PetscValidHeaderSpecific(row,IS_COOKIE,2); 4571 PetscValidHeaderSpecific(col,IS_COOKIE,3); 4572 PetscValidPointer(info,4); 4573 PetscValidPointer(fact,5); 4574 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels); 4575 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 4576 if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name); 4577 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4578 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4579 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4580 4581 ierr = PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4582 ierr = (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 4583 ierr = PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4584 PetscFunctionReturn(0); 4585 } 4586 4587 #undef __FUNCT__ 4588 #define __FUNCT__ "MatICCFactorSymbolic" 4589 /*@ 4590 MatICCFactorSymbolic - Performs symbolic incomplete 4591 Cholesky factorization for a symmetric matrix. Use 4592 MatCholeskyFactorNumeric() to complete the factorization. 4593 4594 Collective on Mat 4595 4596 Input Parameters: 4597 + mat - the matrix 4598 . perm - row and column permutation 4599 - info - structure containing 4600 $ levels - number of levels of fill. 4601 $ expected fill - as ratio of original fill. 4602 4603 Output Parameter: 4604 . fact - the factored matrix 4605 4606 Notes: 4607 Currently only no-fill factorization is supported. 4608 4609 Most users should employ the simplified KSP interface for linear solvers 4610 instead of working directly with matrix algebra routines such as this. 4611 See, e.g., KSPCreate(). 4612 4613 Level: developer 4614 4615 Concepts: matrices^symbolic incomplete Cholesky factorization 4616 Concepts: matrices^factorization 4617 Concepts: Cholsky^symbolic factorization 4618 4619 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 4620 @*/ 4621 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact) 4622 { 4623 PetscErrorCode ierr; 4624 4625 PetscFunctionBegin; 4626 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4627 PetscValidType(mat,1); 4628 PetscValidHeaderSpecific(perm,IS_COOKIE,2); 4629 PetscValidPointer(info,3); 4630 PetscValidPointer(fact,4); 4631 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4632 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels); 4633 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 4634 if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name); 4635 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4636 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4637 4638 ierr = PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4639 ierr = (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);CHKERRQ(ierr); 4640 ierr = PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4641 PetscFunctionReturn(0); 4642 } 4643 4644 #undef __FUNCT__ 4645 #define __FUNCT__ "MatGetArray" 4646 /*@C 4647 MatGetArray - Returns a pointer to the element values in the matrix. 4648 The result of this routine is dependent on the underlying matrix data 4649 structure, and may not even work for certain matrix types. You MUST 4650 call MatRestoreArray() when you no longer need to access the array. 4651 4652 Not Collective 4653 4654 Input Parameter: 4655 . mat - the matrix 4656 4657 Output Parameter: 4658 . v - the location of the values 4659 4660 4661 Fortran Note: 4662 This routine is used differently from Fortran, e.g., 4663 .vb 4664 Mat mat 4665 PetscScalar mat_array(1) 4666 PetscOffset i_mat 4667 PetscErrorCode ierr 4668 call MatGetArray(mat,mat_array,i_mat,ierr) 4669 4670 C Access first local entry in matrix; note that array is 4671 C treated as one dimensional 4672 value = mat_array(i_mat + 1) 4673 4674 [... other code ...] 4675 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4676 .ve 4677 4678 See the Fortran chapter of the users manual and 4679 petsc/src/mat/examples/tests for details. 4680 4681 Level: advanced 4682 4683 Concepts: matrices^access array 4684 4685 .seealso: MatRestoreArray(), MatGetArrayF90() 4686 @*/ 4687 PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[]) 4688 { 4689 PetscErrorCode ierr; 4690 4691 PetscFunctionBegin; 4692 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4693 PetscValidType(mat,1); 4694 PetscValidPointer(v,2); 4695 if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4696 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4697 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 4698 PetscFunctionReturn(0); 4699 } 4700 4701 #undef __FUNCT__ 4702 #define __FUNCT__ "MatRestoreArray" 4703 /*@C 4704 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 4705 4706 Not Collective 4707 4708 Input Parameter: 4709 + mat - the matrix 4710 - v - the location of the values 4711 4712 Fortran Note: 4713 This routine is used differently from Fortran, e.g., 4714 .vb 4715 Mat mat 4716 PetscScalar mat_array(1) 4717 PetscOffset i_mat 4718 PetscErrorCode ierr 4719 call MatGetArray(mat,mat_array,i_mat,ierr) 4720 4721 C Access first local entry in matrix; note that array is 4722 C treated as one dimensional 4723 value = mat_array(i_mat + 1) 4724 4725 [... other code ...] 4726 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4727 .ve 4728 4729 See the Fortran chapter of the users manual and 4730 petsc/src/mat/examples/tests for details 4731 4732 Level: advanced 4733 4734 .seealso: MatGetArray(), MatRestoreArrayF90() 4735 @*/ 4736 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[]) 4737 { 4738 PetscErrorCode ierr; 4739 4740 PetscFunctionBegin; 4741 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4742 PetscValidType(mat,1); 4743 PetscValidPointer(v,2); 4744 #if defined(PETSC_USE_DEBUG) 4745 CHKMEMQ; 4746 #endif 4747 if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4748 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 4749 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4750 PetscFunctionReturn(0); 4751 } 4752 4753 #undef __FUNCT__ 4754 #define __FUNCT__ "MatGetSubMatrices" 4755 /*@C 4756 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 4757 points to an array of valid matrices, they may be reused to store the new 4758 submatrices. 4759 4760 Collective on Mat 4761 4762 Input Parameters: 4763 + mat - the matrix 4764 . n - the number of submatrixes to be extracted (on this processor, may be zero) 4765 . irow, icol - index sets of rows and columns to extract 4766 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 4767 4768 Output Parameter: 4769 . submat - the array of submatrices 4770 4771 Notes: 4772 MatGetSubMatrices() can extract only sequential submatrices 4773 (from both sequential and parallel matrices). Use MatGetSubMatrix() 4774 to extract a parallel submatrix. 4775 4776 When extracting submatrices from a parallel matrix, each processor can 4777 form a different submatrix by setting the rows and columns of its 4778 individual index sets according to the local submatrix desired. 4779 4780 When finished using the submatrices, the user should destroy 4781 them with MatDestroyMatrices(). 4782 4783 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 4784 original matrix has not changed from that last call to MatGetSubMatrices(). 4785 4786 This routine creates the matrices in submat; you should NOT create them before 4787 calling it. It also allocates the array of matrix pointers submat. 4788 4789 For BAIJ matrices the index sets must respect the block structure, that is if they 4790 request one row/column in a block, they must request all rows/columns that are in 4791 that block. For example, if the block size is 2 you cannot request just row 0 and 4792 column 0. 4793 4794 Fortran Note: 4795 The Fortran interface is slightly different from that given below; it 4796 requires one to pass in as submat a Mat (integer) array of size at least m. 4797 4798 Level: advanced 4799 4800 Concepts: matrices^accessing submatrices 4801 Concepts: submatrices 4802 4803 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal() 4804 @*/ 4805 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[]) 4806 { 4807 PetscErrorCode ierr; 4808 PetscInt i; 4809 PetscTruth eq; 4810 4811 PetscFunctionBegin; 4812 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4813 PetscValidType(mat,1); 4814 if (n) { 4815 PetscValidPointer(irow,3); 4816 PetscValidHeaderSpecific(*irow,IS_COOKIE,3); 4817 PetscValidPointer(icol,4); 4818 PetscValidHeaderSpecific(*icol,IS_COOKIE,4); 4819 } 4820 PetscValidPointer(submat,6); 4821 if (n && scall == MAT_REUSE_MATRIX) { 4822 PetscValidPointer(*submat,6); 4823 PetscValidHeaderSpecific(**submat,MAT_COOKIE,6); 4824 } 4825 if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4826 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4827 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4828 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4829 4830 ierr = PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4831 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 4832 ierr = PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4833 for (i=0; i<n; i++) { 4834 if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) { 4835 ierr = ISEqual(irow[i],icol[i],&eq);CHKERRQ(ierr); 4836 if (eq) { 4837 if (mat->symmetric){ 4838 ierr = MatSetOption((*submat)[i],MAT_SYMMETRIC);CHKERRQ(ierr); 4839 } else if (mat->hermitian) { 4840 ierr = MatSetOption((*submat)[i],MAT_HERMITIAN);CHKERRQ(ierr); 4841 } else if (mat->structurally_symmetric) { 4842 ierr = MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);CHKERRQ(ierr); 4843 } 4844 } 4845 } 4846 } 4847 PetscFunctionReturn(0); 4848 } 4849 4850 #undef __FUNCT__ 4851 #define __FUNCT__ "MatDestroyMatrices" 4852 /*@C 4853 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 4854 4855 Collective on Mat 4856 4857 Input Parameters: 4858 + n - the number of local matrices 4859 - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling 4860 sequence of MatGetSubMatrices()) 4861 4862 Level: advanced 4863 4864 Notes: Frees not only the matrices, but also the array that contains the matrices 4865 4866 .seealso: MatGetSubMatrices() 4867 @*/ 4868 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[]) 4869 { 4870 PetscErrorCode ierr; 4871 PetscInt i; 4872 4873 PetscFunctionBegin; 4874 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n); 4875 PetscValidPointer(mat,2); 4876 for (i=0; i<n; i++) { 4877 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 4878 } 4879 /* memory is allocated even if n = 0 */ 4880 ierr = PetscFree(*mat);CHKERRQ(ierr); 4881 PetscFunctionReturn(0); 4882 } 4883 4884 #undef __FUNCT__ 4885 #define __FUNCT__ "MatIncreaseOverlap" 4886 /*@ 4887 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 4888 replaces the index sets by larger ones that represent submatrices with 4889 additional overlap. 4890 4891 Collective on Mat 4892 4893 Input Parameters: 4894 + mat - the matrix 4895 . n - the number of index sets 4896 . is - the array of index sets (these index sets will changed during the call) 4897 - ov - the additional overlap requested 4898 4899 Level: developer 4900 4901 Concepts: overlap 4902 Concepts: ASM^computing overlap 4903 4904 .seealso: MatGetSubMatrices() 4905 @*/ 4906 PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov) 4907 { 4908 PetscErrorCode ierr; 4909 4910 PetscFunctionBegin; 4911 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4912 PetscValidType(mat,1); 4913 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n); 4914 if (n) { 4915 PetscValidPointer(is,3); 4916 PetscValidHeaderSpecific(*is,IS_COOKIE,3); 4917 } 4918 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4919 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4920 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4921 4922 if (!ov) PetscFunctionReturn(0); 4923 if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4924 ierr = PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4925 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 4926 ierr = PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4927 PetscFunctionReturn(0); 4928 } 4929 4930 #undef __FUNCT__ 4931 #define __FUNCT__ "MatPrintHelp" 4932 /*@ 4933 MatPrintHelp - Prints all the options for the matrix. 4934 4935 Collective on Mat 4936 4937 Input Parameter: 4938 . mat - the matrix 4939 4940 Options Database Keys: 4941 + -help - Prints matrix options 4942 - -h - Prints matrix options 4943 4944 Level: developer 4945 4946 .seealso: MatCreate(), MatCreateXXX() 4947 @*/ 4948 PetscErrorCode PETSCMAT_DLLEXPORT MatPrintHelp(Mat mat) 4949 { 4950 static PetscTruth called = PETSC_FALSE; 4951 PetscErrorCode ierr; 4952 4953 PetscFunctionBegin; 4954 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4955 PetscValidType(mat,1); 4956 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4957 4958 if (!called) { 4959 if (mat->ops->printhelp) { 4960 ierr = (*mat->ops->printhelp)(mat);CHKERRQ(ierr); 4961 } 4962 called = PETSC_TRUE; 4963 } 4964 PetscFunctionReturn(0); 4965 } 4966 4967 #undef __FUNCT__ 4968 #define __FUNCT__ "MatGetBlockSize" 4969 /*@ 4970 MatGetBlockSize - Returns the matrix block size; useful especially for the 4971 block row and block diagonal formats. 4972 4973 Not Collective 4974 4975 Input Parameter: 4976 . mat - the matrix 4977 4978 Output Parameter: 4979 . bs - block size 4980 4981 Notes: 4982 Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG. 4983 Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ 4984 4985 Level: intermediate 4986 4987 Concepts: matrices^block size 4988 4989 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag() 4990 @*/ 4991 PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs) 4992 { 4993 PetscErrorCode ierr; 4994 4995 PetscFunctionBegin; 4996 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4997 PetscValidType(mat,1); 4998 PetscValidIntPointer(bs,2); 4999 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5000 *bs = mat->bs; 5001 PetscFunctionReturn(0); 5002 } 5003 5004 #undef __FUNCT__ 5005 #define __FUNCT__ "MatSetBlockSize" 5006 /*@ 5007 MatSetBlockSize - Sets the matrix block size; for many matrix types you 5008 cannot use this and MUST set the blocksize when you preallocate the matrix 5009 5010 Not Collective 5011 5012 Input Parameters: 5013 + mat - the matrix 5014 - bs - block size 5015 5016 Notes: 5017 Only works for shell and AIJ matrices 5018 5019 Level: intermediate 5020 5021 Concepts: matrices^block size 5022 5023 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize() 5024 @*/ 5025 PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs) 5026 { 5027 PetscErrorCode ierr; 5028 5029 PetscFunctionBegin; 5030 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5031 PetscValidType(mat,1); 5032 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5033 if (mat->ops->setblocksize) { 5034 mat->bs = bs; 5035 ierr = (*mat->ops->setblocksize)(mat,bs);CHKERRQ(ierr); 5036 } else { 5037 SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name); 5038 } 5039 PetscFunctionReturn(0); 5040 } 5041 5042 #undef __FUNCT__ 5043 #define __FUNCT__ "MatGetRowIJ" 5044 /*@C 5045 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 5046 5047 Collective on Mat 5048 5049 Input Parameters: 5050 + mat - the matrix 5051 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 5052 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5053 symmetrized 5054 5055 Output Parameters: 5056 + n - number of rows in the (possibly compressed) matrix 5057 . ia - the row pointers 5058 . ja - the column indices 5059 - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers 5060 are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set 5061 5062 Level: developer 5063 5064 Notes: You CANNOT change any of the ia[] or ja[] values. 5065 5066 Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values 5067 5068 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 5069 @*/ 5070 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5071 { 5072 PetscErrorCode ierr; 5073 5074 PetscFunctionBegin; 5075 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5076 PetscValidType(mat,1); 5077 PetscValidIntPointer(n,4); 5078 if (ia) PetscValidIntPointer(ia,5); 5079 if (ja) PetscValidIntPointer(ja,6); 5080 PetscValidIntPointer(done,7); 5081 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5082 if (!mat->ops->getrowij) *done = PETSC_FALSE; 5083 else { 5084 *done = PETSC_TRUE; 5085 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5086 } 5087 PetscFunctionReturn(0); 5088 } 5089 5090 #undef __FUNCT__ 5091 #define __FUNCT__ "MatGetColumnIJ" 5092 /*@C 5093 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 5094 5095 Collective on Mat 5096 5097 Input Parameters: 5098 + mat - the matrix 5099 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5100 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5101 symmetrized 5102 5103 Output Parameters: 5104 + n - number of columns in the (possibly compressed) matrix 5105 . ia - the column pointers 5106 . ja - the row indices 5107 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 5108 5109 Level: developer 5110 5111 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 5112 @*/ 5113 PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5114 { 5115 PetscErrorCode ierr; 5116 5117 PetscFunctionBegin; 5118 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5119 PetscValidType(mat,1); 5120 PetscValidIntPointer(n,4); 5121 if (ia) PetscValidIntPointer(ia,5); 5122 if (ja) PetscValidIntPointer(ja,6); 5123 PetscValidIntPointer(done,7); 5124 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5125 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 5126 else { 5127 *done = PETSC_TRUE; 5128 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5129 } 5130 PetscFunctionReturn(0); 5131 } 5132 5133 #undef __FUNCT__ 5134 #define __FUNCT__ "MatRestoreRowIJ" 5135 /*@C 5136 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 5137 MatGetRowIJ(). 5138 5139 Collective on Mat 5140 5141 Input Parameters: 5142 + mat - the matrix 5143 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5144 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5145 symmetrized 5146 5147 Output Parameters: 5148 + n - size of (possibly compressed) matrix 5149 . ia - the row pointers 5150 . ja - the column indices 5151 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 5152 5153 Level: developer 5154 5155 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 5156 @*/ 5157 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5158 { 5159 PetscErrorCode ierr; 5160 5161 PetscFunctionBegin; 5162 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5163 PetscValidType(mat,1); 5164 if (ia) PetscValidIntPointer(ia,5); 5165 if (ja) PetscValidIntPointer(ja,6); 5166 PetscValidIntPointer(done,7); 5167 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5168 5169 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 5170 else { 5171 *done = PETSC_TRUE; 5172 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5173 } 5174 PetscFunctionReturn(0); 5175 } 5176 5177 #undef __FUNCT__ 5178 #define __FUNCT__ "MatRestoreColumnIJ" 5179 /*@C 5180 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 5181 MatGetColumnIJ(). 5182 5183 Collective on Mat 5184 5185 Input Parameters: 5186 + mat - the matrix 5187 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5188 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5189 symmetrized 5190 5191 Output Parameters: 5192 + n - size of (possibly compressed) matrix 5193 . ia - the column pointers 5194 . ja - the row indices 5195 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 5196 5197 Level: developer 5198 5199 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 5200 @*/ 5201 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5202 { 5203 PetscErrorCode ierr; 5204 5205 PetscFunctionBegin; 5206 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5207 PetscValidType(mat,1); 5208 if (ia) PetscValidIntPointer(ia,5); 5209 if (ja) PetscValidIntPointer(ja,6); 5210 PetscValidIntPointer(done,7); 5211 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5212 5213 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 5214 else { 5215 *done = PETSC_TRUE; 5216 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5217 } 5218 PetscFunctionReturn(0); 5219 } 5220 5221 #undef __FUNCT__ 5222 #define __FUNCT__ "MatColoringPatch" 5223 /*@C 5224 MatColoringPatch -Used inside matrix coloring routines that 5225 use MatGetRowIJ() and/or MatGetColumnIJ(). 5226 5227 Collective on Mat 5228 5229 Input Parameters: 5230 + mat - the matrix 5231 . n - number of colors 5232 . ncolors - max color value 5233 - colorarray - array indicating color for each column 5234 5235 Output Parameters: 5236 . iscoloring - coloring generated using colorarray information 5237 5238 Level: developer 5239 5240 .seealso: MatGetRowIJ(), MatGetColumnIJ() 5241 5242 @*/ 5243 PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt n,PetscInt ncolors,ISColoringValue colorarray[],ISColoring *iscoloring) 5244 { 5245 PetscErrorCode ierr; 5246 5247 PetscFunctionBegin; 5248 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5249 PetscValidType(mat,1); 5250 PetscValidIntPointer(colorarray,4); 5251 PetscValidPointer(iscoloring,5); 5252 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5253 5254 if (!mat->ops->coloringpatch){ 5255 ierr = ISColoringCreate(mat->comm,n,ncolors,colorarray,iscoloring);CHKERRQ(ierr); 5256 } else { 5257 ierr = (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);CHKERRQ(ierr); 5258 } 5259 PetscFunctionReturn(0); 5260 } 5261 5262 5263 #undef __FUNCT__ 5264 #define __FUNCT__ "MatSetUnfactored" 5265 /*@ 5266 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 5267 5268 Collective on Mat 5269 5270 Input Parameter: 5271 . mat - the factored matrix to be reset 5272 5273 Notes: 5274 This routine should be used only with factored matrices formed by in-place 5275 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 5276 format). This option can save memory, for example, when solving nonlinear 5277 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 5278 ILU(0) preconditioner. 5279 5280 Note that one can specify in-place ILU(0) factorization by calling 5281 .vb 5282 PCType(pc,PCILU); 5283 PCFactorSeUseInPlace(pc); 5284 .ve 5285 or by using the options -pc_type ilu -pc_factor_in_place 5286 5287 In-place factorization ILU(0) can also be used as a local 5288 solver for the blocks within the block Jacobi or additive Schwarz 5289 methods (runtime option: -sub_pc_factor_in_place). See the discussion 5290 of these preconditioners in the users manual for details on setting 5291 local solver options. 5292 5293 Most users should employ the simplified KSP interface for linear solvers 5294 instead of working directly with matrix algebra routines such as this. 5295 See, e.g., KSPCreate(). 5296 5297 Level: developer 5298 5299 .seealso: PCFactorSetUseInPlace() 5300 5301 Concepts: matrices^unfactored 5302 5303 @*/ 5304 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat) 5305 { 5306 PetscErrorCode ierr; 5307 5308 PetscFunctionBegin; 5309 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5310 PetscValidType(mat,1); 5311 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5312 mat->factor = 0; 5313 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 5314 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 5315 PetscFunctionReturn(0); 5316 } 5317 5318 /*MC 5319 MatGetArrayF90 - Accesses a matrix array from Fortran90. 5320 5321 Synopsis: 5322 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 5323 5324 Not collective 5325 5326 Input Parameter: 5327 . x - matrix 5328 5329 Output Parameters: 5330 + xx_v - the Fortran90 pointer to the array 5331 - ierr - error code 5332 5333 Example of Usage: 5334 .vb 5335 PetscScalar, pointer xx_v(:) 5336 .... 5337 call MatGetArrayF90(x,xx_v,ierr) 5338 a = xx_v(3) 5339 call MatRestoreArrayF90(x,xx_v,ierr) 5340 .ve 5341 5342 Notes: 5343 Not yet supported for all F90 compilers 5344 5345 Level: advanced 5346 5347 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 5348 5349 Concepts: matrices^accessing array 5350 5351 M*/ 5352 5353 /*MC 5354 MatRestoreArrayF90 - Restores a matrix array that has been 5355 accessed with MatGetArrayF90(). 5356 5357 Synopsis: 5358 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 5359 5360 Not collective 5361 5362 Input Parameters: 5363 + x - matrix 5364 - xx_v - the Fortran90 pointer to the array 5365 5366 Output Parameter: 5367 . ierr - error code 5368 5369 Example of Usage: 5370 .vb 5371 PetscScalar, pointer xx_v(:) 5372 .... 5373 call MatGetArrayF90(x,xx_v,ierr) 5374 a = xx_v(3) 5375 call MatRestoreArrayF90(x,xx_v,ierr) 5376 .ve 5377 5378 Notes: 5379 Not yet supported for all F90 compilers 5380 5381 Level: advanced 5382 5383 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 5384 5385 M*/ 5386 5387 5388 #undef __FUNCT__ 5389 #define __FUNCT__ "MatGetSubMatrix" 5390 /*@ 5391 MatGetSubMatrix - Gets a single submatrix on the same number of processors 5392 as the original matrix. 5393 5394 Collective on Mat 5395 5396 Input Parameters: 5397 + mat - the original matrix 5398 . isrow - rows this processor should obtain 5399 . iscol - columns for all processors you wish to keep 5400 . csize - number of columns "local" to this processor (does nothing for sequential 5401 matrices). This should match the result from VecGetLocalSize(x,...) if you 5402 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 5403 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5404 5405 Output Parameter: 5406 . newmat - the new submatrix, of the same type as the old 5407 5408 Level: advanced 5409 5410 Notes: the iscol argument MUST be the same on each processor. You might be 5411 able to create the iscol argument with ISAllGather(). 5412 5413 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 5414 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 5415 to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX 5416 will reuse the matrix generated the first time. 5417 5418 Concepts: matrices^submatrices 5419 5420 .seealso: MatGetSubMatrices(), ISAllGather() 5421 @*/ 5422 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat) 5423 { 5424 PetscErrorCode ierr; 5425 PetscMPIInt size; 5426 Mat *local; 5427 5428 PetscFunctionBegin; 5429 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5430 PetscValidHeaderSpecific(isrow,IS_COOKIE,2); 5431 PetscValidHeaderSpecific(iscol,IS_COOKIE,3); 5432 PetscValidPointer(newmat,6); 5433 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_COOKIE,6); 5434 PetscValidType(mat,1); 5435 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5436 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5437 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 5438 5439 /* if original matrix is on just one processor then use submatrix generated */ 5440 if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 5441 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 5442 PetscFunctionReturn(0); 5443 } else if (!mat->ops->getsubmatrix && size == 1) { 5444 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 5445 *newmat = *local; 5446 ierr = PetscFree(local);CHKERRQ(ierr); 5447 PetscFunctionReturn(0); 5448 } 5449 5450 if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5451 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);CHKERRQ(ierr); 5452 ierr = PetscObjectStateIncrease((PetscObject)*newmat);CHKERRQ(ierr); 5453 PetscFunctionReturn(0); 5454 } 5455 5456 #undef __FUNCT__ 5457 #define __FUNCT__ "MatGetSubMatrixRaw" 5458 /*@ 5459 MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors 5460 as the original matrix. 5461 5462 Collective on Mat 5463 5464 Input Parameters: 5465 + mat - the original matrix 5466 . nrows - the number of rows this processor should obtain 5467 . rows - rows this processor should obtain 5468 . ncols - the number of columns for all processors you wish to keep 5469 . cols - columns for all processors you wish to keep 5470 . csize - number of columns "local" to this processor (does nothing for sequential 5471 matrices). This should match the result from VecGetLocalSize(x,...) if you 5472 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 5473 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5474 5475 Output Parameter: 5476 . newmat - the new submatrix, of the same type as the old 5477 5478 Level: advanced 5479 5480 Notes: the iscol argument MUST be the same on each processor. You might be 5481 able to create the iscol argument with ISAllGather(). 5482 5483 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 5484 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 5485 to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX 5486 will reuse the matrix generated the first time. 5487 5488 Concepts: matrices^submatrices 5489 5490 .seealso: MatGetSubMatrices(), ISAllGather() 5491 @*/ 5492 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat) 5493 { 5494 IS isrow, iscol; 5495 PetscErrorCode ierr; 5496 5497 PetscFunctionBegin; 5498 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5499 PetscValidIntPointer(rows,2); 5500 PetscValidIntPointer(cols,3); 5501 PetscValidPointer(newmat,6); 5502 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_COOKIE,6); 5503 PetscValidType(mat,1); 5504 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5505 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5506 ierr = ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);CHKERRQ(ierr); 5507 ierr = ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);CHKERRQ(ierr); 5508 ierr = MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);CHKERRQ(ierr); 5509 ierr = ISDestroy(isrow);CHKERRQ(ierr); 5510 ierr = ISDestroy(iscol);CHKERRQ(ierr); 5511 PetscFunctionReturn(0); 5512 } 5513 5514 #undef __FUNCT__ 5515 #define __FUNCT__ "MatStashSetInitialSize" 5516 /*@ 5517 MatStashSetInitialSize - sets the sizes of the matrix stash, that is 5518 used during the assembly process to store values that belong to 5519 other processors. 5520 5521 Not Collective 5522 5523 Input Parameters: 5524 + mat - the matrix 5525 . size - the initial size of the stash. 5526 - bsize - the initial size of the block-stash(if used). 5527 5528 Options Database Keys: 5529 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 5530 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 5531 5532 Level: intermediate 5533 5534 Notes: 5535 The block-stash is used for values set with MatSetValuesBlocked() while 5536 the stash is used for values set with MatSetValues() 5537 5538 Run with the option -info and look for output of the form 5539 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 5540 to determine the appropriate value, MM, to use for size and 5541 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 5542 to determine the value, BMM to use for bsize 5543 5544 Concepts: stash^setting matrix size 5545 Concepts: matrices^stash 5546 5547 @*/ 5548 PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize) 5549 { 5550 PetscErrorCode ierr; 5551 5552 PetscFunctionBegin; 5553 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5554 PetscValidType(mat,1); 5555 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 5556 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 5557 PetscFunctionReturn(0); 5558 } 5559 5560 #undef __FUNCT__ 5561 #define __FUNCT__ "MatInterpolateAdd" 5562 /*@ 5563 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 5564 the matrix 5565 5566 Collective on Mat 5567 5568 Input Parameters: 5569 + mat - the matrix 5570 . x,y - the vectors 5571 - w - where the result is stored 5572 5573 Level: intermediate 5574 5575 Notes: 5576 w may be the same vector as y. 5577 5578 This allows one to use either the restriction or interpolation (its transpose) 5579 matrix to do the interpolation 5580 5581 Concepts: interpolation 5582 5583 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5584 5585 @*/ 5586 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 5587 { 5588 PetscErrorCode ierr; 5589 PetscInt M,N; 5590 5591 PetscFunctionBegin; 5592 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5593 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5594 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5595 PetscValidHeaderSpecific(w,VEC_COOKIE,4); 5596 PetscValidType(A,1); 5597 ierr = MatPreallocated(A);CHKERRQ(ierr); 5598 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5599 if (N > M) { 5600 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 5601 } else { 5602 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 5603 } 5604 PetscFunctionReturn(0); 5605 } 5606 5607 #undef __FUNCT__ 5608 #define __FUNCT__ "MatInterpolate" 5609 /*@ 5610 MatInterpolate - y = A*x or A'*x depending on the shape of 5611 the matrix 5612 5613 Collective on Mat 5614 5615 Input Parameters: 5616 + mat - the matrix 5617 - x,y - the vectors 5618 5619 Level: intermediate 5620 5621 Notes: 5622 This allows one to use either the restriction or interpolation (its transpose) 5623 matrix to do the interpolation 5624 5625 Concepts: matrices^interpolation 5626 5627 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5628 5629 @*/ 5630 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y) 5631 { 5632 PetscErrorCode ierr; 5633 PetscInt M,N; 5634 5635 PetscFunctionBegin; 5636 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5637 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5638 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5639 PetscValidType(A,1); 5640 ierr = MatPreallocated(A);CHKERRQ(ierr); 5641 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5642 if (N > M) { 5643 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5644 } else { 5645 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5646 } 5647 PetscFunctionReturn(0); 5648 } 5649 5650 #undef __FUNCT__ 5651 #define __FUNCT__ "MatRestrict" 5652 /*@ 5653 MatRestrict - y = A*x or A'*x 5654 5655 Collective on Mat 5656 5657 Input Parameters: 5658 + mat - the matrix 5659 - x,y - the vectors 5660 5661 Level: intermediate 5662 5663 Notes: 5664 This allows one to use either the restriction or interpolation (its transpose) 5665 matrix to do the restriction 5666 5667 Concepts: matrices^restriction 5668 5669 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 5670 5671 @*/ 5672 PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y) 5673 { 5674 PetscErrorCode ierr; 5675 PetscInt M,N; 5676 5677 PetscFunctionBegin; 5678 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5679 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5680 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5681 PetscValidType(A,1); 5682 ierr = MatPreallocated(A);CHKERRQ(ierr); 5683 5684 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5685 if (N > M) { 5686 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5687 } else { 5688 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5689 } 5690 PetscFunctionReturn(0); 5691 } 5692 5693 #undef __FUNCT__ 5694 #define __FUNCT__ "MatNullSpaceAttach" 5695 /*@C 5696 MatNullSpaceAttach - attaches a null space to a matrix. 5697 This null space will be removed from the resulting vector whenever 5698 MatMult() is called 5699 5700 Collective on Mat 5701 5702 Input Parameters: 5703 + mat - the matrix 5704 - nullsp - the null space object 5705 5706 Level: developer 5707 5708 Notes: 5709 Overwrites any previous null space that may have been attached 5710 5711 Concepts: null space^attaching to matrix 5712 5713 .seealso: MatCreate(), MatNullSpaceCreate() 5714 @*/ 5715 PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 5716 { 5717 PetscErrorCode ierr; 5718 5719 PetscFunctionBegin; 5720 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5721 PetscValidType(mat,1); 5722 PetscValidHeaderSpecific(nullsp,MAT_NULLSPACE_COOKIE,2); 5723 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5724 5725 if (mat->nullsp) { 5726 ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); 5727 } 5728 mat->nullsp = nullsp; 5729 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 5730 PetscFunctionReturn(0); 5731 } 5732 5733 #undef __FUNCT__ 5734 #define __FUNCT__ "MatICCFactor" 5735 /*@ 5736 MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix. 5737 5738 Collective on Mat 5739 5740 Input Parameters: 5741 + mat - the matrix 5742 . row - row/column permutation 5743 . fill - expected fill factor >= 1.0 5744 - level - level of fill, for ICC(k) 5745 5746 Notes: 5747 Probably really in-place only when level of fill is zero, otherwise allocates 5748 new space to store factored matrix and deletes previous memory. 5749 5750 Most users should employ the simplified KSP interface for linear solvers 5751 instead of working directly with matrix algebra routines such as this. 5752 See, e.g., KSPCreate(). 5753 5754 Level: developer 5755 5756 Concepts: matrices^incomplete Cholesky factorization 5757 Concepts: Cholesky factorization 5758 5759 .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 5760 @*/ 5761 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info) 5762 { 5763 PetscErrorCode ierr; 5764 5765 PetscFunctionBegin; 5766 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5767 PetscValidType(mat,1); 5768 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 5769 PetscValidPointer(info,3); 5770 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 5771 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5772 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5773 if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5774 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5775 ierr = (*mat->ops->iccfactor)(mat,row,info);CHKERRQ(ierr); 5776 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5777 PetscFunctionReturn(0); 5778 } 5779 5780 #undef __FUNCT__ 5781 #define __FUNCT__ "MatSetValuesAdic" 5782 /*@ 5783 MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix. 5784 5785 Not Collective 5786 5787 Input Parameters: 5788 + mat - the matrix 5789 - v - the values compute with ADIC 5790 5791 Level: developer 5792 5793 Notes: 5794 Must call MatSetColoring() before using this routine. Also this matrix must already 5795 have its nonzero pattern determined. 5796 5797 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5798 MatSetValues(), MatSetColoring(), MatSetValuesAdifor() 5799 @*/ 5800 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v) 5801 { 5802 PetscErrorCode ierr; 5803 5804 PetscFunctionBegin; 5805 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5806 PetscValidType(mat,1); 5807 PetscValidPointer(mat,2); 5808 5809 if (!mat->assembled) { 5810 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5811 } 5812 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5813 if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5814 ierr = (*mat->ops->setvaluesadic)(mat,v);CHKERRQ(ierr); 5815 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5816 ierr = MatView_Private(mat);CHKERRQ(ierr); 5817 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5818 PetscFunctionReturn(0); 5819 } 5820 5821 5822 #undef __FUNCT__ 5823 #define __FUNCT__ "MatSetColoring" 5824 /*@ 5825 MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic() 5826 5827 Not Collective 5828 5829 Input Parameters: 5830 + mat - the matrix 5831 - coloring - the coloring 5832 5833 Level: developer 5834 5835 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5836 MatSetValues(), MatSetValuesAdic() 5837 @*/ 5838 PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring) 5839 { 5840 PetscErrorCode ierr; 5841 5842 PetscFunctionBegin; 5843 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5844 PetscValidType(mat,1); 5845 PetscValidPointer(coloring,2); 5846 5847 if (!mat->assembled) { 5848 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5849 } 5850 if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5851 ierr = (*mat->ops->setcoloring)(mat,coloring);CHKERRQ(ierr); 5852 PetscFunctionReturn(0); 5853 } 5854 5855 #undef __FUNCT__ 5856 #define __FUNCT__ "MatSetValuesAdifor" 5857 /*@ 5858 MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix. 5859 5860 Not Collective 5861 5862 Input Parameters: 5863 + mat - the matrix 5864 . nl - leading dimension of v 5865 - v - the values compute with ADIFOR 5866 5867 Level: developer 5868 5869 Notes: 5870 Must call MatSetColoring() before using this routine. Also this matrix must already 5871 have its nonzero pattern determined. 5872 5873 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5874 MatSetValues(), MatSetColoring() 5875 @*/ 5876 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v) 5877 { 5878 PetscErrorCode ierr; 5879 5880 PetscFunctionBegin; 5881 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5882 PetscValidType(mat,1); 5883 PetscValidPointer(v,3); 5884 5885 if (!mat->assembled) { 5886 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5887 } 5888 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5889 if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5890 ierr = (*mat->ops->setvaluesadifor)(mat,nl,v);CHKERRQ(ierr); 5891 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5892 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5893 PetscFunctionReturn(0); 5894 } 5895 5896 #undef __FUNCT__ 5897 #define __FUNCT__ "MatDiagonalScaleLocal" 5898 /*@ 5899 MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 5900 ghosted ones. 5901 5902 Not Collective 5903 5904 Input Parameters: 5905 + mat - the matrix 5906 - diag = the diagonal values, including ghost ones 5907 5908 Level: developer 5909 5910 Notes: Works only for MPIAIJ and MPIBAIJ matrices 5911 5912 .seealso: MatDiagonalScale() 5913 @*/ 5914 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag) 5915 { 5916 PetscErrorCode ierr; 5917 PetscMPIInt size; 5918 5919 PetscFunctionBegin; 5920 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5921 PetscValidHeaderSpecific(diag,VEC_COOKIE,2); 5922 PetscValidType(mat,1); 5923 5924 if (!mat->assembled) { 5925 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5926 } 5927 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5928 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 5929 if (size == 1) { 5930 PetscInt n,m; 5931 ierr = VecGetSize(diag,&n);CHKERRQ(ierr); 5932 ierr = MatGetSize(mat,0,&m);CHKERRQ(ierr); 5933 if (m == n) { 5934 ierr = MatDiagonalScale(mat,0,diag);CHKERRQ(ierr); 5935 } else { 5936 SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions"); 5937 } 5938 } else { 5939 PetscErrorCode (*f)(Mat,Vec); 5940 ierr = PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);CHKERRQ(ierr); 5941 if (f) { 5942 ierr = (*f)(mat,diag);CHKERRQ(ierr); 5943 } else { 5944 SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices"); 5945 } 5946 } 5947 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5948 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5949 PetscFunctionReturn(0); 5950 } 5951 5952 #undef __FUNCT__ 5953 #define __FUNCT__ "MatGetInertia" 5954 /*@ 5955 MatGetInertia - Gets the inertia from a factored matrix 5956 5957 Collective on Mat 5958 5959 Input Parameter: 5960 . mat - the matrix 5961 5962 Output Parameters: 5963 + nneg - number of negative eigenvalues 5964 . nzero - number of zero eigenvalues 5965 - npos - number of positive eigenvalues 5966 5967 Level: advanced 5968 5969 Notes: Matrix must have been factored by MatCholeskyFactor() 5970 5971 5972 @*/ 5973 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos) 5974 { 5975 PetscErrorCode ierr; 5976 5977 PetscFunctionBegin; 5978 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5979 PetscValidType(mat,1); 5980 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 5981 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled"); 5982 if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5983 ierr = (*mat->ops->getinertia)(mat,nneg,nzero,npos);CHKERRQ(ierr); 5984 PetscFunctionReturn(0); 5985 } 5986 5987 /* ----------------------------------------------------------------*/ 5988 #undef __FUNCT__ 5989 #define __FUNCT__ "MatSolves" 5990 /*@ 5991 MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors 5992 5993 Collective on Mat and Vecs 5994 5995 Input Parameters: 5996 + mat - the factored matrix 5997 - b - the right-hand-side vectors 5998 5999 Output Parameter: 6000 . x - the result vectors 6001 6002 Notes: 6003 The vectors b and x cannot be the same. I.e., one cannot 6004 call MatSolves(A,x,x). 6005 6006 Notes: 6007 Most users should employ the simplified KSP interface for linear solvers 6008 instead of working directly with matrix algebra routines such as this. 6009 See, e.g., KSPCreate(). 6010 6011 Level: developer 6012 6013 Concepts: matrices^triangular solves 6014 6015 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve() 6016 @*/ 6017 PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x) 6018 { 6019 PetscErrorCode ierr; 6020 6021 PetscFunctionBegin; 6022 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 6023 PetscValidType(mat,1); 6024 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 6025 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 6026 if (!mat->M && !mat->N) PetscFunctionReturn(0); 6027 6028 if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 6029 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6030 ierr = PetscLogEventBegin(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6031 ierr = (*mat->ops->solves)(mat,b,x);CHKERRQ(ierr); 6032 ierr = PetscLogEventEnd(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6033 PetscFunctionReturn(0); 6034 } 6035 6036 #undef __FUNCT__ 6037 #define __FUNCT__ "MatIsSymmetric" 6038 /*@ 6039 MatIsSymmetric - Test whether a matrix is symmetric 6040 6041 Collective on Mat 6042 6043 Input Parameter: 6044 + A - the matrix to test 6045 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose) 6046 6047 Output Parameters: 6048 . flg - the result 6049 6050 Level: intermediate 6051 6052 Concepts: matrix^symmetry 6053 6054 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 6055 @*/ 6056 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg) 6057 { 6058 PetscErrorCode ierr; 6059 6060 PetscFunctionBegin; 6061 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6062 PetscValidPointer(flg,2); 6063 if (!A->symmetric_set) { 6064 if (!A->ops->issymmetric) { 6065 MatType mattype; 6066 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 6067 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 6068 } 6069 ierr = (*A->ops->issymmetric)(A,tol,&A->symmetric);CHKERRQ(ierr); 6070 A->symmetric_set = PETSC_TRUE; 6071 if (A->symmetric) { 6072 A->structurally_symmetric_set = PETSC_TRUE; 6073 A->structurally_symmetric = PETSC_TRUE; 6074 } 6075 } 6076 *flg = A->symmetric; 6077 PetscFunctionReturn(0); 6078 } 6079 6080 #undef __FUNCT__ 6081 #define __FUNCT__ "MatIsSymmetricKnown" 6082 /*@ 6083 MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric. 6084 6085 Collective on Mat 6086 6087 Input Parameter: 6088 . A - the matrix to check 6089 6090 Output Parameters: 6091 + set - if the symmetric flag is set (this tells you if the next flag is valid) 6092 - flg - the result 6093 6094 Level: advanced 6095 6096 Concepts: matrix^symmetry 6097 6098 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric() 6099 if you want it explicitly checked 6100 6101 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 6102 @*/ 6103 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg) 6104 { 6105 PetscFunctionBegin; 6106 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6107 PetscValidPointer(set,2); 6108 PetscValidPointer(flg,3); 6109 if (A->symmetric_set) { 6110 *set = PETSC_TRUE; 6111 *flg = A->symmetric; 6112 } else { 6113 *set = PETSC_FALSE; 6114 } 6115 PetscFunctionReturn(0); 6116 } 6117 6118 #undef __FUNCT__ 6119 #define __FUNCT__ "MatIsHermitianKnown" 6120 /*@ 6121 MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian. 6122 6123 Collective on Mat 6124 6125 Input Parameter: 6126 . A - the matrix to check 6127 6128 Output Parameters: 6129 + set - if the hermitian flag is set (this tells you if the next flag is valid) 6130 - flg - the result 6131 6132 Level: advanced 6133 6134 Concepts: matrix^symmetry 6135 6136 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian() 6137 if you want it explicitly checked 6138 6139 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 6140 @*/ 6141 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg) 6142 { 6143 PetscFunctionBegin; 6144 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6145 PetscValidPointer(set,2); 6146 PetscValidPointer(flg,3); 6147 if (A->hermitian_set) { 6148 *set = PETSC_TRUE; 6149 *flg = A->hermitian; 6150 } else { 6151 *set = PETSC_FALSE; 6152 } 6153 PetscFunctionReturn(0); 6154 } 6155 6156 #undef __FUNCT__ 6157 #define __FUNCT__ "MatIsStructurallySymmetric" 6158 /*@ 6159 MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric 6160 6161 Collective on Mat 6162 6163 Input Parameter: 6164 . A - the matrix to test 6165 6166 Output Parameters: 6167 . flg - the result 6168 6169 Level: intermediate 6170 6171 Concepts: matrix^symmetry 6172 6173 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption() 6174 @*/ 6175 PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg) 6176 { 6177 PetscErrorCode ierr; 6178 6179 PetscFunctionBegin; 6180 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6181 PetscValidPointer(flg,2); 6182 if (!A->structurally_symmetric_set) { 6183 if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric"); 6184 ierr = (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);CHKERRQ(ierr); 6185 A->structurally_symmetric_set = PETSC_TRUE; 6186 } 6187 *flg = A->structurally_symmetric; 6188 PetscFunctionReturn(0); 6189 } 6190 6191 #undef __FUNCT__ 6192 #define __FUNCT__ "MatIsHermitian" 6193 /*@ 6194 MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose. 6195 6196 Collective on Mat 6197 6198 Input Parameter: 6199 . A - the matrix to test 6200 6201 Output Parameters: 6202 . flg - the result 6203 6204 Level: intermediate 6205 6206 Concepts: matrix^symmetry 6207 6208 .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption() 6209 @*/ 6210 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg) 6211 { 6212 PetscErrorCode ierr; 6213 6214 PetscFunctionBegin; 6215 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6216 PetscValidPointer(flg,2); 6217 if (!A->hermitian_set) { 6218 if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian"); 6219 ierr = (*A->ops->ishermitian)(A,&A->hermitian);CHKERRQ(ierr); 6220 A->hermitian_set = PETSC_TRUE; 6221 if (A->hermitian) { 6222 A->structurally_symmetric_set = PETSC_TRUE; 6223 A->structurally_symmetric = PETSC_TRUE; 6224 } 6225 } 6226 *flg = A->hermitian; 6227 PetscFunctionReturn(0); 6228 } 6229 6230 #undef __FUNCT__ 6231 #define __FUNCT__ "MatStashGetInfo" 6232 extern PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*); 6233 /*@ 6234 MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need 6235 to be communicated to other processors during the MatAssemblyBegin/End() process 6236 6237 Not collective 6238 6239 Input Parameter: 6240 . vec - the vector 6241 6242 Output Parameters: 6243 + nstash - the size of the stash 6244 . reallocs - the number of additional mallocs incurred. 6245 . bnstash - the size of the block stash 6246 - breallocs - the number of additional mallocs incurred.in the block stash 6247 6248 Level: advanced 6249 6250 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize() 6251 6252 @*/ 6253 PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs) 6254 { 6255 PetscErrorCode ierr; 6256 PetscFunctionBegin; 6257 ierr = MatStashGetInfo_Private(&mat->stash,nstash,reallocs);CHKERRQ(ierr); 6258 ierr = MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);CHKERRQ(ierr); 6259 PetscFunctionReturn(0); 6260 } 6261 6262 #undef __FUNCT__ 6263 #define __FUNCT__ "MatGetVecs" 6264 /*@ 6265 MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 6266 parallel layout 6267 6268 Collective on Mat 6269 6270 Input Parameter: 6271 . mat - the matrix 6272 6273 Output Parameter: 6274 + right - (optional) vector that the matrix can be multiplied against 6275 - left - (optional) vector that the matrix vector product can be stored in 6276 6277 Level: advanced 6278 6279 .seealso: MatCreate() 6280 @*/ 6281 PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left) 6282 { 6283 PetscErrorCode ierr; 6284 6285 PetscFunctionBegin; 6286 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 6287 PetscValidType(mat,1); 6288 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6289 if (mat->ops->getvecs) { 6290 ierr = (*mat->ops->getvecs)(mat,right,left);CHKERRQ(ierr); 6291 } else { 6292 PetscMPIInt size; 6293 ierr = MPI_Comm_size(mat->comm, &size);CHKERRQ(ierr); 6294 if (right) { 6295 ierr = VecCreate(mat->comm,right);CHKERRQ(ierr); 6296 ierr = VecSetSizes(*right,mat->n,PETSC_DETERMINE);CHKERRQ(ierr); 6297 if (size > 1) {ierr = VecSetType(*right,VECMPI);CHKERRQ(ierr);} 6298 else {ierr = VecSetType(*right,VECSEQ);CHKERRQ(ierr);} 6299 } 6300 if (left) { 6301 ierr = VecCreate(mat->comm,left);CHKERRQ(ierr); 6302 ierr = VecSetSizes(*left,mat->m,PETSC_DETERMINE);CHKERRQ(ierr); 6303 if (size > 1) {ierr = VecSetType(*left,VECMPI);CHKERRQ(ierr);} 6304 else {ierr = VecSetType(*left,VECSEQ);CHKERRQ(ierr);} 6305 } 6306 } 6307 if (right) {ierr = VecSetBlockSize(*right,mat->bs);CHKERRQ(ierr);} 6308 if (left) {ierr = VecSetBlockSize(*left,mat->bs);CHKERRQ(ierr);} 6309 PetscFunctionReturn(0); 6310 } 6311 6312 #undef __FUNCT__ 6313 #define __FUNCT__ "MatFactorInfoInitialize" 6314 /*@ 6315 MatFactorInfoInitialize - Initializes a MatFactorInfo data structure 6316 with default values. 6317 6318 Not Collective 6319 6320 Input Parameters: 6321 . info - the MatFactorInfo data structure 6322 6323 6324 Notes: The solvers are generally used through the KSP and PC objects, for example 6325 PCLU, PCILU, PCCHOLESKY, PCICC 6326 6327 Level: developer 6328 6329 .seealso: MatFactorInfo 6330 @*/ 6331 6332 PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info) 6333 { 6334 PetscErrorCode ierr; 6335 6336 PetscFunctionBegin; 6337 ierr = PetscMemzero(info,sizeof(MatFactorInfo));CHKERRQ(ierr); 6338 PetscFunctionReturn(0); 6339 } 6340 6341 #undef __FUNCT__ 6342 #define __FUNCT__ "MatPtAP" 6343 /*@ 6344 MatPtAP - Creates the matrix projection C = P^T * A * P 6345 6346 Collective on Mat 6347 6348 Input Parameters: 6349 + A - the matrix 6350 . P - the projection matrix 6351 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6352 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)) 6353 6354 Output Parameters: 6355 . C - the product matrix 6356 6357 Notes: 6358 C will be created and must be destroyed by the user with MatDestroy(). 6359 6360 This routine is currently only implemented for pairs of AIJ matrices and classes 6361 which inherit from AIJ. 6362 6363 Level: intermediate 6364 6365 .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult() 6366 @*/ 6367 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C) 6368 { 6369 PetscErrorCode ierr; 6370 6371 PetscFunctionBegin; 6372 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6373 PetscValidType(A,1); 6374 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6375 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6376 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6377 PetscValidType(P,2); 6378 MatPreallocated(P); 6379 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6380 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6381 PetscValidPointer(C,3); 6382 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 6383 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill); 6384 ierr = MatPreallocated(A);CHKERRQ(ierr); 6385 6386 ierr = PetscLogEventBegin(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 6387 ierr = (*A->ops->ptap)(A,P,scall,fill,C);CHKERRQ(ierr); 6388 ierr = PetscLogEventEnd(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 6389 6390 PetscFunctionReturn(0); 6391 } 6392 6393 #undef __FUNCT__ 6394 #define __FUNCT__ "MatPtAPNumeric" 6395 /*@ 6396 MatPtAPNumeric - Computes the matrix projection C = P^T * A * P 6397 6398 Collective on Mat 6399 6400 Input Parameters: 6401 + A - the matrix 6402 - P - the projection matrix 6403 6404 Output Parameters: 6405 . C - the product matrix 6406 6407 Notes: 6408 C must have been created by calling MatPtAPSymbolic and must be destroyed by 6409 the user using MatDeatroy(). 6410 6411 This routine is currently only implemented for pairs of AIJ matrices and classes 6412 which inherit from AIJ. C will be of type MATAIJ. 6413 6414 Level: intermediate 6415 6416 .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric() 6417 @*/ 6418 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C) 6419 { 6420 PetscErrorCode ierr; 6421 6422 PetscFunctionBegin; 6423 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6424 PetscValidType(A,1); 6425 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6426 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6427 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6428 PetscValidType(P,2); 6429 MatPreallocated(P); 6430 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6431 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6432 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 6433 PetscValidType(C,3); 6434 MatPreallocated(C); 6435 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6436 if (P->N!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->M); 6437 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 6438 if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N); 6439 if (P->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->N); 6440 ierr = MatPreallocated(A);CHKERRQ(ierr); 6441 6442 ierr = PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 6443 ierr = (*A->ops->ptapnumeric)(A,P,C);CHKERRQ(ierr); 6444 ierr = PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 6445 PetscFunctionReturn(0); 6446 } 6447 6448 #undef __FUNCT__ 6449 #define __FUNCT__ "MatPtAPSymbolic" 6450 /*@ 6451 MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P 6452 6453 Collective on Mat 6454 6455 Input Parameters: 6456 + A - the matrix 6457 - P - the projection matrix 6458 6459 Output Parameters: 6460 . C - the (i,j) structure of the product matrix 6461 6462 Notes: 6463 C will be created and must be destroyed by the user with MatDestroy(). 6464 6465 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 6466 which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using 6467 this (i,j) structure by calling MatPtAPNumeric(). 6468 6469 Level: intermediate 6470 6471 .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic() 6472 @*/ 6473 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C) 6474 { 6475 PetscErrorCode ierr; 6476 6477 PetscFunctionBegin; 6478 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6479 PetscValidType(A,1); 6480 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6481 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6482 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6483 PetscValidType(P,2); 6484 MatPreallocated(P); 6485 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6486 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6487 PetscValidPointer(C,3); 6488 6489 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 6490 if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N); 6491 ierr = MatPreallocated(A);CHKERRQ(ierr); 6492 ierr = PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 6493 ierr = (*A->ops->ptapsymbolic)(A,P,fill,C);CHKERRQ(ierr); 6494 ierr = PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 6495 6496 ierr = MatSetBlockSize(*C,A->bs);CHKERRQ(ierr); 6497 6498 PetscFunctionReturn(0); 6499 } 6500 6501 #undef __FUNCT__ 6502 #define __FUNCT__ "MatMatMult" 6503 /*@ 6504 MatMatMult - Performs Matrix-Matrix Multiplication C=A*B. 6505 6506 Collective on Mat 6507 6508 Input Parameters: 6509 + A - the left matrix 6510 . B - the right matrix 6511 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6512 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6513 6514 Output Parameters: 6515 . C - the product matrix 6516 6517 Notes: 6518 C will be created and must be destroyed by the user with MatDestroy(). 6519 Unless scall is MAT_REUSE_MATRIX 6520 6521 This routine is currently only implemented for pairs of AIJ matrices and classes 6522 which inherit from AIJ. C will be of type MATAIJ. 6523 6524 Level: intermediate 6525 6526 .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP() 6527 @*/ 6528 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 6529 { 6530 PetscErrorCode ierr; 6531 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6532 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6533 6534 PetscFunctionBegin; 6535 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6536 PetscValidType(A,1); 6537 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6538 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6539 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6540 PetscValidType(B,2); 6541 MatPreallocated(B); 6542 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6543 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6544 PetscValidPointer(C,3); 6545 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6546 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill); 6547 ierr = MatPreallocated(A);CHKERRQ(ierr); 6548 6549 /* For now, we do not dispatch based on the type of A and B */ 6550 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6551 fA = A->ops->matmult; 6552 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for A of type %s",A->type_name); 6553 fB = B->ops->matmult; 6554 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name); 6555 if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6556 6557 ierr = PetscLogEventBegin(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6558 ierr = (*A->ops->matmult)(A,B,scall,fill,C);CHKERRQ(ierr); 6559 ierr = PetscLogEventEnd(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6560 6561 PetscFunctionReturn(0); 6562 } 6563 6564 #undef __FUNCT__ 6565 #define __FUNCT__ "MatMatMultSymbolic" 6566 /*@ 6567 MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure 6568 of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric(). 6569 6570 Collective on Mat 6571 6572 Input Parameters: 6573 + A - the left matrix 6574 . B - the right matrix 6575 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6576 6577 Output Parameters: 6578 . C - the matrix containing the ij structure of product matrix 6579 6580 Notes: 6581 C will be created as a MATSEQAIJ matrix and must be destroyed by the user with MatDestroy(). 6582 6583 This routine is currently only implemented for SeqAIJ matrices and classes which inherit from SeqAIJ. 6584 6585 Level: intermediate 6586 6587 .seealso: MatMatMult(), MatMatMultNumeric() 6588 @*/ 6589 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C) 6590 { 6591 PetscErrorCode ierr; 6592 PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *); 6593 PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *); 6594 6595 PetscFunctionBegin; 6596 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6597 PetscValidType(A,1); 6598 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6599 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6600 6601 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6602 PetscValidType(B,2); 6603 MatPreallocated(B); 6604 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6605 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6606 PetscValidPointer(C,3); 6607 6608 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6609 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill); 6610 ierr = MatPreallocated(A);CHKERRQ(ierr); 6611 6612 /* For now, we do not dispatch based on the type of A and P */ 6613 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6614 Asymbolic = A->ops->matmultsymbolic; 6615 if (!Asymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for A of type %s",A->type_name); 6616 Bsymbolic = B->ops->matmultsymbolic; 6617 if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name); 6618 if (Bsymbolic!=Asymbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6619 6620 ierr = PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6621 ierr = (*Asymbolic)(A,B,fill,C);CHKERRQ(ierr); 6622 ierr = PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6623 6624 PetscFunctionReturn(0); 6625 } 6626 6627 #undef __FUNCT__ 6628 #define __FUNCT__ "MatMatMultNumeric" 6629 /*@ 6630 MatMatMultNumeric - Performs the numeric matrix-matrix product. 6631 Call this routine after first calling MatMatMultSymbolic(). 6632 6633 Collective on Mat 6634 6635 Input Parameters: 6636 + A - the left matrix 6637 - B - the right matrix 6638 6639 Output Parameters: 6640 . C - the product matrix, whose ij structure was defined from MatMatMultSymbolic(). 6641 6642 Notes: 6643 C must have been created with MatMatMultSymbolic. 6644 6645 This routine is currently only implemented for SeqAIJ type matrices. 6646 6647 Level: intermediate 6648 6649 .seealso: MatMatMult(), MatMatMultSymbolic() 6650 @*/ 6651 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C) 6652 { 6653 PetscErrorCode ierr; 6654 PetscErrorCode (*Anumeric)(Mat,Mat,Mat); 6655 PetscErrorCode (*Bnumeric)(Mat,Mat,Mat); 6656 6657 PetscFunctionBegin; 6658 6659 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6660 PetscValidType(A,1); 6661 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6662 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6663 6664 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6665 PetscValidType(B,2); 6666 MatPreallocated(B); 6667 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6668 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6669 6670 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 6671 PetscValidType(C,3); 6672 MatPreallocated(C); 6673 if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6674 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6675 6676 if (B->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->N,C->N); 6677 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6678 if (A->M!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->M,C->M); 6679 ierr = MatPreallocated(A);CHKERRQ(ierr); 6680 6681 /* For now, we do not dispatch based on the type of A and B */ 6682 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6683 Anumeric = A->ops->matmultnumeric; 6684 if (!Anumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for A of type %s",A->type_name); 6685 Bnumeric = B->ops->matmultnumeric; 6686 if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name); 6687 if (Bnumeric!=Anumeric) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6688 6689 ierr = PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6690 ierr = (*Anumeric)(A,B,C);CHKERRQ(ierr); 6691 ierr = PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6692 6693 PetscFunctionReturn(0); 6694 } 6695 6696 #undef __FUNCT__ 6697 #define __FUNCT__ "MatMatMultTranspose" 6698 /*@ 6699 MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B. 6700 6701 Collective on Mat 6702 6703 Input Parameters: 6704 + A - the left matrix 6705 . B - the right matrix 6706 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6707 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6708 6709 Output Parameters: 6710 . C - the product matrix 6711 6712 Notes: 6713 C will be created and must be destroyed by the user with MatDestroy(). 6714 6715 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 6716 which inherit from SeqAIJ. C will be of type MATSEQAIJ. 6717 6718 Level: intermediate 6719 6720 .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP() 6721 @*/ 6722 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 6723 { 6724 PetscErrorCode ierr; 6725 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6726 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6727 6728 PetscFunctionBegin; 6729 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6730 PetscValidType(A,1); 6731 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6732 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6733 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6734 PetscValidType(B,2); 6735 MatPreallocated(B); 6736 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6737 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6738 PetscValidPointer(C,3); 6739 if (B->M!=A->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->M); 6740 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%G must be > 0.0",fill); 6741 ierr = MatPreallocated(A);CHKERRQ(ierr); 6742 6743 fA = A->ops->matmulttranspose; 6744 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name); 6745 fB = B->ops->matmulttranspose; 6746 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name); 6747 if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6748 6749 ierr = PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6750 ierr = (*A->ops->matmulttranspose)(A,B,scall,fill,C);CHKERRQ(ierr); 6751 ierr = PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6752 6753 PetscFunctionReturn(0); 6754 } 6755