petsc4py.PETSc.Mat#

class petsc4py.PETSc.Mat#

Bases: Object

Matrix object.

Mat is described in the PETSc manual.

See also

Mat

Enumerations

AssemblyType

Matrix assembly type.

DuplicateOption

Matrix duplicate option.

FactorShiftType

Factored matrix shift type.

InfoType

Matrix info type.

Option

Matrix option.

OrderingType

Factored matrix ordering type.

SORType

Matrix SOR type.

SolverType

Factored matrix solver type.

Stencil

Associate structured grid coordinates with matrix indices.

Structure

Matrix modification structure.

Type

Matrix type.

Methods Summary

H2OpusCompress(tol)

Compress a hierarchical matrix.

H2OpusLowRankUpdate(U[, V, s])

Perform a low-rank update of the form self += sUVᵀ.

H2OpusOrthogonalize()

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.

boundToCPU()

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.AIJ matrix, optionally preallocating.

createAIJCRL(size[, bsize, nnz, csr, comm])

Create a sparse Type.AIJCRL matrix.

createAIJWithArrays(size, csr[, bsize, comm])

Create a sparse Type.AIJ matrix with data in CSR format.

createBAIJ(size, bsize[, nnz, csr, comm])

Create a sparse blocked Type.BAIJ matrix, optionally preallocating.

createConstantDiagonal(size, diag[, comm])

Create a diagonal matrix of type Type.CONSTANTDIAGONAL.

createDense(size[, bsize, array, comm])

Create a Type.DENSE matrix.

createDenseCUDA(size[, bsize, array, ...])

Create a Type.DENSECUDA matrix with optional host and device data.

createDiagonal(diag)

Create a diagonal matrix of type Type.DIAGONAL.

createH2OpusFromMat(A[, coordinates, dist, ...])

Create a hierarchical Type.H2OPUS matrix sampling from a provided operator.

createHermitianTranspose(mat)

Create a Type.HERMITIANTRANSPOSE matrix that behaves like (A*)ᵀ.

createIS(size[, bsize, lgmapr, lgmapc, comm])

Create a Type.IS matrix representing globally unassembled operators.

createLRC(A, U, c, V)

Create a low-rank correction Type.LRC matrix representing A + UCVᵀ.

createNest(mats[, isrows, iscols, comm])

Create a Type.NEST matrix containing multiple submatrices.

createNormal(mat)

Create a Type.NORMAL matrix representing AᵀA.

createNormalHermitian(mat)

Create a Type.NORMALHERMITIAN matrix representing (A*)ᵀA.

createPython(size[, context, comm])

Create a Type.PYTHON matrix.

createSBAIJ(size, bsize[, nnz, csr, comm])

Create a sparse Type.SBAIJ matrix in symmetric block format.

createScatter(scatter[, comm])

Create a Type.SCATTER matrix from a vector scatter.

createSubMatrices(isrows[, iscols, submats])

Return several sequential submatrices.

createSubMatrix(isrow[, iscol, submat])

Return a submatrix.

createSubMatrixVirtual(A, isrow[, iscol])

Create a Type.SUBMATRIX matrix that acts as a submatrix.

createTranspose(mat)

Create a Type.TRANSPOSE matrix that behaves like Aᵀ.

createVecLeft()

Return a left vector, a vector that the matrix vector product can be stored in.

createVecRight()

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.

findZeroRows()

Return the index set of empty rows.

fixISLocalEmpty([fix])

Compress out zero local rows from the local matrices.

getBlockSize()

Return the matrix block size.

getBlockSizes()

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.

getDenseLDA()

Return the leading dimension of the array used by the dense matrix.

getDenseLocalMatrix()

Return the local part of the dense matrix.

getDiagonal([result])

Return the diagonal of the matrix.

getDiagonalBlock()

Return the part of the matrix associated with the on-process coupling.

getISAllowRepeated()

Get the flag for repeated entries in the local to global map.

getISLocalMat()

Return the local matrix stored inside a Type.IS matrix.

getInertia()

Return the inertia from a factored matrix.

getInfo([info])

Return summary information.

getLGMap()

Return the local-to-global mappings.

getLRCMats()

Return the constituents of a Type.LRC matrix.

getLocalSize()

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].

getNearNullSpace()

Return the near-nullspace.

getNestISs()

Return the index sets representing the row and column spaces.

getNestLocalISs()

Return the local index sets representing the row and column spaces.

getNestSize()

Return the number of rows and columns of the matrix.

getNestSubMatrix(i, j)

Return a single submatrix.

getNullSpace()

Return the nullspace.

getOption(option)

Return the option value.

getOptionsPrefix()

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.

getOwnershipIS()

Return the ranges of rows and columns owned by each process as index sets.

getOwnershipRange()

Return the locally owned range of rows.

getOwnershipRangeColumn()

Return the locally owned range of columns.

getOwnershipRanges()

Return the range of rows owned by each process.

getOwnershipRangesColumn()

Return the range of columns owned by each process.

getPythonContext()

Return the instance of the class implementing the required Python methods.

getPythonType()

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.

getSize()

Return the global number of rows and columns.

getSizes()

Return the tuple of matrix layouts.

getTransposeNullSpace()

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.

getValuesCSR()

Return the CSR representation of the local part of the matrix.

getVecType()

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.

invertBlockDiagonal()

Return the inverse of the block-diagonal entries.

isAssembled()

The boolean flag indicating if the matrix is assembled.

isHermitian([tol])

Return the boolean indicating if the matrix is Hermitian.

isHermitianKnown()

Return the 2-tuple indicating if the matrix is known to be Hermitian.

isStructurallySymmetric()

Return the boolean indicating if the matrix is structurally symmetric.

isSymmetric([tol])

Return the boolean indicating if the matrix is symmetric.

isSymmetricKnown()

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.

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])

Restore the iᵗʰ column vector of the dense matrix.

restoreISLocalMat(local)

Restore the local matrix obtained with getISLocalMat.

restoreLocalSubMatrix(isrow, iscol, submat)

Restore a reference to a submatrix obtained with getLocalSubMatrix.

retrieveValues()

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.

setFromOptions()

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.IS parallel matrix.

setLGMap(rmap[, cmap])

Set the local-to-global mappings.

setLRCMats(A, U[, c, V])

Set the constituents of a Type.LRC matrix.

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.NEST matrix.

setNullSpace(nsp)

Set the nullspace.

setOption(option, flag)

Set option.

setOptionsPrefix([prefix])

Set the prefix used for searching for options in the database.

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.

setTransposeNullSpace(nsp)

Set the transpose nullspace.

setTransposePrecursor(out)

Set transpose precursor.

setType(mat_type)

Set the matrix type.

setUnfactored()

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.

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.

storeValues()

Stash a copy of the matrix values.

toDLPack([mode])

Return a DLPack PyCapsule wrapping 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.

zeroEntries()

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

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.

Methods Documentation

H2OpusCompress(tol)#

Compress a hierarchical matrix.

Collective.

Parameters:

tol (float) – The absolute truncation threshold.

Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:4905

H2OpusLowRankUpdate(U, V=None, s=1.0)#

Perform a low-rank update of the form self += sUVᵀ.

Collective.

Parameters:
  • U (Mat) – The dense low-rank update matrix.

  • V (Mat | None) – The dense low-rank update matrix. If None, V = U.

  • s (float) – The scaling factor.

Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:4924

H2OpusOrthogonalize()#

Orthogonalize the basis tree of a hierarchical matrix.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:4892

Return type:

Self

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

MatSOR

Source code at petsc4py/PETSc/Mat.pyx:3793

Parameters:
Return type:

None

appendOptionsPrefix(prefix=None)#

Append to the prefix used for searching for options in the database.

Logically collective.

Source code at petsc4py/PETSc/Mat.pyx:1717

Parameters:

prefix (str | None)

Return type:

None

assemble(assembly=None)#

Assemble the matrix.

Collective.

Parameters:

assembly (MatAssemblySpec) – The assembly type.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3306

assemblyBegin(assembly=None)#

Begin an assembling stage of the matrix.

Collective.

Parameters:

assembly (MatAssemblySpec) – The assembly type.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3270

assemblyEnd(assembly=None)#

Complete an assembling stage of the matrix initiated with assemblyBegin.

Collective.

Parameters:

assembly (MatAssemblySpec) – The assembly type.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3288

axpy(alpha, X, structure=None)#

Perform the matrix summation self + = ɑ·X.

Collective.

Parameters:
  • alpha (Scalar) – The scalar.

  • X (Mat) – The matrix to be added.

  • structure (Structure) – The structure of the operation.

Return type:

None

See also

MatAXPY

Source code at petsc4py/PETSc/Mat.pyx:4066

aypx(alpha, X, structure=None)#

Perform the matrix summation self = ɑ·self + X.

Collective.

Parameters:
  • alpha (Scalar) – The scalar.

  • X (Mat) – The matrix to be added.

  • structure (Structure) – The structure of the operation.

Return type:

None

See also

MatAYPX

Source code at petsc4py/PETSc/Mat.pyx:4089

bindToCPU(flg)#

Mark a matrix to temporarily stay on the CPU.

Collective.

Once marked, perform computations on the CPU.

Parameters:

flg (bool) – Bind to the CPU if True.

Return type:

None

See also

MatBindToCPU

Source code at petsc4py/PETSc/Mat.pyx:4433

boundToCPU()#

Query if a matrix is bound to the CPU.

Not collective.

See also

MatBoundToCPU

Source code at petsc4py/PETSc/Mat.pyx:4453

Return type:

bool

chop(tol)#

Set entries smallest of tol (in absolute values) to zero.

Collective.

See also

MatFilter

Source code at petsc4py/PETSc/Mat.pyx:4034

Parameters:

tol (float)

Return type:

None

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 on out.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:2181

convert(mat_type=None, out=None)#

Convert the matrix type.

Collective.

Parameters:
  • mat_type (Type | str) – The type of the new matrix. If None uses Type.SAME.

  • out (Mat | None) – Optional return matrix. If None, inplace conversion is performed. Otherwise, the matrix is reused.

Return type:

Mat

See also

MatConvert

Source code at petsc4py/PETSc/Mat.pyx:2037

copy(result=None, structure=None)#

Return a copy of the matrix.

Collective.

Parameters:
  • result (Mat | None) – Optional return matrix. If None, it is internally created.

  • structure (Structure | None) – The copy structure. Only relevant if result is not None.

Return type:

Mat

See also

MatCopy, MatDuplicate

Source code at petsc4py/PETSc/Mat.pyx:1992

create(comm=None)#

Create the matrix.

Collective.

Once created, the user should call setType or setFromOptions before using the matrix. Alternatively, specific creation routines such as createAIJ or createBAIJ can be used.

Parameters:

comm (Comm | None) – MPI communicator, defaults to Sys.getDefaultComm.

Return type:

Self

See also

destroy, MatCreate

Source code at petsc4py/PETSc/Mat.pyx:488

createAIJ(size, bsize=None, nnz=None, csr=None, comm=None)#

Create a sparse Type.AIJ matrix, optionally preallocating.

Collective.

To preallocate the matrix the user can either pass nnz or csr describing the sparsity. If neither is set then preallocation will not occur. Consult the PETSc manual for more information.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:693

createAIJCRL(size, bsize=None, nnz=None, csr=None, comm=None)#

Create a sparse Type.AIJCRL matrix.

Collective.

This is similar to Type.AIJ matrices but stores some additional information that improves vectorization for the matrix-vector product.

To preallocate the matrix the user can either pass nnz or csr describing the sparsity. If neither is set then preallocation will not occur. Consult the PETSc manual for more information.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:826

createAIJWithArrays(size, csr, bsize=None, comm=None)#

Create a sparse Type.AIJ matrix with data in CSR format.

Collective.

Parameters:
Return type:

Self

Notes

For Type.SEQAIJ matrices, the csr data is not copied. For Type.MPIAIJ matrices, the csr data is not copied only in the case it represents on-process and off-process information.

Source code at petsc4py/PETSc/Mat.pyx:933

createBAIJ(size, bsize, nnz=None, csr=None, comm=None)#

Create a sparse blocked Type.BAIJ matrix, optionally preallocating.

Collective.

To preallocate the matrix the user can either pass nnz or csr describing the sparsity. If neither is set then preallocation will not occur. Consult the PETSc manual for more information.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:738

createConstantDiagonal(size, diag, comm=None)#

Create a diagonal matrix of type Type.CONSTANTDIAGONAL.

Collective.

Parameters:
Return type:

Self

See also

createDiagonal

Source code at petsc4py/PETSc/Mat.pyx:1538

createDense(size, bsize=None, array=None, comm=None)#

Create a Type.DENSE matrix.

Collective.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1024

createDenseCUDA(size, bsize=None, array=None, cudahandle=None, comm=None)#

Create a Type.DENSECUDA matrix with optional host and device data.

Collective.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1060

createDiagonal(diag)#

Create a diagonal matrix of type Type.DIAGONAL.

Collective.

Parameters:

diag (Vec) – The vector holding diagonal values.

Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1571

createH2OpusFromMat(A, coordinates=None, dist=None, eta=None, leafsize=None, maxrank=None, bs=None, rtol=None)#

Create a hierarchical Type.H2OPUS matrix 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:

Self

Notes

See MatCreateH2OpusFromMat for the appropriate database options.

Source code at petsc4py/PETSc/Mat.pyx:1404

createHermitianTranspose(mat)#

Create a Type.HERMITIANTRANSPOSE matrix that behaves like (A*)ᵀ.

Collective.

Parameters:

mat (Mat) – Matrix A to represent the hermitian transpose of.

Return type:

Self

Notes

The Hermitian transpose is never actually formed.

Source code at petsc4py/PETSc/Mat.pyx:1240

createIS(size, bsize=None, lgmapr=None, lgmapc=None, comm=None)#

Create a Type.IS matrix representing globally unassembled operators.

Collective.

Parameters:
  • size (MatSizeSpec) – Matrix size.

  • bsize (MatBlockSizeSpec | None) – Matrix block size. If None, a block size of 1 is 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

MATIS

Source code at petsc4py/PETSc/Mat.pyx:1485

createLRC(A, U, c, V)#

Create a low-rank correction Type.LRC matrix representing A + UCVᵀ.

Collective.

Parameters:
  • A (Mat) – Sparse matrix, can be None.

  • U (Mat) – Dense rectangular matrices.

  • V (Mat) – Dense rectangular matrices.

  • c (Vec) – Vector containing the diagonal of C, can be None.

Return type:

Self

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 U and V.

If A is None then the new object behaves like a low-rank matrix UCVᵀ.

Use the same matrix for V and U (or V=None) for a symmetric low-rank correction, A + UCUᵀ.

If c is None then the low-rank correction is just U*Vᵀ. If a sequential c vector is used for a parallel matrix, PETSc assumes that the values of the vector are consistently set across processors.

See also

MATLRC, MatCreateLRC

Source code at petsc4py/PETSc/Mat.pyx:1265

createNest(mats, isrows=None, iscols=None, comm=None)#

Create a Type.NEST matrix 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 size len(iscols). Empty submatrices can be set with None.

  • 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:

Self

Source code at petsc4py/PETSc/Mat.pyx:1337

createNormal(mat)#

Create a Type.NORMAL matrix representing AᵀA.

Collective.

Parameters:

mat (Mat) – The (possibly rectangular) matrix A.

Return type:

Self

Notes

The product AᵀA is never actually formed. Instead A and Aᵀ are used during mult and various other matrix operations.

Source code at petsc4py/PETSc/Mat.pyx:1165

createNormalHermitian(mat)#

Create a Type.NORMALHERMITIAN matrix representing (A*)ᵀA.

Collective.

Parameters:

mat (Mat) – The (possibly rectangular) matrix A.

Return type:

Self

Notes

The product (A*)ᵀA is never actually formed.

Source code at petsc4py/PETSc/Mat.pyx:1215

createPython(size, context=None, comm=None)#

Create a Type.PYTHON matrix.

Collective.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1594

createSBAIJ(size, bsize, nnz=None, csr=None, comm=None)#

Create a sparse Type.SBAIJ matrix in symmetric block format.

Collective.

To preallocate the matrix the user can either pass nnz or csr describing the sparsity. If neither is set then preallocation will not occur. Consult the PETSc manual for more information.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:782

createScatter(scatter, comm=None)#

Create a Type.SCATTER matrix from a vector scatter.

Collective.

Parameters:
Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1141

createSubMatrices(isrows, iscols=None, submats=None)#

Return several sequential submatrices.

Collective.

Parameters:
  • isrows (IS | Sequence[IS]) – Row index sets.

  • iscols (IS | Sequence[IS]) – Column index sets. If None, iscols = isrows.

  • submats (Mat | Sequence[Mat]) – Optional resultant matrices. When None, new matrices are created, and MAT_INITIAL_MATRIX is used. When not None, the matrices are reused with MAT_REUSE_MATRIX.

Return type:

Sequence[Mat]

Source code at petsc4py/PETSc/Mat.pyx:3880

createSubMatrix(isrow, iscol=None, submat=None)#

Return a submatrix.

Collective.

Parameters:
  • isrow (IS) – Row index set.

  • iscol (IS | None) – Column index set. If None, iscol = isrow.

  • submat (Mat | None) – Optional resultant matrix. When None, a new matrix is created, and MAT_INITIAL_MATRIX is used. When not None, the matrix is reused with MAT_REUSE_MATRIX.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:3850

createSubMatrixVirtual(A, isrow, iscol=None)#

Create a Type.SUBMATRIX matrix that acts as a submatrix.

Collective.

Parameters:
  • A (Mat) – Matrix to extract submatrix from.

  • isrow (IS) – Rows present in the submatrix.

  • iscol (IS | None) – Columns present in the submatrix, defaults to isrow.

Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1312

createTranspose(mat)#

Create a Type.TRANSPOSE matrix that behaves like Aᵀ.

Collective.

Parameters:

mat (Mat) – Matrix A to represent the transpose of.

Return type:

Self

Notes

The transpose is never actually formed. Instead multTranspose is called whenever the matrix-vector product is computed.

Source code at petsc4py/PETSc/Mat.pyx:1190

createVecLeft()#

Return a left vector, a vector that the matrix vector product can be stored in.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3406

Return type:

Vec

createVecRight()#

Return a right vector, a vector that the matrix can be multiplied against.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3392

Return type:

Vec

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 None returns a 2-tuple of vectors (right, left). Otherwise it just return a left or right vector.

Return type:

Vec | tuple[Vec, Vec]

Notes

right vectors are vectors in the column space of the matrix. left vectors are vectors in the row space of the matrix.

Source code at petsc4py/PETSc/Mat.pyx:3353

destroy()#

Destroy the matrix.

Collective.

See also

create, MatDestroy

Source code at petsc4py/PETSc/Mat.pyx:475

Return type:

Self

diagonalScale(L=None, R=None)#

Perform left and/or right diagonal scaling of the matrix.

Collective.

Parameters:
  • L (Vec | None) – Optional left scaling vector.

  • R (Vec | None) – Optional right scaling vector.

Return type:

None

See also

MatDiagonalScale

Source code at petsc4py/PETSc/Mat.pyx:3545

duplicate(copy=False)#

Return a clone of the matrix.

Collective.

Parameters:

copy (bool) – If True, it also copies the values.

Return type:

Mat

See also

MatDuplicate

Source code at petsc4py/PETSc/Mat.pyx:1970

equal(mat)#

Return the result of matrix comparison.

Collective.

See also

MatEqual

Source code at petsc4py/PETSc/Mat.pyx:2225

Parameters:

mat (Mat)

Return type:

bool

factorCholesky(isperm, options=None)#

Perform an in-place Cholesky factorization.

Collective.

Parameters:
  • isperm (IS) – The row and column permutations.

  • 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.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4597

factorICC(isperm, options=None)#

Perform an in-place an incomplete Cholesky factorization.

Collective.

Parameters:
  • isperm (IS) – The row and column permutations

  • 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.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4630

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, and dtcol, the pivot tolerance where 0 indicates no pivot and 1 indicates full column pivoting.

Return type:

None

See also

MatILUFactor

Source code at petsc4py/PETSc/Mat.pyx:4563

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 and dtcol, the pivot tolerance where 0 indicates no pivot and 1 indicates full column pivoting.

Return type:

None

See also

MatLUFactor

Source code at petsc4py/PETSc/Mat.pyx:4525

factorNumericCholesky(mat, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4626

Parameters:

mat (Mat)

Return type:

None

factorNumericLU(mat, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4559

Parameters:

mat (Mat)

Return type:

None

factorSymbolicCholesky(isperm, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4622

Parameters:

isperm (IS)

Return type:

None

factorSymbolicICC(isperm, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4655

Parameters:

isperm (IS)

Return type:

None

factorSymbolicILU(isrow, iscol, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4593

Parameters:
  • isrow (IS)

  • iscol (IS)

Return type:

None

factorSymbolicLU(mat, isrow, iscol, options=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4555

Parameters:
Return type:

None

findZeroRows()#

Return the index set of empty rows.

Collective.

See also

MatFindZeroRows

Source code at petsc4py/PETSc/Mat.pyx:3339

Return type:

IS

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:

None

Source code at petsc4py/PETSc/Mat.pyx:4730

getBlockSize()#

Return the matrix block size.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1840

Return type:

int

getBlockSizes()#

Return the row and column block sizes.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1854

Return type:

tuple[int, int]

getColumnIJ(symmetric=False, compressed=False)#

Return the CSC representation of the local sparsity pattern.

Collective.

Parameters:
  • symmetric (bool) – If True, return the symmetrized graph.

  • compressed (bool) – If True, return the compressed graph.

Return type:

tuple[ArrayInt, ArrayInt]

See also

MatGetRowIJ

Source code at petsc4py/PETSc/Mat.pyx:2484

getColumnVector(column, result=None)#

Return the columnᵗʰ column vector of the matrix.

Collective.

Parameters:
  • column (int) – Column index.

  • result (Vec | None) – Optional vector to store the result.

Return type:

Vec

Source code at petsc4py/PETSc/Mat.pyx:3426

getDM()#

Return the DM defining the data layout of the matrix.

Not collective.

See also

MatGetDM

Source code at petsc4py/PETSc/Mat.pyx:5483

Return type:

DM

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:

ArrayScalar

Source code at petsc4py/PETSc/Mat.pyx:5288

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 returned array

Return type:

Vec

Source code at petsc4py/PETSc/Mat.pyx:5341

getDenseLDA()#

Return the leading dimension of the array used by the dense matrix.

Not collective.

See also

MatDenseGetLDA

Source code at petsc4py/PETSc/Mat.pyx:5274

Return type:

int

getDenseLocalMatrix()#

Return the local part of the dense matrix.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:5326

Return type:

Mat

getDiagonal(result=None)#

Return the diagonal of the matrix.

Collective.

Parameters:

result (Vec | None) – Optional vector to store the result.

Return type:

Vec

Source code at petsc4py/PETSc/Mat.pyx:3481

getDiagonalBlock()#

Return the part of the matrix associated with the on-process coupling.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:3822

Return type:

Mat

getISAllowRepeated()#

Get the flag for repeated entries in the local to global map.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:4716

Return type:

bool

getISLocalMat()#

Return the local matrix stored inside a Type.IS matrix.

Not collective.

See also

MatISGetLocalMat

Source code at petsc4py/PETSc/Mat.pyx:4749

Return type:

Mat

getInertia()#

Return the inertia from a factored matrix.

Collective.

The matrix must have been factored by calling factorCholesky.

Returns:

  • n (int) – The number of negative eigenvalues.

  • z (int) – The number of zero eigenvalues.

  • p (int) – The number of positive eigenvalues.

Return type:

tuple[int, int, int]

See also

MatGetInertia

Source code at petsc4py/PETSc/Mat.pyx:4659

getInfo(info=None)#

Return summary information.

Collective.

Parameters:

info (InfoType) – If None, it uses InfoType.GLOBAL_SUM.

Return type:

dict[str, float]

See also

MatInfo, MatGetInfo

Source code at petsc4py/PETSc/Mat.pyx:1950

getLGMap()#

Return the local-to-global mappings.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:2750

Return type:

tuple[LGMap, LGMap]

getLRCMats()#

Return the constituents of a Type.LRC matrix.

Not collective.

Returns:

  • A (Mat) – The A matrix.

  • U (Mat) – The first dense rectangular matrix.

  • c (Vec) – The sequential vector containing the diagonal of C.

  • V (Mat) – The second dense rectangular matrix.

Return type:

tuple[Mat, Mat, Vec, Mat]

See also

MatLRCGetMats

Source code at petsc4py/PETSc/Mat.pyx:4831

getLocalSize()#

Return the local number of rows and columns.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1810

Return type:

tuple[int, int]

getLocalSubMatrix(isrow, iscol, submat=None)#

Return a reference to a submatrix specified in local numbering.

Collective.

Parameters:
  • isrow (IS) – Row index set.

  • iscol (IS) – Column index set.

  • submat (Mat | None) – Optional resultant matrix. When None, a new matrix is created. When not None, the matrix is first destroyed and then recreated.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:3937

getMumpsCntl(icntl)#

Return the MUMPS parameter, CNTL[icntl].

Logically collective.

Source code at petsc4py/PETSc/Mat.pyx:5009

Parameters:

icntl (int)

Return type:

float

getMumpsIcntl(icntl)#

Return the MUMPS parameter, ICNTL[icntl].

Logically collective.

Source code at petsc4py/PETSc/Mat.pyx:4973

Parameters:

icntl (int)

Return type:

int

getMumpsInfo(icntl)#

Return the MUMPS parameter, INFO[icntl].

Logically collective.

Parameters:

icntl (int) – The index of the MUMPS INFO array.

Return type:

int

See also

MatMumpsGetInfo

Source code at petsc4py/PETSc/Mat.pyx:5024

getMumpsInfog(icntl)#

Return the MUMPS parameter, INFOG[icntl].

Logically collective.

Parameters:

icntl (int) – The index of the MUMPS INFOG array.

Return type:

int

See also

MatMumpsGetInfog

Source code at petsc4py/PETSc/Mat.pyx:5044

getMumpsRinfo(icntl)#

Return the MUMPS parameter, RINFO[icntl].

Logically collective.

Parameters:

icntl (int) – The index of the MUMPS RINFO array.

Return type:

float

See also

MatMumpsGetRinfo

Source code at petsc4py/PETSc/Mat.pyx:5064

getMumpsRinfog(icntl)#

Return the MUMPS parameter, RINFOG[icntl].

Logically collective.

Parameters:

icntl (int) – The index of the MUMPS RINFOG array.

Return type:

float

Source code at petsc4py/PETSc/Mat.pyx:5084

getNearNullSpace()#

Return the near-nullspace.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:3654

Return type:

NullSpace

getNestISs()#

Return the index sets representing the row and column spaces.

Not collective.

See also

MatNestGetISs

Source code at petsc4py/PETSc/Mat.pyx:5415

Return type:

tuple[list[IS], list[IS]]

getNestLocalISs()#

Return the local index sets representing the row and column spaces.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:5436

Return type:

tuple[list[IS], list[IS]]

getNestSize()#

Return the number of rows and columns of the matrix.

Not collective.

See also

MatNestGetSize

Source code at petsc4py/PETSc/Mat.pyx:5401

Return type:

tuple[int, int]

getNestSubMatrix(i, j)#

Return a single submatrix.

Not collective.

Parameters:
  • i (int) – The first index of the matrix within the nesting.

  • j (int) – The second index of the matrix within the nesting.

Return type:

Mat

See also

MatNestGetSubMat

Source code at petsc4py/PETSc/Mat.pyx:5457

getNullSpace()#

Return the nullspace.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:3600

Return type:

NullSpace

getOption(option)#

Return the option value.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1768

Parameters:

option (Option)

Return type:

bool

getOptionsPrefix()#

Return the prefix used for searching for options in the database.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1703

Return type:

str

getOrdering(ord_type)#

Return a reordering for a matrix to improve a LU factorization.

Collective.

Parameters:

ord_type (OrderingType) – The type of reordering.

Returns:

  • rp (IS) – The row permutation indices.

  • cp (IS) – The column permutation indices.

Return type:

tuple[IS, IS]

See also

MatGetOrdering

Source code at petsc4py/PETSc/Mat.pyx:4469

getOwnershipIS()#

Return the ranges of rows and columns owned by each process as index sets.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1935

Return type:

tuple[IS, IS]

getOwnershipRange()#

Return the locally owned range of rows.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1868

Return type:

tuple[int, int]

getOwnershipRangeColumn()#

Return the locally owned range of columns.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1902

Return type:

tuple[int, int]

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.

Source code at petsc4py/PETSc/Mat.pyx:1882

Return type:

ArrayInt

getOwnershipRangesColumn()#

Return the range of columns owned by each process.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1917

Return type:

ArrayInt

getPythonContext()#

Return the instance of the class implementing the required Python methods.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1642

Return type:

Any

getPythonType()#

Return the fully qualified Python name of the class used by the matrix.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1672

Return type:

str

getRedundantMatrix(nsubcomm, subcomm=None, out=None)#

Return redundant matrices on subcommunicators.

Collective.

Parameters:
  • nsubcomm (int) – The number of subcommunicators.

  • subcomm (Comm | None) – Communicator split or None for the null communicator.

  • out (Mat | None) – Optional resultant matrix. When None, a new matrix is created, and MAT_INITIAL_MATRIX is used. When not None, the matrix is reused with MAT_REUSE_MATRIX.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:3451

getRow(row)#

Return the column indices and values for the requested row.

Not collective.

See also

MatGetRow

Source code at petsc4py/PETSc/Mat.pyx:2433

Parameters:

row (int)

Return type:

tuple[ArrayInt, ArrayScalar]

getRowIJ(symmetric=False, compressed=False)#

Return the CSR representation of the local sparsity pattern.

Collective.

Parameters:
  • symmetric (bool) – If True, return the symmetrized graph.

  • compressed (bool) – If True, return the compressed graph.

Return type:

tuple[ArrayInt, ArrayInt]

See also

MatGetRowIJ

Source code at petsc4py/PETSc/Mat.pyx:2453

getRowSum(result=None)#

Return the row-sum vector.

Collective.

Parameters:

result (Vec | None) – Optional vector to store the result.

Return type:

Vec

See also

MatGetRowSum

Source code at petsc4py/PETSc/Mat.pyx:3503

getSize()#

Return the global number of rows and columns.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1796

Return type:

tuple[int, int]

getSizes()#

Return the tuple of matrix layouts.

Not collective.

See also

getLocalSize, getSize

Source code at petsc4py/PETSc/Mat.pyx:1824

Return type:

tuple[LayoutSizeSpec, LayoutSizeSpec]

getTransposeNullSpace()#

Return the transpose nullspace.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:3627

Return type:

NullSpace

getType()#

Return the type of the matrix.

Not collective.

See also

setType, Type, MatGetType

Source code at petsc4py/PETSc/Mat.pyx:1782

Return type:

str

getValue(row, col)#

Return the value in the (row, col) position.

Not collective.

See also

MatGetValues

Source code at petsc4py/PETSc/Mat.pyx:2358

Return type:

Scalar

getValues(rows, cols, values=None)#

Return the values in the zip(rows, cols) positions.

Not collective.

Parameters:
Return type:

ArrayScalar

See also

MatGetValues

Source code at petsc4py/PETSc/Mat.pyx:2374

getValuesCSR()#

Return the CSR representation of the local part of the matrix.

Not collective.

See also

MatGetRow

Source code at petsc4py/PETSc/Mat.pyx:2395

Return type:

tuple[ArrayInt, ArrayInt, ArrayScalar]

getVecType()#

Return the vector type used by the matrix.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:658

Return type:

str

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:

Mat

Source code at petsc4py/PETSc/Mat.pyx:2108

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 on out.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:2158

increaseOverlap(iset, overlap=1)#

Increase the overlap of a index set.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3837

Parameters:
  • iset (IS)

  • overlap (int)

Return type:

None

invertBlockDiagonal()#

Return the inverse of the block-diagonal entries.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3567

Return type:

ArrayScalar

isAssembled()#

The boolean flag indicating if the matrix is assembled.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:3325

Return type:

bool

isHermitian(tol=0)#

Return the boolean indicating if the matrix is Hermitian.

Collective.

Parameters:

tol (float) – Tolerance for comparison.

Return type:

bool

See also

MatIsHermitian

Source code at petsc4py/PETSc/Mat.pyx:2297

isHermitianKnown()#

Return the 2-tuple indicating if the matrix is known to be Hermitian.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:2317

Return type:

tuple[bool, bool]

isStructurallySymmetric()#

Return the boolean indicating if the matrix is structurally symmetric.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:2332

Return type:

bool

isSymmetric(tol=0)#

Return the boolean indicating if the matrix is symmetric.

Collective.

Parameters:

tol (float) – Tolerance for comparison.

Return type:

bool

See also

MatIsSymmetric

Source code at petsc4py/PETSc/Mat.pyx:2262

isSymmetricKnown()#

Return the 2-tuple indicating if the matrix is known to be symmetric.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:2282

Return type:

tuple[bool, bool]

isTranspose(mat=None, tol=0)#

Return the result of matrix comparison with transposition.

Collective.

Parameters:
  • mat (Mat | None) – Matrix to compare against. Uses self if None.

  • tol (float) – Tolerance for comparison.

Return type:

bool

See also

MatIsTranspose

Source code at petsc4py/PETSc/Mat.pyx:2239

kron(mat, result=None)#

Compute C, the Kronecker product of A and B.

Collective.

Parameters:
  • mat (Mat) – The right hand matrix B.

  • result (Mat | None) – The optional resultant matrix. When None, a new matrix is created, and MAT_INITIAL_MATRIX is used. When it is not None, the matrix is reused with MAT_REUSE_MATRIX.

Returns:

result – The resultant matrix C, the Kronecker product of A and B.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:4398

load(viewer)#

Load a matrix.

Collective.

See also

MatLoad

Source code at petsc4py/PETSc/Mat.pyx:2019

Parameters:

viewer (Viewer)

Return type:

Self

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, and MAT_INITIAL_MATRIX is used. When D is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use None if 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:

Mat

Source code at petsc4py/PETSc/Mat.pyx:4353

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, and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use None if 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:

Mat

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

MatMatMult, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4114

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 type Type.AIJ if using MUMPS.

  • X (Mat) – The output solution matrix, must be different than B.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5234

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, and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use None if 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:

Mat

Notes

To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

Source code at petsc4py/PETSc/Mat.pyx:4161

mult(x, y)#

Perform the matrix vector product y = A @ x.

Collective.

Parameters:
  • x (Vec) – The input vector.

  • y (Vec) – The output vector.

Return type:

None

See also

MatMult

Source code at petsc4py/PETSc/Mat.pyx:3671

multAdd(x, v, y)#

Perform the matrix vector product with addition y = A @ x + v.

Collective.

Parameters:
  • x (Vec) – The input vector for the matrix-vector product.

  • v (Vec) – The input vector to be added to.

  • y (Vec) – The output vector.

Return type:

None

See also

MatMultAdd

Source code at petsc4py/PETSc/Mat.pyx:3690

multHermitian(x, y)#

Perform the Hermitian matrix vector product y = A^H @ x.

Collective.

Parameters:
  • x (Vec) – The input vector for the Hermitian matrix-vector product.

  • y (Vec) – The output vector.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3751

multHermitianAdd(x, v, y)#

Perform the Hermitian matrix vector product with addition y = A^H @ x + v.

Collective.

Parameters:
  • x (Vec) – The input vector for the Hermitian matrix-vector product.

  • v (Vec) – The input vector to be added to.

  • y (Vec) – The output vector.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3770

multTranspose(x, y)#

Perform the transposed matrix vector product y = A^T @ x.

Collective.

Parameters:
  • x (Vec) – The input vector.

  • y (Vec) – The output vector.

Return type:

None

See also

MatMultTranspose

Source code at petsc4py/PETSc/Mat.pyx:3711

multTransposeAdd(x, v, y)#

Perform the transposed matrix vector product with addition y = A^T @ x + v.

Collective.

Parameters:
  • x (Vec) – The input vector for the transposed matrix-vector product.

  • v (Vec) – The input vector to be added to.

  • y (Vec) – The output vector.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3730

norm(norm_type=None)#

Compute the requested matrix norm.

Collective.

A 2-tuple is returned if NormType.NORM_1_AND_2 is specified.

See also

MatNorm, NormType

Source code at petsc4py/PETSc/Mat.pyx:3986

Parameters:

norm_type (NormTypeSpec)

Return type:

float | tuple[float, float]

permute(row, col)#

Return the permuted matrix.

Collective.

Parameters:
  • row (IS) – Row permutation.

  • col (IS) – Column permutation.

Return type:

Mat

See also

MatPermute

Source code at petsc4py/PETSc/Mat.pyx:2204

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, and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)), use None if 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:

Mat

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 MatProductCreate and set the desired options before the computation is done.

See also

MatPtAP, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4255

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, and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use None if 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:

Mat

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

MatRARt, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4306

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 on out.

Return type:

Mat

Source code at petsc4py/PETSc/Mat.pyx:2135

reorderForNonzeroDiagonal(isrow, iscol, atol=0)#

Change a matrix ordering to remove zeros from the diagonal.

Collective.

Parameters:
  • isrow (IS) – The row reordering.

  • iscol (IS) – The column reordering.

  • atol (float) – The absolute tolerance. Values along the diagonal whose absolute value are smaller than this tolerance are moved off the diagonal.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4497

restoreDenseColumnVec(i, mode='rw')#

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 restored array

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5373

restoreISLocalMat(local)#

Restore the local matrix obtained with getISLocalMat.

Not collective.

Parameters:

local (Mat) – The local matrix.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4764

restoreLocalSubMatrix(isrow, iscol, submat)#

Restore a reference to a submatrix obtained with getLocalSubMatrix.

Collective.

Parameters:
  • isrow (IS) – Row index set.

  • iscol (IS) – Column index set.

  • submat (Mat) – The submatrix.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3963

retrieveValues()#

Retrieve a copy of the matrix values previously stored with storeValues.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3258

Return type:

None

scale(alpha)#

Scale the matrix.

Collective.

See also

MatScale

Source code at petsc4py/PETSc/Mat.pyx:4008

Parameters:

alpha (Scalar)

Return type:

None

setBlockSize(bsize)#

Set the matrix block size (same for rows and columns).

Logically collective.

Parameters:

bsize (int) – Block size.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:586

setBlockSizes(row_bsize, col_bsize)#

Set the row and column block sizes.

Logically collective.

Parameters:
  • row_bsize (int) – Row block size.

  • col_bsize (int) – Column block size.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:604

setDM(dm)#

Set the DM defining the data layout of the matrix.

Not collective.

Parameters:

dm (DM) – The DM.

Return type:

None

See also

MatSetDM

Source code at petsc4py/PETSc/Mat.pyx:5500

setDenseLDA(lda)#

Set the leading dimension of the array used by the dense matrix.

Not collective.

Parameters:

lda (int) – The leading dimension.

Return type:

None

See also

MatDenseSetLDA

Source code at petsc4py/PETSc/Mat.pyx:5256

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:

None

Source code at petsc4py/PETSc/Mat.pyx:3525

setFromOptions()#

Configure the matrix from the options database.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:1731

Return type:

None

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:

None

Source code at petsc4py/PETSc/Mat.pyx:4698

setISLocalMat(local)#

Set the local matrix stored inside a Type.IS.

Not collective.

Parameters:

local (Mat) – The local matrix.

Return type:

None

See also

MatISSetLocalMat

Source code at petsc4py/PETSc/Mat.pyx:4781

setISPreallocation(nnz, onnz)#

Preallocate memory for a Type.IS parallel 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:

Self

Source code at petsc4py/PETSc/Mat.pyx:4798

setLGMap(rmap, cmap=None)#

Set the local-to-global mappings.

Collective.

Parameters:
  • rmap (LGMap) – Row mapping.

  • cmap (LGMap | None) – Column mapping. If None, cmap = rmap.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2730

setLRCMats(A, U, c=None, V=None)#

Set the constituents of a Type.LRC matrix.

Logically collective.

Parameters:
  • A (Mat) – The A matrix, or None to omit A.

  • U (Mat) – The first dense rectangular matrix.

  • c (Vec) – The sequential vector containing the diagonal of C, or None for all ones.

  • V (Mat) – The second dense rectangular matrix, or None for a copy of U.

Return type:

None

See also

MatLRCSetMats

Source code at petsc4py/PETSc/Mat.pyx:4863

setMumpsCntl(icntl, val)#

Set a MUMPS parameter, CNTL[icntl] = val.

Logically collective.

Parameters:
  • icntl (int) – The index of the MUMPS parameter array.

  • val (float) – The value to set.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4988

setMumpsIcntl(icntl, ival)#

Set a MUMPS parameter, ICNTL[icntl] = ival.

Logically collective.

Parameters:
  • icntl (int) – The index of the MUMPS parameter array.

  • ival (int) – The value to set.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:4952

setNearNullSpace(nsp)#

Set the near-nullspace.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3642

Parameters:

nsp (NullSpace)

Return type:

None

setNestVecType(vec_type)#

Set the vector type for a Type.NEST matrix.

Collective.

Parameters:

vec_type (Type | str) – Vector type used when creating vectors with createVecs.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:672

setNullSpace(nsp)#

Set the nullspace.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3588

Parameters:

nsp (NullSpace)

Return type:

None

setOption(option, flag)#

Set option.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:1756

Parameters:
Return type:

None

setOptionsPrefix(prefix=None)#

Set the prefix used for searching for options in the database.

Logically collective.

Source code at petsc4py/PETSc/Mat.pyx:1689

Parameters:

prefix (str | None)

Return type:

None

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:

Self

Notes

Must use the block-compressed form with Type.BAIJ and Type.SBAIJ.

Source code at petsc4py/PETSc/Mat.pyx:899

setPreallocationDense(array)#

Set the array used for storing matrix elements for a dense matrix.

Collective.

Parameters:

array (Sequence[Scalar]) – Array that will be used to store matrix data.

Return type:

Self

Source code at petsc4py/PETSc/Mat.pyx:1117

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:

Self

Source code at petsc4py/PETSc/Mat.pyx:873

setPythonContext(context)#

Set the instance of the class implementing the required Python methods.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:1630

Parameters:

context (Any)

Return type:

None

setPythonType(py_type)#

Set the fully qualified Python name of the class to be used.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:1657

Parameters:

py_type (str)

Return type:

None

setRandom(random=None)#

Set random values in the matrix.

Collective.

Parameters:

random (Random | None) – The random number generator object or None for the default.

Return type:

None

See also

MatSetRandom

Source code at petsc4py/PETSc/Mat.pyx:4047

setSizes(size, bsize=None)#

Set the local, global and block sizes.

Collective.

Parameters:
Return type:

None

Examples

Create a Mat with n rows and columns and the same local and global sizes.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes(n)

Create a Mat with nr rows, nc columns and the same local and global sizes.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([nr, nc])

Create a Mat with nrl local rows, nrg global rows, ncl local columns and ncg global columns.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([[nrl, nrg], [ncl, ncg]])

Source code at petsc4py/PETSc/Mat.pyx:533

setStencil(dims, starts=None, dof=1)#

Set matrix stencil.

Not collective.

See also

MatSetStencil

Source code at petsc4py/PETSc/Mat.pyx:2988

Parameters:
Return type:

None

setTransposeNullSpace(nsp)#

Set the transpose nullspace.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3615

Parameters:

nsp (NullSpace)

Return type:

None

setTransposePrecursor(out)#

Set transpose precursor.

Logically collective.

Source code at petsc4py/PETSc/Mat.pyx:2096

Parameters:

out (Mat)

Return type:

None

setType(mat_type)#

Set the matrix type.

Collective.

Parameters:

mat_type (Type | str) – The matrix type.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:514

setUnfactored()#

Set a factored matrix to be treated as unfactored.

Logically collective.

See also

MatSetUnfactored

Source code at petsc4py/PETSc/Mat.pyx:4684

Return type:

None

setUp()#

Set up the internal data structures for using the matrix.

Collective.

See also

MatSetUp

Source code at petsc4py/PETSc/Mat.pyx:1743

Return type:

Self

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:

None

See also

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2514

setValueBlockedStagStencil(row, col, value, addv=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:3072

Return type:

None

setValueBlockedStencil(row, col, value, addv=None)#

Set a block of values to row and col stencil.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3042

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:

None

Source code at petsc4py/PETSc/Mat.pyx:2767

setValueStagStencil(row, col, value, addv=None)#

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:3038

Return type:

None

setValueStencil(row, col, value, addv=None)#

Set a value to row and col stencil.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:3008

setValues(rows, cols, values, addv=None)#

Set values to the rows ⊗ cols entries of the matrix.

Not collective.

Parameters:
Return type:

None

See also

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2546

setValuesBlocked(rows, cols, values, addv=None)#

Set values to the rows ⊗ col block entries of the matrix.

Not collective.

Parameters:
  • rows (Sequence[int]) – Block row indices.

  • cols (Sequence[int]) – Block column indices.

  • values (Sequence[Scalar]) – The scalar values. A sequence of length at least len(rows) * len(cols) * bs * bs, where bs is the block size of the matrix.

  • addv (InsertModeSpec) – Insertion mode.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2637

setValuesBlockedCSR(I, J, V, addv=None)#

Set values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2702

setValuesBlockedIJV(I, J, V, addv=None, rowmap=None)#

Set a subset of values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2671

setValuesBlockedLocal(rows, cols, values, addv=None)#

Set values to the rows ⊗ col block entries of the matrix in local ordering.

Not collective.

Parameters:
  • rows (Sequence[int]) – Local block row indices.

  • cols (Sequence[int]) – Local block column indices.

  • values (Sequence[Scalar]) – The scalar values. A sequence of length at least len(rows) * len(cols) * bs * bs, where bs is the block size of the matrix.

  • addv (InsertModeSpec) – Insertion mode.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2891

setValuesBlockedLocalCSR(I, J, V, addv=None)#

Set values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2956

setValuesBlockedLocalIJV(I, J, V, addv=None, rowmap=None)#

Set a subset of values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2925

setValuesBlockedLocalRCV(R, C, V, addv=None)#

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2921

Return type:

None

setValuesBlockedRCV(R, C, V, addv=None)#

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2667

Return type:

None

setValuesCSR(I, J, V, addv=None)#

Set values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2609

setValuesIJV(I, J, V, addv=None, rowmap=None)#

Set a subset of values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2578

setValuesLocal(rows, cols, values, addv=None)#

Set values to the rows ⊗ col entries of the matrix in local ordering.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2800

setValuesLocalCSR(I, J, V, addv=None)#

Set values stored in CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2863

setValuesLocalIJV(I, J, V, addv=None, rowmap=None)#

Set a subset of values stored in CSR format.

Not collective.

Parameters:
Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:2832

setValuesLocalRCV(R, C, V, addv=None)#

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2828

Return type:

None

setValuesRCV(R, C, V, addv=None)#

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2574

Return type:

None

setVariableBlockSizes(blocks)#

Set diagonal point-blocks of the matrix.

Not collective.

Source code at petsc4py/PETSc/Mat.pyx:625

Parameters:

blocks (Sequence[int])

Return type:

None

setVecType(vec_type)#

Set the vector type.

Collective.

Parameters:

vec_type (Type | str) – Vector type used when creating vectors with createVecs.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:639

shift(alpha)#

Shift the matrix.

Collective.

See also

MatShift

Source code at petsc4py/PETSc/Mat.pyx:4021

Parameters:

alpha (Scalar)

Return type:

None

solve(b, x)#

Solve Ax=b, given a factored matrix.

Neighborwise collective.

The vectors b and x cannot be the same. Most users should employ the KSP interface for linear solvers instead of working directly with matrix algebra routines.

Parameters:
  • b (Vec) – The right-hand side vector.

  • x (Vec) – The output solution vector, must be different than b.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5144

solveAdd(b, y, x)#

Solve x=y+A⁻¹b, given a factored matrix.

Neighborwise collective.

The vectors b and x cannot be the same.

Parameters:
  • b (Vec) – The right-hand side vector.

  • y (Vec) – The vector to be added

  • x (Vec) – The output solution vector, must be different than b.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5188

solveBackward(b, x)#

Solve Ux=b, given a factored matrix A=LU.

Neighborwise collective.

Parameters:
  • b (Vec) – The right-hand side vector.

  • x (Vec) – The output solution vector.

Return type:

None

See also

MatBackwardSolve

Source code at petsc4py/PETSc/Mat.pyx:5125

solveForward(b, x)#

Solve Lx = b, given a factored matrix A = LU.

Neighborwise collective.

Parameters:
  • b (Vec) – The right-hand side vector.

  • x (Vec) – The output solution vector.

Return type:

None

See also

MatForwardSolve

Source code at petsc4py/PETSc/Mat.pyx:5106

solveTranspose(b, x)#

Solve Aᵀx=b, given a factored matrix.

Neighborwise collective.

The vectors b and x cannot be the same.

Parameters:
  • b (Vec) – The right-hand side vector.

  • x (Vec) – The output solution vector, must be different than b.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5167

solveTransposeAdd(b, y, x)#

Solve x=y+A⁻ᵀb, given a factored matrix.

Neighborwise collective.

The vectors b and x cannot be the same.

Parameters:
  • b (Vec) – The right-hand side vector.

  • y (Vec) – The vector to be added

  • x (Vec) – The output solution vector, must be different than b.

Return type:

None

Source code at petsc4py/PETSc/Mat.pyx:5211

storeValues()#

Stash a copy of the matrix values.

Collective.

Source code at petsc4py/PETSc/Mat.pyx:3246

Return type:

None

toDLPack(mode='rw')#

Return a DLPack PyCapsule wrapping the vector data.

Source code at petsc4py/PETSc/Mat.pyx:5588

Parameters:

mode (AccessModeSpec)

Return type:

Any

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:

Mat

See also

MatTranspose

Source code at petsc4py/PETSc/Mat.pyx:2069

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, and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.

  • fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use None if 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:

Mat

Notes

To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

Source code at petsc4py/PETSc/Mat.pyx:4208

view(viewer=None)#

View the matrix.

Collective.

Parameters:

viewer (Viewer | None) – A Viewer instance or None for the default viewer.

Return type:

None

Notes

Viewers with type Viewer.Type.ASCII are only recommended for small matrices on small numbers of processes. Larger matrices should use a binary format like Viewer.Type.BINARY.

See also

load, Viewer, MatView

Source code at petsc4py/PETSc/Mat.pyx:450

zeroEntries()#

Zero the entries of the matrix.

Collective.

See also

MatZeroEntries

Source code at petsc4py/PETSc/Mat.pyx:2346

Return type:

None

zeroRows(rows, diag=1, x=None, b=None)#

Zero selected rows of the matrix.

Collective.

Parameters:
  • rows (IS | Sequence[int]) – Row 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:

None

Source code at petsc4py/PETSc/Mat.pyx:3076

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:

None

Source code at petsc4py/PETSc/Mat.pyx:3142

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:

None

Source code at petsc4py/PETSc/Mat.pyx:3176

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:

None

Source code at petsc4py/PETSc/Mat.pyx:3210

zeroRowsLocal(rows, diag=1, x=None, b=None)#

Zero selected rows of the matrix in local ordering.

Collective.

Parameters:
  • rows (IS | Sequence[int]) – Local row 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:

None

Source code at petsc4py/PETSc/Mat.pyx:3109

Attributes Documentation

assembled#

The boolean flag indicating if the matrix is assembled.

Source code at petsc4py/PETSc/Mat.pyx:5563

block_size#

Matrix block size.

Source code at petsc4py/PETSc/Mat.pyx:5541

block_sizes#

Matrix row and column block sizes.

Source code at petsc4py/PETSc/Mat.pyx:5546

hermitian#

The boolean flag indicating if the matrix is Hermitian.

Source code at petsc4py/PETSc/Mat.pyx:5571

local_size#

Matrix local size.

Source code at petsc4py/PETSc/Mat.pyx:5536

owner_range#

Matrix local row range.

Source code at petsc4py/PETSc/Mat.pyx:5551

owner_ranges#

Matrix row ranges.

Source code at petsc4py/PETSc/Mat.pyx:5556

size#

Matrix global size.

Source code at petsc4py/PETSc/Mat.pyx:5531

sizes#

Matrix local and global sizes.

Source code at petsc4py/PETSc/Mat.pyx:5523

structsymm#

The boolean flag indicating if the matrix is structurally symmetric.

Source code at petsc4py/PETSc/Mat.pyx:5575

symmetric#

The boolean flag indicating if the matrix is symmetric.

Source code at petsc4py/PETSc/Mat.pyx:5567