slepc4py.SLEPc.ST#

class slepc4py.SLEPc.ST#

Bases: Object

Spectral Transformation.

The Spectral Transformation (ST) class encapsulates the functionality required for acceleration techniques based on the transformation of the spectrum. The eigensolvers implemented in EPS work by applying an operator to a set of vectors and this operator can adopt different forms. The ST object handles all the different possibilities in a uniform way, so that the solver can proceed without knowing which transformation has been selected. Polynomial eigensolvers in PEP also support spectral transformation.

Enumerations

`FilterDamping`	ST filter damping.
`FilterType`	ST filter type.
`MatMode`	ST matrix mode.
`Type`	ST type.

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 matrix 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.
`getSplitPreconditioner`()	Get the matrices to be used to build the preconditioner.
`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`(mu)	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 related to management of transformed matrices.
`setMatStructure`(structure)	Set the matrix 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.
`setSplitPreconditioner`(operators[, structure])	Set the matrices to be used to build the preconditioner.
`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:256

apply(x, y)#

Apply the spectral transformation operator to a vector.

Collective.

Apply the spectral transformation operator to a vector, for instance \(y=(A-\sigma B)^{-1}Bx\) 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:758

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 \(y=B^*(A - \sigma B)^{-*}x\) 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:804

applyMat(X, Y)#

Apply the spectral transformation operator to a matrix.

Collective.

Apply the spectral transformation operator to a matrix, for instance \(Y=(A-\sigma B)^{-1}BX\) 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

See also

apply, STApplyMat

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

applyTranspose(x, y)#

Apply the transpose of the operator to a vector.

Collective.

Apply the transpose of the operator to a vector, for instance \(y=B^T(A-\sigma B)^{-T}x\) 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:781

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

See also

STCreate

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

destroy()#

Destroy the ST object.

Collective.

See also

STDestroy

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

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

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

getFilterDegree()#

Get the degree of the filter polynomial.

Not collective.

Returns:: The polynomial degree.
Return type:: int

See also

setFilterDegree, STFilterGetDegree

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

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

getFilterRange()#

Get the interval containing all eigenvalues.

Not collective.

Returns:

left (float) – The left end of the spectral range.
right (float) – The right end of the spectral range.

Return type:

tuple[float, float]

See also

getFilterInterval, STFilterGetRange

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

getFilterType()#

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

Not collective.

Returns:: The type of filter.
Return type:: FilterType

See also

setFilterType, STFilterGetType

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

getKSP()#

Get the KSP object associated with the spectral transformation.

Collective.

Returns:: The linear solver object.
Return type:: petsc4py.PETSc.KSP

See also

setKSP, STGetKSP

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

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

See also

setMatMode, STGetMatMode

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

getMatStructure()#

Get the internal matrix structure attribute.

Not collective.

Get the internal petsc4py.PETSc.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

See also

setMatStructure, STGetMatStructure

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

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

getOperator()#

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

Collective.

Returns:: Operator matrix.
Return type:: petsc4py.PETSc.Mat

Notes

The operator is defined in linear eigenproblems only, not in polynomial ones, so the call will fail if more than 2 matrices were passed in setMatrices().

The returned shell matrix is essentially a wrapper to the apply() and applyTranspose() operations. The operator can often be expressed as

\[Op = D K^{-1} M D^{-1}\]

where \(D\) is the balancing matrix, and \(M\) and \(K\) are two matrices corresponding to the numerator and denominator for spectral transformations that represent a rational matrix function.

The preconditioner matrix \(K\) typically depends on the value of the shift, and its inverse is handled via an internal KSP object. Normal usage does not require explicitly calling getOperator(), but it can be used to force the creation of \(K\) and \(M\), and then \(K\) is passed to the KSP. This is useful for setting options associated with the PCFactor (to set MUMPS options, for instance).

The returned matrix must NOT be destroyed by the user. Instead, when no longer needed it must be returned with restoreOperator(). In particular, this is required before modifying the ST matrices or the shift.

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

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

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

getShift()#

Get the shift associated with the spectral transformation.

Not collective.

Returns:: The value of the shift.
Return type:: Scalar

See also

setShift, STGetShift

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

getSplitPreconditioner()#

Get the matrices to be used to build the preconditioner.

Not collective.

Returns:

list of petsc4py.PETSc.Mat – The list of matrices associated with the preconditioner.
petsc4py.PETSc.Mat.Structure – The structure flag.

Return type:

tuple[list[petsc4py.PETSc.Mat], petsc4py.PETSc.Mat.Structure]

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

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

See also

setTransform, STGetTransform

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

getType()#

Get the ST type of this object.

Not collective.

Returns:: The spectral transformation currently being used.
Return type:: str

See also

setType, STGetType

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

reset()#

Reset the ST object.

Collective.

See also

STReset

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

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

See also

getOperator, STRestoreOperator

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

setCayleyAntishift(mu)#

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

Logically collective.

Parameters:: mu (Scalar) – The anti-shift.
Return type:: None

Notes

In the generalized Cayley transform, the operator can be expressed as \((A - \sigma B)^{-1}(A + \mu B)\). This function sets the value of \(mu\). Use setShift() for setting \(\sigma\).

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

setFilterDamping(damping)#

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

Logically collective.

Parameter#

damping: The type of damping.

Notes

Only used in FilterType.CHEBYSHEV filters.

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

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

See also

getFilterDegree, STFilterSetDegree

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

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 setFilterRange().

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

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 spectral range.
right (float) – The right end of the spectral range.

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

setFilterType(filter_type)#

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

Logically collective.

Parameter#

filter_type: The type of filter.

See also

getFilterType, STFilterSetType

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

Parameters:: filter_type (FilterType)
Return type:: None

setFromOptions()#

Set ST options from the options database.

Collective.

Notes

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

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

See also

setOptionsPrefix, STSetFromOptions

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

Return type:: None

setKSP(ksp)#

Set the KSP object associated with the spectral transformation.

Collective.

Parameters:: ksp (KSP) – The linear solver object.
Return type:: None

See also

getKSP, STSetKSP

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

setMatMode(mode)#

Set a flag related to management of transformed matrices.

Logically collective.

The flag indicates how the transformed matrices are being stored in the spectral transformation.

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 modified explicitly, e.g., \(A \leftarrow (A - \sigma B)\).

With ST.MatMode.INPLACE, the original matrix \(A\) is modified at setUp() and reverted 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 transformed 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 two first modes the efficiency of this computation can be controlled with setMatStructure().

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

setMatStructure(structure)#

Set the matrix structure attribute.

Logically collective.

Set an internal petsc4py.PETSc.Mat.Structure attribute to indicate which is the relation of the sparsity pattern of all the ST matrices.

Parameters:: structure (petsc4py.PETSc.Mat.Structure) – The matrix structure specification.
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 Mat.axpy() operations).

This function has no effect in the case of standard eigenproblems.

In case of polynomial eigenproblems, the flag applies to all matrices relative to the first one.

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

setMatrices(operators)#

Set the matrices associated with the eigenvalue problem.

Collective.

Parameters:: operators (list[Mat]) – The matrices associated with the eigensystem.
Return type:: None

Notes

It must be called before setUp(). If it is called again after setUp() then the ST object is reset.

In standard eigenproblems only one matrix is passed, while in generalized problems two matrices are provided. The number of matrices is larger in polynomial eigenproblems.

In normal usage, matrices are provided via the corresponding EPS of PEP interface function.

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

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

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

Notes

This matrix will be passed to the internal KSP object (via the last argument of KSP.setOperators()) as the matrix to be used when constructing the preconditioner. If no matrix is set then \(A-\sigma B\) will be used to build the preconditioner, being \(\sigma\) the value set by setShift().

More precisely, this is relevant for spectral transformations that represent a rational matrix function, and use a KSP object for the denominator. It includes also the PRECOND case. If the user has a good approximation to matrix that can be used to build a cheap preconditioner, it can be passed with this function. Note that it affects only the Pmat argument of KSP.setOperators(), not the Amat argument.

If a preconditioner matrix is set, the default is to use an iterative KSP rather than a direct method.

An alternative to pass an approximation of \(A-\sigma B\) with this function is to provide approximations of \(A\) and \(B\) via setSplitPreconditioner(). The difference is that when \(\sigma\) changes the preconditioner is recomputed.

A call with no matrix argument will remove a previously set matrix.

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

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.

This function is normally not directly called by users, since the shift is indirectly set by EPS.setTarget().

See also

getShift, STSetShift

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

setSplitPreconditioner(operators, structure=None)#

Set the matrices to be used to build the preconditioner.

Collective.

Parameters:

operators (list[petsc4py.PETSc.Mat]) – The matrices associated with the preconditioner.
structure (petsc4py.PETSc.Mat.Structure | None) – The matrix structure specification.

Return type:

None

Notes

The number of matrices passed here must be the same as in setMatrices().

For linear eigenproblems, the preconditioner matrix is computed as \(P(\sigma) = A_0-\sigma B_0\), where \(A_0,B_0\) are approximations of \(A,B\) (the eigenproblem matrices) provided via the operators argument in this function. Compared to setPreconditionerMat(), this function allows setting a preconditioner in a way that is independent of the shift \(\sigma\). Whenever the value of \(\sigma\) changes the preconditioner is recomputed.

Similarly, for polynomial eigenproblems the matrix for the preconditioner is expressed as \(P(\sigma) = \sum_i P_i \phi_i(\sigma)\), for \(i=1,\dots,n\), where \(P_i\) are given in operators and the \(\phi_i\)’s are the polynomial basis functions.

The structure flag provides information about the relative nonzero pattern of the operators matrices, in the same way as in setMatStructure().

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

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

See also

getTransform, STSetTransform

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

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

The default is 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.

See also

getType, STSetType

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

setUp()#

Prepare for the use of a spectral transformation.

Collective.

See also

apply, STSetUp

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