1 #define PETSCMAT_DLL 2 3 /* 4 This is where the abstract matrix operations are defined 5 */ 6 7 #include "include/private/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, MAT_GetRedundantMatrix = 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) { 521 ierr = PetscViewerASCIIGetStdout(mat->comm,&viewer);CHKERRQ(ierr); 522 } 523 PetscValidHeaderSpecific(viewer,PETSC_VIEWER_COOKIE,2); 524 PetscCheckSameComm(mat,1,viewer,2); 525 if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix"); 526 ierr = MatPreallocated(mat);CHKERRQ(ierr); 527 528 ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);CHKERRQ(ierr); 529 if (iascii) { 530 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 531 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 532 if (mat->prefix) { 533 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);CHKERRQ(ierr); 534 } else { 535 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");CHKERRQ(ierr); 536 } 537 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 538 ierr = MatGetType(mat,&cstr);CHKERRQ(ierr); 539 ierr = MatGetSize(mat,&rows,&cols);CHKERRQ(ierr); 540 ierr = PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);CHKERRQ(ierr); 541 if (mat->ops->getinfo) { 542 MatInfo info; 543 ierr = MatGetInfo(mat,MAT_GLOBAL_SUM,&info);CHKERRQ(ierr); 544 ierr = PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n", 545 (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);CHKERRQ(ierr); 546 } 547 } 548 } 549 if (mat->ops->view) { 550 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 551 ierr = (*mat->ops->view)(mat,viewer);CHKERRQ(ierr); 552 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 553 } else if (!iascii) { 554 SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name); 555 } 556 if (iascii) { 557 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 558 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 559 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 560 } 561 } 562 PetscFunctionReturn(0); 563 } 564 565 #undef __FUNCT__ 566 #define __FUNCT__ "MatScaleSystem" 567 /*@C 568 MatScaleSystem - Scale a vector solution and right hand side to 569 match the scaling of a scaled matrix. 570 571 Collective on Mat 572 573 Input Parameter: 574 + mat - the matrix 575 . b - right hand side vector (or PETSC_NULL) 576 - x - solution vector (or PETSC_NULL) 577 578 579 Notes: 580 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 581 internally scaled, so this does nothing. For MPIROWBS it 582 permutes and diagonally scales. 583 584 The KSP methods automatically call this routine when required 585 (via PCPreSolve()) so it is rarely used directly. 586 587 Level: Developer 588 589 Concepts: matrices^scaling 590 591 .seealso: MatUseScaledForm(), MatUnScaleSystem() 592 @*/ 593 PetscErrorCode PETSCMAT_DLLEXPORT MatScaleSystem(Mat mat,Vec b,Vec x) 594 { 595 PetscErrorCode ierr; 596 597 PetscFunctionBegin; 598 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 599 PetscValidType(mat,1); 600 ierr = MatPreallocated(mat);CHKERRQ(ierr); 601 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 602 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 603 604 if (mat->ops->scalesystem) { 605 ierr = (*mat->ops->scalesystem)(mat,b,x);CHKERRQ(ierr); 606 } 607 PetscFunctionReturn(0); 608 } 609 610 #undef __FUNCT__ 611 #define __FUNCT__ "MatUnScaleSystem" 612 /*@C 613 MatUnScaleSystem - Unscales a vector solution and right hand side to 614 match the original scaling of a scaled matrix. 615 616 Collective on Mat 617 618 Input Parameter: 619 + mat - the matrix 620 . b - right hand side vector (or PETSC_NULL) 621 - x - solution vector (or PETSC_NULL) 622 623 624 Notes: 625 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 626 internally scaled, so this does nothing. For MPIROWBS it 627 permutes and diagonally scales. 628 629 The KSP methods automatically call this routine when required 630 (via PCPreSolve()) so it is rarely used directly. 631 632 Level: Developer 633 634 .seealso: MatUseScaledForm(), MatScaleSystem() 635 @*/ 636 PetscErrorCode PETSCMAT_DLLEXPORT MatUnScaleSystem(Mat mat,Vec b,Vec x) 637 { 638 PetscErrorCode ierr; 639 640 PetscFunctionBegin; 641 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 642 PetscValidType(mat,1); 643 ierr = MatPreallocated(mat);CHKERRQ(ierr); 644 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 645 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 646 if (mat->ops->unscalesystem) { 647 ierr = (*mat->ops->unscalesystem)(mat,b,x);CHKERRQ(ierr); 648 } 649 PetscFunctionReturn(0); 650 } 651 652 #undef __FUNCT__ 653 #define __FUNCT__ "MatUseScaledForm" 654 /*@C 655 MatUseScaledForm - For matrix storage formats that scale the 656 matrix (for example MPIRowBS matrices are diagonally scaled on 657 assembly) indicates matrix operations (MatMult() etc) are 658 applied using the scaled matrix. 659 660 Collective on Mat 661 662 Input Parameter: 663 + mat - the matrix 664 - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 665 applying the original matrix 666 667 Notes: 668 For scaled matrix formats, applying the original, unscaled matrix 669 will be slightly more expensive 670 671 Level: Developer 672 673 .seealso: MatScaleSystem(), MatUnScaleSystem() 674 @*/ 675 PetscErrorCode PETSCMAT_DLLEXPORT MatUseScaledForm(Mat mat,PetscTruth scaled) 676 { 677 PetscErrorCode ierr; 678 679 PetscFunctionBegin; 680 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 681 PetscValidType(mat,1); 682 ierr = MatPreallocated(mat);CHKERRQ(ierr); 683 if (mat->ops->usescaledform) { 684 ierr = (*mat->ops->usescaledform)(mat,scaled);CHKERRQ(ierr); 685 } 686 PetscFunctionReturn(0); 687 } 688 689 #undef __FUNCT__ 690 #define __FUNCT__ "MatDestroy" 691 /*@ 692 MatDestroy - Frees space taken by a matrix. 693 694 Collective on Mat 695 696 Input Parameter: 697 . A - the matrix 698 699 Level: beginner 700 701 @*/ 702 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroy(Mat A) 703 { 704 PetscErrorCode ierr; 705 PetscFunctionBegin; 706 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 707 if (--A->refct > 0) PetscFunctionReturn(0); 708 ierr = MatPreallocated(A);CHKERRQ(ierr); 709 /* if memory was published with AMS then destroy it */ 710 ierr = PetscObjectDepublish(A);CHKERRQ(ierr); 711 if (A->ops->destroy) { 712 ierr = (*A->ops->destroy)(A);CHKERRQ(ierr); 713 } 714 if (A->mapping) { 715 ierr = ISLocalToGlobalMappingDestroy(A->mapping);CHKERRQ(ierr); 716 } 717 if (A->bmapping) { 718 ierr = ISLocalToGlobalMappingDestroy(A->bmapping);CHKERRQ(ierr); 719 } 720 ierr = PetscFree(A->rmap.range);CHKERRQ(ierr); 721 ierr = PetscFree(A->cmap.range);CHKERRQ(ierr); 722 ierr = PetscFree(A->spptr);CHKERRQ(ierr); 723 ierr = PetscHeaderDestroy(A);CHKERRQ(ierr); 724 PetscFunctionReturn(0); 725 } 726 727 #undef __FUNCT__ 728 #define __FUNCT__ "MatValid" 729 /*@ 730 MatValid - Checks whether a matrix object is valid. 731 732 Collective on Mat 733 734 Input Parameter: 735 . m - the matrix to check 736 737 Output Parameter: 738 flg - flag indicating matrix status, either 739 PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise. 740 741 Level: developer 742 743 Concepts: matrices^validity 744 @*/ 745 PetscErrorCode PETSCMAT_DLLEXPORT MatValid(Mat m,PetscTruth *flg) 746 { 747 PetscFunctionBegin; 748 PetscValidIntPointer(flg,1); 749 if (!m) *flg = PETSC_FALSE; 750 else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE; 751 else *flg = PETSC_TRUE; 752 PetscFunctionReturn(0); 753 } 754 755 #undef __FUNCT__ 756 #define __FUNCT__ "MatSetValues" 757 /*@ 758 MatSetValues - Inserts or adds a block of values into a matrix. 759 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 760 MUST be called after all calls to MatSetValues() have been completed. 761 762 Not Collective 763 764 Input Parameters: 765 + mat - the matrix 766 . v - a logically two-dimensional array of values 767 . m, idxm - the number of rows and their global indices 768 . n, idxn - the number of columns and their global indices 769 - addv - either ADD_VALUES or INSERT_VALUES, where 770 ADD_VALUES adds values to any existing entries, and 771 INSERT_VALUES replaces existing entries with new values 772 773 Notes: 774 By default the values, v, are row-oriented and unsorted. 775 See MatSetOption() for other options. 776 777 Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 778 options cannot be mixed without intervening calls to the assembly 779 routines. 780 781 MatSetValues() uses 0-based row and column numbers in Fortran 782 as well as in C. 783 784 Negative indices may be passed in idxm and idxn, these rows and columns are 785 simply ignored. This allows easily inserting element stiffness matrices 786 with homogeneous Dirchlet boundary conditions that you don't want represented 787 in the matrix. 788 789 Efficiency Alert: 790 The routine MatSetValuesBlocked() may offer much better efficiency 791 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 792 793 Level: beginner 794 795 Concepts: matrices^putting entries in 796 797 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 798 InsertMode, INSERT_VALUES, ADD_VALUES 799 @*/ 800 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 801 { 802 PetscErrorCode ierr; 803 804 PetscFunctionBegin; 805 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 806 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 807 PetscValidType(mat,1); 808 PetscValidIntPointer(idxm,3); 809 PetscValidIntPointer(idxn,5); 810 PetscValidScalarPointer(v,6); 811 ierr = MatPreallocated(mat);CHKERRQ(ierr); 812 if (mat->insertmode == NOT_SET_VALUES) { 813 mat->insertmode = addv; 814 } 815 #if defined(PETSC_USE_DEBUG) 816 else if (mat->insertmode != addv) { 817 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 818 } 819 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 820 #endif 821 822 if (mat->assembled) { 823 mat->was_assembled = PETSC_TRUE; 824 mat->assembled = PETSC_FALSE; 825 } 826 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 827 if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 828 ierr = (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 829 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 830 PetscFunctionReturn(0); 831 } 832 833 834 #undef __FUNCT__ 835 #define __FUNCT__ "MatSetValuesRowLocal" 836 /*@ 837 MatSetValuesRowLocal - Inserts a row (block row for BAIJ matrices) of nonzero 838 values into a matrix 839 840 Not Collective 841 842 Input Parameters: 843 + mat - the matrix 844 . row - the (block) row to set 845 - v - a logically two-dimensional array of values 846 847 Notes: 848 By the values, v, are column-oriented (for the block version) and sorted 849 850 All the nonzeros in the row must be provided 851 852 The matrix must have previously had its column indices set 853 854 The row must belong to this process 855 856 Level: intermediate 857 858 Concepts: matrices^putting entries in 859 860 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 861 InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues(), MatSetValuesRow(), MatSetLocalToGlobalMapping() 862 @*/ 863 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRowLocal(Mat mat,PetscInt row,const PetscScalar v[]) 864 { 865 PetscErrorCode ierr; 866 867 PetscFunctionBegin; 868 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 869 PetscValidType(mat,1); 870 PetscValidScalarPointer(v,2); 871 ierr = MatSetValuesRow(mat, mat->mapping->indices[row],v);CHKERRQ(ierr); 872 PetscFunctionReturn(0); 873 } 874 875 #undef __FUNCT__ 876 #define __FUNCT__ "MatSetValuesRow" 877 /*@ 878 MatSetValuesRow - Inserts a row (block row for BAIJ matrices) of nonzero 879 values into a matrix 880 881 Not Collective 882 883 Input Parameters: 884 + mat - the matrix 885 . row - the (block) row to set 886 - v - a logically two-dimensional array of values 887 888 Notes: 889 By the values, v, are column-oriented (for the block version) and sorted 890 891 All the nonzeros in the row must be provided 892 893 The matrix must have previously had its column indices set 894 895 The row must belong to this process 896 897 Level: intermediate 898 899 Concepts: matrices^putting entries in 900 901 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 902 InsertMode, INSERT_VALUES, ADD_VALUES, MatSetValues() 903 @*/ 904 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesRow(Mat mat,PetscInt row,const PetscScalar v[]) 905 { 906 PetscErrorCode ierr; 907 908 PetscFunctionBegin; 909 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 910 PetscValidType(mat,1); 911 PetscValidScalarPointer(v,2); 912 #if defined(PETSC_USE_DEBUG) 913 if (mat->insertmode == ADD_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add and insert values"); 914 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 915 #endif 916 mat->insertmode = INSERT_VALUES; 917 918 if (mat->assembled) { 919 mat->was_assembled = PETSC_TRUE; 920 mat->assembled = PETSC_FALSE; 921 } 922 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 923 if (!mat->ops->setvaluesrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 924 ierr = (*mat->ops->setvaluesrow)(mat,row,v);CHKERRQ(ierr); 925 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 926 PetscFunctionReturn(0); 927 } 928 929 #undef __FUNCT__ 930 #define __FUNCT__ "MatSetValuesStencil" 931 /*@ 932 MatSetValuesStencil - Inserts or adds a block of values into a matrix. 933 Using structured grid indexing 934 935 Not Collective 936 937 Input Parameters: 938 + mat - the matrix 939 . v - a logically two-dimensional array of values 940 . m - number of rows being entered 941 . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered 942 . n - number of columns being entered 943 . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 944 - addv - either ADD_VALUES or INSERT_VALUES, where 945 ADD_VALUES adds values to any existing entries, and 946 INSERT_VALUES replaces existing entries with new values 947 948 Notes: 949 By default the values, v, are row-oriented and unsorted. 950 See MatSetOption() for other options. 951 952 Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 953 options cannot be mixed without intervening calls to the assembly 954 routines. 955 956 The grid coordinates are across the entire grid, not just the local portion 957 958 MatSetValuesStencil() uses 0-based row and column numbers in Fortran 959 as well as in C. 960 961 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 962 963 In order to use this routine you must either obtain the matrix with DAGetMatrix() 964 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 965 966 The columns and rows in the stencil passed in MUST be contained within the 967 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 968 if you create a DA with an overlap of one grid level and on a particular process its first 969 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 970 first i index you can use in your column and row indices in MatSetStencil() is 5. 971 972 In Fortran idxm and idxn should be declared as 973 $ MatStencil idxm(4,m),idxn(4,n) 974 and the values inserted using 975 $ idxm(MatStencil_i,1) = i 976 $ idxm(MatStencil_j,1) = j 977 $ idxm(MatStencil_k,1) = k 978 $ idxm(MatStencil_c,1) = c 979 etc 980 981 For periodic boundary conditions use negative indices for values to the left (below 0; that are to be 982 obtained by wrapping values from right edge). For values to the right of the last entry using that index plus one 983 etc to obtain values that obtained by wrapping the values from the left edge. 984 985 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 986 a single value per point) you can skip filling those indices. 987 988 Inspired by the structured grid interface to the HYPRE package 989 (http://www.llnl.gov/CASC/hypre) 990 991 Efficiency Alert: 992 The routine MatSetValuesBlockedStencil() may offer much better efficiency 993 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 994 995 Level: beginner 996 997 Concepts: matrices^putting entries in 998 999 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1000 MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 1001 @*/ 1002 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 1003 { 1004 PetscErrorCode ierr; 1005 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 1006 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 1007 1008 PetscFunctionBegin; 1009 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1010 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1011 PetscValidType(mat,1); 1012 PetscValidIntPointer(idxm,3); 1013 PetscValidIntPointer(idxn,5); 1014 PetscValidScalarPointer(v,6); 1015 1016 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 1017 if (n > 256) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 1018 1019 for (i=0; i<m; i++) { 1020 for (j=0; j<3-sdim; j++) dxm++; 1021 tmp = *dxm++ - starts[0]; 1022 for (j=0; j<dim-1; j++) { 1023 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1024 else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1]; 1025 } 1026 if (mat->stencil.noc) dxm++; 1027 jdxm[i] = tmp; 1028 } 1029 for (i=0; i<n; i++) { 1030 for (j=0; j<3-sdim; j++) dxn++; 1031 tmp = *dxn++ - starts[0]; 1032 for (j=0; j<dim-1; j++) { 1033 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1034 else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1]; 1035 } 1036 if (mat->stencil.noc) dxn++; 1037 jdxn[i] = tmp; 1038 } 1039 ierr = MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 1040 PetscFunctionReturn(0); 1041 } 1042 1043 #undef __FUNCT__ 1044 #define __FUNCT__ "MatSetValuesBlockedStencil" 1045 /*@C 1046 MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix. 1047 Using structured grid indexing 1048 1049 Not Collective 1050 1051 Input Parameters: 1052 + mat - the matrix 1053 . v - a logically two-dimensional array of values 1054 . m - number of rows being entered 1055 . idxm - grid coordinates for matrix rows being entered 1056 . n - number of columns being entered 1057 . idxn - grid coordinates for matrix columns being entered 1058 - addv - either ADD_VALUES or INSERT_VALUES, where 1059 ADD_VALUES adds values to any existing entries, and 1060 INSERT_VALUES replaces existing entries with new values 1061 1062 Notes: 1063 By default the values, v, are row-oriented and unsorted. 1064 See MatSetOption() for other options. 1065 1066 Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES 1067 options cannot be mixed without intervening calls to the assembly 1068 routines. 1069 1070 The grid coordinates are across the entire grid, not just the local portion 1071 1072 MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran 1073 as well as in C. 1074 1075 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 1076 1077 In order to use this routine you must either obtain the matrix with DAGetMatrix() 1078 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 1079 1080 The columns and rows in the stencil passed in MUST be contained within the 1081 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 1082 if you create a DA with an overlap of one grid level and on a particular process its first 1083 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 1084 first i index you can use in your column and row indices in MatSetStencil() is 5. 1085 1086 In Fortran idxm and idxn should be declared as 1087 $ MatStencil idxm(4,m),idxn(4,n) 1088 and the values inserted using 1089 $ idxm(MatStencil_i,1) = i 1090 $ idxm(MatStencil_j,1) = j 1091 $ idxm(MatStencil_k,1) = k 1092 etc 1093 1094 Negative indices may be passed in idxm and idxn, these rows and columns are 1095 simply ignored. This allows easily inserting element stiffness matrices 1096 with homogeneous Dirchlet boundary conditions that you don't want represented 1097 in the matrix. 1098 1099 Inspired by the structured grid interface to the HYPRE package 1100 (http://www.llnl.gov/CASC/hypre) 1101 1102 Level: beginner 1103 1104 Concepts: matrices^putting entries in 1105 1106 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1107 MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 1108 @*/ 1109 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 1110 { 1111 PetscErrorCode ierr; 1112 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 1113 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 1114 1115 PetscFunctionBegin; 1116 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1117 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1118 PetscValidType(mat,1); 1119 PetscValidIntPointer(idxm,3); 1120 PetscValidIntPointer(idxn,5); 1121 PetscValidScalarPointer(v,6); 1122 1123 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 1124 if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 1125 1126 for (i=0; i<m; i++) { 1127 for (j=0; j<3-sdim; j++) dxm++; 1128 tmp = *dxm++ - starts[0]; 1129 for (j=0; j<sdim-1; j++) { 1130 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1131 else tmp = tmp*dims[j] + *(dxm-1) - starts[j+1]; 1132 } 1133 dxm++; 1134 jdxm[i] = tmp; 1135 } 1136 for (i=0; i<n; i++) { 1137 for (j=0; j<3-sdim; j++) dxn++; 1138 tmp = *dxn++ - starts[0]; 1139 for (j=0; j<sdim-1; j++) { 1140 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 1141 else tmp = tmp*dims[j] + *(dxn-1) - starts[j+1]; 1142 } 1143 dxn++; 1144 jdxn[i] = tmp; 1145 } 1146 ierr = MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 1147 PetscFunctionReturn(0); 1148 } 1149 1150 #undef __FUNCT__ 1151 #define __FUNCT__ "MatSetStencil" 1152 /*@ 1153 MatSetStencil - Sets the grid information for setting values into a matrix via 1154 MatSetValuesStencil() 1155 1156 Not Collective 1157 1158 Input Parameters: 1159 + mat - the matrix 1160 . dim - dimension of the grid 1, 2, or 3 1161 . dims - number of grid points in x, y, and z direction, including ghost points on your processor 1162 . starts - starting point of ghost nodes on your processor in x, y, and z direction 1163 - dof - number of degrees of freedom per node 1164 1165 1166 Inspired by the structured grid interface to the HYPRE package 1167 (www.llnl.gov/CASC/hyper) 1168 1169 For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the 1170 user. 1171 1172 Level: beginner 1173 1174 Concepts: matrices^putting entries in 1175 1176 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 1177 MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil() 1178 @*/ 1179 PetscErrorCode PETSCMAT_DLLEXPORT MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof) 1180 { 1181 PetscInt i; 1182 1183 PetscFunctionBegin; 1184 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1185 PetscValidIntPointer(dims,3); 1186 PetscValidIntPointer(starts,4); 1187 1188 mat->stencil.dim = dim + (dof > 1); 1189 for (i=0; i<dim; i++) { 1190 mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */ 1191 mat->stencil.starts[i] = starts[dim-i-1]; 1192 } 1193 mat->stencil.dims[dim] = dof; 1194 mat->stencil.starts[dim] = 0; 1195 mat->stencil.noc = (PetscTruth)(dof == 1); 1196 PetscFunctionReturn(0); 1197 } 1198 1199 #undef __FUNCT__ 1200 #define __FUNCT__ "MatSetValuesBlocked" 1201 /*@ 1202 MatSetValuesBlocked - Inserts or adds a block of values into a matrix. 1203 1204 Not Collective 1205 1206 Input Parameters: 1207 + mat - the matrix 1208 . v - a logically two-dimensional array of values 1209 . m, idxm - the number of block rows and their global block indices 1210 . n, idxn - the number of block columns and their global block indices 1211 - addv - either ADD_VALUES or INSERT_VALUES, where 1212 ADD_VALUES adds values to any existing entries, and 1213 INSERT_VALUES replaces existing entries with new values 1214 1215 Notes: 1216 The m and n count the NUMBER of blocks in the row direction and column direction, 1217 NOT the total number of rows/columns; for example, if the block size is 2 and 1218 you are passing in values for rows 2,3,4,5 then m would be 2 (not 4). 1219 1220 By default the values, v, are row-oriented and unsorted. So the layout of 1221 v is the same as for MatSetValues(). See MatSetOption() for other options. 1222 1223 Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 1224 options cannot be mixed without intervening calls to the assembly 1225 routines. 1226 1227 MatSetValuesBlocked() uses 0-based row and column numbers in Fortran 1228 as well as in C. 1229 1230 Negative indices may be passed in idxm and idxn, these rows and columns are 1231 simply ignored. This allows easily inserting element stiffness matrices 1232 with homogeneous Dirchlet boundary conditions that you don't want represented 1233 in the matrix. 1234 1235 Each time an entry is set within a sparse matrix via MatSetValues(), 1236 internal searching must be done to determine where to place the the 1237 data in the matrix storage space. By instead inserting blocks of 1238 entries via MatSetValuesBlocked(), the overhead of matrix assembly is 1239 reduced. 1240 1241 Restrictions: 1242 MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats 1243 1244 Level: intermediate 1245 1246 Concepts: matrices^putting entries in blocked 1247 1248 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal() 1249 @*/ 1250 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 1251 { 1252 PetscErrorCode ierr; 1253 1254 PetscFunctionBegin; 1255 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 1256 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1257 PetscValidType(mat,1); 1258 PetscValidIntPointer(idxm,3); 1259 PetscValidIntPointer(idxn,5); 1260 PetscValidScalarPointer(v,6); 1261 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1262 if (mat->insertmode == NOT_SET_VALUES) { 1263 mat->insertmode = addv; 1264 } 1265 #if defined(PETSC_USE_DEBUG) 1266 else if (mat->insertmode != addv) { 1267 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1268 } 1269 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1270 #endif 1271 1272 if (mat->assembled) { 1273 mat->was_assembled = PETSC_TRUE; 1274 mat->assembled = PETSC_FALSE; 1275 } 1276 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1277 if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1278 ierr = (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 1279 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1280 PetscFunctionReturn(0); 1281 } 1282 1283 #undef __FUNCT__ 1284 #define __FUNCT__ "MatGetValues" 1285 /*@ 1286 MatGetValues - Gets a block of values from a matrix. 1287 1288 Not Collective; currently only returns a local block 1289 1290 Input Parameters: 1291 + mat - the matrix 1292 . v - a logically two-dimensional array for storing the values 1293 . m, idxm - the number of rows and their global indices 1294 - n, idxn - the number of columns and their global indices 1295 1296 Notes: 1297 The user must allocate space (m*n PetscScalars) for the values, v. 1298 The values, v, are then returned in a row-oriented format, 1299 analogous to that used by default in MatSetValues(). 1300 1301 MatGetValues() uses 0-based row and column numbers in 1302 Fortran as well as in C. 1303 1304 MatGetValues() requires that the matrix has been assembled 1305 with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to 1306 MatSetValues() and MatGetValues() CANNOT be made in succession 1307 without intermediate matrix assembly. 1308 1309 Level: advanced 1310 1311 Concepts: matrices^accessing values 1312 1313 .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues() 1314 @*/ 1315 PetscErrorCode PETSCMAT_DLLEXPORT MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[]) 1316 { 1317 PetscErrorCode ierr; 1318 1319 PetscFunctionBegin; 1320 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1321 PetscValidType(mat,1); 1322 PetscValidIntPointer(idxm,3); 1323 PetscValidIntPointer(idxn,5); 1324 PetscValidScalarPointer(v,6); 1325 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1326 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1327 if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1328 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1329 1330 ierr = PetscLogEventBegin(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 1331 ierr = (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);CHKERRQ(ierr); 1332 ierr = PetscLogEventEnd(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 1333 PetscFunctionReturn(0); 1334 } 1335 1336 #undef __FUNCT__ 1337 #define __FUNCT__ "MatSetLocalToGlobalMapping" 1338 /*@ 1339 MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by 1340 the routine MatSetValuesLocal() to allow users to insert matrix entries 1341 using a local (per-processor) numbering. 1342 1343 Not Collective 1344 1345 Input Parameters: 1346 + x - the matrix 1347 - mapping - mapping created with ISLocalToGlobalMappingCreate() 1348 or ISLocalToGlobalMappingCreateIS() 1349 1350 Level: intermediate 1351 1352 Concepts: matrices^local to global mapping 1353 Concepts: local to global mapping^for matrices 1354 1355 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal() 1356 @*/ 1357 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping) 1358 { 1359 PetscErrorCode ierr; 1360 PetscFunctionBegin; 1361 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1362 PetscValidType(x,1); 1363 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1364 if (x->mapping) { 1365 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1366 } 1367 ierr = MatPreallocated(x);CHKERRQ(ierr); 1368 1369 if (x->ops->setlocaltoglobalmapping) { 1370 ierr = (*x->ops->setlocaltoglobalmapping)(x,mapping);CHKERRQ(ierr); 1371 } else { 1372 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1373 if (x->mapping) { ierr = ISLocalToGlobalMappingDestroy(x->mapping);CHKERRQ(ierr); } 1374 x->mapping = mapping; 1375 } 1376 PetscFunctionReturn(0); 1377 } 1378 1379 #undef __FUNCT__ 1380 #define __FUNCT__ "MatSetLocalToGlobalMappingBlock" 1381 /*@ 1382 MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use 1383 by the routine MatSetValuesBlockedLocal() to allow users to insert matrix 1384 entries using a local (per-processor) numbering. 1385 1386 Not Collective 1387 1388 Input Parameters: 1389 + x - the matrix 1390 - mapping - mapping created with ISLocalToGlobalMappingCreate() or 1391 ISLocalToGlobalMappingCreateIS() 1392 1393 Level: intermediate 1394 1395 Concepts: matrices^local to global mapping blocked 1396 Concepts: local to global mapping^for matrices, blocked 1397 1398 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(), 1399 MatSetValuesBlocked(), MatSetValuesLocal() 1400 @*/ 1401 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping) 1402 { 1403 PetscErrorCode ierr; 1404 PetscFunctionBegin; 1405 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1406 PetscValidType(x,1); 1407 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1408 if (x->bmapping) { 1409 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1410 } 1411 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1412 if (x->bmapping) { ierr = ISLocalToGlobalMappingDestroy(x->mapping);CHKERRQ(ierr); } 1413 x->bmapping = mapping; 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->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 1609 if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N); 1610 if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n); 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->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N); 1669 if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N); 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->cmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->cmap.N,v1->map.N); 1719 if (mat->rmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->rmap.N,v2->map.N); 1720 if (mat->rmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->rmap.N,v3->map.N); 1721 if (mat->rmap.n != v3->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->rmap.n,v3->map.n); 1722 if (mat->rmap.n != v2->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->rmap.n,v2->map.n); 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->rmap.N != v1->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->rmap.N,v1->map.N); 1773 if (mat->cmap.N != v2->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->cmap.N,v2->map.N); 1774 if (mat->cmap.N != v3->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->cmap.N,v3->map.N); 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->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 1820 if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N); 1821 if (mat->rmap.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->rmap.n,y->map.n); 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->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 1867 if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N); 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->rmap.N != mat->cmap.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->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) { 2210 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N); 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->rmap.N != mat->cmap.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->rmap.N != mat->cmap.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 PetscValidHeaderSpecific(*fact,MAT_COOKIE,2); 2369 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2370 if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2371 if (mat->rmap.N != (*fact)->rmap.N || mat->cmap.N != (*fact)->cmap.N) { 2372 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->rmap.N,(*fact)->rmap.N,mat->cmap.N,(*fact)->cmap.N); 2373 } 2374 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2375 2376 ierr = PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2377 ierr = (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);CHKERRQ(ierr); 2378 ierr = PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2379 2380 ierr = MatView_Private(*fact);CHKERRQ(ierr); 2381 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2382 PetscFunctionReturn(0); 2383 } 2384 2385 /* ----------------------------------------------------------------*/ 2386 #undef __FUNCT__ 2387 #define __FUNCT__ "MatSolve" 2388 /*@ 2389 MatSolve - Solves A x = b, given a factored matrix. 2390 2391 Collective on Mat and Vec 2392 2393 Input Parameters: 2394 + mat - the factored matrix 2395 - b - the right-hand-side vector 2396 2397 Output Parameter: 2398 . x - the result vector 2399 2400 Notes: 2401 The vectors b and x cannot be the same. I.e., one cannot 2402 call MatSolve(A,x,x). 2403 2404 Notes: 2405 Most users should employ the simplified KSP interface for linear solvers 2406 instead of working directly with matrix algebra routines such as this. 2407 See, e.g., KSPCreate(). 2408 2409 Level: developer 2410 2411 Concepts: matrices^triangular solves 2412 2413 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd() 2414 @*/ 2415 PetscErrorCode PETSCMAT_DLLEXPORT MatSolve(Mat mat,Vec b,Vec x) 2416 { 2417 PetscErrorCode ierr; 2418 2419 PetscFunctionBegin; 2420 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2421 PetscValidType(mat,1); 2422 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2423 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2424 PetscCheckSameComm(mat,1,b,2); 2425 PetscCheckSameComm(mat,1,x,3); 2426 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2427 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2428 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2429 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2430 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2431 if (!mat->rmap.N && !mat->cmap.N) PetscFunctionReturn(0); 2432 if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2433 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2434 2435 ierr = PetscLogEventBegin(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2436 ierr = (*mat->ops->solve)(mat,b,x);CHKERRQ(ierr); 2437 ierr = PetscLogEventEnd(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2438 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2439 PetscFunctionReturn(0); 2440 } 2441 2442 #undef __FUNCT__ 2443 #define __FUNCT__ "MatMatSolve" 2444 /*@ 2445 MatMatSolve - Solves A X = B, given a factored matrix. 2446 2447 Collective on Mat 2448 2449 Input Parameters: 2450 + mat - the factored matrix 2451 - b - the right-hand-side vector 2452 2453 Output Parameter: 2454 . x - the result vector 2455 2456 Notes: 2457 The vectors b and x cannot be the same. I.e., one cannot 2458 call MatMatSolve(A,x,x). 2459 2460 Notes: 2461 Most users should employ the simplified KSP interface for linear solvers 2462 instead of working directly with matrix algebra routines such as this. 2463 See, e.g., KSPCreate(). 2464 2465 Level: developer 2466 2467 Concepts: matrices^triangular solves 2468 2469 .seealso: MatMatSolveAdd(), MatMatSolveTranspose(), MatMatSolveTransposeAdd() 2470 @*/ 2471 PetscErrorCode PETSCMAT_DLLEXPORT MatMatSolve(Mat A,Mat B,Mat X) 2472 { 2473 PetscErrorCode ierr; 2474 2475 PetscFunctionBegin; 2476 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 2477 PetscValidType(A,1); 2478 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 2479 PetscValidHeaderSpecific(X,MAT_COOKIE,3); 2480 PetscCheckSameComm(A,1,B,2); 2481 PetscCheckSameComm(A,1,X,3); 2482 if (X == B) SETERRQ(PETSC_ERR_ARG_IDN,"X and B must be different matrices"); 2483 if (!A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2484 if (A->cmap.N != X->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat X: global dim %D %D",A->cmap.N,X->rmap.N); 2485 if (A->rmap.N != B->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D",A->rmap.N,B->rmap.N); 2486 if (A->rmap.n != B->rmap.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: local dim %D %D",A->rmap.n,B->rmap.n); 2487 if (!A->rmap.N && !A->cmap.N) PetscFunctionReturn(0); 2488 if (!A->ops->matsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name); 2489 ierr = MatPreallocated(A);CHKERRQ(ierr); 2490 2491 ierr = PetscLogEventBegin(MAT_MatSolve,A,B,X,0);CHKERRQ(ierr); 2492 ierr = (*A->ops->matsolve)(A,B,X);CHKERRQ(ierr); 2493 ierr = PetscLogEventEnd(MAT_MatSolve,A,B,X,0);CHKERRQ(ierr); 2494 ierr = PetscObjectStateIncrease((PetscObject)X);CHKERRQ(ierr); 2495 PetscFunctionReturn(0); 2496 } 2497 2498 2499 #undef __FUNCT__ 2500 #define __FUNCT__ "MatForwardSolve" 2501 /* @ 2502 MatForwardSolve - Solves L x = b, given a factored matrix, A = LU, or 2503 U^T*D^(1/2) x = b, given a factored symmetric matrix, A = U^T*D*U, 2504 2505 Collective on Mat and Vec 2506 2507 Input Parameters: 2508 + mat - the factored matrix 2509 - b - the right-hand-side vector 2510 2511 Output Parameter: 2512 . x - the result vector 2513 2514 Notes: 2515 MatSolve() should be used for most applications, as it performs 2516 a forward solve followed by a backward solve. 2517 2518 The vectors b and x cannot be the same, i.e., one cannot 2519 call MatForwardSolve(A,x,x). 2520 2521 For matrix in seqsbaij format with block size larger than 1, 2522 the diagonal blocks are not implemented as D = D^(1/2) * D^(1/2) yet. 2523 MatForwardSolve() solves U^T*D y = b, and 2524 MatBackwardSolve() solves U x = y. 2525 Thus they do not provide a symmetric preconditioner. 2526 2527 Most users should employ the simplified KSP interface for linear solvers 2528 instead of working directly with matrix algebra routines such as this. 2529 See, e.g., KSPCreate(). 2530 2531 Level: developer 2532 2533 Concepts: matrices^forward solves 2534 2535 .seealso: MatSolve(), MatBackwardSolve() 2536 @ */ 2537 PetscErrorCode PETSCMAT_DLLEXPORT MatForwardSolve(Mat mat,Vec b,Vec x) 2538 { 2539 PetscErrorCode ierr; 2540 2541 PetscFunctionBegin; 2542 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2543 PetscValidType(mat,1); 2544 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2545 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2546 PetscCheckSameComm(mat,1,b,2); 2547 PetscCheckSameComm(mat,1,x,3); 2548 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2549 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2550 if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2551 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2552 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2553 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2554 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2555 ierr = PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2556 ierr = (*mat->ops->forwardsolve)(mat,b,x);CHKERRQ(ierr); 2557 ierr = PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2558 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2559 PetscFunctionReturn(0); 2560 } 2561 2562 #undef __FUNCT__ 2563 #define __FUNCT__ "MatBackwardSolve" 2564 /* @ 2565 MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU. 2566 D^(1/2) U x = b, given a factored symmetric matrix, A = U^T*D*U, 2567 2568 Collective on Mat and Vec 2569 2570 Input Parameters: 2571 + mat - the factored matrix 2572 - b - the right-hand-side vector 2573 2574 Output Parameter: 2575 . x - the result vector 2576 2577 Notes: 2578 MatSolve() should be used for most applications, as it performs 2579 a forward solve followed by a backward solve. 2580 2581 The vectors b and x cannot be the same. I.e., one cannot 2582 call MatBackwardSolve(A,x,x). 2583 2584 For matrix in seqsbaij format with block size larger than 1, 2585 the diagonal blocks are not implemented as D = D^(1/2) * D^(1/2) yet. 2586 MatForwardSolve() solves U^T*D y = b, and 2587 MatBackwardSolve() solves U x = y. 2588 Thus they do not provide a symmetric preconditioner. 2589 2590 Most users should employ the simplified KSP interface for linear solvers 2591 instead of working directly with matrix algebra routines such as this. 2592 See, e.g., KSPCreate(). 2593 2594 Level: developer 2595 2596 Concepts: matrices^backward solves 2597 2598 .seealso: MatSolve(), MatForwardSolve() 2599 @ */ 2600 PetscErrorCode PETSCMAT_DLLEXPORT MatBackwardSolve(Mat mat,Vec b,Vec x) 2601 { 2602 PetscErrorCode ierr; 2603 2604 PetscFunctionBegin; 2605 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2606 PetscValidType(mat,1); 2607 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2608 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2609 PetscCheckSameComm(mat,1,b,2); 2610 PetscCheckSameComm(mat,1,x,3); 2611 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2612 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2613 if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2614 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2615 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2616 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2617 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2618 2619 ierr = PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2620 ierr = (*mat->ops->backwardsolve)(mat,b,x);CHKERRQ(ierr); 2621 ierr = PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2622 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2623 PetscFunctionReturn(0); 2624 } 2625 2626 #undef __FUNCT__ 2627 #define __FUNCT__ "MatSolveAdd" 2628 /*@ 2629 MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix. 2630 2631 Collective on Mat and Vec 2632 2633 Input Parameters: 2634 + mat - the factored matrix 2635 . b - the right-hand-side vector 2636 - y - the vector to be added to 2637 2638 Output Parameter: 2639 . x - the result vector 2640 2641 Notes: 2642 The vectors b and x cannot be the same. I.e., one cannot 2643 call MatSolveAdd(A,x,y,x). 2644 2645 Most users should employ the simplified KSP interface for linear solvers 2646 instead of working directly with matrix algebra routines such as this. 2647 See, e.g., KSPCreate(). 2648 2649 Level: developer 2650 2651 Concepts: matrices^triangular solves 2652 2653 .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd() 2654 @*/ 2655 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveAdd(Mat mat,Vec b,Vec y,Vec x) 2656 { 2657 PetscScalar one = 1.0; 2658 Vec tmp; 2659 PetscErrorCode ierr; 2660 2661 PetscFunctionBegin; 2662 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2663 PetscValidType(mat,1); 2664 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2665 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2666 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2667 PetscCheckSameComm(mat,1,b,2); 2668 PetscCheckSameComm(mat,1,y,2); 2669 PetscCheckSameComm(mat,1,x,3); 2670 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2671 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2672 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2673 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2674 if (mat->rmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->rmap.N,y->map.N); 2675 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2676 if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n); 2677 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2678 2679 ierr = PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2680 if (mat->ops->solveadd) { 2681 ierr = (*mat->ops->solveadd)(mat,b,y,x);CHKERRQ(ierr); 2682 } else { 2683 /* do the solve then the add manually */ 2684 if (x != y) { 2685 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2686 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2687 } else { 2688 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2689 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2690 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2691 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2692 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2693 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2694 } 2695 } 2696 ierr = PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2697 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2698 PetscFunctionReturn(0); 2699 } 2700 2701 #undef __FUNCT__ 2702 #define __FUNCT__ "MatSolveTranspose" 2703 /*@ 2704 MatSolveTranspose - Solves A' x = b, given a factored matrix. 2705 2706 Collective on Mat and Vec 2707 2708 Input Parameters: 2709 + mat - the factored matrix 2710 - b - the right-hand-side vector 2711 2712 Output Parameter: 2713 . x - the result vector 2714 2715 Notes: 2716 The vectors b and x cannot be the same. I.e., one cannot 2717 call MatSolveTranspose(A,x,x). 2718 2719 Most users should employ the simplified KSP interface for linear solvers 2720 instead of working directly with matrix algebra routines such as this. 2721 See, e.g., KSPCreate(). 2722 2723 Level: developer 2724 2725 Concepts: matrices^triangular solves 2726 2727 .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd() 2728 @*/ 2729 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTranspose(Mat mat,Vec b,Vec x) 2730 { 2731 PetscErrorCode ierr; 2732 2733 PetscFunctionBegin; 2734 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2735 PetscValidType(mat,1); 2736 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2737 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2738 PetscCheckSameComm(mat,1,b,2); 2739 PetscCheckSameComm(mat,1,x,3); 2740 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2741 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2742 if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name); 2743 if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N); 2744 if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N); 2745 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2746 ierr = PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2747 ierr = (*mat->ops->solvetranspose)(mat,b,x);CHKERRQ(ierr); 2748 ierr = PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2749 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2750 PetscFunctionReturn(0); 2751 } 2752 2753 #undef __FUNCT__ 2754 #define __FUNCT__ "MatSolveTransposeAdd" 2755 /*@ 2756 MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 2757 factored matrix. 2758 2759 Collective on Mat and Vec 2760 2761 Input Parameters: 2762 + mat - the factored matrix 2763 . b - the right-hand-side vector 2764 - y - the vector to be added to 2765 2766 Output Parameter: 2767 . x - the result vector 2768 2769 Notes: 2770 The vectors b and x cannot be the same. I.e., one cannot 2771 call MatSolveTransposeAdd(A,x,y,x). 2772 2773 Most users should employ the simplified KSP interface for linear solvers 2774 instead of working directly with matrix algebra routines such as this. 2775 See, e.g., KSPCreate(). 2776 2777 Level: developer 2778 2779 Concepts: matrices^triangular solves 2780 2781 .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose() 2782 @*/ 2783 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x) 2784 { 2785 PetscScalar one = 1.0; 2786 PetscErrorCode ierr; 2787 Vec tmp; 2788 2789 PetscFunctionBegin; 2790 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2791 PetscValidType(mat,1); 2792 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2793 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2794 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2795 PetscCheckSameComm(mat,1,b,2); 2796 PetscCheckSameComm(mat,1,y,3); 2797 PetscCheckSameComm(mat,1,x,4); 2798 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2799 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2800 if (mat->rmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->rmap.N,x->map.N); 2801 if (mat->cmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->cmap.N,b->map.N); 2802 if (mat->cmap.N != y->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->cmap.N,y->map.N); 2803 if (x->map.n != y->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->map.n,y->map.n); 2804 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2805 2806 ierr = PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2807 if (mat->ops->solvetransposeadd) { 2808 ierr = (*mat->ops->solvetransposeadd)(mat,b,y,x);CHKERRQ(ierr); 2809 } else { 2810 /* do the solve then the add manually */ 2811 if (x != y) { 2812 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2813 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2814 } else { 2815 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2816 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2817 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2818 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2819 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2820 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2821 } 2822 } 2823 ierr = PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2824 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2825 PetscFunctionReturn(0); 2826 } 2827 /* ----------------------------------------------------------------*/ 2828 2829 #undef __FUNCT__ 2830 #define __FUNCT__ "MatRelax" 2831 /*@ 2832 MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2833 2834 Collective on Mat and Vec 2835 2836 Input Parameters: 2837 + mat - the matrix 2838 . b - the right hand side 2839 . omega - the relaxation factor 2840 . flag - flag indicating the type of SOR (see below) 2841 . shift - diagonal shift 2842 - its - the number of iterations 2843 - lits - the number of local iterations 2844 2845 Output Parameters: 2846 . x - the solution (can contain an initial guess) 2847 2848 SOR Flags: 2849 . SOR_FORWARD_SWEEP - forward SOR 2850 . SOR_BACKWARD_SWEEP - backward SOR 2851 . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR) 2852 . SOR_LOCAL_FORWARD_SWEEP - local forward SOR 2853 . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 2854 . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR 2855 . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 2856 upper/lower triangular part of matrix to 2857 vector (with omega) 2858 . SOR_ZERO_INITIAL_GUESS - zero initial guess 2859 2860 Notes: 2861 SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and 2862 SOR_LOCAL_SYMMETRIC_SWEEP perform separate independent smoothings 2863 on each processor. 2864 2865 Application programmers will not generally use MatRelax() directly, 2866 but instead will employ the KSP/PC interface. 2867 2868 Notes for Advanced Users: 2869 The flags are implemented as bitwise inclusive or operations. 2870 For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP) 2871 to specify a zero initial guess for SSOR. 2872 2873 Most users should employ the simplified KSP interface for linear solvers 2874 instead of working directly with matrix algebra routines such as this. 2875 See, e.g., KSPCreate(). 2876 2877 See also, MatPBRelax(). This routine will automatically call the point block 2878 version if the point version is not available. 2879 2880 Level: developer 2881 2882 Concepts: matrices^relaxation 2883 Concepts: matrices^SOR 2884 Concepts: matrices^Gauss-Seidel 2885 2886 @*/ 2887 PetscErrorCode PETSCMAT_DLLEXPORT MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2888 { 2889 PetscErrorCode ierr; 2890 2891 PetscFunctionBegin; 2892 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2893 PetscValidType(mat,1); 2894 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2895 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2896 PetscCheckSameComm(mat,1,b,2); 2897 PetscCheckSameComm(mat,1,x,8); 2898 if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2899 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2900 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2901 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2902 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2903 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2904 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2905 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2906 if (mat->ops->relax) { 2907 ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2908 } else { 2909 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2910 } 2911 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2912 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2913 PetscFunctionReturn(0); 2914 } 2915 2916 #undef __FUNCT__ 2917 #define __FUNCT__ "MatPBRelax" 2918 /*@ 2919 MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2920 2921 Collective on Mat and Vec 2922 2923 See MatRelax() for usage 2924 2925 For multi-component PDEs where the Jacobian is stored in a point block format 2926 (with the PETSc BAIJ matrix formats) the relaxation is done one point block at 2927 a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved 2928 simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point. 2929 2930 Level: developer 2931 2932 @*/ 2933 PetscErrorCode PETSCMAT_DLLEXPORT MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2934 { 2935 PetscErrorCode ierr; 2936 2937 PetscFunctionBegin; 2938 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2939 PetscValidType(mat,1); 2940 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2941 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2942 PetscCheckSameComm(mat,1,b,2); 2943 PetscCheckSameComm(mat,1,x,8); 2944 if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2945 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2946 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2947 if (mat->cmap.N != x->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->cmap.N,x->map.N); 2948 if (mat->rmap.N != b->map.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->rmap.N,b->map.N); 2949 if (mat->rmap.n != b->map.n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->rmap.n,b->map.n); 2950 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2951 2952 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2953 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2954 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2955 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2956 PetscFunctionReturn(0); 2957 } 2958 2959 #undef __FUNCT__ 2960 #define __FUNCT__ "MatCopy_Basic" 2961 /* 2962 Default matrix copy routine. 2963 */ 2964 PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str) 2965 { 2966 PetscErrorCode ierr; 2967 PetscInt i,rstart,rend,nz; 2968 const PetscInt *cwork; 2969 const PetscScalar *vwork; 2970 2971 PetscFunctionBegin; 2972 if (B->assembled) { 2973 ierr = MatZeroEntries(B);CHKERRQ(ierr); 2974 } 2975 ierr = MatGetOwnershipRange(A,&rstart,&rend);CHKERRQ(ierr); 2976 for (i=rstart; i<rend; i++) { 2977 ierr = MatGetRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2978 ierr = MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);CHKERRQ(ierr); 2979 ierr = MatRestoreRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2980 } 2981 ierr = MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2982 ierr = MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2983 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2984 PetscFunctionReturn(0); 2985 } 2986 2987 #undef __FUNCT__ 2988 #define __FUNCT__ "MatCopy" 2989 /*@ 2990 MatCopy - Copys a matrix to another matrix. 2991 2992 Collective on Mat 2993 2994 Input Parameters: 2995 + A - the matrix 2996 - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN 2997 2998 Output Parameter: 2999 . B - where the copy is put 3000 3001 Notes: 3002 If you use SAME_NONZERO_PATTERN then the two matrices had better have the 3003 same nonzero pattern or the routine will crash. 3004 3005 MatCopy() copies the matrix entries of a matrix to another existing 3006 matrix (after first zeroing the second matrix). A related routine is 3007 MatConvert(), which first creates a new matrix and then copies the data. 3008 3009 Level: intermediate 3010 3011 Concepts: matrices^copying 3012 3013 .seealso: MatConvert(), MatDuplicate() 3014 3015 @*/ 3016 PetscErrorCode PETSCMAT_DLLEXPORT MatCopy(Mat A,Mat B,MatStructure str) 3017 { 3018 PetscErrorCode ierr; 3019 3020 PetscFunctionBegin; 3021 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3022 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3023 PetscValidType(A,1); 3024 PetscValidType(B,2); 3025 MatPreallocated(B); 3026 PetscCheckSameComm(A,1,B,2); 3027 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3028 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3029 if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N); 3030 ierr = MatPreallocated(A);CHKERRQ(ierr); 3031 3032 ierr = PetscLogEventBegin(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 3033 if (A->ops->copy) { 3034 ierr = (*A->ops->copy)(A,B,str);CHKERRQ(ierr); 3035 } else { /* generic conversion */ 3036 ierr = MatCopy_Basic(A,B,str);CHKERRQ(ierr); 3037 } 3038 if (A->mapping) { 3039 if (B->mapping) {ierr = ISLocalToGlobalMappingDestroy(B->mapping);CHKERRQ(ierr);B->mapping = 0;} 3040 ierr = MatSetLocalToGlobalMapping(B,A->mapping);CHKERRQ(ierr); 3041 } 3042 if (A->bmapping) { 3043 if (B->bmapping) {ierr = ISLocalToGlobalMappingDestroy(B->bmapping);CHKERRQ(ierr);B->bmapping = 0;} 3044 ierr = MatSetLocalToGlobalMappingBlock(B,A->mapping);CHKERRQ(ierr); 3045 } 3046 ierr = PetscLogEventEnd(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 3047 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3048 PetscFunctionReturn(0); 3049 } 3050 3051 #undef __FUNCT__ 3052 #define __FUNCT__ "MatConvert" 3053 /*@C 3054 MatConvert - Converts a matrix to another matrix, either of the same 3055 or different type. 3056 3057 Collective on Mat 3058 3059 Input Parameters: 3060 + mat - the matrix 3061 . newtype - new matrix type. Use MATSAME to create a new matrix of the 3062 same type as the original matrix. 3063 - reuse - denotes if the destination matrix is to be created or reused. Currently 3064 MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use 3065 MAT_INITIAL_MATRIX. 3066 Output Parameter: 3067 . M - pointer to place new matrix 3068 3069 Notes: 3070 MatConvert() first creates a new matrix and then copies the data from 3071 the first matrix. A related routine is MatCopy(), which copies the matrix 3072 entries of one matrix to another already existing matrix context. 3073 3074 Level: intermediate 3075 3076 Concepts: matrices^converting between storage formats 3077 3078 .seealso: MatCopy(), MatDuplicate() 3079 @*/ 3080 PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat, MatType newtype,MatReuse reuse,Mat *M) 3081 { 3082 PetscErrorCode ierr; 3083 PetscTruth sametype,issame,flg; 3084 char convname[256],mtype[256]; 3085 Mat B; 3086 3087 PetscFunctionBegin; 3088 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3089 PetscValidType(mat,1); 3090 PetscValidPointer(M,3); 3091 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3092 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3093 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3094 3095 ierr = PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);CHKERRQ(ierr); 3096 if (flg) { 3097 newtype = mtype; 3098 } 3099 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3100 3101 ierr = PetscTypeCompare((PetscObject)mat,newtype,&sametype);CHKERRQ(ierr); 3102 ierr = PetscStrcmp(newtype,"same",&issame);CHKERRQ(ierr); 3103 if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) { 3104 SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for in-place conversion currently"); 3105 } 3106 if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) { 3107 ierr = (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);CHKERRQ(ierr); 3108 } else { 3109 PetscErrorCode (*conv)(Mat, MatType,MatReuse,Mat*)=PETSC_NULL; 3110 const char *prefix[3] = {"seq","mpi",""}; 3111 PetscInt i; 3112 3113 /* 3114 Order of precedence: 3115 1) See if a specialized converter is known to the current matrix. 3116 2) See if a specialized converter is known to the desired matrix class. 3117 3) See if a good general converter is registered for the desired class 3118 (as of 6/27/03 only MATMPIADJ falls into this category). 3119 4) See if a good general converter is known for the current matrix. 3120 5) Use a really basic converter. 3121 */ 3122 for (i=0; i<3; i++) { 3123 /* 1) See if a specialized converter is known to the current matrix and the desired class */ 3124 ierr = PetscStrcpy(convname,"MatConvert_");CHKERRQ(ierr); 3125 ierr = PetscStrcat(convname,mat->type_name);CHKERRQ(ierr); 3126 ierr = PetscStrcat(convname,"_");CHKERRQ(ierr); 3127 ierr = PetscStrcat(convname,prefix[i]);CHKERRQ(ierr); 3128 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 3129 ierr = PetscStrcat(convname,"_C");CHKERRQ(ierr); 3130 ierr = PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);CHKERRQ(ierr); 3131 if (conv) goto foundconv; 3132 } 3133 3134 /* 2) See if a specialized converter is known to the desired matrix class. */ 3135 ierr = MatCreate(mat->comm,&B);CHKERRQ(ierr); 3136 ierr = MatSetSizes(B,mat->rmap.n,mat->cmap.n,mat->rmap.N,mat->cmap.N);CHKERRQ(ierr); 3137 ierr = MatSetType(B,newtype);CHKERRQ(ierr); 3138 for (i=0; i<3; i++) { 3139 ierr = PetscStrcpy(convname,"MatConvert_");CHKERRQ(ierr); 3140 ierr = PetscStrcat(convname,mat->type_name);CHKERRQ(ierr); 3141 ierr = PetscStrcat(convname,"_");CHKERRQ(ierr); 3142 ierr = PetscStrcat(convname,prefix[i]);CHKERRQ(ierr); 3143 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 3144 ierr = PetscStrcat(convname,"_C");CHKERRQ(ierr); 3145 ierr = PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);CHKERRQ(ierr); 3146 if (conv) { 3147 ierr = MatDestroy(B);CHKERRQ(ierr); 3148 goto foundconv; 3149 } 3150 } 3151 3152 /* 3) See if a good general converter is registered for the desired class */ 3153 conv = B->ops->convertfrom; 3154 ierr = MatDestroy(B);CHKERRQ(ierr); 3155 if (conv) goto foundconv; 3156 3157 /* 4) See if a good general converter is known for the current matrix */ 3158 if (mat->ops->convert) { 3159 conv = mat->ops->convert; 3160 } 3161 if (conv) goto foundconv; 3162 3163 /* 5) Use a really basic converter. */ 3164 conv = MatConvert_Basic; 3165 3166 foundconv: 3167 ierr = (*conv)(mat,newtype,reuse,M);CHKERRQ(ierr); 3168 } 3169 B = *M; 3170 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3171 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3172 PetscFunctionReturn(0); 3173 } 3174 3175 3176 #undef __FUNCT__ 3177 #define __FUNCT__ "MatDuplicate" 3178 /*@ 3179 MatDuplicate - Duplicates a matrix including the non-zero structure. 3180 3181 Collective on Mat 3182 3183 Input Parameters: 3184 + mat - the matrix 3185 - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero 3186 values as well or not 3187 3188 Output Parameter: 3189 . M - pointer to place new matrix 3190 3191 Level: intermediate 3192 3193 Concepts: matrices^duplicating 3194 3195 .seealso: MatCopy(), MatConvert() 3196 @*/ 3197 PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M) 3198 { 3199 PetscErrorCode ierr; 3200 Mat B; 3201 3202 PetscFunctionBegin; 3203 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3204 PetscValidType(mat,1); 3205 PetscValidPointer(M,3); 3206 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3207 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3208 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3209 3210 *M = 0; 3211 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3212 if (!mat->ops->duplicate) { 3213 SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type"); 3214 } 3215 ierr = (*mat->ops->duplicate)(mat,op,M);CHKERRQ(ierr); 3216 B = *M; 3217 if (mat->mapping) { 3218 ierr = MatSetLocalToGlobalMapping(B,mat->mapping);CHKERRQ(ierr); 3219 } 3220 if (mat->bmapping) { 3221 ierr = MatSetLocalToGlobalMappingBlock(B,mat->bmapping);CHKERRQ(ierr); 3222 } 3223 ierr = PetscMapCopy(mat->comm,&mat->rmap,&B->rmap);CHKERRQ(ierr); 3224 ierr = PetscMapCopy(mat->comm,&mat->cmap,&B->cmap);CHKERRQ(ierr); 3225 3226 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 3227 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 3228 PetscFunctionReturn(0); 3229 } 3230 3231 #undef __FUNCT__ 3232 #define __FUNCT__ "MatGetDiagonal" 3233 /*@ 3234 MatGetDiagonal - Gets the diagonal of a matrix. 3235 3236 Collective on Mat and Vec 3237 3238 Input Parameters: 3239 + mat - the matrix 3240 - v - the vector for storing the diagonal 3241 3242 Output Parameter: 3243 . v - the diagonal of the matrix 3244 3245 Notes: 3246 For the SeqAIJ matrix format, this routine may also be called 3247 on a LU factored matrix; in that case it routines the reciprocal of 3248 the diagonal entries in U. It returns the entries permuted by the 3249 row and column permutation used during the symbolic factorization. 3250 3251 Level: intermediate 3252 3253 Concepts: matrices^accessing diagonals 3254 3255 .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax() 3256 @*/ 3257 PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v) 3258 { 3259 PetscErrorCode ierr; 3260 3261 PetscFunctionBegin; 3262 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3263 PetscValidType(mat,1); 3264 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 3265 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3266 if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3267 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3268 3269 ierr = (*mat->ops->getdiagonal)(mat,v);CHKERRQ(ierr); 3270 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 3271 PetscFunctionReturn(0); 3272 } 3273 3274 #undef __FUNCT__ 3275 #define __FUNCT__ "MatGetRowMax" 3276 /*@ 3277 MatGetRowMax - Gets the maximum value (in absolute value) of each 3278 row of the matrix 3279 3280 Collective on Mat and Vec 3281 3282 Input Parameters: 3283 . mat - the matrix 3284 3285 Output Parameter: 3286 . v - the vector for storing the maximums 3287 3288 Level: intermediate 3289 3290 Concepts: matrices^getting row maximums 3291 3292 .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix() 3293 @*/ 3294 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v) 3295 { 3296 PetscErrorCode ierr; 3297 3298 PetscFunctionBegin; 3299 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3300 PetscValidType(mat,1); 3301 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 3302 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3303 if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3304 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3305 3306 ierr = (*mat->ops->getrowmax)(mat,v);CHKERRQ(ierr); 3307 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 3308 PetscFunctionReturn(0); 3309 } 3310 3311 #undef __FUNCT__ 3312 #define __FUNCT__ "MatTranspose" 3313 /*@C 3314 MatTranspose - Computes an in-place or out-of-place transpose of a matrix. 3315 3316 Collective on Mat 3317 3318 Input Parameter: 3319 . mat - the matrix to transpose 3320 3321 Output Parameters: 3322 . B - the transpose 3323 3324 Notes: 3325 If you pass in PETSC_NULL for B an in-place transpose in mat will be done 3326 3327 Level: intermediate 3328 3329 Concepts: matrices^transposing 3330 3331 .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose() 3332 @*/ 3333 PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B) 3334 { 3335 PetscErrorCode ierr; 3336 3337 PetscFunctionBegin; 3338 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3339 PetscValidType(mat,1); 3340 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3341 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3342 if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3343 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3344 3345 ierr = PetscLogEventBegin(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 3346 ierr = (*mat->ops->transpose)(mat,B);CHKERRQ(ierr); 3347 ierr = PetscLogEventEnd(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 3348 if (B) {ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr);} 3349 PetscFunctionReturn(0); 3350 } 3351 3352 #undef __FUNCT__ 3353 #define __FUNCT__ "MatIsTranspose" 3354 /*@C 3355 MatIsTranspose - Test whether a matrix is another one's transpose, 3356 or its own, in which case it tests symmetry. 3357 3358 Collective on Mat 3359 3360 Input Parameter: 3361 + A - the matrix to test 3362 - B - the matrix to test against, this can equal the first parameter 3363 3364 Output Parameters: 3365 . flg - the result 3366 3367 Notes: 3368 Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm 3369 has a running time of the order of the number of nonzeros; the parallel 3370 test involves parallel copies of the block-offdiagonal parts of the matrix. 3371 3372 Level: intermediate 3373 3374 Concepts: matrices^transposing, matrix^symmetry 3375 3376 .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian() 3377 @*/ 3378 PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg) 3379 { 3380 PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*); 3381 3382 PetscFunctionBegin; 3383 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3384 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3385 PetscValidPointer(flg,3); 3386 ierr = PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);CHKERRQ(ierr); 3387 ierr = PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);CHKERRQ(ierr); 3388 if (f && g) { 3389 if (f==g) { 3390 ierr = (*f)(A,B,tol,flg);CHKERRQ(ierr); 3391 } else { 3392 SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test"); 3393 } 3394 } 3395 PetscFunctionReturn(0); 3396 } 3397 3398 #undef __FUNCT__ 3399 #define __FUNCT__ "MatPermute" 3400 /*@C 3401 MatPermute - Creates a new matrix with rows and columns permuted from the 3402 original. 3403 3404 Collective on Mat 3405 3406 Input Parameters: 3407 + mat - the matrix to permute 3408 . row - row permutation, each processor supplies only the permutation for its rows 3409 - col - column permutation, each processor needs the entire column permutation, that is 3410 this is the same size as the total number of columns in the matrix 3411 3412 Output Parameters: 3413 . B - the permuted matrix 3414 3415 Level: advanced 3416 3417 Concepts: matrices^permuting 3418 3419 .seealso: MatGetOrdering() 3420 @*/ 3421 PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B) 3422 { 3423 PetscErrorCode ierr; 3424 3425 PetscFunctionBegin; 3426 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3427 PetscValidType(mat,1); 3428 PetscValidHeaderSpecific(row,IS_COOKIE,2); 3429 PetscValidHeaderSpecific(col,IS_COOKIE,3); 3430 PetscValidPointer(B,4); 3431 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3432 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3433 if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"MatPermute not available for Mat type %s",mat->type_name); 3434 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3435 3436 ierr = (*mat->ops->permute)(mat,row,col,B);CHKERRQ(ierr); 3437 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3438 PetscFunctionReturn(0); 3439 } 3440 3441 #undef __FUNCT__ 3442 #define __FUNCT__ "MatPermuteSparsify" 3443 /*@C 3444 MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the 3445 original and sparsified to the prescribed tolerance. 3446 3447 Collective on Mat 3448 3449 Input Parameters: 3450 + A - The matrix to permute 3451 . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE 3452 . frac - The half-bandwidth as a fraction of the total size, or 0.0 3453 . tol - The drop tolerance 3454 . rowp - The row permutation 3455 - colp - The column permutation 3456 3457 Output Parameter: 3458 . B - The permuted, sparsified matrix 3459 3460 Level: advanced 3461 3462 Note: 3463 The default behavior (band = PETSC_DECIDE and frac = 0.0) is to 3464 restrict the half-bandwidth of the resulting matrix to 5% of the 3465 total matrix size. 3466 3467 .keywords: matrix, permute, sparsify 3468 3469 .seealso: MatGetOrdering(), MatPermute() 3470 @*/ 3471 PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B) 3472 { 3473 IS irowp, icolp; 3474 PetscInt *rows, *cols; 3475 PetscInt M, N, locRowStart, locRowEnd; 3476 PetscInt nz, newNz; 3477 const PetscInt *cwork; 3478 PetscInt *cnew; 3479 const PetscScalar *vwork; 3480 PetscScalar *vnew; 3481 PetscInt bw, issize; 3482 PetscInt row, locRow, newRow, col, newCol; 3483 PetscErrorCode ierr; 3484 3485 PetscFunctionBegin; 3486 PetscValidHeaderSpecific(A, MAT_COOKIE,1); 3487 PetscValidHeaderSpecific(rowp, IS_COOKIE,5); 3488 PetscValidHeaderSpecific(colp, IS_COOKIE,6); 3489 PetscValidPointer(B,7); 3490 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix"); 3491 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix"); 3492 if (!A->ops->permutesparsify) { 3493 ierr = MatGetSize(A, &M, &N);CHKERRQ(ierr); 3494 ierr = MatGetOwnershipRange(A, &locRowStart, &locRowEnd);CHKERRQ(ierr); 3495 ierr = ISGetSize(rowp, &issize);CHKERRQ(ierr); 3496 if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M); 3497 ierr = ISGetSize(colp, &issize);CHKERRQ(ierr); 3498 if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N); 3499 ierr = ISInvertPermutation(rowp, 0, &irowp);CHKERRQ(ierr); 3500 ierr = ISGetIndices(irowp, &rows);CHKERRQ(ierr); 3501 ierr = ISInvertPermutation(colp, 0, &icolp);CHKERRQ(ierr); 3502 ierr = ISGetIndices(icolp, &cols);CHKERRQ(ierr); 3503 ierr = PetscMalloc(N * sizeof(PetscInt), &cnew);CHKERRQ(ierr); 3504 ierr = PetscMalloc(N * sizeof(PetscScalar), &vnew);CHKERRQ(ierr); 3505 3506 /* Setup bandwidth to include */ 3507 if (band == PETSC_DECIDE) { 3508 if (frac <= 0.0) 3509 bw = (PetscInt) (M * 0.05); 3510 else 3511 bw = (PetscInt) (M * frac); 3512 } else { 3513 if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer"); 3514 bw = band; 3515 } 3516 3517 /* Put values into new matrix */ 3518 ierr = MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);CHKERRQ(ierr); 3519 for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) { 3520 ierr = MatGetRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3521 newRow = rows[locRow]+locRowStart; 3522 for(col = 0, newNz = 0; col < nz; col++) { 3523 newCol = cols[cwork[col]]; 3524 if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) { 3525 cnew[newNz] = newCol; 3526 vnew[newNz] = vwork[col]; 3527 newNz++; 3528 } 3529 } 3530 ierr = MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);CHKERRQ(ierr); 3531 ierr = MatRestoreRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3532 } 3533 ierr = PetscFree(cnew);CHKERRQ(ierr); 3534 ierr = PetscFree(vnew);CHKERRQ(ierr); 3535 ierr = MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3536 ierr = MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3537 ierr = ISRestoreIndices(irowp, &rows);CHKERRQ(ierr); 3538 ierr = ISRestoreIndices(icolp, &cols);CHKERRQ(ierr); 3539 ierr = ISDestroy(irowp);CHKERRQ(ierr); 3540 ierr = ISDestroy(icolp);CHKERRQ(ierr); 3541 } else { 3542 ierr = (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);CHKERRQ(ierr); 3543 } 3544 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3545 PetscFunctionReturn(0); 3546 } 3547 3548 #undef __FUNCT__ 3549 #define __FUNCT__ "MatEqual" 3550 /*@ 3551 MatEqual - Compares two matrices. 3552 3553 Collective on Mat 3554 3555 Input Parameters: 3556 + A - the first matrix 3557 - B - the second matrix 3558 3559 Output Parameter: 3560 . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise. 3561 3562 Level: intermediate 3563 3564 Concepts: matrices^equality between 3565 @*/ 3566 PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg) 3567 { 3568 PetscErrorCode ierr; 3569 3570 PetscFunctionBegin; 3571 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3572 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3573 PetscValidType(A,1); 3574 PetscValidType(B,2); 3575 MatPreallocated(B); 3576 PetscValidIntPointer(flg,3); 3577 PetscCheckSameComm(A,1,B,2); 3578 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3579 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3580 if (A->rmap.N != B->rmap.N || A->cmap.N != B->cmap.N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->rmap.N,B->rmap.N,A->cmap.N,B->cmap.N); 3581 if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name); 3582 if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name); 3583 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); 3584 ierr = MatPreallocated(A);CHKERRQ(ierr); 3585 3586 ierr = (*A->ops->equal)(A,B,flg);CHKERRQ(ierr); 3587 PetscFunctionReturn(0); 3588 } 3589 3590 #undef __FUNCT__ 3591 #define __FUNCT__ "MatDiagonalScale" 3592 /*@ 3593 MatDiagonalScale - Scales a matrix on the left and right by diagonal 3594 matrices that are stored as vectors. Either of the two scaling 3595 matrices can be PETSC_NULL. 3596 3597 Collective on Mat 3598 3599 Input Parameters: 3600 + mat - the matrix to be scaled 3601 . l - the left scaling vector (or PETSC_NULL) 3602 - r - the right scaling vector (or PETSC_NULL) 3603 3604 Notes: 3605 MatDiagonalScale() computes A = LAR, where 3606 L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector) 3607 3608 Level: intermediate 3609 3610 Concepts: matrices^diagonal scaling 3611 Concepts: diagonal scaling of matrices 3612 3613 .seealso: MatScale() 3614 @*/ 3615 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r) 3616 { 3617 PetscErrorCode ierr; 3618 3619 PetscFunctionBegin; 3620 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3621 PetscValidType(mat,1); 3622 if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3623 if (l) {PetscValidHeaderSpecific(l,VEC_COOKIE,2);PetscCheckSameComm(mat,1,l,2);} 3624 if (r) {PetscValidHeaderSpecific(r,VEC_COOKIE,3);PetscCheckSameComm(mat,1,r,3);} 3625 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3626 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3627 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3628 3629 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3630 ierr = (*mat->ops->diagonalscale)(mat,l,r);CHKERRQ(ierr); 3631 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3632 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3633 PetscFunctionReturn(0); 3634 } 3635 3636 #undef __FUNCT__ 3637 #define __FUNCT__ "MatScale" 3638 /*@ 3639 MatScale - Scales all elements of a matrix by a given number. 3640 3641 Collective on Mat 3642 3643 Input Parameters: 3644 + mat - the matrix to be scaled 3645 - a - the scaling value 3646 3647 Output Parameter: 3648 . mat - the scaled matrix 3649 3650 Level: intermediate 3651 3652 Concepts: matrices^scaling all entries 3653 3654 .seealso: MatDiagonalScale() 3655 @*/ 3656 PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a) 3657 { 3658 PetscErrorCode ierr; 3659 3660 PetscFunctionBegin; 3661 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3662 PetscValidType(mat,1); 3663 if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3664 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3665 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3666 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3667 3668 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3669 ierr = (*mat->ops->scale)(mat,a);CHKERRQ(ierr); 3670 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3671 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3672 PetscFunctionReturn(0); 3673 } 3674 3675 #undef __FUNCT__ 3676 #define __FUNCT__ "MatNorm" 3677 /*@ 3678 MatNorm - Calculates various norms of a matrix. 3679 3680 Collective on Mat 3681 3682 Input Parameters: 3683 + mat - the matrix 3684 - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY 3685 3686 Output Parameters: 3687 . nrm - the resulting norm 3688 3689 Level: intermediate 3690 3691 Concepts: matrices^norm 3692 Concepts: norm^of matrix 3693 @*/ 3694 PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm) 3695 { 3696 PetscErrorCode ierr; 3697 3698 PetscFunctionBegin; 3699 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3700 PetscValidType(mat,1); 3701 PetscValidScalarPointer(nrm,3); 3702 3703 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3704 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3705 if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3706 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3707 3708 ierr = (*mat->ops->norm)(mat,type,nrm);CHKERRQ(ierr); 3709 PetscFunctionReturn(0); 3710 } 3711 3712 /* 3713 This variable is used to prevent counting of MatAssemblyBegin() that 3714 are called from within a MatAssemblyEnd(). 3715 */ 3716 static PetscInt MatAssemblyEnd_InUse = 0; 3717 #undef __FUNCT__ 3718 #define __FUNCT__ "MatAssemblyBegin" 3719 /*@ 3720 MatAssemblyBegin - Begins assembling the matrix. This routine should 3721 be called after completing all calls to MatSetValues(). 3722 3723 Collective on Mat 3724 3725 Input Parameters: 3726 + mat - the matrix 3727 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3728 3729 Notes: 3730 MatSetValues() generally caches the values. The matrix is ready to 3731 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3732 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3733 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3734 using the matrix. 3735 3736 Level: beginner 3737 3738 Concepts: matrices^assembling 3739 3740 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled() 3741 @*/ 3742 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type) 3743 { 3744 PetscErrorCode ierr; 3745 3746 PetscFunctionBegin; 3747 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3748 PetscValidType(mat,1); 3749 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3750 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?"); 3751 if (mat->assembled) { 3752 mat->was_assembled = PETSC_TRUE; 3753 mat->assembled = PETSC_FALSE; 3754 } 3755 if (!MatAssemblyEnd_InUse) { 3756 ierr = PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3757 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3758 ierr = PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3759 } else { 3760 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3761 } 3762 PetscFunctionReturn(0); 3763 } 3764 3765 #undef __FUNCT__ 3766 #define __FUNCT__ "MatAssembed" 3767 /*@ 3768 MatAssembled - Indicates if a matrix has been assembled and is ready for 3769 use; for example, in matrix-vector product. 3770 3771 Collective on Mat 3772 3773 Input Parameter: 3774 . mat - the matrix 3775 3776 Output Parameter: 3777 . assembled - PETSC_TRUE or PETSC_FALSE 3778 3779 Level: advanced 3780 3781 Concepts: matrices^assembled? 3782 3783 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin() 3784 @*/ 3785 PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled) 3786 { 3787 PetscFunctionBegin; 3788 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3789 PetscValidType(mat,1); 3790 PetscValidPointer(assembled,2); 3791 *assembled = mat->assembled; 3792 PetscFunctionReturn(0); 3793 } 3794 3795 #undef __FUNCT__ 3796 #define __FUNCT__ "MatView_Private" 3797 /* 3798 Processes command line options to determine if/how a matrix 3799 is to be viewed. Called by MatAssemblyEnd() and MatLoad(). 3800 */ 3801 PetscErrorCode MatView_Private(Mat mat) 3802 { 3803 PetscErrorCode ierr; 3804 PetscTruth flg1,flg2,flg3,flg4,flg6,flg7,flg8; 3805 static PetscTruth incall = PETSC_FALSE; 3806 #if defined(PETSC_USE_SOCKET_VIEWER) 3807 PetscTruth flg5; 3808 #endif 3809 3810 PetscFunctionBegin; 3811 if (incall) PetscFunctionReturn(0); 3812 incall = PETSC_TRUE; 3813 ierr = PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");CHKERRQ(ierr); 3814 ierr = PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg1);CHKERRQ(ierr); 3815 ierr = PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg2);CHKERRQ(ierr); 3816 ierr = PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg3);CHKERRQ(ierr); 3817 ierr = PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg4);CHKERRQ(ierr); 3818 #if defined(PETSC_USE_SOCKET_VIEWER) 3819 ierr = PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg5);CHKERRQ(ierr); 3820 #endif 3821 ierr = PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg6);CHKERRQ(ierr); 3822 ierr = PetscOptionsName("-mat_view_draw","Draw the matrix nonzero structure","MatView",&flg7);CHKERRQ(ierr); 3823 ierr = PetscOptionsEnd();CHKERRQ(ierr); 3824 3825 if (flg1) { 3826 PetscViewer viewer; 3827 3828 ierr = PetscViewerASCIIGetStdout(mat->comm,&viewer);CHKERRQ(ierr); 3829 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);CHKERRQ(ierr); 3830 ierr = MatView(mat,viewer);CHKERRQ(ierr); 3831 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 3832 } 3833 if (flg2) { 3834 PetscViewer viewer; 3835 3836 ierr = PetscViewerASCIIGetStdout(mat->comm,&viewer);CHKERRQ(ierr); 3837 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO_DETAIL);CHKERRQ(ierr); 3838 ierr = MatView(mat,viewer);CHKERRQ(ierr); 3839 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 3840 } 3841 if (flg3) { 3842 PetscViewer viewer; 3843 3844 ierr = PetscViewerASCIIGetStdout(mat->comm,&viewer);CHKERRQ(ierr); 3845 ierr = MatView(mat,viewer);CHKERRQ(ierr); 3846 } 3847 if (flg4) { 3848 PetscViewer viewer; 3849 3850 ierr = PetscViewerASCIIGetStdout(mat->comm,&viewer);CHKERRQ(ierr); 3851 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);CHKERRQ(ierr); 3852 ierr = MatView(mat,viewer);CHKERRQ(ierr); 3853 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 3854 } 3855 #if defined(PETSC_USE_SOCKET_VIEWER) 3856 if (flg5) { 3857 ierr = MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3858 ierr = PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3859 } 3860 #endif 3861 if (flg6) { 3862 ierr = MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3863 ierr = PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3864 } 3865 if (flg7) { 3866 ierr = PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg8);CHKERRQ(ierr); 3867 if (flg8) { 3868 PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);CHKERRQ(ierr); 3869 } 3870 ierr = MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3871 ierr = PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3872 if (flg8) { 3873 PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3874 } 3875 } 3876 incall = PETSC_FALSE; 3877 PetscFunctionReturn(0); 3878 } 3879 3880 #undef __FUNCT__ 3881 #define __FUNCT__ "MatAssemblyEnd" 3882 /*@ 3883 MatAssemblyEnd - Completes assembling the matrix. This routine should 3884 be called after MatAssemblyBegin(). 3885 3886 Collective on Mat 3887 3888 Input Parameters: 3889 + mat - the matrix 3890 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3891 3892 Options Database Keys: 3893 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 3894 . -mat_view_info_detailed - Prints more detailed info 3895 . -mat_view - Prints matrix in ASCII format 3896 . -mat_view_matlab - Prints matrix in Matlab format 3897 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 3898 . -display <name> - Sets display name (default is host) 3899 . -draw_pause <sec> - Sets number of seconds to pause after display 3900 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 3901 . -viewer_socket_machine <machine> 3902 . -viewer_socket_port <port> 3903 . -mat_view_binary - save matrix to file in binary format 3904 - -viewer_binary_filename <name> 3905 3906 Notes: 3907 MatSetValues() generally caches the values. The matrix is ready to 3908 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3909 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3910 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3911 using the matrix. 3912 3913 Level: beginner 3914 3915 .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen() 3916 @*/ 3917 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type) 3918 { 3919 PetscErrorCode ierr; 3920 static PetscInt inassm = 0; 3921 PetscTruth flg; 3922 3923 PetscFunctionBegin; 3924 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3925 PetscValidType(mat,1); 3926 3927 inassm++; 3928 MatAssemblyEnd_InUse++; 3929 if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */ 3930 ierr = PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3931 if (mat->ops->assemblyend) { 3932 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3933 } 3934 ierr = PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3935 } else { 3936 if (mat->ops->assemblyend) { 3937 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3938 } 3939 } 3940 3941 /* Flush assembly is not a true assembly */ 3942 if (type != MAT_FLUSH_ASSEMBLY) { 3943 mat->assembled = PETSC_TRUE; mat->num_ass++; 3944 } 3945 mat->insertmode = NOT_SET_VALUES; 3946 MatAssemblyEnd_InUse--; 3947 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3948 if (!mat->symmetric_eternal) { 3949 mat->symmetric_set = PETSC_FALSE; 3950 mat->hermitian_set = PETSC_FALSE; 3951 mat->structurally_symmetric_set = PETSC_FALSE; 3952 } 3953 if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) { 3954 ierr = MatView_Private(mat);CHKERRQ(ierr); 3955 ierr = PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);CHKERRQ(ierr); 3956 if (flg) { 3957 PetscReal tol = 0.0; 3958 ierr = PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);CHKERRQ(ierr); 3959 ierr = MatIsSymmetric(mat,tol,&flg);CHKERRQ(ierr); 3960 if (flg) { 3961 ierr = PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 3962 } else { 3963 ierr = PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 3964 } 3965 } 3966 } 3967 inassm--; 3968 PetscFunctionReturn(0); 3969 } 3970 3971 3972 #undef __FUNCT__ 3973 #define __FUNCT__ "MatCompress" 3974 /*@ 3975 MatCompress - Tries to store the matrix in as little space as 3976 possible. May fail if memory is already fully used, since it 3977 tries to allocate new space. 3978 3979 Collective on Mat 3980 3981 Input Parameters: 3982 . mat - the matrix 3983 3984 Level: advanced 3985 3986 @*/ 3987 PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat) 3988 { 3989 PetscErrorCode ierr; 3990 3991 PetscFunctionBegin; 3992 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3993 PetscValidType(mat,1); 3994 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3995 if (mat->ops->compress) {ierr = (*mat->ops->compress)(mat);CHKERRQ(ierr);} 3996 PetscFunctionReturn(0); 3997 } 3998 3999 #undef __FUNCT__ 4000 #define __FUNCT__ "MatSetOption" 4001 /*@ 4002 MatSetOption - Sets a parameter option for a matrix. Some options 4003 may be specific to certain storage formats. Some options 4004 determine how values will be inserted (or added). Sorted, 4005 row-oriented input will generally assemble the fastest. The default 4006 is row-oriented, nonsorted input. 4007 4008 Collective on Mat 4009 4010 Input Parameters: 4011 + mat - the matrix 4012 - option - the option, one of those listed below (and possibly others), 4013 e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR 4014 4015 Options Describing Matrix Structure: 4016 + MAT_SYMMETRIC - symmetric in terms of both structure and value 4017 . MAT_HERMITIAN - transpose is the complex conjugation 4018 . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 4019 . MAT_NOT_SYMMETRIC - not symmetric in value 4020 . MAT_NOT_HERMITIAN - transpose is not the complex conjugation 4021 . MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure 4022 . MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag 4023 you set to be kept with all future use of the matrix 4024 including after MatAssemblyBegin/End() which could 4025 potentially change the symmetry structure, i.e. you 4026 KNOW the matrix will ALWAYS have the property you set. 4027 - MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 4028 flags you set will be dropped (in case potentially 4029 the symmetry etc was lost). 4030 4031 Options For Use with MatSetValues(): 4032 Insert a logically dense subblock, which can be 4033 + MAT_ROW_ORIENTED - row-oriented (default) 4034 . MAT_COLUMN_ORIENTED - column-oriented 4035 . MAT_ROWS_SORTED - sorted by row 4036 . MAT_ROWS_UNSORTED - not sorted by row (default) 4037 . MAT_COLUMNS_SORTED - sorted by column 4038 - MAT_COLUMNS_UNSORTED - not sorted by column (default) 4039 4040 Not these options reflect the data you pass in with MatSetValues(); it has 4041 nothing to do with how the data is stored internally in the matrix 4042 data structure. 4043 4044 When (re)assembling a matrix, we can restrict the input for 4045 efficiency/debugging purposes. These options include 4046 + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be 4047 allowed if they generate a new nonzero 4048 . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed 4049 . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if 4050 they generate a nonzero in a new diagonal (for block diagonal format only) 4051 . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 4052 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 4053 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 4054 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 4055 4056 Notes: 4057 Some options are relevant only for particular matrix types and 4058 are thus ignored by others. Other options are not supported by 4059 certain matrix types and will generate an error message if set. 4060 4061 If using a Fortran 77 module to compute a matrix, one may need to 4062 use the column-oriented option (or convert to the row-oriented 4063 format). 4064 4065 MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 4066 that would generate a new entry in the nonzero structure is instead 4067 ignored. Thus, if memory has not alredy been allocated for this particular 4068 data, then the insertion is ignored. For dense matrices, in which 4069 the entire array is allocated, no entries are ever ignored. 4070 Set after the first MatAssemblyEnd() 4071 4072 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 4073 that would generate a new entry in the nonzero structure instead produces 4074 an error. (Currently supported for AIJ and BAIJ formats only.) 4075 This is a useful flag when using SAME_NONZERO_PATTERN in calling 4076 KSPSetOperators() to ensure that the nonzero pattern truely does 4077 remain unchanged. Set after the first MatAssemblyEnd() 4078 4079 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 4080 that would generate a new entry that has not been preallocated will 4081 instead produce an error. (Currently supported for AIJ and BAIJ formats 4082 only.) This is a useful flag when debugging matrix memory preallocation. 4083 4084 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 4085 other processors should be dropped, rather than stashed. 4086 This is useful if you know that the "owning" processor is also 4087 always generating the correct matrix entries, so that PETSc need 4088 not transfer duplicate entries generated on another processor. 4089 4090 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 4091 searches during matrix assembly. When this flag is set, the hash table 4092 is created during the first Matrix Assembly. This hash table is 4093 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 4094 to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 4095 should be used with MAT_USE_HASH_TABLE flag. This option is currently 4096 supported by MATMPIBAIJ format only. 4097 4098 MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries 4099 are kept in the nonzero structure 4100 4101 MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating 4102 a zero location in the matrix 4103 4104 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 4105 ROWBS matrix types 4106 4107 MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works 4108 with AIJ and ROWBS matrix types (database option "-mat_no_inode") 4109 4110 Level: intermediate 4111 4112 Concepts: matrices^setting options 4113 4114 @*/ 4115 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op) 4116 { 4117 PetscErrorCode ierr; 4118 4119 PetscFunctionBegin; 4120 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4121 PetscValidType(mat,1); 4122 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4123 switch (op) { 4124 case MAT_SYMMETRIC: 4125 mat->symmetric = PETSC_TRUE; 4126 mat->structurally_symmetric = PETSC_TRUE; 4127 mat->symmetric_set = PETSC_TRUE; 4128 mat->structurally_symmetric_set = PETSC_TRUE; 4129 break; 4130 case MAT_HERMITIAN: 4131 mat->hermitian = PETSC_TRUE; 4132 mat->structurally_symmetric = PETSC_TRUE; 4133 mat->hermitian_set = PETSC_TRUE; 4134 mat->structurally_symmetric_set = PETSC_TRUE; 4135 break; 4136 case MAT_STRUCTURALLY_SYMMETRIC: 4137 mat->structurally_symmetric = PETSC_TRUE; 4138 mat->structurally_symmetric_set = PETSC_TRUE; 4139 break; 4140 case MAT_NOT_SYMMETRIC: 4141 mat->symmetric = PETSC_FALSE; 4142 mat->symmetric_set = PETSC_TRUE; 4143 break; 4144 case MAT_NOT_HERMITIAN: 4145 mat->hermitian = PETSC_FALSE; 4146 mat->hermitian_set = PETSC_TRUE; 4147 break; 4148 case MAT_NOT_STRUCTURALLY_SYMMETRIC: 4149 mat->structurally_symmetric = PETSC_FALSE; 4150 mat->structurally_symmetric_set = PETSC_TRUE; 4151 break; 4152 case MAT_SYMMETRY_ETERNAL: 4153 mat->symmetric_eternal = PETSC_TRUE; 4154 break; 4155 case MAT_NOT_SYMMETRY_ETERNAL: 4156 mat->symmetric_eternal = PETSC_FALSE; 4157 break; 4158 default: 4159 break; 4160 } 4161 if (mat->ops->setoption) { 4162 ierr = (*mat->ops->setoption)(mat,op);CHKERRQ(ierr); 4163 } 4164 PetscFunctionReturn(0); 4165 } 4166 4167 #undef __FUNCT__ 4168 #define __FUNCT__ "MatZeroEntries" 4169 /*@ 4170 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 4171 this routine retains the old nonzero structure. 4172 4173 Collective on Mat 4174 4175 Input Parameters: 4176 . mat - the matrix 4177 4178 Level: intermediate 4179 4180 Concepts: matrices^zeroing 4181 4182 .seealso: MatZeroRows() 4183 @*/ 4184 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat) 4185 { 4186 PetscErrorCode ierr; 4187 4188 PetscFunctionBegin; 4189 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4190 PetscValidType(mat,1); 4191 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4192 if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled"); 4193 if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4194 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4195 4196 ierr = PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4197 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 4198 ierr = PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4199 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4200 PetscFunctionReturn(0); 4201 } 4202 4203 #undef __FUNCT__ 4204 #define __FUNCT__ "MatZeroRows" 4205 /*@C 4206 MatZeroRows - Zeros all entries (except possibly the main diagonal) 4207 of a set of rows of a matrix. 4208 4209 Collective on Mat 4210 4211 Input Parameters: 4212 + mat - the matrix 4213 . numRows - the number of rows to remove 4214 . rows - the global row indices 4215 - diag - value put in all diagonals of eliminated rows 4216 4217 Notes: 4218 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 4219 but does not release memory. For the dense and block diagonal 4220 formats this does not alter the nonzero structure. 4221 4222 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4223 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4224 merely zeroed. 4225 4226 The user can set a value in the diagonal entry (or for the AIJ and 4227 row formats can optionally remove the main diagonal entry from the 4228 nonzero structure as well, by passing 0.0 as the final argument). 4229 4230 For the parallel case, all processes that share the matrix (i.e., 4231 those in the communicator used for matrix creation) MUST call this 4232 routine, regardless of whether any rows being zeroed are owned by 4233 them. 4234 4235 Each processor should list the rows that IT wants zeroed 4236 4237 Level: intermediate 4238 4239 Concepts: matrices^zeroing rows 4240 4241 .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 4242 @*/ 4243 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 4244 { 4245 PetscErrorCode ierr; 4246 4247 PetscFunctionBegin; 4248 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4249 PetscValidType(mat,1); 4250 if (numRows) PetscValidIntPointer(rows,3); 4251 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4252 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4253 if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4254 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4255 4256 ierr = (*mat->ops->zerorows)(mat,numRows,rows,diag);CHKERRQ(ierr); 4257 ierr = MatView_Private(mat);CHKERRQ(ierr); 4258 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4259 PetscFunctionReturn(0); 4260 } 4261 4262 #undef __FUNCT__ 4263 #define __FUNCT__ "MatZeroRowsIS" 4264 /*@C 4265 MatZeroRowsIS - Zeros all entries (except possibly the main diagonal) 4266 of a set of rows of a matrix. 4267 4268 Collective on Mat 4269 4270 Input Parameters: 4271 + mat - the matrix 4272 . is - index set of rows to remove 4273 - diag - value put in all diagonals of eliminated rows 4274 4275 Notes: 4276 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 4277 but does not release memory. For the dense and block diagonal 4278 formats this does not alter the nonzero structure. 4279 4280 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4281 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4282 merely zeroed. 4283 4284 The user can set a value in the diagonal entry (or for the AIJ and 4285 row formats can optionally remove the main diagonal entry from the 4286 nonzero structure as well, by passing 0.0 as the final argument). 4287 4288 For the parallel case, all processes that share the matrix (i.e., 4289 those in the communicator used for matrix creation) MUST call this 4290 routine, regardless of whether any rows being zeroed are owned by 4291 them. 4292 4293 Each processor should list the rows that IT wants zeroed 4294 4295 Level: intermediate 4296 4297 Concepts: matrices^zeroing rows 4298 4299 .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 4300 @*/ 4301 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag) 4302 { 4303 PetscInt numRows; 4304 PetscInt *rows; 4305 PetscErrorCode ierr; 4306 4307 PetscFunctionBegin; 4308 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4309 PetscValidType(mat,1); 4310 PetscValidHeaderSpecific(is,IS_COOKIE,2); 4311 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 4312 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 4313 ierr = MatZeroRows(mat,numRows,rows,diag);CHKERRQ(ierr); 4314 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 4315 PetscFunctionReturn(0); 4316 } 4317 4318 #undef __FUNCT__ 4319 #define __FUNCT__ "MatZeroRowsLocal" 4320 /*@C 4321 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 4322 of a set of rows of a matrix; using local numbering of rows. 4323 4324 Collective on Mat 4325 4326 Input Parameters: 4327 + mat - the matrix 4328 . numRows - the number of rows to remove 4329 . rows - the global row indices 4330 - diag - value put in all diagonals of eliminated rows 4331 4332 Notes: 4333 Before calling MatZeroRowsLocal(), the user must first set the 4334 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 4335 4336 For the AIJ matrix formats this removes the old nonzero structure, 4337 but does not release memory. For the dense and block diagonal 4338 formats this does not alter the nonzero structure. 4339 4340 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4341 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4342 merely zeroed. 4343 4344 The user can set a value in the diagonal entry (or for the AIJ and 4345 row formats can optionally remove the main diagonal entry from the 4346 nonzero structure as well, by passing 0.0 as the final argument). 4347 4348 Level: intermediate 4349 4350 Concepts: matrices^zeroing 4351 4352 .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 4353 @*/ 4354 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 4355 { 4356 PetscErrorCode ierr; 4357 4358 PetscFunctionBegin; 4359 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4360 PetscValidType(mat,1); 4361 if (numRows) PetscValidIntPointer(rows,3); 4362 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4363 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4364 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4365 4366 if (mat->ops->zerorowslocal) { 4367 ierr = (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);CHKERRQ(ierr); 4368 } else { 4369 IS is, newis; 4370 PetscInt *newRows; 4371 4372 if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 4373 ierr = ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);CHKERRQ(ierr); 4374 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 4375 ierr = ISGetIndices(newis,&newRows);CHKERRQ(ierr); 4376 ierr = (*mat->ops->zerorows)(mat,numRows,newRows,diag);CHKERRQ(ierr); 4377 ierr = ISRestoreIndices(newis,&newRows);CHKERRQ(ierr); 4378 ierr = ISDestroy(newis);CHKERRQ(ierr); 4379 ierr = ISDestroy(is);CHKERRQ(ierr); 4380 } 4381 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4382 PetscFunctionReturn(0); 4383 } 4384 4385 #undef __FUNCT__ 4386 #define __FUNCT__ "MatZeroRowsLocal" 4387 /*@C 4388 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 4389 of a set of rows of a matrix; using local numbering of rows. 4390 4391 Collective on Mat 4392 4393 Input Parameters: 4394 + mat - the matrix 4395 . is - index set of rows to remove 4396 - diag - value put in all diagonals of eliminated rows 4397 4398 Notes: 4399 Before calling MatZeroRowsLocal(), the user must first set the 4400 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 4401 4402 For the AIJ matrix formats this removes the old nonzero structure, 4403 but does not release memory. For the dense and block diagonal 4404 formats this does not alter the nonzero structure. 4405 4406 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 4407 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4408 merely zeroed. 4409 4410 The user can set a value in the diagonal entry (or for the AIJ and 4411 row formats can optionally remove the main diagonal entry from the 4412 nonzero structure as well, by passing 0.0 as the final argument). 4413 4414 Level: intermediate 4415 4416 Concepts: matrices^zeroing 4417 4418 .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 4419 @*/ 4420 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag) 4421 { 4422 PetscErrorCode ierr; 4423 PetscInt numRows; 4424 PetscInt *rows; 4425 4426 PetscFunctionBegin; 4427 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4428 PetscValidType(mat,1); 4429 PetscValidHeaderSpecific(is,IS_COOKIE,2); 4430 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4431 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4432 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4433 4434 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 4435 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 4436 ierr = MatZeroRowsLocal(mat,numRows,rows,diag);CHKERRQ(ierr); 4437 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 4438 PetscFunctionReturn(0); 4439 } 4440 4441 #undef __FUNCT__ 4442 #define __FUNCT__ "MatGetSize" 4443 /*@ 4444 MatGetSize - Returns the numbers of rows and columns in a matrix. 4445 4446 Not Collective 4447 4448 Input Parameter: 4449 . mat - the matrix 4450 4451 Output Parameters: 4452 + m - the number of global rows 4453 - n - the number of global columns 4454 4455 Note: both output parameters can be PETSC_NULL on input. 4456 4457 Level: beginner 4458 4459 Concepts: matrices^size 4460 4461 .seealso: MatGetLocalSize() 4462 @*/ 4463 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n) 4464 { 4465 PetscFunctionBegin; 4466 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4467 if (m) *m = mat->rmap.N; 4468 if (n) *n = mat->cmap.N; 4469 PetscFunctionReturn(0); 4470 } 4471 4472 #undef __FUNCT__ 4473 #define __FUNCT__ "MatGetLocalSize" 4474 /*@ 4475 MatGetLocalSize - Returns the number of rows and columns in a matrix 4476 stored locally. This information may be implementation dependent, so 4477 use with care. 4478 4479 Not Collective 4480 4481 Input Parameters: 4482 . mat - the matrix 4483 4484 Output Parameters: 4485 + m - the number of local rows 4486 - n - the number of local columns 4487 4488 Note: both output parameters can be PETSC_NULL on input. 4489 4490 Level: beginner 4491 4492 Concepts: matrices^local size 4493 4494 .seealso: MatGetSize() 4495 @*/ 4496 PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n) 4497 { 4498 PetscFunctionBegin; 4499 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4500 if (m) PetscValidIntPointer(m,2); 4501 if (n) PetscValidIntPointer(n,3); 4502 if (m) *m = mat->rmap.n; 4503 if (n) *n = mat->cmap.n; 4504 PetscFunctionReturn(0); 4505 } 4506 4507 4508 #undef __FUNCT__ 4509 #define __FUNCT__ "MatGetOwnershipRange" 4510 /*@ 4511 MatGetOwnershipRange - Returns the range of matrix rows owned by 4512 this processor, assuming that the matrix is laid out with the first 4513 n1 rows on the first processor, the next n2 rows on the second, etc. 4514 For certain parallel layouts this range may not be well defined. 4515 4516 Not Collective 4517 4518 Input Parameters: 4519 . mat - the matrix 4520 4521 Output Parameters: 4522 + m - the global index of the first local row 4523 - n - one more than the global index of the last local row 4524 4525 Note: both output parameters can be PETSC_NULL on input. 4526 4527 Level: beginner 4528 4529 Concepts: matrices^row ownership 4530 4531 .seealso: MatGetOwnershipRanges() 4532 4533 @*/ 4534 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n) 4535 { 4536 PetscErrorCode ierr; 4537 4538 PetscFunctionBegin; 4539 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4540 PetscValidType(mat,1); 4541 if (m) PetscValidIntPointer(m,2); 4542 if (n) PetscValidIntPointer(n,3); 4543 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4544 if (m) *m = mat->rmap.rstart; 4545 if (n) *n = mat->rmap.rend; 4546 PetscFunctionReturn(0); 4547 } 4548 4549 #undef __FUNCT__ 4550 #define __FUNCT__ "MatGetOwnershipRanges" 4551 /*@C 4552 MatGetOwnershipRanges - Returns the range of matrix rows owned by 4553 each process 4554 4555 Not Collective 4556 4557 Input Parameters: 4558 . mat - the matrix 4559 4560 Output Parameters: 4561 . ranges - start of each processors portion plus one more then the total length at the end 4562 4563 Level: beginner 4564 4565 Concepts: matrices^row ownership 4566 4567 .seealso: MatGetOwnershipRange() 4568 4569 @*/ 4570 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRanges(Mat mat,const PetscInt **ranges) 4571 { 4572 PetscErrorCode ierr; 4573 4574 PetscFunctionBegin; 4575 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4576 PetscValidType(mat,1); 4577 ierr = PetscMapGetGlobalRange(&mat->rmap,ranges);CHKERRQ(ierr); 4578 PetscFunctionReturn(0); 4579 } 4580 4581 #undef __FUNCT__ 4582 #define __FUNCT__ "MatILUFactorSymbolic" 4583 /*@ 4584 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 4585 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 4586 to complete the factorization. 4587 4588 Collective on Mat 4589 4590 Input Parameters: 4591 + mat - the matrix 4592 . row - row permutation 4593 . column - column permutation 4594 - info - structure containing 4595 $ levels - number of levels of fill. 4596 $ expected fill - as ratio of original fill. 4597 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 4598 missing diagonal entries) 4599 4600 Output Parameters: 4601 . fact - new matrix that has been symbolically factored 4602 4603 Notes: 4604 See the users manual for additional information about 4605 choosing the fill factor for better efficiency. 4606 4607 Most users should employ the simplified KSP interface for linear solvers 4608 instead of working directly with matrix algebra routines such as this. 4609 See, e.g., KSPCreate(). 4610 4611 Level: developer 4612 4613 Concepts: matrices^symbolic LU factorization 4614 Concepts: matrices^factorization 4615 Concepts: LU^symbolic factorization 4616 4617 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 4618 MatGetOrdering(), MatFactorInfo 4619 4620 @*/ 4621 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 4622 { 4623 PetscErrorCode ierr; 4624 4625 PetscFunctionBegin; 4626 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4627 PetscValidType(mat,1); 4628 PetscValidHeaderSpecific(row,IS_COOKIE,2); 4629 PetscValidHeaderSpecific(col,IS_COOKIE,3); 4630 PetscValidPointer(info,4); 4631 PetscValidPointer(fact,5); 4632 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill 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->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name); 4635 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4636 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4637 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4638 4639 ierr = PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4640 ierr = (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 4641 ierr = PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4642 PetscFunctionReturn(0); 4643 } 4644 4645 #undef __FUNCT__ 4646 #define __FUNCT__ "MatICCFactorSymbolic" 4647 /*@ 4648 MatICCFactorSymbolic - Performs symbolic incomplete 4649 Cholesky factorization for a symmetric matrix. Use 4650 MatCholeskyFactorNumeric() to complete the factorization. 4651 4652 Collective on Mat 4653 4654 Input Parameters: 4655 + mat - the matrix 4656 . perm - row and column permutation 4657 - info - structure containing 4658 $ levels - number of levels of fill. 4659 $ expected fill - as ratio of original fill. 4660 4661 Output Parameter: 4662 . fact - the factored matrix 4663 4664 Notes: 4665 Most users should employ the KSP interface for linear solvers 4666 instead of working directly with matrix algebra routines such as this. 4667 See, e.g., KSPCreate(). 4668 4669 Level: developer 4670 4671 Concepts: matrices^symbolic incomplete Cholesky factorization 4672 Concepts: matrices^factorization 4673 Concepts: Cholsky^symbolic factorization 4674 4675 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 4676 @*/ 4677 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact) 4678 { 4679 PetscErrorCode ierr; 4680 4681 PetscFunctionBegin; 4682 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4683 PetscValidType(mat,1); 4684 PetscValidHeaderSpecific(perm,IS_COOKIE,2); 4685 PetscValidPointer(info,3); 4686 PetscValidPointer(fact,4); 4687 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4688 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels); 4689 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 4690 if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name); 4691 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4692 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4693 4694 ierr = PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4695 ierr = (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);CHKERRQ(ierr); 4696 ierr = PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4697 PetscFunctionReturn(0); 4698 } 4699 4700 #undef __FUNCT__ 4701 #define __FUNCT__ "MatGetArray" 4702 /*@C 4703 MatGetArray - Returns a pointer to the element values in the matrix. 4704 The result of this routine is dependent on the underlying matrix data 4705 structure, and may not even work for certain matrix types. You MUST 4706 call MatRestoreArray() when you no longer need to access the array. 4707 4708 Not Collective 4709 4710 Input Parameter: 4711 . mat - the matrix 4712 4713 Output Parameter: 4714 . v - the location of the values 4715 4716 4717 Fortran Note: 4718 This routine is used differently from Fortran, e.g., 4719 .vb 4720 Mat mat 4721 PetscScalar mat_array(1) 4722 PetscOffset i_mat 4723 PetscErrorCode ierr 4724 call MatGetArray(mat,mat_array,i_mat,ierr) 4725 4726 C Access first local entry in matrix; note that array is 4727 C treated as one dimensional 4728 value = mat_array(i_mat + 1) 4729 4730 [... other code ...] 4731 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4732 .ve 4733 4734 See the Fortran chapter of the users manual and 4735 petsc/src/mat/examples/tests for details. 4736 4737 Level: advanced 4738 4739 Concepts: matrices^access array 4740 4741 .seealso: MatRestoreArray(), MatGetArrayF90() 4742 @*/ 4743 PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[]) 4744 { 4745 PetscErrorCode ierr; 4746 4747 PetscFunctionBegin; 4748 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4749 PetscValidType(mat,1); 4750 PetscValidPointer(v,2); 4751 if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4752 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4753 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 4754 CHKMEMQ; 4755 PetscFunctionReturn(0); 4756 } 4757 4758 #undef __FUNCT__ 4759 #define __FUNCT__ "MatRestoreArray" 4760 /*@C 4761 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 4762 4763 Not Collective 4764 4765 Input Parameter: 4766 + mat - the matrix 4767 - v - the location of the values 4768 4769 Fortran Note: 4770 This routine is used differently from Fortran, e.g., 4771 .vb 4772 Mat mat 4773 PetscScalar mat_array(1) 4774 PetscOffset i_mat 4775 PetscErrorCode ierr 4776 call MatGetArray(mat,mat_array,i_mat,ierr) 4777 4778 C Access first local entry in matrix; note that array is 4779 C treated as one dimensional 4780 value = mat_array(i_mat + 1) 4781 4782 [... other code ...] 4783 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4784 .ve 4785 4786 See the Fortran chapter of the users manual and 4787 petsc/src/mat/examples/tests for details 4788 4789 Level: advanced 4790 4791 .seealso: MatGetArray(), MatRestoreArrayF90() 4792 @*/ 4793 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[]) 4794 { 4795 PetscErrorCode ierr; 4796 4797 PetscFunctionBegin; 4798 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4799 PetscValidType(mat,1); 4800 PetscValidPointer(v,2); 4801 #if defined(PETSC_USE_DEBUG) 4802 CHKMEMQ; 4803 #endif 4804 if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4805 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 4806 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4807 PetscFunctionReturn(0); 4808 } 4809 4810 #undef __FUNCT__ 4811 #define __FUNCT__ "MatGetSubMatrices" 4812 /*@C 4813 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 4814 points to an array of valid matrices, they may be reused to store the new 4815 submatrices. 4816 4817 Collective on Mat 4818 4819 Input Parameters: 4820 + mat - the matrix 4821 . n - the number of submatrixes to be extracted (on this processor, may be zero) 4822 . irow, icol - index sets of rows and columns to extract 4823 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 4824 4825 Output Parameter: 4826 . submat - the array of submatrices 4827 4828 Notes: 4829 MatGetSubMatrices() can extract only sequential submatrices 4830 (from both sequential and parallel matrices). Use MatGetSubMatrix() 4831 to extract a parallel submatrix. 4832 4833 When extracting submatrices from a parallel matrix, each processor can 4834 form a different submatrix by setting the rows and columns of its 4835 individual index sets according to the local submatrix desired. 4836 4837 When finished using the submatrices, the user should destroy 4838 them with MatDestroyMatrices(). 4839 4840 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 4841 original matrix has not changed from that last call to MatGetSubMatrices(). 4842 4843 This routine creates the matrices in submat; you should NOT create them before 4844 calling it. It also allocates the array of matrix pointers submat. 4845 4846 For BAIJ matrices the index sets must respect the block structure, that is if they 4847 request one row/column in a block, they must request all rows/columns that are in 4848 that block. For example, if the block size is 2 you cannot request just row 0 and 4849 column 0. 4850 4851 Fortran Note: 4852 The Fortran interface is slightly different from that given below; it 4853 requires one to pass in as submat a Mat (integer) array of size at least m. 4854 4855 Level: advanced 4856 4857 Concepts: matrices^accessing submatrices 4858 Concepts: submatrices 4859 4860 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal() 4861 @*/ 4862 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[]) 4863 { 4864 PetscErrorCode ierr; 4865 PetscInt i; 4866 PetscTruth eq; 4867 4868 PetscFunctionBegin; 4869 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4870 PetscValidType(mat,1); 4871 if (n) { 4872 PetscValidPointer(irow,3); 4873 PetscValidHeaderSpecific(*irow,IS_COOKIE,3); 4874 PetscValidPointer(icol,4); 4875 PetscValidHeaderSpecific(*icol,IS_COOKIE,4); 4876 } 4877 PetscValidPointer(submat,6); 4878 if (n && scall == MAT_REUSE_MATRIX) { 4879 PetscValidPointer(*submat,6); 4880 PetscValidHeaderSpecific(**submat,MAT_COOKIE,6); 4881 } 4882 if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4883 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4884 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4885 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4886 4887 ierr = PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4888 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 4889 ierr = PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4890 for (i=0; i<n; i++) { 4891 if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) { 4892 ierr = ISEqual(irow[i],icol[i],&eq);CHKERRQ(ierr); 4893 if (eq) { 4894 if (mat->symmetric){ 4895 ierr = MatSetOption((*submat)[i],MAT_SYMMETRIC);CHKERRQ(ierr); 4896 } else if (mat->hermitian) { 4897 ierr = MatSetOption((*submat)[i],MAT_HERMITIAN);CHKERRQ(ierr); 4898 } else if (mat->structurally_symmetric) { 4899 ierr = MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);CHKERRQ(ierr); 4900 } 4901 } 4902 } 4903 } 4904 PetscFunctionReturn(0); 4905 } 4906 4907 #undef __FUNCT__ 4908 #define __FUNCT__ "MatDestroyMatrices" 4909 /*@C 4910 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 4911 4912 Collective on Mat 4913 4914 Input Parameters: 4915 + n - the number of local matrices 4916 - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling 4917 sequence of MatGetSubMatrices()) 4918 4919 Level: advanced 4920 4921 Notes: Frees not only the matrices, but also the array that contains the matrices 4922 4923 .seealso: MatGetSubMatrices() 4924 @*/ 4925 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[]) 4926 { 4927 PetscErrorCode ierr; 4928 PetscInt i; 4929 4930 PetscFunctionBegin; 4931 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n); 4932 PetscValidPointer(mat,2); 4933 for (i=0; i<n; i++) { 4934 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 4935 } 4936 /* memory is allocated even if n = 0 */ 4937 ierr = PetscFree(*mat);CHKERRQ(ierr); 4938 PetscFunctionReturn(0); 4939 } 4940 4941 #undef __FUNCT__ 4942 #define __FUNCT__ "MatIncreaseOverlap" 4943 /*@ 4944 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 4945 replaces the index sets by larger ones that represent submatrices with 4946 additional overlap. 4947 4948 Collective on Mat 4949 4950 Input Parameters: 4951 + mat - the matrix 4952 . n - the number of index sets 4953 . is - the array of index sets (these index sets will changed during the call) 4954 - ov - the additional overlap requested 4955 4956 Level: developer 4957 4958 Concepts: overlap 4959 Concepts: ASM^computing overlap 4960 4961 .seealso: MatGetSubMatrices() 4962 @*/ 4963 PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov) 4964 { 4965 PetscErrorCode ierr; 4966 4967 PetscFunctionBegin; 4968 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4969 PetscValidType(mat,1); 4970 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n); 4971 if (n) { 4972 PetscValidPointer(is,3); 4973 PetscValidHeaderSpecific(*is,IS_COOKIE,3); 4974 } 4975 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4976 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4977 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4978 4979 if (!ov) PetscFunctionReturn(0); 4980 if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4981 ierr = PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4982 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 4983 ierr = PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4984 PetscFunctionReturn(0); 4985 } 4986 4987 #undef __FUNCT__ 4988 #define __FUNCT__ "MatGetBlockSize" 4989 /*@ 4990 MatGetBlockSize - Returns the matrix block size; useful especially for the 4991 block row and block diagonal formats. 4992 4993 Not Collective 4994 4995 Input Parameter: 4996 . mat - the matrix 4997 4998 Output Parameter: 4999 . bs - block size 5000 5001 Notes: 5002 Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG. 5003 Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ 5004 5005 Level: intermediate 5006 5007 Concepts: matrices^block size 5008 5009 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag() 5010 @*/ 5011 PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs) 5012 { 5013 PetscErrorCode ierr; 5014 5015 PetscFunctionBegin; 5016 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5017 PetscValidType(mat,1); 5018 PetscValidIntPointer(bs,2); 5019 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5020 *bs = mat->rmap.bs; 5021 PetscFunctionReturn(0); 5022 } 5023 5024 #undef __FUNCT__ 5025 #define __FUNCT__ "MatSetBlockSize" 5026 /*@ 5027 MatSetBlockSize - Sets the matrix block size; for many matrix types you 5028 cannot use this and MUST set the blocksize when you preallocate the matrix 5029 5030 Not Collective 5031 5032 Input Parameters: 5033 + mat - the matrix 5034 - bs - block size 5035 5036 Notes: 5037 Only works for shell and AIJ matrices 5038 5039 Level: intermediate 5040 5041 Concepts: matrices^block size 5042 5043 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize() 5044 @*/ 5045 PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs) 5046 { 5047 PetscErrorCode ierr; 5048 5049 PetscFunctionBegin; 5050 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5051 PetscValidType(mat,1); 5052 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5053 if (mat->ops->setblocksize) { 5054 mat->rmap.bs = bs; 5055 ierr = (*mat->ops->setblocksize)(mat,bs);CHKERRQ(ierr); 5056 } else { 5057 SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name); 5058 } 5059 PetscFunctionReturn(0); 5060 } 5061 5062 #undef __FUNCT__ 5063 #define __FUNCT__ "MatGetRowIJ" 5064 /*@C 5065 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 5066 5067 Collective on Mat 5068 5069 Input Parameters: 5070 + mat - the matrix 5071 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 5072 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5073 symmetrized 5074 5075 Output Parameters: 5076 + n - number of rows in the (possibly compressed) matrix 5077 . ia - the row pointers 5078 . ja - the column indices 5079 - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers 5080 are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set 5081 5082 Level: developer 5083 5084 Notes: You CANNOT change any of the ia[] or ja[] values. 5085 5086 Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values 5087 5088 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 5089 @*/ 5090 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5091 { 5092 PetscErrorCode ierr; 5093 5094 PetscFunctionBegin; 5095 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5096 PetscValidType(mat,1); 5097 PetscValidIntPointer(n,4); 5098 if (ia) PetscValidIntPointer(ia,5); 5099 if (ja) PetscValidIntPointer(ja,6); 5100 PetscValidIntPointer(done,7); 5101 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5102 if (!mat->ops->getrowij) *done = PETSC_FALSE; 5103 else { 5104 *done = PETSC_TRUE; 5105 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5106 } 5107 PetscFunctionReturn(0); 5108 } 5109 5110 #undef __FUNCT__ 5111 #define __FUNCT__ "MatGetColumnIJ" 5112 /*@C 5113 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 5114 5115 Collective on Mat 5116 5117 Input Parameters: 5118 + mat - the matrix 5119 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5120 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5121 symmetrized 5122 5123 Output Parameters: 5124 + n - number of columns in the (possibly compressed) matrix 5125 . ia - the column pointers 5126 . ja - the row indices 5127 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 5128 5129 Level: developer 5130 5131 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 5132 @*/ 5133 PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5134 { 5135 PetscErrorCode ierr; 5136 5137 PetscFunctionBegin; 5138 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5139 PetscValidType(mat,1); 5140 PetscValidIntPointer(n,4); 5141 if (ia) PetscValidIntPointer(ia,5); 5142 if (ja) PetscValidIntPointer(ja,6); 5143 PetscValidIntPointer(done,7); 5144 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5145 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 5146 else { 5147 *done = PETSC_TRUE; 5148 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5149 } 5150 PetscFunctionReturn(0); 5151 } 5152 5153 #undef __FUNCT__ 5154 #define __FUNCT__ "MatRestoreRowIJ" 5155 /*@C 5156 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 5157 MatGetRowIJ(). 5158 5159 Collective on Mat 5160 5161 Input Parameters: 5162 + mat - the matrix 5163 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5164 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5165 symmetrized 5166 5167 Output Parameters: 5168 + n - size of (possibly compressed) matrix 5169 . ia - the row pointers 5170 . ja - the column indices 5171 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 5172 5173 Level: developer 5174 5175 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 5176 @*/ 5177 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5178 { 5179 PetscErrorCode ierr; 5180 5181 PetscFunctionBegin; 5182 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5183 PetscValidType(mat,1); 5184 if (ia) PetscValidIntPointer(ia,5); 5185 if (ja) PetscValidIntPointer(ja,6); 5186 PetscValidIntPointer(done,7); 5187 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5188 5189 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 5190 else { 5191 *done = PETSC_TRUE; 5192 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5193 } 5194 PetscFunctionReturn(0); 5195 } 5196 5197 #undef __FUNCT__ 5198 #define __FUNCT__ "MatRestoreColumnIJ" 5199 /*@C 5200 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 5201 MatGetColumnIJ(). 5202 5203 Collective on Mat 5204 5205 Input Parameters: 5206 + mat - the matrix 5207 . shift - 1 or zero indicating we want the indices starting at 0 or 1 5208 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5209 symmetrized 5210 5211 Output Parameters: 5212 + n - size of (possibly compressed) matrix 5213 . ia - the column pointers 5214 . ja - the row indices 5215 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 5216 5217 Level: developer 5218 5219 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 5220 @*/ 5221 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 5222 { 5223 PetscErrorCode ierr; 5224 5225 PetscFunctionBegin; 5226 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5227 PetscValidType(mat,1); 5228 if (ia) PetscValidIntPointer(ia,5); 5229 if (ja) PetscValidIntPointer(ja,6); 5230 PetscValidIntPointer(done,7); 5231 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5232 5233 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 5234 else { 5235 *done = PETSC_TRUE; 5236 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 5237 } 5238 PetscFunctionReturn(0); 5239 } 5240 5241 #undef __FUNCT__ 5242 #define __FUNCT__ "MatColoringPatch" 5243 /*@C 5244 MatColoringPatch -Used inside matrix coloring routines that 5245 use MatGetRowIJ() and/or MatGetColumnIJ(). 5246 5247 Collective on Mat 5248 5249 Input Parameters: 5250 + mat - the matrix 5251 . ncolors - max color value 5252 . n - number of entries in colorarray 5253 - colorarray - array indicating color for each column 5254 5255 Output Parameters: 5256 . iscoloring - coloring generated using colorarray information 5257 5258 Level: developer 5259 5260 .seealso: MatGetRowIJ(), MatGetColumnIJ() 5261 5262 @*/ 5263 PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring) 5264 { 5265 PetscErrorCode ierr; 5266 5267 PetscFunctionBegin; 5268 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5269 PetscValidType(mat,1); 5270 PetscValidIntPointer(colorarray,4); 5271 PetscValidPointer(iscoloring,5); 5272 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5273 5274 if (!mat->ops->coloringpatch){ 5275 ierr = ISColoringCreate(mat->comm,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 5276 } else { 5277 ierr = (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 5278 } 5279 PetscFunctionReturn(0); 5280 } 5281 5282 5283 #undef __FUNCT__ 5284 #define __FUNCT__ "MatSetUnfactored" 5285 /*@ 5286 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 5287 5288 Collective on Mat 5289 5290 Input Parameter: 5291 . mat - the factored matrix to be reset 5292 5293 Notes: 5294 This routine should be used only with factored matrices formed by in-place 5295 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 5296 format). This option can save memory, for example, when solving nonlinear 5297 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 5298 ILU(0) preconditioner. 5299 5300 Note that one can specify in-place ILU(0) factorization by calling 5301 .vb 5302 PCType(pc,PCILU); 5303 PCFactorSeUseInPlace(pc); 5304 .ve 5305 or by using the options -pc_type ilu -pc_factor_in_place 5306 5307 In-place factorization ILU(0) can also be used as a local 5308 solver for the blocks within the block Jacobi or additive Schwarz 5309 methods (runtime option: -sub_pc_factor_in_place). See the discussion 5310 of these preconditioners in the users manual for details on setting 5311 local solver options. 5312 5313 Most users should employ the simplified KSP interface for linear solvers 5314 instead of working directly with matrix algebra routines such as this. 5315 See, e.g., KSPCreate(). 5316 5317 Level: developer 5318 5319 .seealso: PCFactorSetUseInPlace() 5320 5321 Concepts: matrices^unfactored 5322 5323 @*/ 5324 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat) 5325 { 5326 PetscErrorCode ierr; 5327 5328 PetscFunctionBegin; 5329 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5330 PetscValidType(mat,1); 5331 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5332 mat->factor = 0; 5333 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 5334 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 5335 PetscFunctionReturn(0); 5336 } 5337 5338 /*MC 5339 MatGetArrayF90 - Accesses a matrix array from Fortran90. 5340 5341 Synopsis: 5342 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 5343 5344 Not collective 5345 5346 Input Parameter: 5347 . x - matrix 5348 5349 Output Parameters: 5350 + xx_v - the Fortran90 pointer to the array 5351 - ierr - error code 5352 5353 Example of Usage: 5354 .vb 5355 PetscScalar, pointer xx_v(:) 5356 .... 5357 call MatGetArrayF90(x,xx_v,ierr) 5358 a = xx_v(3) 5359 call MatRestoreArrayF90(x,xx_v,ierr) 5360 .ve 5361 5362 Notes: 5363 Not yet supported for all F90 compilers 5364 5365 Level: advanced 5366 5367 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 5368 5369 Concepts: matrices^accessing array 5370 5371 M*/ 5372 5373 /*MC 5374 MatRestoreArrayF90 - Restores a matrix array that has been 5375 accessed with MatGetArrayF90(). 5376 5377 Synopsis: 5378 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 5379 5380 Not collective 5381 5382 Input Parameters: 5383 + x - matrix 5384 - xx_v - the Fortran90 pointer to the array 5385 5386 Output Parameter: 5387 . ierr - error code 5388 5389 Example of Usage: 5390 .vb 5391 PetscScalar, pointer xx_v(:) 5392 .... 5393 call MatGetArrayF90(x,xx_v,ierr) 5394 a = xx_v(3) 5395 call MatRestoreArrayF90(x,xx_v,ierr) 5396 .ve 5397 5398 Notes: 5399 Not yet supported for all F90 compilers 5400 5401 Level: advanced 5402 5403 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 5404 5405 M*/ 5406 5407 5408 #undef __FUNCT__ 5409 #define __FUNCT__ "MatGetSubMatrix" 5410 /*@ 5411 MatGetSubMatrix - Gets a single submatrix on the same number of processors 5412 as the original matrix. 5413 5414 Collective on Mat 5415 5416 Input Parameters: 5417 + mat - the original matrix 5418 . isrow - rows this processor should obtain 5419 . iscol - columns for all processors you wish to keep 5420 . csize - number of columns "local" to this processor (does nothing for sequential 5421 matrices). This should match the result from VecGetLocalSize(x,...) if you 5422 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 5423 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5424 5425 Output Parameter: 5426 . newmat - the new submatrix, of the same type as the old 5427 5428 Level: advanced 5429 5430 Notes: the iscol argument MUST be the same on each processor. You might be 5431 able to create the iscol argument with ISAllGather(). The rows is isrow will be 5432 sorted into the same order as the original matrix. 5433 5434 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 5435 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 5436 to this routine with a mat of the same nonzero structure and with a call of MAT_REUSE_MATRIX 5437 will reuse the matrix generated the first time. You should call MatDestroy() on newmat when 5438 you are finished using it. 5439 5440 Concepts: matrices^submatrices 5441 5442 .seealso: MatGetSubMatrices(), ISAllGather() 5443 @*/ 5444 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat) 5445 { 5446 PetscErrorCode ierr; 5447 PetscMPIInt size; 5448 Mat *local; 5449 5450 PetscFunctionBegin; 5451 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5452 PetscValidHeaderSpecific(isrow,IS_COOKIE,2); 5453 PetscValidHeaderSpecific(iscol,IS_COOKIE,3); 5454 PetscValidPointer(newmat,6); 5455 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_COOKIE,6); 5456 PetscValidType(mat,1); 5457 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5458 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5459 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 5460 5461 /* if original matrix is on just one processor then use submatrix generated */ 5462 if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 5463 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 5464 PetscFunctionReturn(0); 5465 } else if (!mat->ops->getsubmatrix && size == 1) { 5466 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 5467 *newmat = *local; 5468 ierr = PetscFree(local);CHKERRQ(ierr); 5469 PetscFunctionReturn(0); 5470 } 5471 5472 if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5473 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);CHKERRQ(ierr); 5474 ierr = PetscObjectStateIncrease((PetscObject)*newmat);CHKERRQ(ierr); 5475 PetscFunctionReturn(0); 5476 } 5477 5478 #undef __FUNCT__ 5479 #define __FUNCT__ "MatGetSubMatrixRaw" 5480 /*@ 5481 MatGetSubMatrixRaw - Gets a single submatrix on the same number of processors 5482 as the original matrix. 5483 5484 Collective on Mat 5485 5486 Input Parameters: 5487 + mat - the original matrix 5488 . nrows - the number of rows this processor should obtain 5489 . rows - rows this processor should obtain 5490 . ncols - the number of columns for all processors you wish to keep 5491 . cols - columns for all processors you wish to keep 5492 . csize - number of columns "local" to this processor (does nothing for sequential 5493 matrices). This should match the result from VecGetLocalSize(x,...) if you 5494 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 5495 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5496 5497 Output Parameter: 5498 . newmat - the new submatrix, of the same type as the old 5499 5500 Level: advanced 5501 5502 Notes: the iscol argument MUST be the same on each processor. You might be 5503 able to create the iscol argument with ISAllGather(). 5504 5505 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 5506 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 5507 to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX 5508 will reuse the matrix generated the first time. 5509 5510 Concepts: matrices^submatrices 5511 5512 .seealso: MatGetSubMatrices(), ISAllGather() 5513 @*/ 5514 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrixRaw(Mat mat,PetscInt nrows,const PetscInt rows[],PetscInt ncols,const PetscInt cols[],PetscInt csize,MatReuse cll,Mat *newmat) 5515 { 5516 IS isrow, iscol; 5517 PetscErrorCode ierr; 5518 5519 PetscFunctionBegin; 5520 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5521 PetscValidIntPointer(rows,2); 5522 PetscValidIntPointer(cols,3); 5523 PetscValidPointer(newmat,6); 5524 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_COOKIE,6); 5525 PetscValidType(mat,1); 5526 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5527 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5528 ierr = ISCreateGeneralWithArray(PETSC_COMM_SELF, nrows, (PetscInt *) rows, &isrow);CHKERRQ(ierr); 5529 ierr = ISCreateGeneralWithArray(PETSC_COMM_SELF, ncols, (PetscInt *) cols, &iscol);CHKERRQ(ierr); 5530 ierr = MatGetSubMatrix(mat, isrow, iscol, csize, cll, newmat);CHKERRQ(ierr); 5531 ierr = ISDestroy(isrow);CHKERRQ(ierr); 5532 ierr = ISDestroy(iscol);CHKERRQ(ierr); 5533 PetscFunctionReturn(0); 5534 } 5535 5536 #undef __FUNCT__ 5537 #define __FUNCT__ "MatStashSetInitialSize" 5538 /*@ 5539 MatStashSetInitialSize - sets the sizes of the matrix stash, that is 5540 used during the assembly process to store values that belong to 5541 other processors. 5542 5543 Not Collective 5544 5545 Input Parameters: 5546 + mat - the matrix 5547 . size - the initial size of the stash. 5548 - bsize - the initial size of the block-stash(if used). 5549 5550 Options Database Keys: 5551 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 5552 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 5553 5554 Level: intermediate 5555 5556 Notes: 5557 The block-stash is used for values set with MatSetValuesBlocked() while 5558 the stash is used for values set with MatSetValues() 5559 5560 Run with the option -info and look for output of the form 5561 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 5562 to determine the appropriate value, MM, to use for size and 5563 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 5564 to determine the value, BMM to use for bsize 5565 5566 Concepts: stash^setting matrix size 5567 Concepts: matrices^stash 5568 5569 @*/ 5570 PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize) 5571 { 5572 PetscErrorCode ierr; 5573 5574 PetscFunctionBegin; 5575 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5576 PetscValidType(mat,1); 5577 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 5578 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 5579 PetscFunctionReturn(0); 5580 } 5581 5582 #undef __FUNCT__ 5583 #define __FUNCT__ "MatInterpolateAdd" 5584 /*@ 5585 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 5586 the matrix 5587 5588 Collective on Mat 5589 5590 Input Parameters: 5591 + mat - the matrix 5592 . x,y - the vectors 5593 - w - where the result is stored 5594 5595 Level: intermediate 5596 5597 Notes: 5598 w may be the same vector as y. 5599 5600 This allows one to use either the restriction or interpolation (its transpose) 5601 matrix to do the interpolation 5602 5603 Concepts: interpolation 5604 5605 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5606 5607 @*/ 5608 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 5609 { 5610 PetscErrorCode ierr; 5611 PetscInt M,N; 5612 5613 PetscFunctionBegin; 5614 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5615 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5616 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5617 PetscValidHeaderSpecific(w,VEC_COOKIE,4); 5618 PetscValidType(A,1); 5619 ierr = MatPreallocated(A);CHKERRQ(ierr); 5620 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5621 if (N > M) { 5622 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 5623 } else { 5624 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 5625 } 5626 PetscFunctionReturn(0); 5627 } 5628 5629 #undef __FUNCT__ 5630 #define __FUNCT__ "MatInterpolate" 5631 /*@ 5632 MatInterpolate - y = A*x or A'*x depending on the shape of 5633 the matrix 5634 5635 Collective on Mat 5636 5637 Input Parameters: 5638 + mat - the matrix 5639 - x,y - the vectors 5640 5641 Level: intermediate 5642 5643 Notes: 5644 This allows one to use either the restriction or interpolation (its transpose) 5645 matrix to do the interpolation 5646 5647 Concepts: matrices^interpolation 5648 5649 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5650 5651 @*/ 5652 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y) 5653 { 5654 PetscErrorCode ierr; 5655 PetscInt M,N; 5656 5657 PetscFunctionBegin; 5658 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5659 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5660 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5661 PetscValidType(A,1); 5662 ierr = MatPreallocated(A);CHKERRQ(ierr); 5663 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5664 if (N > M) { 5665 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5666 } else { 5667 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5668 } 5669 PetscFunctionReturn(0); 5670 } 5671 5672 #undef __FUNCT__ 5673 #define __FUNCT__ "MatRestrict" 5674 /*@ 5675 MatRestrict - y = A*x or A'*x 5676 5677 Collective on Mat 5678 5679 Input Parameters: 5680 + mat - the matrix 5681 - x,y - the vectors 5682 5683 Level: intermediate 5684 5685 Notes: 5686 This allows one to use either the restriction or interpolation (its transpose) 5687 matrix to do the restriction 5688 5689 Concepts: matrices^restriction 5690 5691 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 5692 5693 @*/ 5694 PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y) 5695 { 5696 PetscErrorCode ierr; 5697 PetscInt M,N; 5698 5699 PetscFunctionBegin; 5700 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5701 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5702 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5703 PetscValidType(A,1); 5704 ierr = MatPreallocated(A);CHKERRQ(ierr); 5705 5706 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5707 if (N > M) { 5708 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5709 } else { 5710 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5711 } 5712 PetscFunctionReturn(0); 5713 } 5714 5715 #undef __FUNCT__ 5716 #define __FUNCT__ "MatNullSpaceAttach" 5717 /*@C 5718 MatNullSpaceAttach - attaches a null space to a matrix. 5719 This null space will be removed from the resulting vector whenever 5720 MatMult() is called 5721 5722 Collective on Mat 5723 5724 Input Parameters: 5725 + mat - the matrix 5726 - nullsp - the null space object 5727 5728 Level: developer 5729 5730 Notes: 5731 Overwrites any previous null space that may have been attached 5732 5733 Concepts: null space^attaching to matrix 5734 5735 .seealso: MatCreate(), MatNullSpaceCreate() 5736 @*/ 5737 PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 5738 { 5739 PetscErrorCode ierr; 5740 5741 PetscFunctionBegin; 5742 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5743 PetscValidType(mat,1); 5744 PetscValidHeaderSpecific(nullsp,MAT_NULLSPACE_COOKIE,2); 5745 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5746 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 5747 if (mat->nullsp) { ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); } 5748 mat->nullsp = nullsp; 5749 PetscFunctionReturn(0); 5750 } 5751 5752 #undef __FUNCT__ 5753 #define __FUNCT__ "MatICCFactor" 5754 /*@ 5755 MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix. 5756 5757 Collective on Mat 5758 5759 Input Parameters: 5760 + mat - the matrix 5761 . row - row/column permutation 5762 . fill - expected fill factor >= 1.0 5763 - level - level of fill, for ICC(k) 5764 5765 Notes: 5766 Probably really in-place only when level of fill is zero, otherwise allocates 5767 new space to store factored matrix and deletes previous memory. 5768 5769 Most users should employ the simplified KSP interface for linear solvers 5770 instead of working directly with matrix algebra routines such as this. 5771 See, e.g., KSPCreate(). 5772 5773 Level: developer 5774 5775 Concepts: matrices^incomplete Cholesky factorization 5776 Concepts: Cholesky factorization 5777 5778 .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 5779 @*/ 5780 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info) 5781 { 5782 PetscErrorCode ierr; 5783 5784 PetscFunctionBegin; 5785 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5786 PetscValidType(mat,1); 5787 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 5788 PetscValidPointer(info,3); 5789 if (mat->rmap.N != mat->cmap.N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 5790 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5791 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5792 if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5793 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5794 ierr = (*mat->ops->iccfactor)(mat,row,info);CHKERRQ(ierr); 5795 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5796 PetscFunctionReturn(0); 5797 } 5798 5799 #undef __FUNCT__ 5800 #define __FUNCT__ "MatSetValuesAdic" 5801 /*@ 5802 MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix. 5803 5804 Not Collective 5805 5806 Input Parameters: 5807 + mat - the matrix 5808 - v - the values compute with ADIC 5809 5810 Level: developer 5811 5812 Notes: 5813 Must call MatSetColoring() before using this routine. Also this matrix must already 5814 have its nonzero pattern determined. 5815 5816 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5817 MatSetValues(), MatSetColoring(), MatSetValuesAdifor() 5818 @*/ 5819 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v) 5820 { 5821 PetscErrorCode ierr; 5822 5823 PetscFunctionBegin; 5824 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5825 PetscValidType(mat,1); 5826 PetscValidPointer(mat,2); 5827 5828 if (!mat->assembled) { 5829 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5830 } 5831 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5832 if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5833 ierr = (*mat->ops->setvaluesadic)(mat,v);CHKERRQ(ierr); 5834 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5835 ierr = MatView_Private(mat);CHKERRQ(ierr); 5836 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5837 PetscFunctionReturn(0); 5838 } 5839 5840 5841 #undef __FUNCT__ 5842 #define __FUNCT__ "MatSetColoring" 5843 /*@ 5844 MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic() 5845 5846 Not Collective 5847 5848 Input Parameters: 5849 + mat - the matrix 5850 - coloring - the coloring 5851 5852 Level: developer 5853 5854 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5855 MatSetValues(), MatSetValuesAdic() 5856 @*/ 5857 PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring) 5858 { 5859 PetscErrorCode ierr; 5860 5861 PetscFunctionBegin; 5862 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5863 PetscValidType(mat,1); 5864 PetscValidPointer(coloring,2); 5865 5866 if (!mat->assembled) { 5867 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5868 } 5869 if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5870 ierr = (*mat->ops->setcoloring)(mat,coloring);CHKERRQ(ierr); 5871 PetscFunctionReturn(0); 5872 } 5873 5874 #undef __FUNCT__ 5875 #define __FUNCT__ "MatSetValuesAdifor" 5876 /*@ 5877 MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix. 5878 5879 Not Collective 5880 5881 Input Parameters: 5882 + mat - the matrix 5883 . nl - leading dimension of v 5884 - v - the values compute with ADIFOR 5885 5886 Level: developer 5887 5888 Notes: 5889 Must call MatSetColoring() before using this routine. Also this matrix must already 5890 have its nonzero pattern determined. 5891 5892 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5893 MatSetValues(), MatSetColoring() 5894 @*/ 5895 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v) 5896 { 5897 PetscErrorCode ierr; 5898 5899 PetscFunctionBegin; 5900 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5901 PetscValidType(mat,1); 5902 PetscValidPointer(v,3); 5903 5904 if (!mat->assembled) { 5905 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5906 } 5907 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5908 if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5909 ierr = (*mat->ops->setvaluesadifor)(mat,nl,v);CHKERRQ(ierr); 5910 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5911 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5912 PetscFunctionReturn(0); 5913 } 5914 5915 #undef __FUNCT__ 5916 #define __FUNCT__ "MatDiagonalScaleLocal" 5917 /*@ 5918 MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 5919 ghosted ones. 5920 5921 Not Collective 5922 5923 Input Parameters: 5924 + mat - the matrix 5925 - diag = the diagonal values, including ghost ones 5926 5927 Level: developer 5928 5929 Notes: Works only for MPIAIJ and MPIBAIJ matrices 5930 5931 .seealso: MatDiagonalScale() 5932 @*/ 5933 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag) 5934 { 5935 PetscErrorCode ierr; 5936 PetscMPIInt size; 5937 5938 PetscFunctionBegin; 5939 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5940 PetscValidHeaderSpecific(diag,VEC_COOKIE,2); 5941 PetscValidType(mat,1); 5942 5943 if (!mat->assembled) { 5944 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5945 } 5946 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5947 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 5948 if (size == 1) { 5949 PetscInt n,m; 5950 ierr = VecGetSize(diag,&n);CHKERRQ(ierr); 5951 ierr = MatGetSize(mat,0,&m);CHKERRQ(ierr); 5952 if (m == n) { 5953 ierr = MatDiagonalScale(mat,0,diag);CHKERRQ(ierr); 5954 } else { 5955 SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions"); 5956 } 5957 } else { 5958 PetscErrorCode (*f)(Mat,Vec); 5959 ierr = PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);CHKERRQ(ierr); 5960 if (f) { 5961 ierr = (*f)(mat,diag);CHKERRQ(ierr); 5962 } else { 5963 SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices"); 5964 } 5965 } 5966 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5967 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5968 PetscFunctionReturn(0); 5969 } 5970 5971 #undef __FUNCT__ 5972 #define __FUNCT__ "MatGetInertia" 5973 /*@ 5974 MatGetInertia - Gets the inertia from a factored matrix 5975 5976 Collective on Mat 5977 5978 Input Parameter: 5979 . mat - the matrix 5980 5981 Output Parameters: 5982 + nneg - number of negative eigenvalues 5983 . nzero - number of zero eigenvalues 5984 - npos - number of positive eigenvalues 5985 5986 Level: advanced 5987 5988 Notes: Matrix must have been factored by MatCholeskyFactor() 5989 5990 5991 @*/ 5992 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos) 5993 { 5994 PetscErrorCode ierr; 5995 5996 PetscFunctionBegin; 5997 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5998 PetscValidType(mat,1); 5999 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 6000 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled"); 6001 if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 6002 ierr = (*mat->ops->getinertia)(mat,nneg,nzero,npos);CHKERRQ(ierr); 6003 PetscFunctionReturn(0); 6004 } 6005 6006 /* ----------------------------------------------------------------*/ 6007 #undef __FUNCT__ 6008 #define __FUNCT__ "MatSolves" 6009 /*@ 6010 MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors 6011 6012 Collective on Mat and Vecs 6013 6014 Input Parameters: 6015 + mat - the factored matrix 6016 - b - the right-hand-side vectors 6017 6018 Output Parameter: 6019 . x - the result vectors 6020 6021 Notes: 6022 The vectors b and x cannot be the same. I.e., one cannot 6023 call MatSolves(A,x,x). 6024 6025 Notes: 6026 Most users should employ the simplified KSP interface for linear solvers 6027 instead of working directly with matrix algebra routines such as this. 6028 See, e.g., KSPCreate(). 6029 6030 Level: developer 6031 6032 Concepts: matrices^triangular solves 6033 6034 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve() 6035 @*/ 6036 PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x) 6037 { 6038 PetscErrorCode ierr; 6039 6040 PetscFunctionBegin; 6041 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 6042 PetscValidType(mat,1); 6043 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 6044 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 6045 if (!mat->rmap.N && !mat->cmap.N) PetscFunctionReturn(0); 6046 6047 if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 6048 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6049 ierr = PetscLogEventBegin(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6050 ierr = (*mat->ops->solves)(mat,b,x);CHKERRQ(ierr); 6051 ierr = PetscLogEventEnd(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6052 PetscFunctionReturn(0); 6053 } 6054 6055 #undef __FUNCT__ 6056 #define __FUNCT__ "MatIsSymmetric" 6057 /*@ 6058 MatIsSymmetric - Test whether a matrix is symmetric 6059 6060 Collective on Mat 6061 6062 Input Parameter: 6063 + A - the matrix to test 6064 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose) 6065 6066 Output Parameters: 6067 . flg - the result 6068 6069 Level: intermediate 6070 6071 Concepts: matrix^symmetry 6072 6073 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 6074 @*/ 6075 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg) 6076 { 6077 PetscErrorCode ierr; 6078 6079 PetscFunctionBegin; 6080 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6081 PetscValidPointer(flg,2); 6082 if (!A->symmetric_set) { 6083 if (!A->ops->issymmetric) { 6084 MatType mattype; 6085 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 6086 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 6087 } 6088 ierr = (*A->ops->issymmetric)(A,tol,&A->symmetric);CHKERRQ(ierr); 6089 A->symmetric_set = PETSC_TRUE; 6090 if (A->symmetric) { 6091 A->structurally_symmetric_set = PETSC_TRUE; 6092 A->structurally_symmetric = PETSC_TRUE; 6093 } 6094 } 6095 *flg = A->symmetric; 6096 PetscFunctionReturn(0); 6097 } 6098 6099 #undef __FUNCT__ 6100 #define __FUNCT__ "MatIsSymmetricKnown" 6101 /*@ 6102 MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric. 6103 6104 Collective on Mat 6105 6106 Input Parameter: 6107 . A - the matrix to check 6108 6109 Output Parameters: 6110 + set - if the symmetric flag is set (this tells you if the next flag is valid) 6111 - flg - the result 6112 6113 Level: advanced 6114 6115 Concepts: matrix^symmetry 6116 6117 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric() 6118 if you want it explicitly checked 6119 6120 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 6121 @*/ 6122 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg) 6123 { 6124 PetscFunctionBegin; 6125 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6126 PetscValidPointer(set,2); 6127 PetscValidPointer(flg,3); 6128 if (A->symmetric_set) { 6129 *set = PETSC_TRUE; 6130 *flg = A->symmetric; 6131 } else { 6132 *set = PETSC_FALSE; 6133 } 6134 PetscFunctionReturn(0); 6135 } 6136 6137 #undef __FUNCT__ 6138 #define __FUNCT__ "MatIsHermitianKnown" 6139 /*@ 6140 MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian. 6141 6142 Collective on Mat 6143 6144 Input Parameter: 6145 . A - the matrix to check 6146 6147 Output Parameters: 6148 + set - if the hermitian flag is set (this tells you if the next flag is valid) 6149 - flg - the result 6150 6151 Level: advanced 6152 6153 Concepts: matrix^symmetry 6154 6155 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian() 6156 if you want it explicitly checked 6157 6158 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 6159 @*/ 6160 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg) 6161 { 6162 PetscFunctionBegin; 6163 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6164 PetscValidPointer(set,2); 6165 PetscValidPointer(flg,3); 6166 if (A->hermitian_set) { 6167 *set = PETSC_TRUE; 6168 *flg = A->hermitian; 6169 } else { 6170 *set = PETSC_FALSE; 6171 } 6172 PetscFunctionReturn(0); 6173 } 6174 6175 #undef __FUNCT__ 6176 #define __FUNCT__ "MatIsStructurallySymmetric" 6177 /*@ 6178 MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric 6179 6180 Collective on Mat 6181 6182 Input Parameter: 6183 . A - the matrix to test 6184 6185 Output Parameters: 6186 . flg - the result 6187 6188 Level: intermediate 6189 6190 Concepts: matrix^symmetry 6191 6192 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption() 6193 @*/ 6194 PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg) 6195 { 6196 PetscErrorCode ierr; 6197 6198 PetscFunctionBegin; 6199 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6200 PetscValidPointer(flg,2); 6201 if (!A->structurally_symmetric_set) { 6202 if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric"); 6203 ierr = (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);CHKERRQ(ierr); 6204 A->structurally_symmetric_set = PETSC_TRUE; 6205 } 6206 *flg = A->structurally_symmetric; 6207 PetscFunctionReturn(0); 6208 } 6209 6210 #undef __FUNCT__ 6211 #define __FUNCT__ "MatIsHermitian" 6212 /*@ 6213 MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose. 6214 6215 Collective on Mat 6216 6217 Input Parameter: 6218 . A - the matrix to test 6219 6220 Output Parameters: 6221 . flg - the result 6222 6223 Level: intermediate 6224 6225 Concepts: matrix^symmetry 6226 6227 .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption() 6228 @*/ 6229 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg) 6230 { 6231 PetscErrorCode ierr; 6232 6233 PetscFunctionBegin; 6234 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6235 PetscValidPointer(flg,2); 6236 if (!A->hermitian_set) { 6237 if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian"); 6238 ierr = (*A->ops->ishermitian)(A,&A->hermitian);CHKERRQ(ierr); 6239 A->hermitian_set = PETSC_TRUE; 6240 if (A->hermitian) { 6241 A->structurally_symmetric_set = PETSC_TRUE; 6242 A->structurally_symmetric = PETSC_TRUE; 6243 } 6244 } 6245 *flg = A->hermitian; 6246 PetscFunctionReturn(0); 6247 } 6248 6249 #undef __FUNCT__ 6250 #define __FUNCT__ "MatStashGetInfo" 6251 extern PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*); 6252 /*@ 6253 MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need 6254 to be communicated to other processors during the MatAssemblyBegin/End() process 6255 6256 Not collective 6257 6258 Input Parameter: 6259 . vec - the vector 6260 6261 Output Parameters: 6262 + nstash - the size of the stash 6263 . reallocs - the number of additional mallocs incurred. 6264 . bnstash - the size of the block stash 6265 - breallocs - the number of additional mallocs incurred.in the block stash 6266 6267 Level: advanced 6268 6269 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize() 6270 6271 @*/ 6272 PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs) 6273 { 6274 PetscErrorCode ierr; 6275 PetscFunctionBegin; 6276 ierr = MatStashGetInfo_Private(&mat->stash,nstash,reallocs);CHKERRQ(ierr); 6277 ierr = MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);CHKERRQ(ierr); 6278 PetscFunctionReturn(0); 6279 } 6280 6281 #undef __FUNCT__ 6282 #define __FUNCT__ "MatGetVecs" 6283 /*@ 6284 MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 6285 parallel layout 6286 6287 Collective on Mat 6288 6289 Input Parameter: 6290 . mat - the matrix 6291 6292 Output Parameter: 6293 + right - (optional) vector that the matrix can be multiplied against 6294 - left - (optional) vector that the matrix vector product can be stored in 6295 6296 Level: advanced 6297 6298 .seealso: MatCreate() 6299 @*/ 6300 PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left) 6301 { 6302 PetscErrorCode ierr; 6303 6304 PetscFunctionBegin; 6305 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 6306 PetscValidType(mat,1); 6307 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6308 if (mat->ops->getvecs) { 6309 ierr = (*mat->ops->getvecs)(mat,right,left);CHKERRQ(ierr); 6310 } else { 6311 PetscMPIInt size; 6312 ierr = MPI_Comm_size(mat->comm, &size);CHKERRQ(ierr); 6313 if (right) { 6314 ierr = VecCreate(mat->comm,right);CHKERRQ(ierr); 6315 ierr = VecSetSizes(*right,mat->cmap.n,PETSC_DETERMINE);CHKERRQ(ierr); 6316 if (size > 1) {ierr = VecSetType(*right,VECMPI);CHKERRQ(ierr);} 6317 else {ierr = VecSetType(*right,VECSEQ);CHKERRQ(ierr);} 6318 } 6319 if (left) { 6320 ierr = VecCreate(mat->comm,left);CHKERRQ(ierr); 6321 ierr = VecSetSizes(*left,mat->rmap.n,PETSC_DETERMINE);CHKERRQ(ierr); 6322 if (size > 1) {ierr = VecSetType(*left,VECMPI);CHKERRQ(ierr);} 6323 else {ierr = VecSetType(*left,VECSEQ);CHKERRQ(ierr);} 6324 } 6325 } 6326 if (right) {ierr = VecSetBlockSize(*right,mat->rmap.bs);CHKERRQ(ierr);} 6327 if (left) {ierr = VecSetBlockSize(*left,mat->rmap.bs);CHKERRQ(ierr);} 6328 PetscFunctionReturn(0); 6329 } 6330 6331 #undef __FUNCT__ 6332 #define __FUNCT__ "MatFactorInfoInitialize" 6333 /*@ 6334 MatFactorInfoInitialize - Initializes a MatFactorInfo data structure 6335 with default values. 6336 6337 Not Collective 6338 6339 Input Parameters: 6340 . info - the MatFactorInfo data structure 6341 6342 6343 Notes: The solvers are generally used through the KSP and PC objects, for example 6344 PCLU, PCILU, PCCHOLESKY, PCICC 6345 6346 Level: developer 6347 6348 .seealso: MatFactorInfo 6349 @*/ 6350 6351 PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info) 6352 { 6353 PetscErrorCode ierr; 6354 6355 PetscFunctionBegin; 6356 ierr = PetscMemzero(info,sizeof(MatFactorInfo));CHKERRQ(ierr); 6357 PetscFunctionReturn(0); 6358 } 6359 6360 #undef __FUNCT__ 6361 #define __FUNCT__ "MatPtAP" 6362 /*@ 6363 MatPtAP - Creates the matrix projection C = P^T * A * P 6364 6365 Collective on Mat 6366 6367 Input Parameters: 6368 + A - the matrix 6369 . P - the projection matrix 6370 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6371 - fill - expected fill as ratio of nnz(C)/nnz(A) 6372 6373 Output Parameters: 6374 . C - the product matrix 6375 6376 Notes: 6377 C will be created and must be destroyed by the user with MatDestroy(). 6378 6379 This routine is currently only implemented for pairs of AIJ matrices and classes 6380 which inherit from AIJ. 6381 6382 Level: intermediate 6383 6384 .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult() 6385 @*/ 6386 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C) 6387 { 6388 PetscErrorCode ierr; 6389 6390 PetscFunctionBegin; 6391 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6392 PetscValidType(A,1); 6393 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6394 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6395 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6396 PetscValidType(P,2); 6397 MatPreallocated(P); 6398 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6399 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6400 PetscValidPointer(C,3); 6401 if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N); 6402 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 6403 ierr = MatPreallocated(A);CHKERRQ(ierr); 6404 6405 ierr = PetscLogEventBegin(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 6406 ierr = (*A->ops->ptap)(A,P,scall,fill,C);CHKERRQ(ierr); 6407 ierr = PetscLogEventEnd(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 6408 6409 PetscFunctionReturn(0); 6410 } 6411 6412 #undef __FUNCT__ 6413 #define __FUNCT__ "MatPtAPNumeric" 6414 /*@ 6415 MatPtAPNumeric - Computes the matrix projection C = P^T * A * P 6416 6417 Collective on Mat 6418 6419 Input Parameters: 6420 + A - the matrix 6421 - P - the projection matrix 6422 6423 Output Parameters: 6424 . C - the product matrix 6425 6426 Notes: 6427 C must have been created by calling MatPtAPSymbolic and must be destroyed by 6428 the user using MatDeatroy(). 6429 6430 This routine is currently only implemented for pairs of AIJ matrices and classes 6431 which inherit from AIJ. C will be of type MATAIJ. 6432 6433 Level: intermediate 6434 6435 .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric() 6436 @*/ 6437 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C) 6438 { 6439 PetscErrorCode ierr; 6440 6441 PetscFunctionBegin; 6442 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6443 PetscValidType(A,1); 6444 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6445 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6446 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6447 PetscValidType(P,2); 6448 MatPreallocated(P); 6449 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6450 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6451 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 6452 PetscValidType(C,3); 6453 MatPreallocated(C); 6454 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6455 if (P->cmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->rmap.N); 6456 if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N); 6457 if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N); 6458 if (P->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap.N,C->cmap.N); 6459 ierr = MatPreallocated(A);CHKERRQ(ierr); 6460 6461 ierr = PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 6462 ierr = (*A->ops->ptapnumeric)(A,P,C);CHKERRQ(ierr); 6463 ierr = PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 6464 PetscFunctionReturn(0); 6465 } 6466 6467 #undef __FUNCT__ 6468 #define __FUNCT__ "MatPtAPSymbolic" 6469 /*@ 6470 MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P 6471 6472 Collective on Mat 6473 6474 Input Parameters: 6475 + A - the matrix 6476 - P - the projection matrix 6477 6478 Output Parameters: 6479 . C - the (i,j) structure of the product matrix 6480 6481 Notes: 6482 C will be created and must be destroyed by the user with MatDestroy(). 6483 6484 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 6485 which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using 6486 this (i,j) structure by calling MatPtAPNumeric(). 6487 6488 Level: intermediate 6489 6490 .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic() 6491 @*/ 6492 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C) 6493 { 6494 PetscErrorCode ierr; 6495 6496 PetscFunctionBegin; 6497 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6498 PetscValidType(A,1); 6499 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6500 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6501 if (fill <1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 6502 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 6503 PetscValidType(P,2); 6504 MatPreallocated(P); 6505 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6506 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6507 PetscValidPointer(C,3); 6508 6509 if (P->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap.N,A->cmap.N); 6510 if (A->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->rmap.N,A->cmap.N); 6511 ierr = MatPreallocated(A);CHKERRQ(ierr); 6512 ierr = PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 6513 ierr = (*A->ops->ptapsymbolic)(A,P,fill,C);CHKERRQ(ierr); 6514 ierr = PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 6515 6516 ierr = MatSetBlockSize(*C,A->rmap.bs);CHKERRQ(ierr); 6517 6518 PetscFunctionReturn(0); 6519 } 6520 6521 #undef __FUNCT__ 6522 #define __FUNCT__ "MatMatMult" 6523 /*@ 6524 MatMatMult - Performs Matrix-Matrix Multiplication C=A*B. 6525 6526 Collective on Mat 6527 6528 Input Parameters: 6529 + A - the left matrix 6530 . B - the right matrix 6531 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6532 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6533 6534 Output Parameters: 6535 . C - the product matrix 6536 6537 Notes: 6538 C will be created and must be destroyed by the user with MatDestroy(). 6539 Unless scall is MAT_REUSE_MATRIX 6540 6541 If you have many matrices with the same non-zero structure to multiply, you 6542 should either 6543 $ 1) use MAT_REUSE_MATRIX in all calls but the first or 6544 $ 2) call MatMatMultSymbolic() once and then MatMatMultNumeric() for each product needed 6545 6546 Level: intermediate 6547 6548 .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP() 6549 @*/ 6550 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 6551 { 6552 PetscErrorCode ierr; 6553 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6554 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6555 PetscErrorCode (*mult)(Mat,Mat,MatReuse,PetscReal,Mat *)=PETSC_NULL; 6556 6557 PetscFunctionBegin; 6558 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6559 PetscValidType(A,1); 6560 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6561 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6562 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6563 PetscValidType(B,2); 6564 MatPreallocated(B); 6565 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6566 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6567 PetscValidPointer(C,3); 6568 if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N); 6569 if (fill == PETSC_DEFAULT) fill = 2.0; 6570 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 6571 ierr = MatPreallocated(A);CHKERRQ(ierr); 6572 6573 fA = A->ops->matmult; 6574 fB = B->ops->matmult; 6575 if (fB == fA) { 6576 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name); 6577 mult = fB; 6578 } else { 6579 /* dispatch based on the type of A and B */ 6580 char multname[256]; 6581 ierr = PetscStrcpy(multname,"MatMatMult_");CHKERRQ(ierr); 6582 ierr = PetscStrcat(multname,A->type_name);CHKERRQ(ierr); 6583 ierr = PetscStrcat(multname,"_");CHKERRQ(ierr); 6584 ierr = PetscStrcat(multname,B->type_name);CHKERRQ(ierr); 6585 ierr = PetscStrcat(multname,"_C");CHKERRQ(ierr); /* e.g., multname = "MatMatMult_aij_dense_C" */ 6586 ierr = PetscObjectQueryFunction((PetscObject)B,multname,(void (**)(void))&mult);CHKERRQ(ierr); 6587 if (!mult) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6588 } 6589 ierr = PetscLogEventBegin(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6590 ierr = (*mult)(A,B,scall,fill,C);CHKERRQ(ierr); 6591 ierr = PetscLogEventEnd(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6592 PetscFunctionReturn(0); 6593 } 6594 6595 #undef __FUNCT__ 6596 #define __FUNCT__ "MatMatMultSymbolic" 6597 /*@ 6598 MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure 6599 of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric(). 6600 6601 Collective on Mat 6602 6603 Input Parameters: 6604 + A - the left matrix 6605 . B - the right matrix 6606 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6607 6608 Output Parameters: 6609 . C - the matrix containing the ij structure of product matrix 6610 6611 Notes: 6612 C will be created and must be destroyed by the user with MatDestroy(). 6613 6614 This routine is currently implemented for 6615 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ. 6616 - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE. 6617 6618 Level: intermediate 6619 6620 .seealso: MatMatMult(), MatMatMultNumeric() 6621 @*/ 6622 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C) 6623 { 6624 PetscErrorCode ierr; 6625 PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *); 6626 PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *); 6627 PetscErrorCode (*symbolic)(Mat,Mat,PetscReal,Mat *)=PETSC_NULL; 6628 6629 PetscFunctionBegin; 6630 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6631 PetscValidType(A,1); 6632 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6633 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6634 6635 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6636 PetscValidType(B,2); 6637 MatPreallocated(B); 6638 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6639 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6640 PetscValidPointer(C,3); 6641 6642 if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N); 6643 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 6644 ierr = MatPreallocated(A);CHKERRQ(ierr); 6645 6646 Asymbolic = A->ops->matmultsymbolic; 6647 Bsymbolic = B->ops->matmultsymbolic; 6648 if (Asymbolic == Bsymbolic){ 6649 if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name); 6650 symbolic = Bsymbolic; 6651 } else { /* dispatch based on the type of A and B */ 6652 char symbolicname[256]; 6653 ierr = PetscStrcpy(symbolicname,"MatMatMultSymbolic_");CHKERRQ(ierr); 6654 ierr = PetscStrcat(symbolicname,A->type_name);CHKERRQ(ierr); 6655 ierr = PetscStrcat(symbolicname,"_");CHKERRQ(ierr); 6656 ierr = PetscStrcat(symbolicname,B->type_name);CHKERRQ(ierr); 6657 ierr = PetscStrcat(symbolicname,"_C");CHKERRQ(ierr); 6658 ierr = PetscObjectQueryFunction((PetscObject)B,symbolicname,(void (**)(void))&symbolic);CHKERRQ(ierr); 6659 if (!symbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6660 } 6661 ierr = PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6662 ierr = (*symbolic)(A,B,fill,C);CHKERRQ(ierr); 6663 ierr = PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6664 PetscFunctionReturn(0); 6665 } 6666 6667 #undef __FUNCT__ 6668 #define __FUNCT__ "MatMatMultNumeric" 6669 /*@ 6670 MatMatMultNumeric - Performs the numeric matrix-matrix product. 6671 Call this routine after first calling MatMatMultSymbolic(). 6672 6673 Collective on Mat 6674 6675 Input Parameters: 6676 + A - the left matrix 6677 - B - the right matrix 6678 6679 Output Parameters: 6680 . C - the product matrix, whose ij structure was defined from MatMatMultSymbolic(). 6681 6682 Notes: 6683 C must have been created with MatMatMultSymbolic. 6684 6685 This routine is currently implemented for 6686 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ. 6687 - pairs of AIJ (A) and Dense (B) matrix, C will be of type MATDENSE. 6688 6689 Level: intermediate 6690 6691 .seealso: MatMatMult(), MatMatMultSymbolic() 6692 @*/ 6693 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C) 6694 { 6695 PetscErrorCode ierr; 6696 PetscErrorCode (*Anumeric)(Mat,Mat,Mat); 6697 PetscErrorCode (*Bnumeric)(Mat,Mat,Mat); 6698 PetscErrorCode (*numeric)(Mat,Mat,Mat)=PETSC_NULL; 6699 6700 PetscFunctionBegin; 6701 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6702 PetscValidType(A,1); 6703 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6704 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6705 6706 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6707 PetscValidType(B,2); 6708 MatPreallocated(B); 6709 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6710 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6711 6712 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 6713 PetscValidType(C,3); 6714 MatPreallocated(C); 6715 if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6716 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6717 6718 if (B->cmap.N!=C->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap.N,C->cmap.N); 6719 if (B->rmap.N!=A->cmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->cmap.N); 6720 if (A->rmap.N!=C->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap.N,C->rmap.N); 6721 ierr = MatPreallocated(A);CHKERRQ(ierr); 6722 6723 Anumeric = A->ops->matmultnumeric; 6724 Bnumeric = B->ops->matmultnumeric; 6725 if (Anumeric == Bnumeric){ 6726 if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name); 6727 numeric = Bnumeric; 6728 } else { 6729 char numericname[256]; 6730 ierr = PetscStrcpy(numericname,"MatMatMultNumeric_");CHKERRQ(ierr); 6731 ierr = PetscStrcat(numericname,A->type_name);CHKERRQ(ierr); 6732 ierr = PetscStrcat(numericname,"_");CHKERRQ(ierr); 6733 ierr = PetscStrcat(numericname,B->type_name);CHKERRQ(ierr); 6734 ierr = PetscStrcat(numericname,"_C");CHKERRQ(ierr); 6735 ierr = PetscObjectQueryFunction((PetscObject)B,numericname,(void (**)(void))&numeric);CHKERRQ(ierr); 6736 if (!numeric) 6737 SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6738 } 6739 ierr = PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6740 ierr = (*numeric)(A,B,C);CHKERRQ(ierr); 6741 ierr = PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6742 PetscFunctionReturn(0); 6743 } 6744 6745 #undef __FUNCT__ 6746 #define __FUNCT__ "MatMatMultTranspose" 6747 /*@ 6748 MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B. 6749 6750 Collective on Mat 6751 6752 Input Parameters: 6753 + A - the left matrix 6754 . B - the right matrix 6755 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6756 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6757 6758 Output Parameters: 6759 . C - the product matrix 6760 6761 Notes: 6762 C will be created and must be destroyed by the user with MatDestroy(). 6763 6764 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 6765 which inherit from SeqAIJ. C will be of type MATSEQAIJ. 6766 6767 Level: intermediate 6768 6769 .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP() 6770 @*/ 6771 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 6772 { 6773 PetscErrorCode ierr; 6774 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6775 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6776 6777 PetscFunctionBegin; 6778 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6779 PetscValidType(A,1); 6780 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6781 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6782 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6783 PetscValidType(B,2); 6784 MatPreallocated(B); 6785 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6786 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6787 PetscValidPointer(C,3); 6788 if (B->rmap.N!=A->rmap.N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap.N,A->rmap.N); 6789 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 6790 ierr = MatPreallocated(A);CHKERRQ(ierr); 6791 6792 fA = A->ops->matmulttranspose; 6793 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name); 6794 fB = B->ops->matmulttranspose; 6795 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name); 6796 if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6797 6798 ierr = PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6799 ierr = (*A->ops->matmulttranspose)(A,B,scall,fill,C);CHKERRQ(ierr); 6800 ierr = PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6801 6802 PetscFunctionReturn(0); 6803 } 6804 6805 #undef __FUNCT__ 6806 #define __FUNCT__ "MatGetRedundantMatrix" 6807 /*@C 6808 MatGetRedundantMatrix - Create redundant matrices and put them into processors of subcommunicators. 6809 6810 Collective on Mat 6811 6812 Input Parameters: 6813 + mat - the matrix 6814 . nsubcomm - the number of subcommunicators (= number of redundant pareallel or sequential matrices) 6815 . subcomm - MPI communicator split from the communicator where mat resides in 6816 . mlocal_red - number of local rows of the redundant matrix 6817 - reuse - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6818 6819 Output Parameter: 6820 . matredundant - redundant matrix 6821 6822 Notes: 6823 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 6824 original matrix has not changed from that last call to MatGetRedundantMatrix(). 6825 6826 This routine creates the duplicated matrices in subcommunicators; you should NOT create them before 6827 calling it. 6828 6829 Only MPIAIJ matrix is supported. 6830 6831 Level: advanced 6832 6833 Concepts: subcommunicator 6834 Concepts: duplicate matrix 6835 6836 .seealso: MatDestroy() 6837 @*/ 6838 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRedundantMatrix(Mat mat,PetscInt nsubcomm,MPI_Comm subcomm,PetscInt mlocal_red,MatReuse reuse,Mat *matredundant) 6839 { 6840 PetscErrorCode ierr; 6841 6842 PetscFunctionBegin; 6843 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 6844 if (nsubcomm && reuse == MAT_REUSE_MATRIX) { 6845 PetscValidPointer(*matredundant,6); 6846 PetscValidHeaderSpecific(*matredundant,MAT_COOKIE,6); 6847 } 6848 if (!mat->ops->getredundantmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 6849 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6850 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6851 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6852 6853 ierr = PetscLogEventBegin(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 6854 ierr = (*mat->ops->getredundantmatrix)(mat,nsubcomm,subcomm,mlocal_red,reuse,matredundant);CHKERRQ(ierr); 6855 ierr = PetscLogEventEnd(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 6856 PetscFunctionReturn(0); 6857 } 6858