Package slepc4py :: Module SLEPc :: Class ST
[hide private]
[frames] | no frames]

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 transformation 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 transformation 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 transformation 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 transformation 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 transformation 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 transformation 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 transformation 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 transformation 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 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(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