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