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

Class EPS


EPS
Nested Classes [hide private]
  Class
EPS class of method
  ConvergedReason
EPS convergence reasons
  Extraction
EPS extraction technique
  LanczosReorthogType
EPS Lanczos reorthogonalization type
  PowerShiftType
EPS Power shift type.
  ProblemType
EPS problem type
  Type
EPS type
  Which
EPS desired piece of spectrum
Instance Methods [hide private]
a new object with type S, a subtype of T
__new__(S, ...)
 
attachDeflationSpace(self, space, ortho=False)
Add vectors to the basis of the deflation space.
 
computeRelativeError(self, int i)
Computes the relative error bound associated with the i-th computed eigenpair.
 
computeRelativeErrorLeft(self, int i)
Computes the left relative error bound associated with the i-th computed eigenpair (only available in two-sided eigensolvers).
 
computeResidualNorm(self, int i)
Computes the norm of the residual vector associated with the i-th computed eigenpair.
 
computeResidualNormLeft(self, int i)
Computes the norm of the residual vector associated with the i-th computed left eigenpair (only available in two-sided eigensolvers).
 
create(self, comm=None)
Creates the EPS object.
 
destroy(self)
Destroys the EPS object.
 
getArnoldiDelayed(self)
Gets the type of reorthogonalization used during the Arnoldi iteration.
 
getClass(self)
Gets the eigensolver class from the EPS object.
 
getConverged(self)
Gets the number of converged eigenpairs.
 
getConvergedReason(self)
Gets the reason why the solve() iteration was stopped.
 
getDimensions(self)
Gets the number of eigenvalues to compute and the dimension of the subspace.
 
getEigenpair(self, int i, Vec Vr=None, Vec Vi=None)
Gets the i-th solution of the eigenproblem as computed by solve().
 
getErrorEstimate(self, int i)
Returns the error estimate associated to the i-th computed eigenpair.
 
getErrorEstimateLeft(self, int i)
Returns the left error estimate associated to the i-th computed eigenpair (only available in two-sided eigensolvers).
 
getExtraction(self)
Gets the extraction type used by the EPS object.
 
getIP(self)
Obtain the inner product associated to the eigensolver.
 
getInitialVector(self)
Gets the initial vector associated with the eigensolver; if the vector was not set it will return a NULL vector or a vector randomly generated by setUp().
 
getInitialVectorLeft(self)
Gets the left initial vector associated with the eigensolver; if the vector was not set it will return a NULL vector or a vector randomly generated by setUp().
 
getInvariantSubspace(self)
Gets an orthonormal basis of the computed invariant subspace.
 
getInvariantSubspaceLeft(self)
Gets an orthonormal basis of the computed left invariant subspace (only available in two-sided eigensolvers).
 
getIterationNumber(self)
Gets the current iteration number.
 
getLanczosReorthogType(self)
Gets the type of reorthogonalization used during the Lanczos iteration.
 
getOperationCounters(self)
Gets the total number of operator applications, inner product operations and linear iterations used by the ST object during the last solve() call.
 
getOperators(self)
Gets the matrices associated with the eigenvalue problem.
 
getOptionsPrefix(self)
Gets the prefix used for searching for all EPS options in the database.
 
getPowerShiftType(self)
Gets the type of shifts used during the power iteration.
 
getProblemType(self)
Gets the problem type from the EPS object.
 
getST(self)
Obtain the spectral transformation (ST) object associated to the eigensolver object.
 
getTarget(self)
Gets the value of the target.
 
getTolerances(self)
Gets the tolerance and maximum iteration count used by the default EPS convergence tests.
 
getType(self)
Gets the EPS type of this object.
 
getValue(self, int i)
Gets the i-th eigenvalue as computed by solve().
 
getVector(self, int i, Vec Vr, Vec Vi=None)
Gets the i-th eigenvector as computed by solve().
 
getVectorLeft(self, int i, Vec Wr, Vec Wi=None)
Gets the i-th left eigenvector as computed by solve(), (only available in two-sided eigensolvers).
 
getWhichEigenpairs(self)
Returns which portion of the spectrum is to be sought.
 
isGeneralized(self)
Tells whether the EPS object corresponds to a generalized eigenvalue problem.
 
isHermitian(self)
Tells whether the EPS object corresponds to a Hermitian eigenvalue problem.
 
removeDeflationSpace(self)
Removes the deflation space previously set with attachDeflationSpace().
 
setArnoldiDelayed(self, delayed)
Activates or deactivates delayed reorthogonalization in the Arnoldi iteration.
 
setClass(self, klass)
Specifies the eigensolver class, either one-sided or two-sided.
 
setDimensions(self, nev=None, ncv=None, mpd=None)
Sets the number of eigenvalues to compute and the dimension of the subspace.
 
setExtraction(self, extraction)
Sets the extraction type used by the EPS object.
 
setFromOptions(self)
Sets EPS options from the options database.
 
setIP(self, IP ip)
Associates an inner product to the eigensolver.
 
setInitialVector(self, Vec V)
Sets the initial vector from which the eigensolver starts to iterate.
 
setInitialVectorLeft(self, Vec W)
Sets the left initial vector from which the eigensolver starts to iterate, corresponding to the left recurrence (two-sided solvers).
 
setLanczosReorthogType(self, reorthog)
Sets the type of reorthogonalization used during the Lanczos iteration.
 
setOperators(self, Mat A, Mat B=None)
Sets the matrices associated with the eigenvalue problem.
 
setOptionsPrefix(self, prefix)
Sets the prefix used for searching for all EPS options in the database.
 
setPowerShiftType(self, shift)
Sets the type of shifts used during the power iteration.
 
setProblemType(self, problem_type)
Specifies the type of the eigenvalue problem.
 
setST(self, ST st)
Associates a spectral transformation object to the eigensolver.
 
setTarget(self, target)
Sets the value of the target.
 
setTolerances(self, tol=None, max_it=None)
Sets the tolerance and maximum iteration count used by the default EPS convergence tests.
 
setType(self, eps_type)
Selects the particular solver to be used in the EPS object.
 
setUp(self)
Sets up all the internal data structures necessary for the execution of the eigensolver.
 
setWhichEigenpairs(self, which)
Specifies which portion of the spectrum is to be sought.
 
solve(self)
Solves the eigensystem.
 
view(self, Viewer viewer=None)
Prints the EPS data structure.

Inherited from petsc4py.PETSc.Object: __eq__, __ge__, __gt__, __le__, __lt__, __ne__, __nonzero__, compose, decRef, getAttr, getClassName, getComm, getCookie, getDict, getName, getRefCount, incRef, query, setAttr, setName

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

Properties [hide private]
  extraction
  ip
  max_it
  problem_type
  st
  target
  tol
  which

Inherited from petsc4py.PETSc.Object: comm, cookie, 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__

attachDeflationSpace(self, space, ortho=False)

 

Add vectors to the basis of the deflation space.

Parameters

space: a Vec or an array of Vec
Set of basis vectors to be added to the deflation space.
ortho: boolean, optional
True if the basis vectors can be assumed to be mutullay orthonormal.

Notes

When a deflation space is given, the eigensolver seeks the eigensolution in the restriction of the problem to the orthogonal complement of this space. This can be used for instance in the case that an invariant subspace is known beforehand (such as the nullspace of the matrix).

The basis vectors can be provided all at once or incrementally with several calls to attachDeflationSpace().

Set ortho to True if all the vectors passed in are known to be mutually orthonormal.

computeRelativeError(self, int i)

 

Computes the relative error bound associated with the i-th computed eigenpair.

Parameters

i: int
Index of the solution to be considered.

Returns

e: real
The relative error bound, computed as ||Ax-kBx||_2/||kx||_2 where k is the eigenvalue and x is the eigenvector. If k=0 the relative error is computed as ||Ax||_2/||x||_2.

Notes

The index i should be a value between 0 and nconv-1 (see getConverged(). Eigenpairs are indexed according to the ordering criterion established with setWhichEigenpairs().

computeRelativeErrorLeft(self, int i)

 

Computes the left relative error bound associated with the i-th computed eigenpair (only available in two-sided eigensolvers).

Parameters

i: int
Index of the solution to be considered.

Returns

e: real
The relative error bound, computed as ||y'A-ky'B||_2/||ky||_2 where k is the eigenvalue and y is the left eigenvector. If k=0 the relative error is computed as ||y'A||_2/||y||_2.

computeResidualNorm(self, int i)

 

Computes the norm of the residual vector associated with the i-th computed eigenpair.

Parameters

i: int
Index of the solution to be considered.

Returns

norm: real
The residual norm, computed as ||Ax-kBx||_2 where k is the eigenvalue and x is the eigenvector. If k=0 then the residual norm is computed as ||Ax||_2.

computeResidualNormLeft(self, int i)

 

Computes the norm of the residual vector associated with the i-th computed left eigenpair (only available in two-sided eigensolvers).

Parameters

i: int
Index of the solution to be considered.

Returns

norm: real
The residual norm, computed as ||y'A-ky'B||_2 where k is the eigenvalue and y is the left eigenvector. If k=0 then the residual norm is computed as ||y'A||_2.

create(self, comm=None)

 

Creates the EPS object.

Parameters

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

destroy(self)

 
Destroys the EPS object.
Overrides: petsc4py.PETSc.Object.destroy

getArnoldiDelayed(self)

 

Gets the type of reorthogonalization used during the Arnoldi iteration.

Returns

delayed: boolean
True if delayed reorthogonalization is to be used.

getClass(self)

 

Gets the eigensolver class from the EPS object.

Returns

klass: EPS.Class enumerate
The class of eigensolver, either one-side or two-side.

getConverged(self)

 

Gets the number of converged eigenpairs.

Returns

nconv: int
Number of converged eigenpairs.

Notes

This function should be called after solve() has finished.

getConvergedReason(self)

 

Gets the reason why the solve() iteration was stopped.

Returns

reason: EPS.ConvergedReason enumerate
Negative value indicates diverged, positive value converged.

getDimensions(self)

 

Gets the number of eigenvalues to compute and the dimension of the subspace.

Returns

nev: int
Number of eigenvalues to compute.
ncv: int
Maximum dimension of the subspace to be used by the solver.
mpd: int
Maximum dimension allowed for the projected problem.

getEigenpair(self, int i, Vec Vr=None, Vec Vi=None)

 

Gets the i-th solution of the eigenproblem as computed by solve(). The solution consists of both the eigenvalue and the eigenvector.

Parameters

i: int
Index of the solution to be obtained.
Vr: Vec
Placeholder for the returned eigenvector (real part).
Vi: Vec
Placeholder for the returned eigenvector (imaginary part).

Returns

e: scalar (possibly complex)
The computed eigenvalue.

Notes

The index i should be a value between 0 and nconv-1 (see getConverged(). Eigenpairs are indexed according to the ordering criterion established with setWhichEigenpairs().

getErrorEstimate(self, int i)

 

Returns the error estimate associated to the i-th computed eigenpair.

Parameters

i: int
Index of the solution to be considered.

Returns

e: real
Error estimate.

Notes

This is the error estimate used internally by the eigensolver. The actual error bound can be computed with computeRelativeError().

getErrorEstimateLeft(self, int i)

 

Returns the left error estimate associated to the i-th computed eigenpair (only available in two-sided eigensolvers).

Parameters

i: int
Index of the solution to be considered.

Returns

e: real
Left error estimate.

Notes

This is the error estimate used internally by the eigensolver. The actual error bound can be computed with computeRelativeError().

getExtraction(self)

 

Gets the extraction type used by the EPS object.

Returns

extraction: EPS.Extraction enumerate
The method of extraction.

getIP(self)

 

Obtain the inner product associated to the eigensolver.

Returns

ip: IP
The inner product context.

getInitialVector(self)

 

Gets the initial vector associated with the eigensolver; if the vector was not set it will return a NULL vector or a vector randomly generated by setUp().

Returns

V: Vec
The initial vector.

getInitialVectorLeft(self)

 

Gets the left initial vector associated with the eigensolver; if the vector was not set it will return a NULL vector or a vector randomly generated by setUp().

Returns

V: Vec
The initial vector.

getInvariantSubspace(self)

 

Gets an orthonormal basis of the computed invariant subspace.

Returns

subspace: list of Vec
Basis of the invariant subspace.

Notes

This function should be called after solve() has finished.

The returned vectors span an invariant subspace associated with the computed eigenvalues. An invariant subspace X of A` satisfies ``A x in X for all x in X (a similar definition applies for generalized eigenproblems).

getInvariantSubspaceLeft(self)

 

Gets an orthonormal basis of the computed left invariant subspace (only available in two-sided eigensolvers).

Returns

v: array of Vec
Basis of the left invariant subspace.

Notes

See getInvariantSubspace() for additional information.

getIterationNumber(self)

 

Gets the current iteration number. If the call to solve() is complete, then it returns the number of iterations carried out by the solution method.

Returns

its: int
Iteration number.

getLanczosReorthogType(self)

 

Gets the type of reorthogonalization used during the Lanczos iteration.

Returns

reorthog: EPS.LanczosReorthogType enumerate
The type of reorthogonalization.

getOperationCounters(self)

 

Gets the total number of operator applications, inner product operations and linear iterations used by the ST object during the last solve() call.

Returns

ops: int
number of operator applications.
dots: int
number of inner product operations.
lits: int
number of linear iterations.

Notes

When the eigensolver algorithm invokes ST.apply() then a linear system must be solved (except in the case of standard eigenproblems and shift transformation). The number of iterations required in this solve is accumulated into a counter whose value is returned by this function.

These counters are reset to zero at each successive call to solve().

getOperators(self)

 

Gets the matrices associated with the eigenvalue problem.

Returns

A: Mat
The matrix associated with the eigensystem.
B: Mat
The second matrix in the case of generalized eigenproblems.

getOptionsPrefix(self)

 

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

Returns

prefix: string
The prefix string set for this EPS object.
Overrides: petsc4py.PETSc.Object.getOptionsPrefix

getPowerShiftType(self)

 

Gets the type of shifts used during the power iteration.

Returns

shift: EPS.PowerShiftType enumerate
The type of shift.

getProblemType(self)

 

Gets the problem type from the EPS object.

Returns

problem_type: EPS.ProblemType enumerate
The problem type that was previously set.

getST(self)

 

Obtain the spectral transformation (ST) object associated to the eigensolver object.

Returns

st: ST
The spectral transformation.

getTarget(self)

 

Gets the value of the target.

Returns

target: float (real or complex)
The value of the target.

Notes

If the target was not set by the user, then zero is returned.

getTolerances(self)

 

Gets the tolerance and maximum iteration count used by the default EPS convergence tests.

Returns

tol: float
The convergence tolerance.
max_it: int
The maximum number of iterations

getType(self)

 

Gets the EPS type of this object.

Returns

type: EPS.Type enumerate
The solver currently being used.
Overrides: petsc4py.PETSc.Object.getType

getValue(self, int i)

 

Gets the i-th eigenvalue as computed by solve().

Parameters

i: int
Index of the solution to be obtained.

Returns

e: scalar (possibly complex)
The computed eigenvalue.

Notes

The index i should be a value between 0 and nconv-1 (see getConverged(). Eigenpairs are indexed according to the ordering criterion established with setWhichEigenpairs().

getVector(self, int i, Vec Vr, Vec Vi=None)

 

Gets the i-th eigenvector as computed by solve().

Parameters

i: int
Index of the solution to be obtained.
Vr: Vec
Placeholder for the returned eigenvector (real part).
Vi: Vec, optional
Placeholder for the returned eigenvector (imaginary part).

Notes

The index i should be a value between 0 and nconv-1 (see getConverged(). Eigenpairs are indexed according to the ordering criterion established with setWhichEigenpairs().

getVectorLeft(self, int i, Vec Wr, Vec Wi=None)

 

Gets the i-th left eigenvector as computed by solve(), (only available in two-sided eigensolvers).

Parameters

i: int
Index of the solution to be obtained.
Wr: Vec
Placeholder for the returned left eigenvector (real part).
Wi: Vec, optional
Placeholder for the returned left eigenvector (imaginary part).

Notes

The index i should be a value between 0 and nconv-1 (see getConverged(). Eigenpairs are indexed according to the ordering criterion established with setWhichEigenpairs().

getWhichEigenpairs(self)

 

Returns which portion of the spectrum is to be sought.

Returns

which: EPS.Which enumerate
The portion of the spectrum to be sought by the solver.

isGeneralized(self)

 

Tells whether the EPS object corresponds to a generalized eigenvalue problem.

Returns

flag: boolean
True if two matrices were set with setOperators().

isHermitian(self)

 

Tells whether the EPS object corresponds to a Hermitian eigenvalue problem.

Returns

flag: boolean
True if the problem type set with setProblemType() was Hermitian.

setArnoldiDelayed(self, delayed)

 

Activates or deactivates delayed reorthogonalization in the Arnoldi iteration.

Parameters

delayed: boolean
True if delayed reorthogonalization is to be used.

Notes

This call is only relevant if the type was set to EPS.Type.ARNOLDI with setType().

Delayed reorthogonalization is an aggressive optimization for the Arnoldi eigensolver than may provide better scalability, but sometimes makes the solver converge less than the default algorithm.

setClass(self, klass)

 

Specifies the eigensolver class, either one-sided or two-sided.

Parameters

klass: EPS.Class enumerate
The class of eigensolver, either one-side or two-side.

Notes

Allowed solver classes are: one-sided (EPS.Class.ONE_SIDE) and two-sided (EPS.Class.TWO_SIDE). One-sided eigensolvers are the standard ones, which allow the computation of eigenvalues and (right) eigenvectors, whereas two-sided eigensolvers compute left eigenvectors as well.

setDimensions(self, nev=None, ncv=None, mpd=None)

 

Sets the number of eigenvalues to compute and the dimension of the subspace.

Parameters

nev: int, optional
Number of eigenvalues to compute.
ncv: int, optional
Maximum dimension of the subspace to be used by the solver.
mpd: int, optional
Maximum dimension allowed for the projected problem.

Notes

Use DECIDE for ncv and mpd to assign a reasonably good value, which is dependent on the solution method.

The parameters ncv and mpd are intimately related, so that the user is advised to set one of them at most. Normal usage is the following:

  • In cases where nev is small, the user sets ncv (a reasonable default is 2 * nev).
  • In cases where nev is large, the user sets mpd.

The value of ncv should always be between nev and (nev + mpd), typically ncv = nev + mpd. If nev is not too large, mpd = nev is a reasonable choice, otherwise a smaller value should be used.

setExtraction(self, extraction)

 

Sets the extraction type used by the EPS object.

Parameters

extraction: EPS.Extraction enumerate
The extraction method to be used by the solver.

Notes

Not all eigensolvers support all types of extraction. See the SLEPc documentation for details.

By default, a standard Rayleigh-Ritz extraction is used. Other extractions may be useful when computing interior eigenvalues.

Harmonic-type extractions are used in combination with a target. See setTarget().

setFromOptions(self)

 

Sets EPS 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

setIP(self, IP ip)

 

Associates an inner product to the eigensolver.

Parameters

ip: IP
The inner product context.

setInitialVector(self, Vec V)

 

Sets the initial vector from which the eigensolver starts to iterate.

Parameters

V: Vec
The initial vector.

setInitialVectorLeft(self, Vec W)

 

Sets the left initial vector from which the eigensolver starts to iterate, corresponding to the left recurrence (two-sided solvers).

Parameters

V: Vec
The initial vector.

setLanczosReorthogType(self, reorthog)

 

Sets the type of reorthogonalization used during the Lanczos iteration.

Parameters

reorthog: EPS.LanczosReorthogType enumerate
The type of reorthogonalization.

Notes

This call is only relevant if the type was set to EPS.Type.LANCZOS with setType().

setOperators(self, Mat A, Mat B=None)

 

Sets the matrices associated with the eigenvalue problem.

Parameters

A: Mat
The matrix associated with the eigensystem.
B: Mat, optional
The second matrix in the case of generalized eigenproblems; if not provided, a standard eigenproblem is assumed.

setOptionsPrefix(self, prefix)

 

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

Parameters

prefix: string
The prefix string to prepend to all EPS 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.

For example, to distinguish between the runtime options for two different EPS contexts, one could call:

E1.setOptionsPrefix("eig1_")
E2.setOptionsPrefix("eig2_")
Overrides: petsc4py.PETSc.Object.setOptionsPrefix

setPowerShiftType(self, shift)

 

Sets the type of shifts used during the power iteration. This can be used to emulate the Rayleigh Quotient Iteration (RQI) method.

Parameters

shift: EPS.PowerShiftType enumerate
The type of shift.

Notes

This call is only relevant if the type was set to EPS.Type.POWER with setType().

By default, shifts are constant (EPS.PowerShiftType.CONSTANT) and the iteration is the simple power method (or inverse iteration if a shift-and-invert transformation is being used).

A variable shift can be specified (EPS.PowerShiftType.RAYLEIGH or EPS.PowerShiftType.WILKINSON). In this case, the iteration behaves rather like a cubic converging method as RQI.

setProblemType(self, problem_type)

 

Specifies the type of the eigenvalue problem.

Parameters

problem_type: EPS.ProblemType enumerate
The problem type to be set.

Notes

Allowed values are: Hermitian (HEP), non-Hermitian (NHEP), generalized Hermitian (GHEP), generalized non-Hermitian (GNHEP), and generalized non-Hermitian with positive semi-definite B (PGNHEP).

This function must be used to instruct SLEPc to exploit symmetry. If no problem type is specified, by default a non-Hermitian problem is assumed (either standard or generalized). If the user knows that the problem is Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and B positive definite) then it is recommended to set the problem type so that eigensolver can exploit these properties.

setST(self, ST st)

 

Associates a spectral transformation object to the eigensolver.

Parameters

st: ST
The spectral transformation.

setTarget(self, target)

 

Sets the value of the target.

Parameters

target: float (real or complex)
The value of the target.

Notes

The target is a scalar value used to determine the portion of the spectrum of interest.

If the target is not specified, then eigenvalues are computed according to the which parameter, see setWhichEigenpairs().

If the target is specified, then the sought-after eigenvalues are those closest to the target.

setTolerances(self, tol=None, max_it=None)

 

Sets the tolerance and maximum iteration count used by the default EPS convergence tests.

Parameters

tol: float, optional
The convergence tolerance.
max_it: int, optional
The maximum number of iterations

Notes

Use DECIDE for maxits to assign a reasonably good value, which is dependent on the solution method.

setType(self, eps_type)

 

Selects the particular solver to be used in the EPS object.

Parameters

eps_type: EPS.Type enumerate
The solver to be used.

Notes

See EPS.Type for available methods. The default is EPS.Type.KRYLOVSCHUR. Normally, it is best to use setFromOptions() and then set the EPS 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.

setUp(self)

 

Sets up all the internal data structures necessary for the execution of the eigensolver.

Notes

This function need not be called explicitly in most cases, since solve() calls it. It can be useful when one wants to measure the set-up time separately from the solve time.

setWhichEigenpairs(self, which)

 

Specifies which portion of the spectrum is to be sought.

Parameters

which: EPS.Which enumerate
The portion of the spectrum to be sought by the solver.

Notes

Not all eigensolvers implemented in EPS account for all the possible values. Also, some values make sense only for certain types of problems. If SLEPc is compiled for real numbers EPS.Which.LARGEST_IMAGINARY and EPS.Which.SMALLEST_IMAGINARY use the absolute value of the imaginary part for eigenvalue selection.

view(self, Viewer viewer=None)

 

Prints the EPS data structure.

Parameters

viewer: Viewer, optional.
Visualization context; if not provided, the standard output is used.
Overrides: petsc4py.PETSc.Object.view