Skip to main content
`Ctrl`+`K`

# 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

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `STAppendOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:256 <slepc4py/SLEPc/ST.pyx#L256>`

  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

    See also

    `applyTranspose`, `applyHermitianTranspose`, `applyMat`, `STApply`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:758 <slepc4py/SLEPc/ST.pyx#L758>`

  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

    See also

    `apply`, `applyTranspose`, `STApplyHermitianTranspose`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:804 <slepc4py/SLEPc/ST.pyx#L804>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:827 <slepc4py/SLEPc/ST.pyx#L827>`

  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

    See also

    `apply`, `applyHermitianTranspose`, `STApplyTranspose`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:781 <slepc4py/SLEPc/ST.pyx#L781>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:145 <slepc4py/SLEPc/ST.pyx#L145>`

  destroy()

    Destroy the ST object.

    Collective.

    See also

    `STDestroy`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:119 <slepc4py/SLEPc/ST.pyx#L119>`

    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`

    See also

    `setCayleyAntishift`, `STCayleyGetAntishift`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:942 <slepc4py/SLEPc/ST.pyx#L942>`

  getFilterDamping()

    Get the type of damping used in the polynomial filter.

    Not collective.

    Returns:

      The type of damping.

    Return type:

      `FilterDamping`

    See also

    `setFilterDamping`, `STFilterGetDamping`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1164 <slepc4py/SLEPc/ST.pyx#L1164>`

  getFilterDegree()

    Get the degree of the filter polynomial.

    Not collective.

    Returns:

      The polynomial degree.

    Return type:

      `int`

    See also

    `setFilterDegree`, `STFilterGetDegree`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1123 <slepc4py/SLEPc/ST.pyx#L1123>`

  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]

    See also

    `setFilterInterval`, `STFilterGetInterval`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1031 <slepc4py/SLEPc/ST.pyx#L1031>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1083 <slepc4py/SLEPc/ST.pyx#L1083>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:979 <slepc4py/SLEPc/ST.pyx#L979>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:585 <slepc4py/SLEPc/ST.pyx#L585>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:430 <slepc4py/SLEPc/ST.pyx#L430>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:545 <slepc4py/SLEPc/ST.pyx#L545>`

  getMatrices()

    Get the matrices associated with the eigenvalue problem.

    Collective.

    Returns:

      The matrices associated with the eigensystem.

    Return type:

      `list` of `petsc4py.PETSc.Mat`

    See also

    `setMatrices`, `STGetNumMatrices`, `STGetMatrix`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:486 <slepc4py/SLEPc/ST.pyx#L486>`

  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.

    See also

    `apply`, `setMatrices`, `setShift`, `restoreOperator`, `STGetOperator`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:850 <slepc4py/SLEPc/ST.pyx#L850>`

  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`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `STGetOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:237 <slepc4py/SLEPc/ST.pyx#L237>`

  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`

    See also

    `setPreconditionerMat`, `STGetPreconditionerMat`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:649 <slepc4py/SLEPc/ST.pyx#L649>`

  getShift()

    Get the shift associated with the spectral transformation.

    Not collective.

    Returns:

      The value of the shift.

    Return type:

      `Scalar`

    See also

    `setShift`, `STGetShift`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:323 <slepc4py/SLEPc/ST.pyx#L323>`

  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]

    See also

    `STGetSplitPreconditionerInfo`, `STGetSplitPreconditionerTerm`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:716 <slepc4py/SLEPc/ST.pyx#L716>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:364 <slepc4py/SLEPc/ST.pyx#L364>`

  getType()

    Get the ST type of this object.

    Not collective.

    Returns:

      The spectral transformation currently being used.

    Return type:

      `str`

    See also

    `setType`, `STGetType`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:193 <slepc4py/SLEPc/ST.pyx#L193>`

  reset()

    Reset the ST object.

    Collective.

    See also

    `STReset`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:133 <slepc4py/SLEPc/ST.pyx#L133>`

    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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:898 <slepc4py/SLEPc/ST.pyx#L898>`

  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\).

    See also

    `setShift`, `getCayleyAntishift`, `STCayleySetAntishift`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:918 <slepc4py/SLEPc/ST.pyx#L918>`

  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.

    See also

    `getFilterDamping`, `STFilterSetDamping`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1142 <slepc4py/SLEPc/ST.pyx#L1142>`

    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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1105 <slepc4py/SLEPc/ST.pyx#L1105>`

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

    See also

    `getFilterInterval`, `setFilterRange`, `STFilterSetInterval`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:998 <slepc4py/SLEPc/ST.pyx#L998>`

  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.

    See also

    `setFilterInterval`, `getFilterRange`, `STFilterSetRange`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1053 <slepc4py/SLEPc/ST.pyx#L1053>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:961 <slepc4py/SLEPc/ST.pyx#L961>`

    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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:275 <slepc4py/SLEPc/ST.pyx#L275>`

    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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:568 <slepc4py/SLEPc/ST.pyx#L568>`

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

    See also

    `setMatrices`, `setMatStructure`, `getMatMode`, `STSetMatMode`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:387 <slepc4py/SLEPc/ST.pyx#L387>`

  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.

    See also

    `getMatStructure`, `setMatrices`, `STSetMatStructure`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:512 <slepc4py/SLEPc/ST.pyx#L512>`

  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.

    See also

    `getMatrices`, `setUp`, `reset`, `STSetMatrices`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:452 <slepc4py/SLEPc/ST.pyx#L452>`

  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.

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `STGetOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:212 <slepc4py/SLEPc/ST.pyx#L212>`

  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.

    See also

    `getPreconditionerMat`, `STSetPreconditionerMat`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:605 <slepc4py/SLEPc/ST.pyx#L605>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:296 <slepc4py/SLEPc/ST.pyx#L296>`

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

    See also

    `getSplitPreconditioner`, `setPreconditionerMat`, `STSetSplitPreconditioner`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:669 <slepc4py/SLEPc/ST.pyx#L669>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:342 <slepc4py/SLEPc/ST.pyx#L342>`

  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`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:166 <slepc4py/SLEPc/ST.pyx#L166>`

  setUp()

    Prepare for the use of a spectral transformation.

    Collective.

    See also

    `apply`, `STSetUp`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:746 <slepc4py/SLEPc/ST.pyx#L746>`

    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

    See also

    `STView`

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:100 <slepc4py/SLEPc/ST.pyx#L100>`

  Attributes Documentation

  ksp

    KSP object associated with the spectral transformation.

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1213 <slepc4py/SLEPc/ST.pyx#L1213>`

  mat_mode

    How the transformed matrices are being stored in the ST.

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1199 <slepc4py/SLEPc/ST.pyx#L1199>`

  mat_structure

    Relation of the sparsity pattern of all ST matrices.

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1206 <slepc4py/SLEPc/ST.pyx#L1206>`

  shift

    Value of the shift.

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1185 <slepc4py/SLEPc/ST.pyx#L1185>`

  transform

    If the transformed matrices are computed.

    :sources:`Source code at slepc4py/SLEPc/ST.pyx:1192 <slepc4py/SLEPc/ST.pyx#L1192>`