slepc4py.SLEPc.ST#

class slepc4py.SLEPc.ST#

Bases: Object

ST.

Enumerations

FilterDamping

ST filter damping.

FilterType

ST filter type.

MatMode

ST matrix mode.

Type

ST types.

Methods Summary

appendOptionsPrefix([prefix])

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

apply(x, y)

Apply the spectral transformation operator to a vector.

applyHermitianTranspose(x, y)

Apply the hermitian-transpose of the operator to a vector.

applyMat(x, y)

Apply the spectral transformation operator to a matrix.

applyTranspose(x, y)

Apply the transpose of the operator to a vector.

create([comm])

Create the ST object.

destroy()

Destroy the ST object.

getCayleyAntishift()

Get the value of the anti-shift for the Cayley spectral transformation.

getFilterDamping()

Get the type of damping used in the polynomial filter.

getFilterDegree()

Get the degree of the filter polynomial.

getFilterInterval()

Get the interval containing the desired eigenvalues.

getFilterRange()

Get the interval containing all eigenvalues.

getFilterType()

Get the method to be used to build the polynomial filter.

getKSP()

Get the KSP object associated with the spectral transformation.

getMatMode()

Get a flag that indicates how the matrix is being shifted.

getMatStructure()

Get the internal Mat.Structure attribute.

getMatrices()

Get the matrices associated with the eigenvalue problem.

getOperator()

Get a shell matrix that represents the operator of the spectral transformation.

getOptionsPrefix()

Get the prefix used for searching for all ST options in the database.

getPreconditionerMat()

Get the matrix previously set by setPreconditionerMat().

getShift()

Get the shift associated with the spectral transformation.

getTransform()

Get the flag indicating whether the transformed matrices are computed or not.

getType()

Get the ST type of this object.

reset()

Reset the ST object.

restoreOperator(op)

Restore the previously seized operator matrix.

setCayleyAntishift(tau)

Set the value of the anti-shift for the Cayley spectral transformation.

setFilterDamping(damping)

Set the type of damping to be used in the polynomial filter.

setFilterDegree(deg)

Set the degree of the filter polynomial.

setFilterInterval(inta, intb)

Set the interval containing the desired eigenvalues.

setFilterRange(left, right)

Set the numerical range (or field of values) of the matrix.

setFilterType(filter_type)

Set the method to be used to build the polynomial filter.

setFromOptions()

Set ST options from the options database.

setKSP(ksp)

Set the KSP object associated with the spectral transformation.

setMatMode(mode)

Set a flag to indicate how the matrix is being shifted.

setMatStructure(structure)

Set an internal Mat.Structure attribute.

setMatrices(operators)

Set the matrices associated with the eigenvalue problem.

setOptionsPrefix([prefix])

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

setPreconditionerMat([P])

Set the matrix to be used to build the preconditioner.

setShift(shift)

Set the shift associated with the spectral transformation.

setTransform([flag])

Set a flag to indicate whether the transformed matrices are computed or not.

setType(st_type)

Set the particular spectral transformation to be used.

setUp()

Prepare for the use of a spectral transformation.

view([viewer])

Print the ST data structure.

Attributes Summary

ksp

KSP object associated with the spectral transformation.

mat_mode

How the transformed matrices are being stored in the ST.

mat_structure

Relation of the sparsity pattern of all ST matrices.

shift

Value of the shift.

transform

If the transformed matrices are computed.

Methods Documentation

appendOptionsPrefix(prefix=None)#

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

Logically collective.

Parameters:

prefix (str | None) – The prefix string to prepend to all ST option requests.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:198

apply(x, y)#

Apply the spectral transformation operator to a vector.

Collective.

Apply the spectral transformation operator to a vector, for instance \((A - s B)^{-1} B\) in the case of the shift-and-invert transformation and generalized eigenproblem.

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

  • y (Vec) – The result vector.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:520

applyHermitianTranspose(x, y)#

Apply the hermitian-transpose of the operator to a vector.

Collective.

Apply the hermitian-transpose of the operator to a vector, for instance \(B^H(A - s B)^{-H}\) in the case of the shift-and-invert transformation and generalized eigenproblem.

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

  • y (Vec) – The result vector.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:558

applyMat(x, y)#

Apply the spectral transformation operator to a matrix.

Collective.

Apply the spectral transformation operator to a matrix, for instance \((A - s B)^{-1} B\) in the case of the shift-and-invert transformation and generalized eigenproblem.

Parameters:
  • x (Mat) – The input matrix.

  • y (Mat) – The result matrix.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:577

applyTranspose(x, y)#

Apply the transpose of the operator to a vector.

Collective.

Apply the transpose of the operator to a vector, for instance \(B^T(A - s B)^{-T}\) in the case of the shift-and-invert transformation and generalized eigenproblem.

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

  • y (Vec) – The result vector.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:539

create(comm=None)#

Create the ST object.

Collective.

Parameters:

comm (Comm | None) – MPI communicator; if not provided, it defaults to all processes.

Return type:

Self

Source code at slepc4py/SLEPc/ST.pyx:106

destroy()#

Destroy the ST object.

Collective.

Source code at slepc4py/SLEPc/ST.pyx:88

Return type:

Self

getCayleyAntishift()#

Get the value of the anti-shift for the Cayley spectral transformation.

Not collective.

Returns:

The anti-shift.

Return type:

Scalar

Source code at slepc4py/SLEPc/ST.pyx:649

getFilterDamping()#

Get the type of damping used in the polynomial filter.

Not collective.

Returns:

The type of damping.

Return type:

FilterDamping

Source code at slepc4py/SLEPc/ST.pyx:827

getFilterDegree()#

Get the degree of the filter polynomial.

Not collective.

Returns:

The polynomial degree.

Return type:

int

Source code at slepc4py/SLEPc/ST.pyx:798

getFilterInterval()#

Get the interval containing the desired eigenvalues.

Not collective.

Returns:

  • inta (float) – The left end of the interval.

  • intb (float) – The right end of the interval.

Return type:

tuple[float, float]

Source code at slepc4py/SLEPc/ST.pyx:722

getFilterRange()#

Get the interval containing all eigenvalues.

Not collective.

Returns:

  • left (float) – The left end of the interval.

  • right (float) – The right end of the interval.

Return type:

tuple[float, float]

Source code at slepc4py/SLEPc/ST.pyx:766

getFilterType()#

Get the method to be used to build the polynomial filter.

Not collective.

Returns:

The type of filter.

Return type:

FilterType

Source code at slepc4py/SLEPc/ST.pyx:678

getKSP()#

Get the KSP object associated with the spectral transformation.

Collective.

Returns:

The linear solver object.

Return type:

petsc4py.PETSc.KSP

Notes

On output, the internal value of petsc4py.PETSc.KSP can be NULL if the combination of eigenproblem type and selected transformation does not require to solve a linear system of equations.

Source code at slepc4py/SLEPc/ST.pyx:458

getMatMode()#

Get a flag that indicates how the matrix is being shifted.

Not collective.

Get a flag that indicates how the matrix is being shifted in the shift-and-invert and Cayley spectral transformations.

Returns:

The mode flag.

Return type:

MatMode

Source code at slepc4py/SLEPc/ST.pyx:342

getMatStructure()#

Get the internal Mat.Structure attribute.

Not collective.

Get the internal Mat.Structure attribute to indicate which is the relation of the sparsity pattern of the matrices.

Returns:

The structure flag.

Return type:

petsc4py.PETSc.Mat.Structure

Source code at slepc4py/SLEPc/ST.pyx:427

getMatrices()#

Get the matrices associated with the eigenvalue problem.

Collective.

Returns:

The matrices associated with the eigensystem.

Return type:

list of petsc4py.PETSc.Mat

Source code at slepc4py/SLEPc/ST.pyx:378

getOperator()#

Get a shell matrix that represents the operator of the spectral transformation.

Collective.

Returns:

Operator matrix.

Return type:

petsc4py.PETSc.Mat

Source code at slepc4py/SLEPc/ST.pyx:596

getOptionsPrefix()#

Get the prefix used for searching for all ST options in the database.

Not collective.

Returns:

The prefix string set for this ST object.

Return type:

str

Source code at slepc4py/SLEPc/ST.pyx:183

getPreconditionerMat()#

Get the matrix previously set by setPreconditionerMat().

Not collective.

Returns:

The matrix that will be used in constructing the preconditioner.

Return type:

petsc4py.PETSc.Mat

Source code at slepc4py/SLEPc/ST.pyx:494

getShift()#

Get the shift associated with the spectral transformation.

Not collective.

Returns:

The value of the shift.

Return type:

Scalar

Source code at slepc4py/SLEPc/ST.pyx:250

getTransform()#

Get the flag indicating whether the transformed matrices are computed or not.

Not collective.

Returns:

This flag is intended for the case of polynomial eigenproblems solved via linearization. If this flag is False (default) the spectral transformation is applied to the linearization (handled by the eigensolver), otherwise it is applied to the original problem.

Return type:

bool

Source code at slepc4py/SLEPc/ST.pyx:283

getType()#

Get the ST type of this object.

Not collective.

Returns:

The spectral transformation currently being used.

Return type:

str

Source code at slepc4py/SLEPc/ST.pyx:147

reset()#

Reset the ST object.

Collective.

Source code at slepc4py/SLEPc/ST.pyx:98

Return type:

None

restoreOperator(op)#

Restore the previously seized operator matrix.

Logically collective.

Parameters:

op (Mat) – Operator matrix previously obtained with getOperator().

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:612

setCayleyAntishift(tau)#

Set the value of the anti-shift for the Cayley spectral transformation.

Logically collective.

Parameters:

tau (Scalar) – The anti-shift.

Return type:

None

Notes

In the generalized Cayley transform, the operator can be expressed as \(OP = inv(A - \sigma B) (A + tau B)\). This function sets the value of \(tau\). Use setShift() for setting \(\sigma\).

Source code at slepc4py/SLEPc/ST.pyx:628

setFilterDamping(damping)#

Set the type of damping to be used in the polynomial filter.

Logically collective.

Parameter#

damping

The type of damping.

Source code at slepc4py/SLEPc/ST.pyx:813

Parameters:

damping (FilterDamping)

Return type:

None

setFilterDegree(deg)#

Set the degree of the filter polynomial.

Logically collective.

Parameters:

deg (int) – The polynomial degree.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:784

setFilterInterval(inta, intb)#

Set the interval containing the desired eigenvalues.

Logically collective.

Parameters:
  • inta (float) – The left end of the interval.

  • intb (float) – The right end of the interval.

Return type:

None

Notes

The filter will be configured to emphasize eigenvalues contained in the given interval, and damp out eigenvalues outside it. If the interval is open, then the filter is low- or high-pass, otherwise it is mid-pass.

Common usage is to set the interval in EPS with EPS.setInterval().

The interval must be contained within the numerical range of the matrix, see ST.setFilterRange().

Source code at slepc4py/SLEPc/ST.pyx:693

setFilterRange(left, right)#

Set the numerical range (or field of values) of the matrix.

Logically collective.

Set the numerical range (or field of values) of the matrix, that is, the interval containing all eigenvalues.

Parameters:
  • left (float) – The left end of the interval.

  • right (float) – The right end of the interval.

Return type:

None

Notes

The filter will be most effective if the numerical range is tight, that is, left and right are good approximations to the leftmost and rightmost eigenvalues, respectively.

Source code at slepc4py/SLEPc/ST.pyx:740

setFilterType(filter_type)#

Set the method to be used to build the polynomial filter.

Logically collective.

Parameter#

filter_type

The type of filter.

Source code at slepc4py/SLEPc/ST.pyx:664

Parameters:

filter_type (FilterType)

Return type:

None

setFromOptions()#

Set ST options from the options database.

Collective.

This routine must be called before setUp() if the user is to be allowed to set the solver type.

Notes

To see all options, run your program with the -help option.

Source code at slepc4py/SLEPc/ST.pyx:213

Return type:

None

setKSP(ksp)#

Set the KSP object associated with the spectral transformation.

Collective.

Parameters:
Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:445

setMatMode(mode)#

Set a flag to indicate how the matrix is being shifted.

Logically collective.

Set a flag to indicate how the matrix is being shifted in the shift-and-invert and Cayley spectral transformations.

Parameters:

mode (MatMode) – The mode flag.

Return type:

None

Notes

By default (ST.MatMode.COPY), a copy of matrix \(A\) is made and then this copy is shifted explicitly, e.g. \(A \leftarrow (A - s B)\).

With ST.MatMode.INPLACE, the original matrix \(A\) is shifted at setUp() and unshifted at the end of the computations. With respect to the previous one, this mode avoids a copy of matrix \(A\). However, a backdraw is that the recovered matrix might be slightly different from the original one (due to roundoff).

With ST.MatMode.SHELL, the solver works with an implicit shell matrix that represents the shifted matrix. This mode is the most efficient in creating the shifted matrix but it places serious limitations to the linear solves performed in each iteration of the eigensolver (typically, only iterative solvers with Jacobi preconditioning can be used).

In the case of generalized problems, in the two first modes the matrix \(A - s B\) has to be computed explicitly. The efficiency of this computation can be controlled with setMatStructure().

Source code at slepc4py/SLEPc/ST.pyx:302

setMatStructure(structure)#

Set an internal Mat.Structure attribute.

Logically collective.

Set an internal Mat.Structure attribute to indicate which is the relation of the sparsity pattern of the two matrices \(A\) and \(B\) constituting the generalized eigenvalue problem. This function has no effect in the case of standard eigenproblems.

Parameters:

structure (petsc4py.PETSc.Mat.Structure) – Either same, different, or a subset of the non-zero sparsity pattern.

Return type:

None

Notes

By default, the sparsity patterns are assumed to be different. If the patterns are equal or a subset then it is recommended to set this attribute for efficiency reasons (in particular, for internal AXPY() matrix operations).

Source code at slepc4py/SLEPc/ST.pyx:400

setMatrices(operators)#

Set the matrices associated with the eigenvalue problem.

Collective.

Parameters:

operators (list[Mat]) – The matrices associated with the eigensystem.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:360

setOptionsPrefix(prefix=None)#

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

Logically collective.

Parameters:

prefix (str | None) – The prefix string to prepend to all ST option requests.

Return type:

None

Notes

A hyphen (-) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen.

Source code at slepc4py/SLEPc/ST.pyx:162

setPreconditionerMat(P=None)#

Set the matrix to be used to build the preconditioner.

Collective.

Parameters:

P (Mat | None) – The matrix that will be used in constructing the preconditioner.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:480

setShift(shift)#

Set the shift associated with the spectral transformation.

Collective.

Parameters:

shift (Scalar) – The value of the shift.

Return type:

None

Notes

In some spectral transformations, changing the shift may have associated a lot of work, for example recomputing a factorization.

Source code at slepc4py/SLEPc/ST.pyx:230

setTransform(flag=True)#

Set a flag to indicate whether the transformed matrices are computed or not.

Logically collective.

Parameters:

flag (bool) – This flag is intended for the case of polynomial eigenproblems solved via linearization. If this flag is False (default) the spectral transformation is applied to the linearization (handled by the eigensolver), otherwise it is applied to the original problem.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:265

setType(st_type)#

Set the particular spectral transformation to be used.

Logically collective.

Parameters:

st_type (Type | str) – The spectral transformation to be used.

Return type:

None

Notes

See ST.Type for available methods. The default is ST.Type.SHIFT with a zero shift. Normally, it is best to use setFromOptions() and then set the ST type from the options database rather than by using this routine. Using the options database provides the user with maximum flexibility in evaluating the different available methods.

Source code at slepc4py/SLEPc/ST.pyx:123

setUp()#

Prepare for the use of a spectral transformation.

Collective.

Source code at slepc4py/SLEPc/ST.pyx:512

Return type:

None

view(viewer=None)#

Print the ST data structure.

Collective.

Parameters:

viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

Return type:

None

Source code at slepc4py/SLEPc/ST.pyx:73

Attributes Documentation

ksp#

KSP object associated with the spectral transformation.

Source code at slepc4py/SLEPc/ST.pyx:872

mat_mode#

How the transformed matrices are being stored in the ST.

Source code at slepc4py/SLEPc/ST.pyx:858

mat_structure#

Relation of the sparsity pattern of all ST matrices.

Source code at slepc4py/SLEPc/ST.pyx:865

shift#

Value of the shift.

Source code at slepc4py/SLEPc/ST.pyx:844

transform#

If the transformed matrices are computed.

Source code at slepc4py/SLEPc/ST.pyx:851