Package slepc4py :: Module SLEPc :: Class ST

Class ST

ST

Nested Classes

[hide private]

MatMode
ST matrix mode

Type
ST types

Instance Methods

[hide private]

a new object with type S, a subtype of T

__new__(S, ...)

apply(self, Vec x, Vec y)
Applies the spectral transformation operator to a vector, for instance ``(A - sB)^-1 B`` in the case of the shift-and-invert tranformation and generalized eigenproblem.

applyHermitianTranspose(self, Vec x, Vec y)
Applies the hermitian-transpose of the operator to a vector, for instance ``B^H(A - sB)^-H`` in the case of the shift-and-invert tranformation and generalized eigenproblem.

applyMat(self, Mat x, Mat y)
Applies the spectral transformation operator to a matrix, for instance ``(A - sB)^-1 B`` in the case of the shift-and-invert tranformation and generalized eigenproblem.

applyTranspose(self, Vec x, Vec y)
Applies the transpose of the operator to a vector, for instance ``B^T(A - sB)^-T`` in the case of the shift-and-invert tranformation and generalized eigenproblem.

create(self, comm=None)
Creates the ST object.

destroy(self)
Destroys the ST object.

getCayleyAntishift(self)
Gets the value of the anti-shift for the Cayley spectral transformation.

getFilterDegree(self)
Gets the degree of the filter polynomial.

getFilterInterval(self)
Gets the interval containing the desired eigenvalues.

getFilterRange(self)
Gets the interval containing all eigenvalues.

getKSP(self)
Gets the KSP object associated with the spectral transformation.

getMatMode(self)
Gets a flag that indicates how the matrix is being shifted in the shift-and-invert and Cayley spectral transformations.

getMatStructure(self)
Gets the internal Mat.Structure attribute to indicate which is the relation of the sparsity pattern of the matrices.

getMatrices(self)
Gets the matrices associated with the eigenvalue problem.

getOperator(self)
Returns a shell matrix that represents the operator of the spectral transformation.

getOptionsPrefix(self)
Gets the prefix used for searching for all ST options in the database.

getPreconditionerMat(self)
Gets the matrix previously set by setPreconditionerMat().

getShift(self)
Gets the shift associated with the spectral transformation.

getTransform(self)
Gets the flag indicating whether the transformed matrices are computed or not.

getType(self)
Gets the ST type of this object.

reset(self)
Resets the ST object.

restoreOperator(self, Mat op)
Restore the previously seized operator matrix.

setCayleyAntishift(self, tau)
Sets the value of the anti-shift for the Cayley spectral transformation.

setFilterDegree(self, deg)
Sets the degree of the filter polynomial.

setFilterInterval(self, inta, intb)
Defines the interval containing the desired eigenvalues.

setFilterRange(self, left, right)
Defines the numerical range (or field of values) of the matrix, that is, the interval containing all eigenvalues.

setFromOptions(self)
Sets ST options from the options database.

setKSP(self, KSP ksp)
Sets the KSP object associated with the spectral transformation.

setMatMode(self, mode)
Sets a flag to indicate how the matrix is being shifted in the shift-and-invert and Cayley spectral transformations.

setMatStructure(self, structure)
Sets 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.

setMatrices(self, operators)
Sets the matrices associated with the eigenvalue problem.

setOptionsPrefix(self, prefix)
Sets the prefix used for searching for all ST options in the database.

setPreconditionerMat(self, Mat P=None)
Sets the matrix to be used to build the preconditioner.

setShift(self, shift)
Sets the shift associated with the spectral transformation.

setTransform(self, flag=True)
Sets a flag to indicate whether the transformed matrices are computed or not.

setType(self, st_type)
Builds ST for a particular spectral transformation.

setUp(self)
Prepares for the use of a spectral transformation.

view(self, Viewer viewer=None)
Prints the ST data structure.

Inherited from petsc4py.PETSc.Object: __copy__, __deepcopy__, __eq__, __ge__, __gt__, __le__, __lt__, __ne__, __nonzero__, compose, decRef, getAttr, getClassId, getClassName, getComm, getDict, getName, getRefCount, getTabLevel, incRef, incrementTabLevel, query, setAttr, setName, setTabLevel, stateIncrease, viewFromOptions

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties

[hide private]

ksp

mat_mode

mat_structure

shift

transform

Inherited from petsc4py.PETSc.Object: classid, comm, fortran, handle, klass, name, prefix, refcount, type

Inherited from object: __class__

Method Details

[hide private]

new(S, ...)

Returns: a new object with type S, a subtype of T
Overrides: object.__new__

apply(self, Vec x, Vec y)

Applies the spectral transformation operator to a vector, for
instance ``(A - sB)^-1 B`` in the case of the shift-and-invert
tranformation and generalized eigenproblem.

Parameters
----------
x: Vec
   The input vector.
y: Vec
   The result vector.

applyHermitianTranspose(self, Vec x, Vec y)

Applies the hermitian-transpose of the operator to a vector, for
instance ``B^H(A - sB)^-H`` in the case of the
shift-and-invert tranformation and generalized eigenproblem.

Parameters
----------
x: Vec
   The input vector.
y: Vec
   The result vector.

applyMat(self, Mat x, Mat y)

Applies the spectral transformation operator to a matrix, for
instance ``(A - sB)^-1 B`` in the case of the shift-and-invert
tranformation and generalized eigenproblem.

Parameters
----------
x: Mat
   The input matrix.
y: Mat
   The result matrix.

applyTranspose(self, Vec x, Vec y)

Applies the transpose of the operator to a vector, for
instance ``B^T(A - sB)^-T`` in the case of the
shift-and-invert tranformation and generalized eigenproblem.

Parameters
----------
x: Vec
   The input vector.
y: Vec
   The result vector.

create(self, comm=None)

Creates the ST object.

Parameters
----------
comm: Comm, optional
      MPI communicator; if not provided, it defaults to all
      processes.

destroy(self)

Destroys the ST object.

Overrides: petsc4py.PETSc.Object.destroy

getCayleyAntishift(self)

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

Returns
-------
tau: scalar (possibly complex)
     The anti-shift.

getFilterDegree(self)

Gets the degree of the filter polynomial.

Returns
-------
deg: int
     The polynomial degree.

getFilterInterval(self)

Gets the interval containing the desired eigenvalues.

Returns
-------
inta: float
      The left end of the interval.
intb: float
      The right end of the interval.

getFilterRange(self)

Gets the interval containing all eigenvalues.

Returns
-------
left: float
      The left end of the interval.
right: float
      The right end of the interval.

getKSP(self)

Gets the KSP object associated with the spectral
transformation.

Returns
-------
ksp: KSP
     The linear solver object.

Notes
-----
On output, the internal value of KSP can be ``NULL`` if the
combination of eigenproblem type and selected transformation
does not require to solve a linear system of equations.

getMatMode(self)

Gets a flag that indicates how the matrix is being shifted in
the shift-and-invert and Cayley spectral transformations.

Returns
-------
mode: `ST.MatMode` enumerate
      The mode flag.

getMatStructure(self)

Gets the internal Mat.Structure attribute to indicate which is
the relation of the sparsity pattern of the matrices.

Returns
-------
structure: `PETSc.Mat.Structure` enumerate
           The structure flag.

getMatrices(self)

Gets the matrices associated with the eigenvalue problem.

Returns
-------
operators: tuple of Mat
   The matrices associated with the eigensystem.

getOperator(self)

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

Returns
-------
op: Mat
    Operator matrix.

getOptionsPrefix(self)

Gets the prefix used for searching for all ST options in the
database.

Returns
-------
prefix: string
        The prefix string set for this ST object.

Overrides: petsc4py.PETSc.Object.getOptionsPrefix

getPreconditionerMat(self)

Gets the matrix previously set by setPreconditionerMat().

Returns
-------
P: Mat
   The matrix that will be used in constructing the preconditioner.

getShift(self)

Gets the shift associated with the spectral transformation.

Returns
-------
shift: scalar (possibly complex)
       The value of the shift.

getTransform(self)

Gets the flag indicating whether the transformed matrices
are computed or not.

Returns
-------
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.

getType(self)

Gets the ST type of this object.

Returns
-------
type: `ST.Type` enumerate
      The spectral transformation currently being used.

Overrides: petsc4py.PETSc.Object.getType

restoreOperator(self, Mat op)

Restore the previously seized operator matrix.

Parameters
----------
op: Mat
    Operator matrix previously obtained with getOperator().

setCayleyAntishift(self, tau)

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

Parameters
----------
tau: scalar (possibly complex)
     The anti-shift.

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

setFilterDegree(self, deg)

Sets the degree of the filter polynomial.

Parameters
----------
deg: int
     The polynomial degree.

setFilterInterval(self, inta, intb)

Defines the interval containing the desired eigenvalues.

Parameters
----------
inta: float
      The left end of the interval.
intb: float
      The right end of the interval.

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

setFilterRange(self, left, right)

Defines 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.

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.

setFromOptions(self)

Sets ST options from the options database. 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.

Overrides: petsc4py.PETSc.Object.setFromOptions

setKSP(self, KSP ksp)

Sets the KSP object associated with the spectral
transformation.

Parameters
----------
ksp: KSP
     The linear solver object.

setMatMode(self, mode)

Sets a flag to indicate how the matrix is being shifted in the
shift-and-invert and Cayley spectral transformations.

Parameters
----------
mode: `ST.MatMode` enumerate
      The mode flag.

Notes
-----
By default (`ST.MatMode.COPY`), a copy of matrix ``A`` is made
and then this copy is shifted explicitly, e.g. ``A <- (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 interative
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(self, structure)

Sets 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: `PETSc.Mat.Structure` enumerate
           Either same, different, or a subset of the non-zero
           sparsity pattern.

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(self, operators)

Sets the matrices associated with the eigenvalue problem.

Parameters
----------
operators: sequence of Mat
   The matrices associated with the eigensystem.

setOptionsPrefix(self, prefix)

Sets the prefix used for searching for all ST options in the
database.

Parameters
----------
prefix: string
        The prefix string to prepend to all ST option
        requests.

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.

Overrides: petsc4py.PETSc.Object.setOptionsPrefix

setPreconditionerMat(self, Mat P=None)

Sets the matrix to be used to build the preconditioner.

Parameters
----------
P: Mat, optional
   The matrix that will be used in constructing the preconditioner.

setShift(self, shift)

Sets the shift associated with the spectral transformation.

Parameters
----------
shift: scalar (possibly complex)
       The value of the shift.

Notes
-----
In some spectral transformations, changing the shift may have
associated a lot of work, for example recomputing a
factorization.

setTransform(self, flag=True)

Sets a flag to indicate whether the transformed matrices
are computed or not.

Parameters
----------
flag: bool, optional
      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.

setType(self, st_type)

Builds ST for a particular spectral transformation.

Parameters
----------
st_type: `ST.Type` enumerate
         The spectral transformation to be used.

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.

view(self, Viewer viewer=None)

Prints the ST data structure.

Parameters
----------
viewer: Viewer, optional
        Visualization context; if not provided, the standard
        output is used.

Overrides: petsc4py.PETSc.Object.view