STGetOperator#

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

Synopsis#

#include "slepcst.h" 
PetscErrorCode STGetOperator(ST st,Mat *Op)

Collective

Input Parameter#

st - the spectral transformation context

Output Parameter#

Op - operator matrix

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

The returned shell matrix is essentially a wrapper to the STApply() and STApplyTranspose() 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. In the case of STSHELL, the inner part \(K^{-1}M\) is replaced by the user-provided operation from STShellSetApply().

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 STGetOperator(), 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 STRestoreOperator(). In particular, this is required before modifying the ST matrices or the shift.

A NULL pointer can be passed in Op in case the matrix is not required but we want to force its creation. In this case, STRestoreOperator() should not be called.