Class NEP

Returns:

a new object with type S, a subtype of T

Overrides: object.__new__

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

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

Applies the resolvent T^{-1}(z) to a given vector.

Parameters
----------
omega: scalar
    Value where the resolvent must be evaluated.
v: Vec
    Input vector.
r: Vec
    Placeholder for the result vector.
rg: `RG` object, optional
    Region.

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: `NEP.ErrorType` enumerate
    The error type to compute.

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

Creates the NEP object.

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

Destroys the NEP object.

Overrides: petsc4py.PETSc.Object.destroy

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

Parameters
----------
etype: `NEP.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.

Obtain the basis vectors object associated to the eigensolver.

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

Gets the extraction technique used in the CISS solver.

Returns
-------
extraction: `NEP.CISSExtraction` enumerate
       The extraction technique.

Retrieve the array of linear solver objects associated with
the CISS solver.

Returns
-------
ksp: list of `KSP`
     The linear solver objects.

Notes
-----
The number of `KSP` solvers is equal to the number of integration
points divided by the number of partitions. This value is halved in
the case of real matrices with a region centered at the real axis.

Gets the values of various refinement parameters in the CISS solver.

Returns
-------
inner: int
     Number of iterative refinement iterations (inner loop).
blsize: int
     Number of iterative refinement iterations (blocksize loop).

Gets the values of various size parameters in the CISS solver.

Returns
-------
ip: int
     Number of integration points.
bs: int
     Block size.
ms: int
     Moment size.
npart: int
     Number of partitions when splitting the communicator.
bsmax: int
     Maximum block size.
realmats: bool
     True if A and B are real.

Gets the values of various threshold parameters in the CISS solver.

Returns
-------
delta: float
        Threshold for numerical rank.
spur: float
        Spurious threshold (to discard spurious eigenpairs.

Gets the number of converged eigenpairs.

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

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

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

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

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

Obtain the direct solver associated to the eigensolver.

Returns
-------
ds: DS
    The direct solver context.

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.

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.

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.

Returns the function to compute the nonlinear Function T(lambda) and the matrix.

Parameters
----------
F: Mat
    Function matrix
P: Mat
    preconditioner matrix (usually the same as the F)
function:
    Function evaluation routine

Gets the tolerance and maximum degree when building the
interpolation polynomial.

Returns
-------
tol: float
    The tolerance to stop computing polynomial coefficients.
deg: int
    The maximum degree of interpolation.

Retrieve the polynomial eigensolver object associated with the nonlinear eigensolver.

Returns
-------
pep: `PEP`
     The polynomial eigensolver.

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.

Returns the function to compute the Jacobian T'(lambda) and the matrix.

Parameters
----------
J: Mat
    Jacobian matrix
jacobian:
    Jacobian evaluation routine

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

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

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

Left eigenvectors are available only if the twosided flag was set
with `setTwoSided()`.

Retrieve the linear solver object associated with the nonlinear eigensolver.

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

Indicates how often the preconditioner is rebuilt.

Returns
-------
lag: int
     The lag parameter.

Retrieve the linear eigensolver object associated with the nonlinear eigensolver.

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

Gets the flag that indicates if NLEIGS is using the full-basis variant.

Returns
-------
fullbasis: bool
      True if the full-basis variant must be selected.

Gets the tolerance and maximum degree when building the
interpolation via divided differences.

Returns
-------
tol: float
    The tolerance to stop computing divided differences.
deg: int
    The maximum degree of interpolation.

Retrieve the array of linear solver objects associated with
the NLEIGS solver.

Returns
-------
ksp: list of `KSP`
     The linear solver objects.

Notes
-----
The number of `KSP` solvers is equal to the number of shifts provided
by the user, or 1 if the user did not provide shifts.

Gets the locking flag used in the NLEIGS method.

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

Gets the list of shifts used in the Rational Krylov method.

Returns
-------
shifts: array of scalars
    The shift values.

Gets the restart parameter used in the NLEIGS method.

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

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

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

Overrides: petsc4py.PETSc.Object.getOptionsPrefix

Gets the problem type from the `NEP` object.

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

Obtain the region object associated to the eigensolver.

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

Returns the constant tolerance flag.

Returns
-------
cct: bool
     If True, the `KSP` relative tolerance is constant.

Returns the threshold value that controls deflation.

Returns
-------
deftol: float
        The threshold value.

Returns the flag about using the Hermitian version of the scalar
nonlinear equation.

Returns
-------
herm: bool
      If True, the Hermitian version is used.

Retrieve the linear solver object associated with the nonlinear eigensolver.

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

Indicates how often the preconditioner is rebuilt.

Returns
-------
lag: int
    The lag parameter.

Gets the maximum number of inner iterations of RII.

Returns
-------
its: int
     Maximum inner iterations.

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

Returns
-------
ref: NEP.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: NEP.RefineScheme
    Scheme for solving linear systems

Obtain the `KSP` object used by the eigensolver in the
refinement phase.

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

Returns the threshold value that controls deflation.

Returns
-------
deftol: float
        The threshold value.

Retrieve the linear eigensolver object associated with the nonlinear eigensolver.

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

Retrieve the left eigensolver.

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

Retrieve the linear solver object associated with the nonlinear eigensolver.

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

Returns the operator of the nonlinear eigenvalue problem
in split form.

Returns
-------
A: sequence of Mat
    Coefficient matrices of the split form.
f: sequence of FN
    Scalar functions of the split form.
structure: `PETSc.Mat.Structure` enumerate
    Structure flag for matrices.

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.

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

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

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

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

Returns the flag indicating whether a two-sided variant
of the algorithm is being used or not.

Returns
-------
twosided: bool
    Whether the two-sided variant is to be used or not.

Gets the NEP type of this object.

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

Overrides: petsc4py.PETSc.Object.getType

Returns which portion of the spectrum is to be sought.

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

Associates a basis vectors object to the eigensolver.

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

Sets the extraction technique used in the CISS solver.

Parameters
----------
extraction: `NEP.CISSExtraction` enumerate
       The extraction technique.

Sets the values of various refinement parameters in the CISS solver.

Parameters
----------
inner: int, optional
     Number of iterative refinement iterations (inner loop).
blsize: int, optional
     Number of iterative refinement iterations (blocksize loop).

Sets the values of various size parameters in the CISS solver.

Parameters
----------
ip: int, optional
     Number of integration points.
bs: int, optional
     Block size.
ms: int, optional
     Moment size.
npart: int, optional
     Number of partitions when splitting the communicator.
bsmax: int, optional
     Maximum block size.
realmats: bool, optional
     True if A and B are real.

Notes
-----
The default number of partitions is 1. This means the internal `KSP` object
is shared among all processes of the `NEP` communicator. Otherwise, the
communicator is split into npart communicators, so that `npart` `KSP` solves
proceed simultaneously.

Sets the values of various threshold parameters in the CISS solver.

Parameters
----------
delta: float
        Threshold for numerical rank.
spur: float
        Spurious threshold (to discard spurious eigenpairs).

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

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

Associates a direct solver object to the eigensolver.

Parameters
----------
ds: DS
    The direct solver context.

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.

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

Sets the function to compute the nonlinear Function T(lambda)
as well as the location to store the matrix.

Parameters
----------
function:
    Function evaluation routine
F: Mat
    Function matrix
P: Mat
    preconditioner matrix (usually the same as F)

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

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

Sets the tolerance and maximum degree when building the
interpolation polynomial.

Parameters
----------
tol: float, optional
    The tolerance to stop computing polynomial coefficients.
deg: int, optional
    The maximum degree of interpolation.

Associate a polynomial eigensolver object to the nonlinear eigensolver.

Parameters
----------
pep: `PEP`
     The polynomial eigensolver.

Sets the function to compute the Jacobian T'(lambda) as well
as the location to store the matrix.

Parameters
----------
jacobian:
    Jacobian evaluation routine
J: Mat
    Jacobian matrix

Associate a linear solver object to the nonlinear eigensolver.

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

Determines when the preconditioner is rebuilt in the nonlinear solve.

Parameters
----------
lag: int
     0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
     computed within the nonlinear iteration, 2 means every second time
     the Jacobian is built, etc.

Notes
-----
The default is 1. The preconditioner is ALWAYS built in the first
iteration of a nonlinear solve.

Associate a linear eigensolver object to the nonlinear eigensolver.

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

Choose between TOAR-basis (default) and full-basis variants
of the NLEIGS method.

Parameters
----------
fullbasis: bool
      True if the full-basis variant must be selected.

Sets the tolerance and maximum degree when building the
interpolation via divided differences.

Parameters
----------
tol: float, optional
    The tolerance to stop computing divided differences.
deg: int, optional
    The maximum degree of interpolation.

Choose between locking and non-locking variants of the
NLEIGS 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).

Sets a list of shifts to be used in the Rational Krylov method.

Parameters
----------
shifts: array of scalars
    Values specifying the shifts.

Sets the restart parameter for the NLEIGS 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.

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

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

Overrides: petsc4py.PETSc.Object.setOptionsPrefix

Specifies the type of the eigenvalue problem.

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

Associates a region object to the eigensolver.

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

Sets a flag to keep the tolerance used in the linear solver constant.

Parameters
----------
cct: bool
     If True, the `KSP` relative tolerance is constant.

Sets the threshold value used to switch between deflated and
non-deflated iteration.

Parameters
----------
deftol: float
        The threshold value.

Sets a flag to indicate if the Hermitian version of the scalar
nonlinear equation must be used by the solver.

Parameters
----------
herm: bool
      If True, the Hermitian version is used.

Associate a linear solver object to the nonlinear eigensolver.

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

Determines when the preconditioner is rebuilt in the
nonlinear solve.

Parameters
----------
lag: int
    0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
    computed within the nonlinear iteration, 2 means every second time
    the Jacobian is built, etc.

Sets the maximum number of inner iterations to be used in
the RII solver. These are the Newton iterations related to the
computation of the nonlinear Rayleigh functional.

Parameters
----------
its: int
     Maximum inner iterations.

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

Parameters
----------
ref: NEP.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: NEP.RefineScheme, optional
    Scheme for linear system solves

Sets the threshold value used to switch between deflated and
non-deflated iteration.

Parameters
----------
deftol: float
        The threshold value.

Associate a linear eigensolver object to the nonlinear eigensolver.

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

Associate a linear eigensolver object to the nonlinear eigensolver,
used to compute left eigenvectors in the two-sided variant of SLP.

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

Associate a linear solver object to the nonlinear eigensolver.

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

Sets the operator of the nonlinear eigenvalue problem
in split form.

Parameters
----------
A: Mat or sequence of Mat
    Coefficient matrices of the split form.
f: sequence of FN
    Scalar functions of the split form.
structure: `PETSc.Mat.Structure` enumerate, optional
    Structure flag for matrices.

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

Sets the tolerance and maximum iteration count used in convergence tests.

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

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

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

Sets the solver to use a two-sided variant so that left
eigenvectors are also computed.

Parameters
----------
twosided: bool
    Whether the two-sided variant is to be used or not.

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

Parameters
----------
nep_type: `NEP.Type` enumerate
    The solver to be used.

Specifies which portion of the spectrum is to be sought.

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

Displays the computed eigenvalues in a viewer.

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

Outputs computed eigenvectors to a viewer.

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

Prints the NEP data structure.

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

Overrides: petsc4py.PETSc.Object.view