petsc4py.PETSc.Mat#
- class petsc4py.PETSc.Mat#
Bases:
ObjectMatrix object.
Mat is described in the
PETSc manual.See also
Enumerations
Matrix assembly type.
Matrix duplicate option.
Factored matrix shift type.
Matrix info type.
Matrix option.
Factored matrix ordering type.
Matrix SOR type.
Factored matrix solver type.
Associate structured grid coordinates with matrix indices.
Matrix modification structure.
Matrix type.
Methods Summary
H2OpusCompress(tol)Compress a hierarchical matrix.
H2OpusLowRankUpdate(U[, V, s])Perform a low-rank update of the form
self+= sUVᵀ.Orthogonalize the basis tree of a hierarchical matrix.
SOR(b, x[, omega, sortype, shift, its, lits])Compute relaxation (SOR, Gauss-Seidel) sweeps.
appendOptionsPrefix([prefix])Append to the prefix used for searching for options in the database.
assemble([assembly])Assemble the matrix.
assemblyBegin([assembly])Begin an assembling stage of the matrix.
assemblyEnd([assembly])Complete an assembling stage of the matrix initiated with
assemblyBegin.axpy(alpha, X[, structure])Perform the matrix summation
self+ = ɑ·X.aypx(alpha, X[, structure])Perform the matrix summation
self= ɑ·self+ X.bindToCPU(flg)Mark a matrix to temporarily stay on the CPU.
Query if a matrix is bound to the CPU.
chop(tol)Set entries smallest of tol (in absolute values) to zero.
conjugate([out])Return the conjugate matrix.
convert([mat_type, out])Convert the matrix type.
copy([result, structure])Return a copy of the matrix.
create([comm])Create the matrix.
createAIJ(size[, bsize, nnz, csr, comm])Create a sparse
Type.AIJmatrix, optionally preallocating.createAIJCRL(size[, bsize, nnz, csr, comm])Create a sparse
Type.AIJCRLmatrix.createAIJWithArrays(size, csr[, bsize, comm])Create a sparse
Type.AIJmatrix with data in CSR format.createBAIJ(size, bsize[, nnz, csr, comm])Create a sparse blocked
Type.BAIJmatrix, optionally preallocating.createConstantDiagonal(size, diag[, comm])Create a diagonal matrix of type
Type.CONSTANTDIAGONAL.createDense(size[, bsize, array, comm])Create a
Type.DENSEmatrix.createDenseCUDA(size[, bsize, array, ...])Create a
Type.DENSECUDAmatrix with optional host and device data.createDiagonal(diag)Create a diagonal matrix of type
Type.DIAGONAL.createH2OpusFromMat(A[, coordinates, dist, ...])Create a hierarchical
Type.H2OPUSmatrix sampling from a provided operator.Create a
Type.HERMITIANTRANSPOSEmatrix that behaves like (A*)ᵀ.createIS(size[, bsize, lgmapr, lgmapc, comm])Create a
Type.ISmatrix representing globally unassembled operators.createLRC(A, U, c, V)Create a low-rank correction
Type.LRCmatrix representing A + UCVᵀ.createNest(mats[, isrows, iscols, comm])Create a
Type.NESTmatrix containing multiple submatrices.createNormal(mat)Create a
Type.NORMALmatrix representing AᵀA.Create a
Type.NORMALHERMITIANmatrix representing (A*)ᵀA.createPython(size[, context, comm])Create a
Type.PYTHONmatrix.createSBAIJ(size, bsize[, nnz, csr, comm])Create a sparse
Type.SBAIJmatrix in symmetric block format.createScatter(scatter[, comm])Create a
Type.SCATTERmatrix from a vector scatter.createSchurComplement(A00, Ap00, A01, A10[, A11])Create a
Type.SCHURCOMPLEMENTmatrix.createSubMatrices(isrows[, iscols, submats])Return several sequential submatrices.
createSubMatrix(isrow[, iscol, submat])Return a submatrix.
createSubMatrixVirtual(A, isrow[, iscol])Create a
Type.SUBMATRIXmatrix that acts as a submatrix.createTranspose(mat)Create a
Type.TRANSPOSEmatrix that behaves like Aᵀ.Return a left vector, a vector that the matrix vector product can be stored in.
Return a right vector, a vector that the matrix can be multiplied against.
createVecs([side])Return vectors that can be used in matrix vector products.
destroy()Destroy the matrix.
diagonalScale([L, R])Perform left and/or right diagonal scaling of the matrix.
duplicate([copy])Return a clone of the matrix.
equal(mat)Return the result of matrix comparison.
factorCholesky(isperm[, options])Perform an in-place Cholesky factorization.
factorICC(isperm[, options])Perform an in-place an incomplete Cholesky factorization.
factorILU(isrow, iscol[, options])Perform an in-place ILU factorization.
factorLU(isrow, iscol[, options])Perform an in-place LU factorization.
factorNumericCholesky(mat[, options])Not implemented.
factorNumericLU(mat[, options])Not implemented.
factorSymbolicCholesky(isperm[, options])Not implemented.
factorSymbolicICC(isperm[, options])Not implemented.
factorSymbolicILU(isrow, iscol[, options])Not implemented.
factorSymbolicLU(mat, isrow, iscol[, options])Not implemented.
Return the index set of empty rows.
fixISLocalEmpty([fix])Compress out zero local rows from the local matrices.
Return the matrix block size.
Return the row and column block sizes.
getColumnIJ([symmetric, compressed])Return the CSC representation of the local sparsity pattern.
getColumnVector(column[, result])Return the columnᵗʰ column vector of the matrix.
getDM()Return the DM defining the data layout of the matrix.
getDenseArray([readonly])Return the array where the data is stored.
getDenseColumnVec(i[, mode])Return the iᵗʰ column vector of the dense matrix.
Return the leading dimension of the array used by the dense matrix.
Return the local part of the dense matrix.
getDenseSubMatrix([rbegin, rend, cbegin, cend])Get access to a submatrix of a
Type.DENSEmatrix.getDiagonal([result])Return the diagonal of the matrix.
Return the part of the matrix associated with the on-process coupling.
Get the flag for repeated entries in the local to global map.
Return the local matrix stored inside a
Type.ISmatrix.Return the inertia from a factored matrix.
getInfo([info])Return summary information.
getLGMap()Return the local-to-global mappings.
Get the initial Jacobian of the LMVM matrix.
Get the KSP of the LMVM matrix.
Return the constituents of a
Type.LRCmatrix.Return the local number of rows and columns.
getLocalSubMatrix(isrow, iscol[, submat])Return a reference to a submatrix specified in local numbering.
getMumpsCntl(icntl)Return the MUMPS parameter,
CNTL[icntl].getMumpsIcntl(icntl)Return the MUMPS parameter,
ICNTL[icntl].getMumpsInfo(icntl)Return the MUMPS parameter,
INFO[icntl].getMumpsInfog(icntl)Return the MUMPS parameter,
INFOG[icntl].getMumpsRinfo(icntl)Return the MUMPS parameter,
RINFO[icntl].getMumpsRinfog(icntl)Return the MUMPS parameter,
RINFOG[icntl].Return the near-nullspace.
Return the index sets representing the row and column spaces.
Return the local index sets representing the row and column spaces.
Return the number of rows and columns of the matrix.
getNestSubMatrix(i, j)Return a single submatrix.
Return the nullspace.
getOption(option)Return the option value.
Return the prefix used for searching for options in the database.
getOrdering(ord_type)Return a reordering for a matrix to improve a LU factorization.
Return the ranges of rows and columns owned by each process as index sets.
Return the locally owned range of rows.
Return the locally owned range of columns.
Return the range of rows owned by each process.
Return the range of columns owned by each process.
Return the instance of the class implementing the required Python methods.
Return the fully qualified Python name of the class used by the matrix.
getRedundantMatrix(nsubcomm[, subcomm, out])Return redundant matrices on subcommunicators.
getRow(row)Return the column indices and values for the requested row.
getRowIJ([symmetric, compressed])Return the CSR representation of the local sparsity pattern.
getRowSum([result])Return the row-sum vector.
Return Schur complement sub-matrices.
getSize()Return the global number of rows and columns.
getSizes()Return the tuple of matrix layouts.
Return the internal matrix of a
Type.TRANSPOSEmatrix.Return the transpose nullspace.
getType()Return the type of the matrix.
getValue(row, col)Return the value in the (row, col) position.
getValues(rows, cols[, values])Return the values in the
zip(rows, cols)positions.Return the CSR representation of the local part of the matrix.
Return the vector type used by the matrix.
hermitianTranspose([out])Return the transposed Hermitian matrix.
imagPart([out])Return the imaginary part of the matrix.
increaseOverlap(iset[, overlap])Increase the overlap of a index set.
Return the inverse of the block-diagonal entries.
The boolean flag indicating if the matrix is assembled.
isHermitian([tol])Return the boolean indicating if the matrix is Hermitian.
Return the 2-tuple indicating if the matrix is known to be Hermitian.
isLinear([n])Return whether the Mat is a linear operator.
Return the boolean indicating if the matrix is structurally symmetric.
isSymmetric([tol])Return the boolean indicating if the matrix is symmetric.
Return the 2-tuple indicating if the matrix is known to be symmetric.
isTranspose([mat, tol])Return the result of matrix comparison with transposition.
kron(mat[, result])Compute C, the Kronecker product of A and B.
load(viewer)Load a matrix.
matMatMult(B, C[, result, fill])Perform matrix-matrix-matrix multiplication D=ABC.
matMult(mat[, result, fill])Perform matrix-matrix multiplication C=AB.
matSolve(B, X)Solve AX=B, given a factored matrix A.
matTransposeMult(mat[, result, fill])Perform matrix-matrix multiplication C=ABᵀ.
mult(x, y)Perform the matrix vector product y = A @ x.
multAdd(x, v, y)Perform the matrix vector product with addition y = A @ x + v.
multHermitian(x, y)Perform the Hermitian matrix vector product y = A^H @ x.
multHermitianAdd(x, v, y)Perform the Hermitian matrix vector product with addition y = A^H @ x + v.
multTranspose(x, y)Perform the transposed matrix vector product y = A^T @ x.
multTransposeAdd(x, v, y)Perform the transposed matrix vector product with addition y = A^T @ x + v.
norm([norm_type])Compute the requested matrix norm.
permute(row, col)Return the permuted matrix.
preallocatorPreallocate(A[, fill])Preallocate memory for a matrix using a preallocator matrix.
ptap(P[, result, fill])Creates the matrix product C = PᵀAP.
rart(R[, result, fill])Create the matrix product C = RARᵀ.
realPart([out])Return the real part of the matrix.
reorderForNonzeroDiagonal(isrow, iscol[, atol])Change a matrix ordering to remove zeros from the diagonal.
restoreDenseColumnVec(i[, mode, V])Restore the iᵗʰ column vector of the dense matrix.
Restore access to a submatrix of a
Type.DENSEmatrix.restoreISLocalMat(local)Restore the local matrix obtained with
getISLocalMat.restoreLocalSubMatrix(isrow, iscol, submat)Restore a reference to a submatrix obtained with
getLocalSubMatrix.Retrieve a copy of the matrix values previously stored with
storeValues.scale(alpha)Scale the matrix.
setBlockSize(bsize)Set the matrix block size (same for rows and columns).
setBlockSizes(row_bsize, col_bsize)Set the row and column block sizes.
setDM(dm)Set the DM defining the data layout of the matrix.
setDenseLDA(lda)Set the leading dimension of the array used by the dense matrix.
setDiagonal(diag[, addv])Set the diagonal values of the matrix.
Configure the matrix from the options database.
setISAllowRepeated([allow])Allow repeated entries in the local to global map.
setISLocalMat(local)Set the local matrix stored inside a
Type.IS.setISPreallocation(nnz, onnz)Preallocate memory for a
Type.ISparallel matrix.setLGMap(rmap[, cmap])Set the local-to-global mappings.
setLMVMJ0(J0)Set the initial Jacobian of the LMVM matrix.
setLMVMJ0KSP(ksp)Set the KSP of the LMVM matrix.
setLRCMats(A, U[, c, V])Set the constituents of a
Type.LRCmatrix.setMumpsCntl(icntl, val)Set a MUMPS parameter,
CNTL[icntl] = val.setMumpsIcntl(icntl, ival)Set a MUMPS parameter,
ICNTL[icntl] = ival.setNearNullSpace(nsp)Set the near-nullspace.
setNestVecType(vec_type)Set the vector type for a
Type.NESTmatrix.setNullSpace(nsp)Set the nullspace.
setOption(option, flag)Set option.
setOptionsPrefix([prefix])Set the prefix used for searching for options in the database.
setPreallocationCOO(coo_i, coo_j)Set preallocation using coordinate format with global indices.
setPreallocationCOOLocal(coo_i, coo_j)Set preallocation using coordinate format with local indices.
setPreallocationCSR(csr)Preallocate memory for the matrix with a CSR layout.
setPreallocationDense(array)Set the array used for storing matrix elements for a dense matrix.
setPreallocationNNZ(nnz)Preallocate memory for the matrix with a non-zero pattern.
setPythonContext(context)Set the instance of the class implementing the required Python methods.
setPythonType(py_type)Set the fully qualified Python name of the class to be used.
setRandom([random])Set random values in the matrix.
setSizes(size[, bsize])Set the local, global and block sizes.
setStencil(dims[, starts, dof])Set matrix stencil.
Set the transpose nullspace.
Set transpose precursor.
setType(mat_type)Set the matrix type.
Set a factored matrix to be treated as unfactored.
setUp()Set up the internal data structures for using the matrix.
setValue(row, col, value[, addv])Set a value to the
(row, col)entry of the matrix.setValueBlockedStagStencil(row, col, value)Not implemented.
setValueBlockedStencil(row, col, value[, addv])Set a block of values to row and col stencil.
setValueLocal(row, col, value[, addv])Set a value to the
(row, col)entry of the matrix in local ordering.setValueStagStencil(row, col, value[, addv])Not implemented.
setValueStencil(row, col, value[, addv])Set a value to row and col stencil.
setValues(rows, cols, values[, addv])Set values to the rows ⊗ cols entries of the matrix.
setValuesBlocked(rows, cols, values[, addv])Set values to the rows ⊗ col block entries of the matrix.
setValuesBlockedCSR(I, J, V[, addv])Set values stored in block CSR format.
setValuesBlockedIJV(I, J, V[, addv, rowmap])Set a subset of values stored in block CSR format.
setValuesBlockedLocal(rows, cols, values[, addv])Set values to the rows ⊗ col block entries of the matrix in local ordering.
setValuesBlockedLocalCSR(I, J, V[, addv])Set values stored in block CSR format.
setValuesBlockedLocalIJV(I, J, V[, addv, rowmap])Set a subset of values stored in block CSR format.
setValuesBlockedLocalRCV(R, C, V[, addv])Undocumented.
setValuesBlockedRCV(R, C, V[, addv])Undocumented.
setValuesCOO(coo_v[, addv])Set values after preallocation with coordinate format.
setValuesCSR(I, J, V[, addv])Set values stored in CSR format.
setValuesIJV(I, J, V[, addv, rowmap])Set a subset of values stored in CSR format.
setValuesLocal(rows, cols, values[, addv])Set values to the rows ⊗ col entries of the matrix in local ordering.
setValuesLocalCSR(I, J, V[, addv])Set values stored in CSR format.
setValuesLocalIJV(I, J, V[, addv, rowmap])Set a subset of values stored in CSR format.
setValuesLocalRCV(R, C, V[, addv])Undocumented.
setValuesRCV(R, C, V[, addv])Undocumented.
setVariableBlockSizes(blocks)Set diagonal point-blocks of the matrix.
setVecType(vec_type)Set the vector type.
shift(alpha)Shift the matrix.
solve(b, x)Solve Ax=b, given a factored matrix.
solveAdd(b, y, x)Solve x=y+A⁻¹b, given a factored matrix.
solveBackward(b, x)Solve Ux=b, given a factored matrix A=LU.
solveForward(b, x)Solve Lx = b, given a factored matrix A = LU.
solveTranspose(b, x)Solve Aᵀx=b, given a factored matrix.
solveTransposeAdd(b, y, x)Solve x=y+A⁻ᵀb, given a factored matrix.
Stash a copy of the matrix values.
toDLPack([mode])Return a DLPack
PyCapsulewrapping the vector data.transpose([out])Return the transposed matrix.
transposeMatMult(mat[, result, fill])Perform matrix-matrix multiplication C=AᵀB.
view([viewer])View the matrix.
Zero the entries of the matrix.
zeroRows(rows[, diag, x, b])Zero selected rows of the matrix.
zeroRowsColumns(rows[, diag, x, b])Zero selected rows and columns of the matrix.
zeroRowsColumnsLocal(rows[, diag, x, b])Zero selected rows and columns of the matrix in local ordering.
zeroRowsColumnsStencil(rows[, diag, x, b])Zero selected rows and columns of the matrix.
zeroRowsLocal(rows[, diag, x, b])Zero selected rows of the matrix in local ordering.
Attributes Summary
The boolean flag indicating if the matrix is assembled.
Matrix block size.
Matrix row and column block sizes.
The boolean flag indicating if the matrix is Hermitian.
Matrix local size.
Matrix local row range.
Matrix row ranges.
Matrix global size.
Matrix local and global sizes.
The boolean flag indicating if the matrix is structurally symmetric.
The boolean flag indicating if the matrix is symmetric.
Methods Documentation
- H2OpusCompress(tol)#
Compress a hierarchical matrix.
Collective.
See also
- H2OpusLowRankUpdate(U, V=None, s=1.0)#
Perform a low-rank update of the form
self+= sUVᵀ.Collective.
- Parameters:
- Return type:
See also
- H2OpusOrthogonalize()#
Orthogonalize the basis tree of a hierarchical matrix.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5111
- Return type:
- SOR(b, x, omega=1.0, sortype=None, shift=0.0, its=1, lits=1)#
Compute relaxation (SOR, Gauss-Seidel) sweeps.
Neighborwise collective.
See also
- appendOptionsPrefix(prefix=None)#
Append to the prefix used for searching for options in the database.
Logically collective.
- assemble(assembly=None)#
Assemble the matrix.
Collective.
- Parameters:
assembly (MatAssemblySpec) – The assembly type.
- Return type:
See also
- assemblyBegin(assembly=None)#
Begin an assembling stage of the matrix.
Collective.
- Parameters:
assembly (MatAssemblySpec) – The assembly type.
- Return type:
See also
- assemblyEnd(assembly=None)#
Complete an assembling stage of the matrix initiated with
assemblyBegin.Collective.
- Parameters:
assembly (MatAssemblySpec) – The assembly type.
- Return type:
See also
- axpy(alpha, X, structure=None)#
Perform the matrix summation
self+ = ɑ·X.Collective.
- Parameters:
- Return type:
See also
- aypx(alpha, X, structure=None)#
Perform the matrix summation
self= ɑ·self+ X.Collective.
- Parameters:
- Return type:
See also
- bindToCPU(flg)#
Mark a matrix to temporarily stay on the CPU.
Collective.
Once marked, perform computations on the CPU.
See also
- boundToCPU()#
Query if a matrix is bound to the CPU.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:4672
- Return type:
- chop(tol)#
Set entries smallest of tol (in absolute values) to zero.
Collective.
See also
- conjugate(out=None)#
Return the conjugate matrix.
Collective.
- Parameters:
out (Mat | None) – Optional return matrix. If
None, the operation is performed in-place. Otherwise, the operation is performed onout.- Return type:
See also
- convert(mat_type=None, out=None)#
Convert the matrix type.
Collective.
- Parameters:
- Return type:
See also
- copy(result=None, structure=None)#
Return a copy of the matrix.
Collective.
- Parameters:
- Return type:
See also
- create(comm=None)#
Create the matrix.
Collective.
Once created, the user should call
setTypeorsetFromOptionsbefore using the matrix. Alternatively, specific creation routines such ascreateAIJorcreateBAIJcan be used.- Parameters:
comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.- Return type:
- createAIJ(size, bsize=None, nnz=None, csr=None, comm=None)#
Create a sparse
Type.AIJmatrix, optionally preallocating.Collective.
To preallocate the matrix the user can either pass
nnzorcsrdescribing the sparsity. If neither is set then preallocation will not occur. Consult thePETSc manualfor more information.- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.nnz (NNZSpec | None) – Optional non-zeros preallocation pattern.
csr (CSRIndicesSpec | None) – Optional compressed sparse row layout information. If provided, it takes precedence on
nnz.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
- createAIJCRL(size, bsize=None, nnz=None, csr=None, comm=None)#
Create a sparse
Type.AIJCRLmatrix.Collective.
This is similar to
Type.AIJmatrices but stores some additional information that improves vectorization for the matrix-vector product.To preallocate the matrix the user can either pass
nnzorcsrdescribing the sparsity. If neither is set then preallocation will not occur. Consult thePETSc manualfor more information.- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.nnz (NNZSpec | None) – Optional non-zeros preallocation pattern.
csr (CSRIndicesSpec | None) – Optional compressed sparse row layout information. If provided, it takes precedence on
nnz.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
createAIJ,createBAIJ,MatCreateSeqAIJCRL,MatCreateMPIAIJCRL
- createAIJWithArrays(size, csr, bsize=None, comm=None)#
Create a sparse
Type.AIJmatrix with data in CSR format.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
csr (CSRSpec | tuple[CSRSpec, CSRSpec]) – Local matrix data in compressed sparse row format.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
Notes
For
Type.SEQAIJmatrices, thecsrdata is not copied. ForType.MPIAIJmatrices, thecsrdata is not copied only in the case it represents on-process and off-process information.
- createBAIJ(size, bsize, nnz=None, csr=None, comm=None)#
Create a sparse blocked
Type.BAIJmatrix, optionally preallocating.Collective.
To preallocate the matrix the user can either pass
nnzorcsrdescribing the sparsity. If neither is set then preallocation will not occur. Consult thePETSc manualfor more information.- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec) – Matrix block size.
nnz (NNZSpec | None) – Optional non-zeros preallocation pattern for block rows.
csr (CSRIndicesSpec | None) – Optional block-compressed sparse row layout information. If provided, it takes precedence on
nnz.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
setSizes,createAIJ,MATBAIJ,MATSEQBAIJ,MATMPIBAIJ,MatCreateBAIJ
- createConstantDiagonal(size, diag, comm=None)#
Create a diagonal matrix of type
Type.CONSTANTDIAGONAL.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
diag (float) – The diagonal value.
comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
See also
- createDense(size, bsize=None, array=None, comm=None)#
Create a
Type.DENSEmatrix.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.array (Sequence[Scalar] | None) – Optional matrix data. If
None, memory is internally allocated.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
- createDenseCUDA(size, bsize=None, array=None, cudahandle=None, comm=None)#
Create a
Type.DENSECUDAmatrix with optional host and device data.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.array (Sequence[Scalar] | None) – Host data. Will be lazily allocated if
None.cudahandle (int | None) – Address of the array on the GPU. Will be lazily allocated if
None. Ifcudahandleis provided,arraywill be ignored.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
- createDiagonal(diag)#
Create a diagonal matrix of type
Type.DIAGONAL.Collective.
See also
- createH2OpusFromMat(A, coordinates=None, dist=None, eta=None, leafsize=None, maxrank=None, bs=None, rtol=None)#
Create a hierarchical
Type.H2OPUSmatrix sampling from a provided operator.Collective.
- Parameters:
A (Mat) – Matrix to be sampled.
coordinates (Sequence[Scalar] | None) – Coordinates of the points.
dist (bool | None) – Whether or not coordinates are distributed, defaults to
False.eta (float | None) – Admissibility condition tolerance, defaults to
DECIDE.leafsize (int | None) – Leaf size in cluster tree, defaults to
DECIDE.maxrank (int | None) – Maximum rank permitted, defaults to
DECIDE.bs (int | None) – Maximum number of samples to take concurrently, defaults to
DECIDE.rtol (float | None) – Relative tolerance for construction, defaults to
DECIDE.
- Return type:
Notes
See
MatCreateH2OpusFromMatfor the appropriate database options.
- createHermitianTranspose(mat)#
Create a
Type.HERMITIANTRANSPOSEmatrix that behaves like (A*)ᵀ.Collective.
Notes
The Hermitian transpose is never actually formed.
- createIS(size, bsize=None, lgmapr=None, lgmapc=None, comm=None)#
Create a
Type.ISmatrix representing globally unassembled operators.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.lgmapr (LGMap | None) – Optional local-to-global mapping for the rows. If
None, the local row space matches the global row space.lgmapc (LGMap | None) – Optional local-to-global mapping for the columns. If
None, the local column space matches the global column space.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
- createLRC(A, U, c, V)#
Create a low-rank correction
Type.LRCmatrix representing A + UCVᵀ.Collective.
- Parameters:
- Return type:
Notes
The matrix A + UCVᵀ is never actually formed.
C is a diagonal matrix (represented as a vector) of order k, where k is the number of columns of both
UandV.If A is
Nonethen the new object behaves like a low-rank matrix UCVᵀ.Use the same matrix for
VandU(orV=None) for a symmetric low-rank correction, A + UCUᵀ.If
cisNonethen the low-rank correction is just U*Vᵀ. If a sequentialcvector is used for a parallel matrix, PETSc assumes that the values of the vector are consistently set across processors.See also
- createNest(mats, isrows=None, iscols=None, comm=None)#
Create a
Type.NESTmatrix containing multiple submatrices.Collective.
- Parameters:
mats (Sequence[Sequence[Mat]]) – Iterable of matrix block rows with size
len(isrows). Each matrix block row must be of sizelen(iscols). Empty submatrices can be set withNone.isrows (Sequence[IS] | None) – Index set for each nested row block, defaults to contiguous ordering.
iscols (Sequence[IS] | None) – Index set for each nested column block, defaults to contiguous ordering.
comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
See also
- createNormal(mat)#
Create a
Type.NORMALmatrix representing AᵀA.Collective.
Notes
The product AᵀA is never actually formed. Instead A and Aᵀ are used during
multand various other matrix operations.See also
- createNormalHermitian(mat)#
Create a
Type.NORMALHERMITIANmatrix representing (A*)ᵀA.Collective.
Notes
The product (A*)ᵀA is never actually formed.
- createPython(size, context=None, comm=None)#
Create a
Type.PYTHONmatrix.Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
context (Any) – An instance of the Python class implementing the required methods.
comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
See also
PETSc Python matrix type,
setType,setPythonContext,Type.PYTHON
- createSBAIJ(size, bsize, nnz=None, csr=None, comm=None)#
Create a sparse
Type.SBAIJmatrix in symmetric block format.Collective.
To preallocate the matrix the user can either pass
nnzorcsrdescribing the sparsity. If neither is set then preallocation will not occur. Consult thePETSc manualfor more information.- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec) – Matrix block size.
nnz (NNZSpec | None) – Optional upper-triangular (including diagonal) non-zeros preallocation pattern for block rows.
csr (CSRIndicesSpec | None) – Optional block-compressed sparse row layout information. If provided, it takes precedence on
nnz.comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
Self
See also
- createScatter(scatter, comm=None)#
Create a
Type.SCATTERmatrix from a vector scatter.Collective.
- Parameters:
scatter (Scatter) – Vector scatter.
comm (Comm | None) – MPI communicator, defaults to
Sys.getDefaultComm.
- Return type:
See also
- createSchurComplement(A00, Ap00, A01, A10, A11=None)#
Create a
Type.SCHURCOMPLEMENTmatrix.Collective.
- Parameters:
A00 (Mat) – the upper-left block of the original matrix A = [A00 A01; A10 A11].
Ap00 (Mat) – used to construct the preconditioner used in ksp(A00,Ap00) to approximate the action of A00^{-1}.
A01 (Mat) – the upper-right block of the original matrix A = [A00 A01; A10 A11].
A10 (Mat) – the lower-left block of the original matrix A = [A00 A01; A10 A11].
A11 (Mat | None) – Optional lower-right block of the original matrix A = [A00 A01; A10 A11].
- Return type:
See also
- createSubMatrices(isrows, iscols=None, submats=None)#
Return several sequential submatrices.
Collective.
- Parameters:
- Return type:
See also
- createSubMatrix(isrow, iscol=None, submat=None)#
Return a submatrix.
Collective.
- Parameters:
- Return type:
See also
- createSubMatrixVirtual(A, isrow, iscol=None)#
Create a
Type.SUBMATRIXmatrix that acts as a submatrix.Collective.
- Parameters:
- Return type:
See also
- createTranspose(mat)#
Create a
Type.TRANSPOSEmatrix that behaves like Aᵀ.Collective.
Notes
The transpose is never actually formed. Instead
multTransposeis called whenever the matrix-vector product is computed.See also
- createVecLeft()#
Return a left vector, a vector that the matrix vector product can be stored in.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3570
- Return type:
- createVecRight()#
Return a right vector, a vector that the matrix can be multiplied against.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3556
- Return type:
- createVecs(side=None)#
Return vectors that can be used in matrix vector products.
Collective.
- Parameters:
side (Literal['r', 'R', 'right', 'Right', 'RIGHT', 'l', 'L', 'left', 'Left', 'LEFT'] | None) – If
Nonereturns a 2-tuple of vectors(right, left). Otherwise it just return a left or right vector.- Return type:
Notes
rightvectors are vectors in the column space of the matrix.leftvectors are vectors in the row space of the matrix.See also
- destroy()#
Destroy the matrix.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:478
- Return type:
- diagonalScale(L=None, R=None)#
Perform left and/or right diagonal scaling of the matrix.
Collective.
- Parameters:
- Return type:
See also
- duplicate(copy=False)#
Return a clone of the matrix.
Collective.
- Parameters:
copy (DuplicateOption | bool) – If
True, it also copies the values.- Return type:
See also
- equal(mat)#
Return the result of matrix comparison.
Collective.
See also
- factorCholesky(isperm, options=None)#
Perform an in-place Cholesky factorization.
Collective.
- Parameters:
- Return type:
See also
- factorICC(isperm, options=None)#
Perform an in-place an incomplete Cholesky factorization.
Collective.
- Parameters:
- Return type:
See also
- factorILU(isrow, iscol, options=None)#
Perform an in-place ILU factorization.
Collective.
- Parameters:
isrow (IS) – The row permutation.
iscol (IS) – The column permutation.
options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include
levels, the number of levels of fill,fill, the expected fill as a ratio of the original fill, anddtcol, the pivot tolerance where0indicates no pivot and1indicates full column pivoting.
- Return type:
See also
- factorLU(isrow, iscol, options=None)#
Perform an in-place LU factorization.
Collective.
- Parameters:
isrow (IS) – The row permutation.
iscol (IS) – The column permutation.
options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include
fill, the expected fill as a ratio of the original fill anddtcol, the pivot tolerance where0indicates no pivot and1indicates full column pivoting.
- Return type:
See also
- factorNumericCholesky(mat, options=None)#
Not implemented.
- factorNumericLU(mat, options=None)#
Not implemented.
- factorSymbolicCholesky(isperm, options=None)#
Not implemented.
- factorSymbolicICC(isperm, options=None)#
Not implemented.
- factorSymbolicILU(isrow, iscol, options=None)#
Not implemented.
- factorSymbolicLU(mat, isrow, iscol, options=None)#
Not implemented.
- findZeroRows()#
Return the index set of empty rows.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3503
- Return type:
- fixISLocalEmpty(fix=True)#
Compress out zero local rows from the local matrices.
Collective.
- Parameters:
fix (bool) – When
True, new local matrices and local to global maps are generated during the final assembly process.- Return type:
See also
- getBlockSize()#
Return the matrix block size.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1968
- Return type:
- getBlockSizes()#
Return the row and column block sizes.
Not collective.
See also
- getColumnIJ(symmetric=False, compressed=False)#
Return the CSC representation of the local sparsity pattern.
Collective.
- Parameters:
- Return type:
See also
- getColumnVector(column, result=None)#
Return the columnᵗʰ column vector of the matrix.
Collective.
- Parameters:
- Return type:
See also
- getDM()#
Return the DM defining the data layout of the matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5826
- Return type:
- getDenseArray(readonly=False)#
Return the array where the data is stored.
Not collective.
- Parameters:
readonly (bool) – Enable to obtain a read only array.
- Return type:
See also
- getDenseColumnVec(i, mode='rw')#
Return the iᵗʰ column vector of the dense matrix.
Collective.
- Parameters:
i (int) – The column index to access.
mode (AccessModeSpec) – The access type of the vector to be returned.
- Return type:
- getDenseLDA()#
Return the leading dimension of the array used by the dense matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5557
- Return type:
- getDenseLocalMatrix()#
Return the local part of the dense matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5609
- Return type:
- getDenseSubMatrix(rbegin=DECIDE, rend=DECIDE, cbegin=DECIDE, cend=DECIDE)#
Get access to a submatrix of a
Type.DENSEmatrix.Collective.
- Parameters:
- Return type:
See also
- getDiagonal(result=None)#
Return the diagonal of the matrix.
Collective.
See also
- getDiagonalBlock()#
Return the part of the matrix associated with the on-process coupling.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3986
- Return type:
- getISAllowRepeated()#
Get the flag for repeated entries in the local to global map.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:4935
- Return type:
- getISLocalMat()#
Return the local matrix stored inside a
Type.ISmatrix.Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:4968
- Return type:
- getInertia()#
Return the inertia from a factored matrix.
Collective.
The matrix must have been factored by calling
factorCholesky.- Returns:
- Return type:
See also
- getInfo(info=None)#
Return summary information.
Collective.
See also
- getLGMap()#
Return the local-to-global mappings.
Not collective.
See also
- getLMVMJ0()#
Get the initial Jacobian of the LMVM matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5171
- Return type:
- getLMVMJ0KSP()#
Get the KSP of the LMVM matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:5202
- Return type:
- getLRCMats()#
Return the constituents of a
Type.LRCmatrix.Not collective.
- Returns:
- Return type:
See also
- getLocalSize()#
Return the local number of rows and columns.
Not collective.
See also
- getLocalSubMatrix(isrow, iscol, submat=None)#
Return a reference to a submatrix specified in local numbering.
Collective.
- Parameters:
- Return type:
See also
- getMumpsCntl(icntl)#
Return the MUMPS parameter,
CNTL[icntl].Logically collective.
See also
- getMumpsIcntl(icntl)#
Return the MUMPS parameter,
ICNTL[icntl].Logically collective.
See also
- getMumpsInfo(icntl)#
Return the MUMPS parameter,
INFO[icntl].Logically collective.
See also
- getMumpsInfog(icntl)#
Return the MUMPS parameter,
INFOG[icntl].Logically collective.
See also
- getMumpsRinfo(icntl)#
Return the MUMPS parameter,
RINFO[icntl].Logically collective.
See also
- getMumpsRinfog(icntl)#
Return the MUMPS parameter,
RINFOG[icntl].Logically collective.
See also
- getNearNullSpace()#
Return the near-nullspace.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3818
- Return type:
- getNestISs()#
Return the index sets representing the row and column spaces.
Not collective.
See also
- getNestLocalISs()#
Return the local index sets representing the row and column spaces.
Not collective.
See also
- getNestSize()#
Return the number of rows and columns of the matrix.
Not collective.
See also
- getNestSubMatrix(i, j)#
Return a single submatrix.
Not collective.
- Parameters:
- Return type:
See also
- getNullSpace()#
Return the nullspace.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3764
- Return type:
- getOption(option)#
Return the option value.
Not collective.
See also
- getOptionsPrefix()#
Return the prefix used for searching for options in the database.
Not collective.
Source code at petsc4py/PETSc/Mat.pyx:1831
- Return type:
- getOrdering(ord_type)#
Return a reordering for a matrix to improve a LU factorization.
Collective.
- Parameters:
ord_type (OrderingType) – The type of reordering.
- Returns:
- Return type:
See also
- getOwnershipIS()#
Return the ranges of rows and columns owned by each process as index sets.
Not collective.
- getOwnershipRange()#
Return the locally owned range of rows.
Not collective.
- getOwnershipRangeColumn()#
Return the locally owned range of columns.
Not collective.
- getOwnershipRanges()#
Return the range of rows owned by each process.
Not collective.
The returned array is the result of exclusive scan of the local sizes.
See also
Source code at petsc4py/PETSc/Mat.pyx:2010
- Return type:
- getOwnershipRangesColumn()#
Return the range of columns owned by each process.
Not collective.
Source code at petsc4py/PETSc/Mat.pyx:2045
- Return type:
- getPythonContext()#
Return the instance of the class implementing the required Python methods.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1765
- Return type:
- getPythonType()#
Return the fully qualified Python name of the class used by the matrix.
Not collective.
Source code at petsc4py/PETSc/Mat.pyx:1800
- Return type:
- getRedundantMatrix(nsubcomm, subcomm=None, out=None)#
Return redundant matrices on subcommunicators.
Collective.
- Parameters:
- Return type:
See also
- getRow(row)#
Return the column indices and values for the requested row.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:2578
- Parameters:
row (int)
- Return type:
- getRowIJ(symmetric=False, compressed=False)#
Return the CSR representation of the local sparsity pattern.
Collective.
- Parameters:
- Return type:
See also
- getRowSum(result=None)#
Return the row-sum vector.
Collective.
See also
- getSchurComplementSubMatrices()#
Return Schur complement sub-matrices.
Collective.
See also
- getSize()#
Return the global number of rows and columns.
Not collective.
See also
- getSizes()#
Return the tuple of matrix layouts.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1952
- Return type:
- getTransposeMat()#
Return the internal matrix of a
Type.TRANSPOSEmatrix.Not collective.
- Parameters:
mat – Matrix A of type
Type.TRANSPOSE.- Return type:
See also
- getTransposeNullSpace()#
Return the transpose nullspace.
Not collective.
Source code at petsc4py/PETSc/Mat.pyx:3791
- Return type:
- getType()#
Return the type of the matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1910
- Return type:
- getValue(row, col)#
Return the value in the (row, col) position.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:2503
- Return type:
- getValues(rows, cols, values=None)#
Return the values in the
zip(rows, cols)positions.Not collective.
- Parameters:
values (ArrayScalar) – Optional array where to store the values.
- Return type:
See also
- getValuesCSR()#
Return the CSR representation of the local part of the matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:2540
- Return type:
- getVecType()#
Return the vector type used by the matrix.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:661
- Return type:
- hermitianTranspose(out=None)#
Return the transposed Hermitian matrix.
Collective.
- Parameters:
out (Mat | None) – Optional return matrix. If
None, inplace transposition is performed. Otherwise, the matrix is reused.- Return type:
See also
- imagPart(out=None)#
Return the imaginary part of the matrix.
Collective.
- Parameters:
out (Mat | None) – Optional return matrix. If
None, the operation is performed in-place. Otherwise, the operation is performed onout.- Return type:
See also
- increaseOverlap(iset, overlap=1)#
Increase the overlap of a index set.
Collective.
See also
- invertBlockDiagonal()#
Return the inverse of the block-diagonal entries.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3731
- Return type:
- isAssembled()#
The boolean flag indicating if the matrix is assembled.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3489
- Return type:
- isHermitian(tol=0)#
Return the boolean indicating if the matrix is Hermitian.
Collective.
See also
- isHermitianKnown()#
Return the 2-tuple indicating if the matrix is known to be Hermitian.
Not collective.
See also
- isLinear(n=1)#
Return whether the Mat is a linear operator.
Collective.
See also
- isStructurallySymmetric()#
Return the boolean indicating if the matrix is structurally symmetric.
Not collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:2458
- Return type:
- isSymmetric(tol=0)#
Return the boolean indicating if the matrix is symmetric.
Collective.
See also
- isSymmetricKnown()#
Return the 2-tuple indicating if the matrix is known to be symmetric.
Not collective.
See also
- isTranspose(mat=None, tol=0)#
Return the result of matrix comparison with transposition.
Collective.
- Parameters:
- Return type:
See also
- kron(mat, result=None)#
Compute C, the Kronecker product of A and B.
Collective.
- Parameters:
- Returns:
result – The resultant matrix C, the Kronecker product of A and B.
- Return type:
See also
- load(viewer)#
Load a matrix.
Collective.
See also
- matMatMult(B, C, result=None, fill=None)#
Perform matrix-matrix-matrix multiplication D=ABC.
Neighborwise collective.
- Parameters:
B (Mat) – The middle matrix B.
C (Mat) – The right hand matrix C.
result (Mat | None) – The optional resultant matrix D. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When D is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix D.
- Return type:
See also
- matMult(mat, result=None, fill=None)#
Perform matrix-matrix multiplication C=AB.
Neighborwise collective.
- Parameters:
mat (Mat) – The right hand matrix B.
result (Mat | None) – The optional resultant matrix C. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When C is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix C.
- Return type:
Notes
To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.
See also
- matSolve(B, X)#
Solve AX=B, given a factored matrix A.
Neighborwise collective.
- Parameters:
B (Mat) – The right-hand side matrix of type
Type.DENSE. Can be of typeType.AIJif using MUMPS.X (Mat) – The output solution matrix, must be different than
B.
- Return type:
See also
- matTransposeMult(mat, result=None, fill=None)#
Perform matrix-matrix multiplication C=ABᵀ.
Neighborwise collective.
- Parameters:
mat (Mat) – The right hand matrix B.
result (Mat | None) – The optional resultant matrix C. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When C is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix C.
- Return type:
Notes
To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.
See also
- mult(x, y)#
Perform the matrix vector product y = A @ x.
Collective.
See also
- multAdd(x, v, y)#
Perform the matrix vector product with addition y = A @ x + v.
Collective.
- Parameters:
- Return type:
See also
- multHermitian(x, y)#
Perform the Hermitian matrix vector product y = A^H @ x.
Collective.
- Parameters:
- Return type:
See also
- multHermitianAdd(x, v, y)#
Perform the Hermitian matrix vector product with addition y = A^H @ x + v.
Collective.
- Parameters:
- Return type:
See also
- multTranspose(x, y)#
Perform the transposed matrix vector product y = A^T @ x.
Collective.
See also
- multTransposeAdd(x, v, y)#
Perform the transposed matrix vector product with addition y = A^T @ x + v.
Collective.
- Parameters:
- Return type:
See also
- norm(norm_type=None)#
Compute the requested matrix norm.
Collective.
A 2-tuple is returned if
NormType.NORM_1_AND_2is specified.Source code at petsc4py/PETSc/Mat.pyx:4205
- Parameters:
norm_type (NormTypeSpec)
- Return type:
- permute(row, col)#
Return the permuted matrix.
Collective.
See also
- preallocatorPreallocate(A, fill=True)#
Preallocate memory for a matrix using a preallocator matrix.
Collective.
The current matrix (
self) must be of typeType.PREALLOCATOR.- Parameters:
- Return type:
See also
- ptap(P, result=None, fill=None)#
Creates the matrix product C = PᵀAP.
Neighborwise collective.
- Parameters:
P (Mat) – The matrix P.
result (Mat | None) – The optional resultant matrix C. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When C is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix C.
- Return type:
Notes
To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.
An alternative approach to this function is to use
MatProductCreateand set the desired options before the computation is done.
- rart(R, result=None, fill=None)#
Create the matrix product C = RARᵀ.
Neighborwise collective.
- Parameters:
R (Mat) – The projection matrix.
result (Mat | None) – The optional resultant matrix C. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When C is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix C.
- Return type:
Notes
To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.
- realPart(out=None)#
Return the real part of the matrix.
Collective.
- Parameters:
out (Mat | None) – Optional return matrix. If
None, the operation is performed in-place. Otherwise, the operation is performed onout.- Return type:
See also
- reorderForNonzeroDiagonal(isrow, iscol, atol=0)#
Change a matrix ordering to remove zeros from the diagonal.
Collective.
- Parameters:
- Return type:
See also
- restoreDenseColumnVec(i, mode='rw', V=None)#
Restore the iᵗʰ column vector of the dense matrix.
Collective.
- Parameters:
i (int) – The column index to be restored.
mode (AccessModeSpec) – The access type of the vector to be restored.
V (Vec | None) – The vector obtained from calling
getDenseColumnVec.
- Return type:
- restoreDenseSubMatrix(mat)#
Restore access to a submatrix of a
Type.DENSEmatrix.Collective.
- Parameters:
mat (Mat) – the matrix obtained from
getDenseSubMatrix.- Return type:
See also
- restoreISLocalMat(local)#
Restore the local matrix obtained with
getISLocalMat.Not collective.
See also
- restoreLocalSubMatrix(isrow, iscol, submat)#
Restore a reference to a submatrix obtained with
getLocalSubMatrix.Collective.
- Parameters:
- Return type:
See also
- retrieveValues()#
Retrieve a copy of the matrix values previously stored with
storeValues.Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3422
- Return type:
- scale(alpha)#
Scale the matrix.
Collective.
See also
- setBlockSize(bsize)#
Set the matrix block size (same for rows and columns).
Logically collective.
See also
- setBlockSizes(row_bsize, col_bsize)#
Set the row and column block sizes.
Logically collective.
- Parameters:
- Return type:
See also
- setDM(dm)#
Set the DM defining the data layout of the matrix.
Not collective.
See also
- setDenseLDA(lda)#
Set the leading dimension of the array used by the dense matrix.
Not collective.
See also
- setDiagonal(diag, addv=None)#
Set the diagonal values of the matrix.
Collective.
- Parameters:
diag (Vec) – Vector storing diagonal values.
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setFromOptions()#
Configure the matrix from the options database.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1859
- Return type:
- setISAllowRepeated(allow=True)#
Allow repeated entries in the local to global map.
Logically collective.
- Parameters:
allow (bool) – When
True, local dofs are allowed to map to the same global dof.- Return type:
See also
- setISPreallocation(nnz, onnz)#
Preallocate memory for a
Type.ISparallel matrix.Collective.
- Parameters:
nnz (Sequence[int]) – The sequence whose length corresponds to the number of local rows and values which represent the number of nonzeros in the various rows of the diagonal of the local submatrix.
onnz (Sequence[int]) – The sequence whose length corresponds to the number of local rows and values which represent the number of nonzeros in the various rows of the off-diagonal of the local submatrix.
- Return type:
See also
- setLGMap(rmap, cmap=None)#
Set the local-to-global mappings.
Collective.
- Parameters:
- Return type:
See also
- setLMVMJ0(J0)#
Set the initial Jacobian of the LMVM matrix.
Logically collective.
See also
- setLMVMJ0KSP(ksp)#
Set the KSP of the LMVM matrix.
Logically collective.
See also
- setLRCMats(A, U, c=None, V=None)#
Set the constituents of a
Type.LRCmatrix.Logically collective.
- Parameters:
- Return type:
See also
- setMumpsCntl(icntl, val)#
Set a MUMPS parameter,
CNTL[icntl] = val.Logically collective.
- Parameters:
- Return type:
See also
- setMumpsIcntl(icntl, ival)#
Set a MUMPS parameter,
ICNTL[icntl] = ival.Logically collective.
- Parameters:
- Return type:
See also
- setNearNullSpace(nsp)#
Set the near-nullspace.
Collective.
See also
- setNestVecType(vec_type)#
Set the vector type for a
Type.NESTmatrix.Collective.
- Parameters:
vec_type (Type | str) – Vector type used when creating vectors with
createVecs.- Return type:
See also
- setNullSpace(nsp)#
Set the nullspace.
Collective.
See also
- setOption(option, flag)#
Set option.
Collective.
See also
- setOptionsPrefix(prefix=None)#
Set the prefix used for searching for options in the database.
Logically collective.
- setPreallocationCOO(coo_i, coo_j)#
Set preallocation using coordinate format with global indices.
Collective.
- Parameters:
- Return type:
- setPreallocationCOOLocal(coo_i, coo_j)#
Set preallocation using coordinate format with local indices.
Collective.
- Parameters:
- Return type:
- setPreallocationCSR(csr)#
Preallocate memory for the matrix with a CSR layout.
Collective.
Correct preallocation can result in a dramatic reduction in matrix assembly time.
- Parameters:
csr (CSRIndicesSpec) – Local matrix data in compressed sparse row layout format.
- Return type:
Notes
Must use the block-compressed form with
Type.BAIJandType.SBAIJ.
- setPreallocationDense(array)#
Set the array used for storing matrix elements for a dense matrix.
Collective.
- setPreallocationNNZ(nnz)#
Preallocate memory for the matrix with a non-zero pattern.
Collective.
Correct preallocation can result in a dramatic reduction in matrix assembly time.
- Parameters:
nnz (NNZSpec) – The number of non-zeros per row for the local portion of the matrix, or a 2-tuple for the on-process and off-process part of the matrix.
- Return type:
- setPythonContext(context)#
Set the instance of the class implementing the required Python methods.
Logically collective.
Notes
In order to use the matrix,
Mat.setUpmust be called after having set the context. PassNoneto reset the matrix to its initial state.
- setPythonType(py_type)#
Set the fully qualified Python name of the class to be used.
Collective.
Notes
In order to use the matrix,
Mat.setUpmust be called after having set the type.
- setRandom(random=None)#
Set random values in the matrix.
Collective.
- Parameters:
random (Random | None) – The random number generator object or
Nonefor the default.- Return type:
See also
- setSizes(size, bsize=None)#
Set the local, global and block sizes.
Collective.
- Parameters:
size (MatSizeSpec) – Matrix size.
bsize (MatBlockSizeSpec | None) – Matrix block size. If
None, a block size of1is set.
- Return type:
Examples
Create a
Matwithnrows and columns and the same local and global sizes.>>> mat = PETSc.Mat().create() >>> mat.setFromOptions() >>> mat.setSizes(n)
Create a
Matwithnrrows,nccolumns and the same local and global sizes.>>> mat = PETSc.Mat().create() >>> mat.setFromOptions() >>> mat.setSizes([nr, nc])
Create a
Matwithnrllocal rows,nrgglobal rows,ncllocal columns andncgglobal columns.>>> mat = PETSc.Mat().create() >>> mat.setFromOptions() >>> mat.setSizes([[nrl, nrg], [ncl, ncg]])
See also
setBlockSize,setBlockSizes,MatSetSizes,MatSetBlockSize,MatSetBlockSizes
- setStencil(dims, starts=None, dof=1)#
Set matrix stencil.
Not collective.
See also
- setTransposeNullSpace(nsp)#
Set the transpose nullspace.
Collective.
- setTransposePrecursor(out)#
Set transpose precursor.
Logically collective.
See also
- setType(mat_type)#
Set the matrix type.
Collective.
See also
- setUnfactored()#
Set a factored matrix to be treated as unfactored.
Logically collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:4903
- Return type:
- setUp()#
Set up the internal data structures for using the matrix.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:1871
- Return type:
- setValue(row, col, value, addv=None)#
Set a value to the
(row, col)entry of the matrix.Not collective.
- Parameters:
row (int) – Row index.
col (int) – Column index.
value (Scalar) – The scalar value.
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setValueBlockedStagStencil(row, col, value, addv=None)#
Not implemented.
Source code at petsc4py/PETSc/Mat.pyx:3238
- Return type:
- setValueBlockedStencil(row, col, value, addv=None)#
Set a block of values to row and col stencil.
Not collective.
- Parameters:
row (Stencil) – Row stencil.
col (Stencil) – Column stencil.
value (Sequence[Scalar]) – The scalar values.
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setValueLocal(row, col, value, addv=None)#
Set a value to the
(row, col)entry of the matrix in local ordering.Not collective.
- Parameters:
row (int) – Local row index.
col (int) – Local column index.
value (Scalar) – The scalar value.
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setValueStagStencil(row, col, value, addv=None)#
Not implemented.
Source code at petsc4py/PETSc/Mat.pyx:3204
- Return type:
- setValueStencil(row, col, value, addv=None)#
Set a value to row and col stencil.
Not collective.
- Parameters:
row (Stencil) – Row stencil.
col (Stencil) – Column stencil.
value (Sequence[Scalar]) – The scalar values.
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setValues(rows, cols, values, addv=None)#
Set values to the rows ⊗ cols entries of the matrix.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlocked(rows, cols, values, addv=None)#
Set values to the rows ⊗ col block entries of the matrix.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedCSR(I, J, V, addv=None)#
Set values stored in block CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedIJV(I, J, V, addv=None, rowmap=None)#
Set a subset of values stored in block CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedLocal(rows, cols, values, addv=None)#
Set values to the rows ⊗ col block entries of the matrix in local ordering.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedLocalCSR(I, J, V, addv=None)#
Set values stored in block CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedLocalIJV(I, J, V, addv=None, rowmap=None)#
Set a subset of values stored in block CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesBlockedLocalRCV(R, C, V, addv=None)#
Undocumented.
Source code at petsc4py/PETSc/Mat.pyx:3087
- Return type:
- setValuesBlockedRCV(R, C, V, addv=None)#
Undocumented.
Source code at petsc4py/PETSc/Mat.pyx:2833
- Return type:
- setValuesCOO(coo_v, addv=None)#
Set values after preallocation with coordinate format.
Collective.
- Parameters:
addv (InsertModeSpec) – Insertion mode.
- Return type:
See also
- setValuesCSR(I, J, V, addv=None)#
Set values stored in CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesIJV(I, J, V, addv=None, rowmap=None)#
Set a subset of values stored in CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesLocal(rows, cols, values, addv=None)#
Set values to the rows ⊗ col entries of the matrix in local ordering.
Not collective.
- Parameters:
- Return type:
See also
- setValuesLocalCSR(I, J, V, addv=None)#
Set values stored in CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesLocalIJV(I, J, V, addv=None, rowmap=None)#
Set a subset of values stored in CSR format.
Not collective.
- Parameters:
- Return type:
See also
- setValuesLocalRCV(R, C, V, addv=None)#
Undocumented.
Source code at petsc4py/PETSc/Mat.pyx:2994
- Return type:
- setValuesRCV(R, C, V, addv=None)#
Undocumented.
Source code at petsc4py/PETSc/Mat.pyx:2719
- Return type:
- setVariableBlockSizes(blocks)#
Set diagonal point-blocks of the matrix.
Not collective.
See also
- setVecType(vec_type)#
Set the vector type.
Collective.
- Parameters:
vec_type (Type | str) – Vector type used when creating vectors with
createVecs.- Return type:
See also
- shift(alpha)#
Shift the matrix.
Collective.
See also
- solve(b, x)#
Solve Ax=b, given a factored matrix.
Neighborwise collective.
The vectors
bandxcannot be the same. Most users should employ theKSPinterface for linear solvers instead of working directly with matrix algebra routines.- Parameters:
- Return type:
See also
- solveAdd(b, y, x)#
Solve x=y+A⁻¹b, given a factored matrix.
Neighborwise collective.
The vectors
bandxcannot be the same.- Parameters:
- Return type:
See also
- solveBackward(b, x)#
Solve Ux=b, given a factored matrix A=LU.
Neighborwise collective.
- Parameters:
- Return type:
See also
- solveForward(b, x)#
Solve Lx = b, given a factored matrix A = LU.
Neighborwise collective.
- Parameters:
- Return type:
See also
- solveTranspose(b, x)#
Solve Aᵀx=b, given a factored matrix.
Neighborwise collective.
The vectors
bandxcannot be the same.- Parameters:
- Return type:
See also
- solveTransposeAdd(b, y, x)#
Solve x=y+A⁻ᵀb, given a factored matrix.
Neighborwise collective.
The vectors
bandxcannot be the same.- Parameters:
- Return type:
See also
- storeValues()#
Stash a copy of the matrix values.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:3410
- Return type:
- toDLPack(mode='rw')#
Return a DLPack
PyCapsulewrapping the vector data.Source code at petsc4py/PETSc/Mat.pyx:5931
- Parameters:
mode (AccessModeSpec)
- Return type:
- transpose(out=None)#
Return the transposed matrix.
Collective.
- Parameters:
out (Mat | None) – Optional return matrix. If
None, inplace transposition is performed. Otherwise, the matrix is reused.- Return type:
See also
- transposeMatMult(mat, result=None, fill=None)#
Perform matrix-matrix multiplication C=AᵀB.
Neighborwise collective.
- Parameters:
mat (Mat) – The right hand matrix B.
result (Mat | None) – The optional resultant matrix C. When
None, a new matrix is created, andMAT_INITIAL_MATRIXis used. When C is notNone, the matrix is reused withMAT_REUSE_MATRIX.fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use
Noneif you do not have a good estimate. If the result is a dense matrix this is irrelevant.
- Returns:
result – The resultant product matrix C.
- Return type:
Notes
To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.
See also
- view(viewer=None)#
View the matrix.
Collective.
Notes
Viewers with type
Viewer.Type.ASCIIare only recommended for small matrices on small numbers of processes. Larger matrices should use a binary format likeViewer.Type.BINARY.
- zeroEntries()#
Zero the entries of the matrix.
Collective.
See also
Source code at petsc4py/PETSc/Mat.pyx:2491
- Return type:
- zeroRows(rows, diag=1, x=None, b=None)#
Zero selected rows of the matrix.
Collective.
- Parameters:
- Return type:
See also
- zeroRowsColumns(rows, diag=1, x=None, b=None)#
Zero selected rows and columns of the matrix.
Collective.
- Parameters:
rows (IS | Sequence[int]) – Row/column indices to be zeroed.
diag (Scalar) – Scalar value to be inserted into the diagonal.
x (Vec | None) – Optional solution vector to be modified for zeroed rows.
b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.
- Return type:
- zeroRowsColumnsLocal(rows, diag=1, x=None, b=None)#
Zero selected rows and columns of the matrix in local ordering.
Collective.
- Parameters:
rows (IS | Sequence[int]) – Local row/column indices to be zeroed.
diag (Scalar) – Scalar value to be inserted into the diagonal.
x (Vec | None) – Optional solution vector to be modified for zeroed rows.
b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.
- Return type:
- zeroRowsColumnsStencil(rows, diag=1, x=None, b=None)#
Zero selected rows and columns of the matrix.
Collective.
- Parameters:
rows (Sequence[Stencil]) – Iterable of stencil rows and columns.
diag (Scalar) – Scalar value to be inserted into the diagonal.
x (Vec | None) – Optional solution vector to be modified for zeroed rows.
b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.
- Return type:
- zeroRowsLocal(rows, diag=1, x=None, b=None)#
Zero selected rows of the matrix in local ordering.
Collective.
- Parameters:
- Return type:
See also
Attributes Documentation
- assembled#
The boolean flag indicating if the matrix is assembled.
- block_size#
Matrix block size.
- block_sizes#
Matrix row and column block sizes.
- hermitian#
The boolean flag indicating if the matrix is Hermitian.
- local_size#
Matrix local size.
- owner_range#
Matrix local row range.
- owner_ranges#
Matrix row ranges.
- size#
Matrix global size.
- sizes#
Matrix local and global sizes.
- structsymm#
The boolean flag indicating if the matrix is structurally symmetric.
- symmetric#
The boolean flag indicating if the matrix is symmetric.