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

Class PEP



PEP

Nested Classes [hide private]
  Basis
  Conv
PEP convergence test
  ConvergedReason
PEP convergence reasons
  ErrorType
PEP error type to assess accuracy of computed solutions
  Extract
Extraction strategy used to obtain eigenvectors of the PEP from the eigenvectors of the linearization
  ProblemType
PEP problem type
  Refine
PEP refinement strategy
  RefineScheme
Scheme for solving linear systems during iterative refinement
  Scale
PEP scaling strategy
  Type
PEP type
  Which
PEP desired part of spectrum
Instance Methods [hide private]
a new object with type S, a subtype of T

__new__(S, ...)
 
appendOptionsPrefix(self, prefix)
Appends to the prefix used for searching for all PEP options in the database.
 
cancelMonitor(self)
Clears all monitors for a PEP object.
 
computeError(self, int i, etype=None)
Computes the error (based on the residual norm) associated with the i-th computed eigenpair.
 
create(self, comm=None)
Creates the PEP object.
 
destroy(self)
Destroys the PEP object.
 
errorView(self, etype=None, Viewer viewer=None)
Displays the errors associated with the computed solution (as well as the eigenvalues).
 
getBV(self)
Obtain the basis vectors object associated to the eigensolver.
 
getBasis(self)
Gets the type of polynomial basis used to describe the polynomial eigenvalue problem.
 
getConverged(self)
Gets the number of converged eigenpairs.
 
getConvergedReason(self)
Gets the reason why the `solve()` iteration was stopped.
 
getConvergenceTest(self)
Return the method used to compute the error estimate used in the convergence test.
 
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.
 
getInterval(self)
Gets the computational interval for spectrum slicing.
 
getIterationNumber(self)
Gets the current iteration number.
 
getJDFix(self)
Gets threshold for changing the target in the correction equation.
 
getJDRestart(self)
Gets the restart parameter used in the Jacobi-Davidson method.
 
getLinearEPS(self)
Retrieve the eigensolver object (EPS) associated to the polynomial eigenvalue solver.
 
getLinearExplicitMatrix(self)
Returns the flag indicating if the matrices A and B for the linearization are built explicitly.
 
getLinearLinearization(self)
Returns the coefficients that define the linearization of a quadratic eigenproblem.
 
getOperators(self)
Gets the matrices associated with the eigenvalue problem.
 
getOptionsPrefix(self)
Gets the prefix used for searching for all PEP options in the database.
 
getProblemType(self)
Gets the problem type from the PEP object.
 
getRG(self)
Obtain the region object associated to the eigensolver.
 
getRefine(self)
Gets the refinement strategy used by the PEP object, and the associated parameters.
 
getST(self)
Obtain the spectral transformation (`ST`) object associated to the eigensolver object.
 
getSTOARDetectZeros(self)
Gets the flag that enforces zero detection in spectrum slicing.
 
getSTOARDimensions(self)
Gets the dimensions used for each subsolve step in case of doing spectrum slicing for a computational interval.
 
getSTOARLocking(self)
Gets the locking flag used in the STOAR method.
 
getScale(self, Vec Dl=None, Vec Dr=None)
Gets the strategy used for scaling the polynomial eigenproblem.
 
getTOARLocking(self)
Gets the locking flag used in the TOAR method.
 
getTOARRestart(self)
Gets the restart parameter used in the TOAR method.
 
getTarget(self)
Gets the value of the target.
 
getTolerances(self)
Gets the tolerance and maximum iteration count used by the default PEP convergence tests.
 
getTrackAll(self)
Returns the flag indicating whether all residual norms must be computed or not.
 
getType(self)
Gets the PEP type of this object.
 
getWhichEigenpairs(self)
Returns which portion of the spectrum is to be sought.
 
reset(self)
Resets the PEP object.
 
setBV(self, BV bv)
Associates a basis vectors object to the eigensolver.
 
setBasis(self, basis)
Specifies the type of polynomial basis used to describe the polynomial eigenvalue problem.
 
setConvergenceTest(self, conv)
Specifies how to compute the error estimate used in the convergence test.
 
setDimensions(self, nev=None, ncv=None, mpd=None)
Sets the number of eigenvalues to compute and the dimension of the subspace.
 
setFromOptions(self)
Sets PEP options from the options database.
 
setInitialSpace(self, space)
Sets the initial space from which the eigensolver starts to iterate.
 
setInterval(self, inta, intb)
Defines the computational interval for spectrum slicing.
 
setJDFix(self, fix)
Sets the threshold for changing the target in the correction equation.
 
setJDRestart(self, keep)
Sets the restart parameter for the Jacobi-Davidson method, in particular the proportion of basis vectors that must be kept after restart.
 
setLinearEPS(self, EPS eps)
Associate an eigensolver object (EPS) to the polynomial eigenvalue solver.
 
setLinearExplicitMatrix(self, flag)
Indicate if the matrices A and B for the linearization of the problem must be built explicitly.
 
setLinearLinearization(self, alpha=1.0, beta=0.0)
Set the coefficients that define the linearization of a quadratic eigenproblem.
 
setOperators(self, operators)
Sets the matrices associated with the eigenvalue problem.
 
setOptionsPrefix(self, prefix)
Sets the prefix used for searching for all PEP options in the database.
 
setProblemType(self, problem_type)
Specifies the type of the eigenvalue problem.
 
setRG(self, RG rg)
Associates a region object to the eigensolver.
 
setRefine(self, ref, npart=None, tol=None, its=None, scheme=None)
Sets the refinement strategy used by the PEP object, and the associated parameters.
 
setST(self, ST st)
Associates a spectral transformation object to the eigensolver.
 
setSTOARDetectZeros(self, detect)
Sets a flag to enforce detection of zeros during the factorizations throughout the spectrum slicing computation.
 
setSTOARDimensions(self, nev=None, ncv=None, mpd=None)
Sets the dimensions used for each subsolve step in case of doing spectrum slicing for a computational interval.
 
setSTOARLocking(self, lock)
Choose between locking and non-locking variants of the STOAR method.
 
setScale(self, scale, alpha=None, Vec Dl=None, Vec Dr=None, its=None, lbda=None)
Sets the scaling strategy to be used for scaling the polynomial problem before attempting to solve.
 
setTOARLocking(self, lock)
Choose between locking and non-locking variants of the TOAR method.
 
setTOARRestart(self, keep)
Sets the restart parameter for the TOAR method, in particular the proportion of basis vectors that must be kept after restart.
 
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 PEP convergence tests.
 
setTrackAll(self, trackall)
Specifies if the solver must compute the residual of all approximate eigenpairs or not.
 
setType(self, pep_type)
Selects the particular solver to be used in the PEP 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 PEP 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]

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__

appendOptionsPrefix(self, prefix)

 
Appends to the prefix used for searching for all PEP options
in the database.

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

computeError(self, int i, etype=None)

 
Computes the error (based on the residual norm) associated with the i-th
computed eigenpair.

Parameters
----------
i: int
   Index of the solution to be considered.
etype: `PEP.ErrorType` enumerate
   The error type to compute.

Returns
-------
error: real
   The error bound, computed in various ways from the
   residual norm ``||P(l)x||_2`` where ``l`` is the
   eigenvalue and ``x`` is the eigenvector.

Notes
-----
The index ``i`` should be a value between ``0`` and
``nconv-1`` (see `getConverged()`).

create(self, comm=None)

 
Creates the PEP object.

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

destroy(self)

 
Destroys the PEP object.

Overrides: petsc4py.PETSc.Object.destroy

errorView(self, etype=None, Viewer viewer=None)

 
Displays the errors associated with the computed solution
(as well as the eigenvalues).

Parameters
----------
etype: `PEP.ErrorType` enumerate, optional
   The error type to compute.
viewer: Viewer, optional.
        Visualization context; if not provided, the standard
        output is used.

Notes
-----
By default, this function checks the error of all eigenpairs and prints
the eigenvalues if all of them are below the requested tolerance.
If the viewer has format ``ASCII_INFO_DETAIL`` then a table with
eigenvalues and corresponding errors is printed.

getBV(self)

 
Obtain the basis vectors object associated to the eigensolver.

Returns
-------
bv: BV
    The basis vectors context.

getBasis(self)

 
Gets the type of polynomial basis used to 
describe the polynomial eigenvalue problem.

Returns
-------
basis: `PEP.Basis` enumerate
    the basis that was previously set.

getConverged(self)

 
Gets the number of converged eigenpairs.

Returns
-------
nconv: int
    Number of converged eigenpairs.

getConvergedReason(self)

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

Returns
-------
reason: `PEP.ConvergedReason` enumerate
    Negative value indicates diverged, positive value
    converged.

getConvergenceTest(self)

 
Return the method used to compute the error estimate 
used in the convergence test. 

Returns
-------
conv: PEP.Conv
    The method used to compute the error estimate 
    used in the convergence test. 

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, optional
    Placeholder for the returned eigenvector (real part).
Vi: Vec, optional
    Placeholder for the returned eigenvector (imaginary part).

Returns
-------
e: scalar (possibly complex)
    The computed eigenvalue.

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
-------
error: real
    Error estimate.

getInterval(self)

 
Gets the computational interval for spectrum slicing.

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

Notes
-----
If the interval was not set by the user, then zeros are returned.

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.

getJDFix(self)

 
Gets threshold for changing the target in the correction equation.

Returns
-------
fix: float
      The threshold for changing the target.

getJDRestart(self)

 
Gets the restart parameter used in the Jacobi-Davidson method.

Returns
-------
keep: float
      The number of vectors to be kept at restart.

getLinearEPS(self)

 
Retrieve the eigensolver object (EPS) associated to the polynomial
eigenvalue solver.

Returns
-------
eps: EPS
    The linear eigensolver.

getLinearExplicitMatrix(self)

 
Returns the flag indicating if the matrices A and B for the linearization
are built explicitly.

Returns
-------
flag: boolean

getLinearLinearization(self)

 
Returns the coefficients that define the linearization of a quadratic eigenproblem.

Returns
-------
alpha: float
    first parameter of the linearization.
beta: float
    second parameter of the linearization.

getOperators(self)

 
Gets the matrices associated with the eigenvalue problem.

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

getOptionsPrefix(self)

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

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

Overrides: petsc4py.PETSc.Object.getOptionsPrefix

getProblemType(self)

 
Gets the problem type from the PEP object.

Returns
-------
problem_type: `PEP.ProblemType` enumerate
    The problem type that was previously set.

getRG(self)

 
Obtain the region object associated to the eigensolver.

Returns
-------
rg: RG
    The region context.

getRefine(self)

 
Gets the refinement strategy used by the PEP object, 
and the associated parameters. 

Returns
-------
ref: PEP.Refine
    The refinement type.
npart: int
    The number of partitions of the communicator.
tol: real
    The convergence tolerance.
its: int
    The maximum number of refinement iterations.
scheme: PEP.RefineScheme
    Scheme for solving linear systems

getST(self)

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

Returns
-------
st: ST
    The spectral transformation.

getSTOARDetectZeros(self)

 
Gets the flag that enforces zero detection in spectrum slicing.

Returns
-------
detect: bool
      The zero detection flag.

getSTOARDimensions(self)

 
Gets the dimensions used for each subsolve step in case of doing
spectrum slicing for a computational interval.

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.

getSTOARLocking(self)

 
Gets the locking flag used in the STOAR method.

Returns
-------
lock: bool
      The locking flag.

getScale(self, Vec Dl=None, Vec Dr=None)

 
Gets the strategy used for scaling the polynomial eigenproblem.

Parameters
----------
Dl: Vec, optional
    Placeholder for the returned left diagonal matrix.
Dr: Vec, optional
    Placeholder for the returned right diagonal matrix.

Returns
-------
scale: `PEP.Scale` enumerate
    The scaling strategy.
alpha: real
    The scaling factor.
its: integer
    The number of iteration of diagonal scaling.
lbda: real
    Approximation of the wanted eigenvalues (modulus).

getTOARLocking(self)

 
Gets the locking flag used in the TOAR method.

Returns
-------
lock: bool
      The locking flag.

getTOARRestart(self)

 
Gets the restart parameter used in the TOAR method.

Returns
-------
keep: float
      The number of vectors to be kept at restart.

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 PEP convergence tests.

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

getTrackAll(self)

 
Returns the flag indicating whether all residual norms must be
computed or not.

Returns
-------
trackall: bool
    Whether the solver compute all residuals or not.

getType(self)

 
Gets the PEP type of this object.

Returns
-------
type: `PEP.Type` enumerate
    The solver currently being used.

Overrides: petsc4py.PETSc.Object.getType

getWhichEigenpairs(self)

 
Returns which portion of the spectrum is to be sought.

Returns
-------
which: `PEP.Which` enumerate
    The portion of the spectrum to be sought by the solver.

setBV(self, BV bv)

 
Associates a basis vectors object to the eigensolver.

Parameters
----------
bv: BV
    The basis vectors context.

setBasis(self, basis)

 
Specifies the type of polynomial basis used to 
describe the polynomial eigenvalue problem.

Parameters
----------
basis: `PEP.Basis` enumerate
    the basis to be set.

setConvergenceTest(self, conv)

 
Specifies how to compute the error estimate 
used in the convergence test. 

Parameters
----------
conv: PEP.Conv
    The method used to compute the error estimate 
    used in the convergence test.

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.

setFromOptions(self)

 
Sets PEP options from the options database. This routine must
be called before `setUp()` if the user is to be allowed to set
the solver type.

Overrides: petsc4py.PETSc.Object.setFromOptions

setInitialSpace(self, space)

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

Parameters
----------
space: Vec or sequence of Vec
   The initial space

setInterval(self, inta, intb)

 
Defines the computational interval for spectrum slicing.

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

Notes
-----
Spectrum slicing is a technique employed for computing all
eigenvalues of symmetric quadratic eigenproblems in a given interval.
This function provides the interval to be considered. It must
be used in combination with `PEP.Which.ALL`, see
`setWhichEigenpairs()`.

setJDFix(self, fix)

 
Sets the threshold for changing the target in the correction
equation.

Parameters
----------
fix: float
      Threshold for changing the target.

Notes
-----
The target in the correction equation is fixed at the first iterations.
When the norm of the residual vector is lower than the fix value,
the target is set to the corresponding eigenvalue.

setJDRestart(self, keep)

 
Sets the restart parameter for the Jacobi-Davidson method, in
particular the proportion of basis vectors that must be kept
after restart.

Parameters
----------
keep: float
      The number of vectors to be kept at restart.

Notes
-----
Allowed values are in the range [0.1,0.9]. The default is 0.5.

setLinearEPS(self, EPS eps)

 
Associate an eigensolver object (EPS) to the polynomial eigenvalue solver.

Parameters
----------
eps: EPS
    The linear eigensolver.

setLinearExplicitMatrix(self, flag)

 
Indicate if the matrices A and B for the linearization of the problem
must be built explicitly.

Parameters
----------
flag: boolean
    boolean flag indicating if the matrices are built explicitly .

setLinearLinearization(self, alpha=1.0, beta=0.0)

 
Set the coefficients that define the linearization of a quadratic eigenproblem.

Parameters
----------
alpha: float
    first parameter of the linearization.
beta: float
    second parameter of the linearization.

setOperators(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 PEP options in the
database.

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

Overrides: petsc4py.PETSc.Object.setOptionsPrefix

setProblemType(self, problem_type)

 
Specifies the type of the eigenvalue problem.

Parameters
----------
problem_type: `PEP.ProblemType` enumerate
    The problem type to be set.

setRG(self, RG rg)

 
Associates a region object to the eigensolver.

Parameters
----------
rg: RG
    The region context.

setRefine(self, ref, npart=None, tol=None, its=None, scheme=None)

 
Sets the refinement strategy used by the PEP object, 
and the associated parameters. 

Parameters
----------
ref: PEP.Refine
    The refinement type.
npart: int, optional
    The number of partitions of the communicator.
tol: real, optional
    The convergence tolerance.
its: int, optional
    The maximum number of refinement iterations.
scheme: PEP.RefineScheme, optional
    Scheme for linear system solves

setST(self, ST st)

 
Associates a spectral transformation object to the
eigensolver.

Parameters
----------
st: ST
    The spectral transformation.

setSTOARDetectZeros(self, detect)

 
Sets a flag to enforce detection of zeros during the factorizations
throughout the spectrum slicing computation.

Parameters
----------
detect: bool
      True if zeros must checked for.

Notes
-----
A zero in the factorization indicates that a shift coincides with
an eigenvalue.

This flag is turned off by default, and may be necessary in some cases.
This feature currently requires an external package for factorizations
with support for zero detection, e.g. MUMPS.

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

 
Sets the dimensions used for each subsolve step in case of doing
spectrum slicing for a computational interval. The meaning of the
parameters is the same as in `setDimensions()`.

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.

setSTOARLocking(self, lock)

 
Choose between locking and non-locking variants of the
STOAR method.

Parameters
----------
lock: bool
      True if the locking variant must be selected.

Notes
-----
The default is to lock converged eigenpairs when the method restarts.
This behaviour can be changed so that all directions are kept in the
working subspace even if already converged to working accuracy (the
non-locking variant).

setScale(self, scale, alpha=None, Vec Dl=None, Vec Dr=None, its=None, lbda=None)

 
Sets the scaling strategy to be used for scaling the polynomial problem
before attempting to solve.

Parameters
----------
scale: `PEP.Scale` enumerate
    The scaling strategy.
alpha: real, optional
    The scaling factor.
Dl: Vec, optional
    The left diagonal matrix.
Dr: Vec, optional
    The right diagonal matrix.
its: integer, optional
    The number of iteration of diagonal scaling.
lbda: real, optional
    Approximation of the wanted eigenvalues (modulus).

setTOARLocking(self, lock)

 
Choose between locking and non-locking variants of the
TOAR method.

Parameters
----------
lock: bool
      True if the locking variant must be selected.

Notes
-----
The default is to lock converged eigenpairs when the method restarts.
This behaviour can be changed so that all directions are kept in the
working subspace even if already converged to working accuracy (the
non-locking variant).

setTOARRestart(self, keep)

 
Sets the restart parameter for the TOAR method, in
particular the proportion of basis vectors that must be kept
after restart.

Parameters
----------
keep: float
      The number of vectors to be kept at restart.

Notes
-----
Allowed values are in the range [0.1,0.9]. The default is 0.5.

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. It is used in combination with
`setWhichEigenpairs()`.

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

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

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

setTrackAll(self, trackall)

 
Specifies if the solver must compute the residual of all
approximate eigenpairs or not.

Parameters
----------
trackall: bool
    Whether compute all residuals or not.

setType(self, pep_type)

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

Parameters
----------
pep_type: `PEP.Type` enumerate
    The solver to be used.

setWhichEigenpairs(self, which)

 
Specifies which portion of the spectrum is to be sought.

Parameters
----------
which: `PEP.Which` enumerate
    The portion of the spectrum to be sought by the solver.

view(self, Viewer viewer=None)

 
Prints the PEP data structure.

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

Overrides: petsc4py.PETSc.Object.view