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.

createSchurComplement(A00, Ap00, A01, A10[, A11])

Create a Type.SCHURCOMPLEMENT matrix.

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.

getSchurComplementSubMatrices()

Return Schur complement sub-matrices.

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

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

H2OpusOrthogonalize()#

Orthogonalize the basis tree of a hierarchical matrix.

Collective.

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

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

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

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

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

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

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

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

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

boundToCPU()#

Query if a matrix is bound to the CPU.

Not collective.

See also

MatBoundToCPU

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

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

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

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

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

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

createSchurComplement(A00, Ap00, A01, A10, A11=None)#

Create a Type.SCHURCOMPLEMENT matrix.

Collective.

Parameters:
  • A00 (Mat) – the upper-left block of the original matrix A = [A00 A01; A10 A11].

  • Ap00 (Mat) – preconditioning matrix for use 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:

Self

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

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

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

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

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

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

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

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

equal(mat)#

Return the result of matrix comparison.

Collective.

See also

MatEqual

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

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

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

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

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

factorNumericCholesky(mat, options=None)#

Not implemented.

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

Parameters:

mat (Mat)

Return type:

None

factorNumericLU(mat, options=None)#

Not implemented.

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

Parameters:

mat (Mat)

Return type:

None

factorSymbolicCholesky(isperm, options=None)#

Not implemented.

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

Parameters:

isperm (IS)

Return type:

None

factorSymbolicICC(isperm, options=None)#

Not implemented.

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

Parameters:

isperm (IS)

Return type:

None

factorSymbolicILU(isrow, iscol, options=None)#

Not implemented.

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

Parameters:
  • isrow (IS)

  • iscol (IS)

Return type:

None

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

Not implemented.

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

Parameters:
Return type:

None

findZeroRows()#

Return the index set of empty rows.

Collective.

See also

MatFindZeroRows

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

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

getBlockSize()#

Return the matrix block size.

Not collective.

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

Return type:

int

getBlockSizes()#

Return the row and column block sizes.

Not collective.

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

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

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

getDM()#

Return the DM defining the data layout of the matrix.

Not collective.

See also

MatGetDM

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

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

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

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

Return type:

int

getDenseLocalMatrix()#

Return the local part of the dense matrix.

Not collective.

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

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

getDiagonalBlock()#

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

Not collective.

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

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

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

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

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

getLGMap()#

Return the local-to-global mappings.

Not collective.

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

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

getLocalSize()#

Return the local number of rows and columns.

Not collective.

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

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

getMumpsCntl(icntl)#

Return the MUMPS parameter, CNTL[icntl].

Logically collective.

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

Parameters:

icntl (int)

Return type:

float

getMumpsIcntl(icntl)#

Return the MUMPS parameter, ICNTL[icntl].

Logically collective.

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

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

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

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

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

getNearNullSpace()#

Return the near-nullspace.

Not collective.

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

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

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

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

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

getNullSpace()#

Return the nullspace.

Not collective.

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

Return type:

NullSpace

getOption(option)#

Return the option value.

Not collective.

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

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

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

getOwnershipIS()#

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

Not collective.

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

Return type:

tuple[IS, IS]

getOwnershipRange()#

Return the locally owned range of rows.

Not collective.

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

Return type:

tuple[int, int]

getOwnershipRangeColumn()#

Return the locally owned range of columns.

Not collective.

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

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

Return type:

ArrayInt

getOwnershipRangesColumn()#

Return the range of columns owned by each process.

Not collective.

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

Return type:

ArrayInt

getPythonContext()#

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

Not collective.

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

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

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

getRow(row)#

Return the column indices and values for the requested row.

Not collective.

See also

MatGetRow

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

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

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

getSchurComplementSubMatrices()#

Return Schur complement sub-matrices.

Collective.

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

Return type:

tuple[Mat, Mat, Mat, Mat, Mat]

getSize()#

Return the global number of rows and columns.

Not collective.

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

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

Return type:

tuple[LayoutSizeSpec, LayoutSizeSpec]

getTransposeNullSpace()#

Return the transpose nullspace.

Not collective.

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

Return type:

NullSpace

getType()#

Return the type of the matrix.

Not collective.

See also

setType, Type, MatGetType

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

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

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

getValuesCSR()#

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

Not collective.

See also

MatGetRow

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

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

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

increaseOverlap(iset, overlap=1)#

Increase the overlap of a index set.

Collective.

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

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

Return type:

ArrayScalar

isAssembled()#

The boolean flag indicating if the matrix is assembled.

Not collective.

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

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

isHermitianKnown()#

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

Not collective.

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

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

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

isSymmetricKnown()#

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

Not collective.

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

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

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

load(viewer)#

Load a matrix.

Collective.

See also

MatLoad

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

retrieveValues()#

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

Collective.

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

Return type:

None

scale(alpha)#

Scale the matrix.

Collective.

See also

MatScale

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

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

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

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

setFromOptions()#

Configure the matrix from the options database.

Collective.

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

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

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

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

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

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

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

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

setNearNullSpace(nsp)#

Set the near-nullspace.

Collective.

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

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

Parameters:

nsp (NullSpace)

Return type:

None

setOption(option, flag)#

Set option.

Collective.

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

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

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.

Logically collective.

Notes

In order to use the matrix, Mat.setUp must be called after having set the context. Pass None to reset the matrix to its initial state.

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

Parameters:

context (Any)

Return type:

None

setPythonType(py_type)#

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

Collective.

Notes

In order to use the matrix, Mat.setUp must be called after having set the type.

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

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

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

Parameters:
Return type:

None

setTransposeNullSpace(nsp)#

Set the transpose nullspace.

Collective.

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

Parameters:

nsp (NullSpace)

Return type:

None

setTransposePrecursor(out)#

Set transpose precursor.

Logically collective.

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

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

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

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

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

Not implemented.

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

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

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

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

Not implemented.

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

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

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

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

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

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

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

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

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

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

Undocumented.

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

Return type:

None

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

Undocumented.

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

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

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

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

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

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

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

Undocumented.

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

Return type:

None

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

Undocumented.

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

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

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

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

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

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

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

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

storeValues()#

Stash a copy of the matrix values.

Collective.

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

Return type:

None

toDLPack(mode='rw')#

Return a DLPack PyCapsule wrapping the vector data.

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

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

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

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

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

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

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

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

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

Attributes Documentation

assembled#

The boolean flag indicating if the matrix is assembled.

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

block_size#

Matrix block size.

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

block_sizes#

Matrix row and column block sizes.

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

hermitian#

The boolean flag indicating if the matrix is Hermitian.

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

local_size#

Matrix local size.

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

owner_range#

Matrix local row range.

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

owner_ranges#

Matrix row ranges.

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

size#

Matrix global size.

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

sizes#

Matrix local and global sizes.

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

structsymm#

The boolean flag indicating if the matrix is structurally symmetric.

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

symmetric#

The boolean flag indicating if the matrix is symmetric.

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