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