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

getIterationNumber(self) Gets the current iteration number. |

getLinearCompanionForm(self) Returns the number of the companion form that will be used for the linearization of a quadratic eigenproblem. |

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

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

getScale(self, Vec Dl=None, Vec Dr=None) Gets the strategy used for scaling the polynomial eigenproblem. |

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

setLinearCompanionForm(self, cform) Choose between the two companion forms available for the linearization of a quadratic eigenproblem. |

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

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

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

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`

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.

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

### getLinearCompanionForm(self)

Returns the number of the companion form that will be used for the linearization of a quadratic eigenproblem.

# Returns

cform: integer
  1 or 2 (first or second companion form).

### 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

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

### 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).

### 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

### setLinearCompanionForm(self, cform)

Choose between the two companion forms available for the linearization of a quadratic eigenproblem.

# Parameters

cform: integer
  1 or 2 (first or second companion form).

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

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

### 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).

### 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