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