slepc4py.SLEPc.ST#
- class slepc4py.SLEPc.ST#
Bases:
ObjectST.
Enumerations
ST filter damping.
ST filter type.
ST matrix mode.
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.
Get the value of the anti-shift for the Cayley spectral transformation.
Get the type of damping used in the polynomial filter.
Get the degree of the filter polynomial.
Get the interval containing the desired eigenvalues.
Get the interval containing all eigenvalues.
Get the method to be used to build the polynomial filter.
getKSP()Get the
KSPobject associated with the spectral transformation.Get a flag that indicates how the matrix is being shifted.
Get the internal Mat.Structure attribute.
Get the matrices associated with the eigenvalue problem.
Get a shell matrix that represents the operator of the spectral transformation.
Get the prefix used for searching for all ST options in the database.
Get the matrix previously set by setPreconditionerMat().
getShift()Get the shift associated with the spectral transformation.
Get the matrices to be used to build the preconditioner.
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.
Set ST options from the options database.
setKSP(ksp)Set the
KSPobject 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.
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 object associated with the spectral transformation.
How the transformed matrices are being stored in the ST.
Relation of the sparsity pattern of all ST matrices.
Value of the shift.
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.
- 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.
- 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.
- 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.
- 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.
- create(comm=None)#
Create the ST object.
Collective.
- destroy()#
Destroy the ST object.
Collective.
Source code at slepc4py/SLEPc/ST.pyx:88
- Return type:
- getCayleyAntishift()#
Get the value of the anti-shift for the Cayley spectral transformation.
Not collective.
- Returns:
The anti-shift.
- Return type:
- getFilterDamping()#
Get the type of damping used in the polynomial filter.
Not collective.
- Returns:
The type of damping.
- Return type:
- getFilterDegree()#
Get the degree of the filter polynomial.
Not collective.
- Returns:
The polynomial degree.
- Return type:
- getFilterInterval()#
Get the interval containing the desired eigenvalues.
Not collective.
- Returns:
- Return type:
- getFilterRange()#
Get the interval containing all eigenvalues.
Not collective.
- Returns:
- Return type:
- getFilterType()#
Get the method to be used to build the polynomial filter.
Not collective.
- Returns:
The type of filter.
- Return type:
- getKSP()#
Get the
KSPobject associated with the spectral transformation.Collective.
- Returns:
The linear solver object.
- Return type:
Notes
On output, the internal value of
petsc4py.PETSc.KSPcan beNULLif the combination of eigenproblem type and selected transformation does not require to solve a linear system of equations.
- 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:
- 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:
- getMatrices()#
Get the matrices associated with the eigenvalue problem.
Collective.
- Returns:
The matrices associated with the eigensystem.
- Return type:
- getOperator()#
Get a shell matrix that represents the operator of the spectral transformation.
Collective.
- Returns:
Operator matrix.
- Return type:
- 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:
- getPreconditionerMat()#
Get the matrix previously set by setPreconditionerMat().
Not collective.
- Returns:
The matrix that will be used in constructing the preconditioner.
- Return type:
- getShift()#
Get the shift associated with the spectral transformation.
Not collective.
- Returns:
The value of the shift.
- Return type:
- getSplitPreconditioner()#
Get the matrices to be used to build the preconditioner.
Not collective.
- Returns:
listofpetsc4py.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]
- 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:
- getType()#
Get the ST type of this object.
Not collective.
- Returns:
The spectral transformation currently being used.
- Return type:
- reset()#
Reset the ST object.
Collective.
Source code at slepc4py/SLEPc/ST.pyx:98
- Return type:
- restoreOperator(op)#
Restore the previously seized operator matrix.
Logically collective.
- setCayleyAntishift(tau)#
Set the value of the anti-shift for the Cayley spectral transformation.
Logically collective.
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\).
- setFilterDamping(damping)#
Set the type of damping to be used in the polynomial filter.
Logically collective.
Parameter#
- damping
The type of damping.
- Parameters:
damping (FilterDamping)
- Return type:
- setFilterDegree(deg)#
Set the degree of the filter polynomial.
Logically collective.
- setFilterInterval(inta, intb)#
Set the interval containing the desired eigenvalues.
Logically collective.
- Parameters:
- Return type:
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
EPSwithEPS.setInterval().The interval must be contained within the numerical range of the matrix, see
ST.setFilterRange().
- 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:
- Return type:
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.
- setFilterType(filter_type)#
Set the method to be used to build the polynomial filter.
Logically collective.
Parameter#
- filter_type
The type of filter.
- Parameters:
filter_type (FilterType)
- Return type:
- 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:
- setKSP(ksp)#
Set the
KSPobject associated with the spectral transformation.Collective.
- Parameters:
petsc4py.PETSc.KSP – The linear solver object.
ksp (petsc4py.PETSc.KSP)
- Return type:
- 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.
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 atsetUp()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().
- 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:
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).
- setMatrices(operators)#
Set the matrices associated with the eigenvalue problem.
Collective.
- 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:
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.
- setPreconditionerMat(P=None)#
Set the matrix to be used to build the preconditioner.
Collective.
- setShift(shift)#
Set the shift associated with the spectral transformation.
Collective.
Notes
In some spectral transformations, changing the shift may have associated a lot of work, for example recomputing a factorization.
- 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)
- Return type:
- 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:
- setType(st_type)#
Set the particular spectral transformation to be used.
Logically collective.
Notes
See
ST.Typefor available methods. The default isST.Type.SHIFTwith a zero shift. Normally, it is best to usesetFromOptions()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.
- setUp()#
Prepare for the use of a spectral transformation.
Collective.
Source code at slepc4py/SLEPc/ST.pyx:555
- Return type:
- view(viewer=None)#
Print the ST data structure.
Collective.
Attributes Documentation
- 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.