Skip to main content
`Ctrl`+`K`

# 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.
  `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`(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.
  `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: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:563

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

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

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

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

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

  getFilterDegree()

    Get the degree of the filter polynomial.

    Not collective.

    Returns:

      The polynomial degree.

    Return type:

      `int`

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

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

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

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

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

  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

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

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

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

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

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

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

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

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

    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:

      - petsc4py.PETSc.KSP – The linear solver object.

      - ksp (petsc4py.PETSc.KSP)

    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

  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:

      None

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

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

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

  mat_mode

    How the transformed matrices are being stored in the ST.

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

  mat_structure

    Relation of the sparsity pattern of all ST matrices.

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

  shift

    Value of the shift.

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

  transform

    If the transformed matrices are computed.

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