slepc4py.SLEPc.EPS#
- class slepc4py.SLEPc.EPS#
Bases:
ObjectEigenvalue Problem Solver.
The Eigenvalue Problem Solver (
EPS) is the object provided by slepc4py for specifying a linear eigenvalue problem, either in standard or generalized form. It provides uniform and efficient access to all of the linear eigensolvers included in the package.Enumerations
EPS type of balancing used for non-Hermitian problems.
EPS CISS extraction technique.
EPS CISS quadrature rule.
EPS convergence test.
EPS convergence reasons.
EPS error type to assess accuracy of computed solutions.
EPS extraction technique.
EPS Krylov-Schur method for BSE problems.
EPS Lanczos reorthogonalization type.
EPS Power shift type.
EPS problem type.
EPS stopping test.
EPS type.
EPS desired part of spectrum.
Methods Summary
appendOptionsPrefix([prefix])Append to the prefix used for searching for all EPS options in the database.
Clear all monitors for an
EPSobject.computeError(i[, etype])Compute the error associated with the i-th computed eigenpair.
create([comm])Create the EPS object.
destroy()Destroy the EPS object.
errorView([etype, viewer])Display the errors associated with the computed solution.
Get the type of reorthogonalization used during the Arnoldi iteration.
getBV()Get the basis vector objects associated to the eigensolver.
Get the balancing type used by the EPS, and the associated parameters.
Get the extraction technique used in the CISS solver.
Get the array of linear solver objects associated with the CISS solver.
Get the quadrature rule used in the CISS solver.
Get the values of various refinement parameters in the CISS solver.
Get the values of various size parameters in the CISS solver.
Get the values of various threshold parameters in the CISS solver.
Get the flag indicating the use of the
STobject in the CISS solver.Get the number of converged eigenpairs.
Get the reason why the
solve()iteration was stopped.Get how to compute the error estimate used in the convergence test.
getDS()Get the direct solver associated to the eigensolver.
Get number of eigenvalues to compute and the dimension of the subspace.
getEigenpair(i[, Vr, Vi])Get the i-th solution of the eigenproblem as computed by
solve().Get the i-th eigenvalue as computed by
solve().getEigenvector(i[, Vr, Vi])Get the i-th eigenvector as computed by
solve().Get the error estimate associated to the i-th computed eigenpair.
Get the extraction type used by the EPS object.
Get the orthogonalization used in the search subspace.
Get the number of vectors to be added to the searching space.
Get a flag indicating whether the double expansion variant is active.
Get the initial size of the searching space.
Get a flag indicating if the search subspace is started with a Krylov basis.
Get the number of vectors of the search space after restart.
Get the computational interval for spectrum slicing.
Get an orthonormal basis of the computed invariant subspace.
Get the current iteration number.
Get the orthogonalization used in the search subspace.
Get the number of vectors to be added to the searching space.
Get the flag indicating if the dynamic stopping is being used.
getJDFix()Get the threshold for changing the target in the correction equation.
Get the initial size of the searching space.
Get a flag indicating if the search subspace is started with a Krylov basis.
Get the number of vectors of the search space after restart.
Get the method used for BSE structured eigenproblems (Krylov-Schur).
Get the flag that enforces zero detection in spectrum slicing.
Get the dimensions used for each subsolve step (spectrum slicing).
Get the values of the shifts and their corresponding inertias.
Get the linear solver object associated with the internal
EPSobject.Get the locking flag used in the Krylov-Schur method.
Get the number of partitions of the communicator (spectrum slicing).
Get the restart parameter used in the Krylov-Schur method.
Get information related to the case of doing spectrum slicing.
Get the eigenproblem matrices stored in the subcommunicator.
Get the i-th eigenpair stored in the multi-communicator of the process.
Get the points that delimit the subintervals.
Get the block size used in the LOBPCG method.
Get the locking flag used in the LOBPCG method.
Get the restart parameter used in the LOBPCG method.
Get the type of reorthogonalization used during the Lanczos iteration.
getLeftEigenvector(i[, Wr, Wi])Get the i-th left eigenvector as computed by
solve().Get the rank values used for the Lyapunov step.
Get the list of monitor functions.
Get the matrices associated with the eigenvalue problem.
Get the prefix used for searching for all EPS options in the database.
Get the type of shifts used during the power iteration.
Get the problem type from the EPS object.
Get the flag indicating whether purification is activated or not.
getRG()Get the region object associated to the eigensolver.
Get the reset parameter used in the RQCG method.
getST()Get the spectral transformation object associated to the eigensolver.
Get the stopping function.
Get the value of the target.
Get the threshold used in the threshold stopping test.
Get the tolerance and max.
Get the flag indicating if all residual norms must be computed or not.
Get the flag indicating if true residual must be computed explicitly.
Get the flag indicating if a two-sided variant of the algorithm is being used.
getType()Get the EPS type of this object.
Get which portion of the spectrum is to be sought.
Tell if the EPS object corresponds to a generalized eigenproblem.
Tell if the EPS object corresponds to a Hermitian eigenproblem.
Eigenproblem requiring a positive (semi-) definite matrix \(B\).
Tell if the EPS object corresponds to a structured eigenvalue problem.
reset()Reset the EPS object.
setArbitrarySelection(arbitrary[, args, kargs])Set an arbitrary selection criterion function.
setArnoldiDelayed(delayed)Set (toggle) delayed reorthogonalization in the Arnoldi iteration.
setBV(bv)Set a basis vectors object associated to the eigensolver.
setBalance([balance, iterations, cutoff])Set the balancing technique to be used by the eigensolver.
setCISSExtraction(extraction)Set the extraction technique used in the CISS solver.
setCISSQuadRule(quad)Set the quadrature rule used in the CISS solver.
setCISSRefinement([inner, blsize])Set the values of various refinement parameters in the CISS solver.
setCISSSizes([ip, bs, ms, npart, bsmax, ...])Set the values of various size parameters in the CISS solver.
setCISSThreshold([delta, spur])Set the values of various threshold parameters in the CISS solver.
setCISSUseST(usest)Set a flag indicating that the CISS solver will use the
STobject.setConvergenceTest(conv)Set how to compute the error estimate used in the convergence test.
setDS(ds)Set a direct solver object associated to the eigensolver.
setDeflationSpace(space)Add vectors to the basis of the deflation space.
setDimensions([nev, ncv, mpd])Set number of eigenvalues to compute and the dimension of the subspace.
setEigenvalueComparison(comparison[, args, ...])Set an eigenvalue comparison function.
setExtraction(extraction)Set the extraction type used by the EPS object.
Set EPS options from the options database.
setGDBOrth(borth)Set the orthogonalization that will be used in the search subspace.
setGDBlockSize(bs)Set the number of vectors to be added to the searching space.
setGDDoubleExpansion(doubleexp)Set that the search subspace is expanded with double expansion.
setGDInitialSize(initialsize)Set the initial size of the searching space.
setGDKrylovStart([krylovstart])Set (toggle) starting the search subspace with a Krylov basis.
setGDRestart([minv, plusk])Set the number of vectors of the search space after restart.
setInitialSpace(space)Set the initial space from which the eigensolver starts to iterate.
setInterval(inta, intb)Set the computational interval for spectrum slicing.
setJDBOrth(borth)Set the orthogonalization that will be used in the search subspace.
setJDBlockSize(bs)Set the number of vectors to be added to the searching space.
setJDConstCorrectionTol(constant)Deactivate the dynamic stopping criterion.
setJDFix(fix)Set the threshold for changing the target in the correction equation.
setJDInitialSize(initialsize)Set the initial size of the searching space.
setJDKrylovStart([krylovstart])Set (toggle) starting the search subspace with a Krylov basis.
setJDRestart([minv, plusk])Set the number of vectors of the search space after restart.
Set the Krylov-Schur variant used for BSE structured eigenproblems.
setKrylovSchurDetectZeros(detect)Set the flag that enforces zero detection in spectrum slicing.
setKrylovSchurDimensions([nev, ncv, mpd])Set the dimensions used for each subsolve step (spectrum slicing).
setKrylovSchurLocking(lock)Set (toggle) locking/non-locking variants of the Krylov-Schur method.
setKrylovSchurPartitions(npart)Set the number of partitions of the communicator (spectrum slicing).
setKrylovSchurRestart(keep)Set the restart parameter for the Krylov-Schur method.
setKrylovSchurSubintervals(subint)Set the subinterval boundaries.
Set the block size of the LOBPCG method.
setLOBPCGLocking(lock)Toggle between locking and non-locking (LOBPCG method).
setLOBPCGRestart(restart)Set the restart parameter for the LOBPCG method.
setLanczosReorthogType(reorthog)Set the type of reorthogonalization used during the Lanczos iteration.
setLeftInitialSpace(space)Set a left initial space from which the eigensolver starts to iterate.
setLyapIIRanks([rkc, rkl])Set the ranks used in the solution of the Lyapunov equation.
setMonitor(monitor[, args, kargs])Append a monitor function to the list of monitors.
setOperators(A[, B])Set the matrices associated with the eigenvalue problem.
setOptionsPrefix([prefix])Set the prefix used for searching for all EPS options in the database.
setPowerShiftType(shift)Set the type of shifts used during the power iteration.
setProblemType(problem_type)Set the type of the eigenvalue problem.
setPurify([purify])Set (toggle) eigenvector purification.
setRG(rg)Set a region object associated to the eigensolver.
setRQCGReset(nrest)Set the reset parameter of the RQCG iteration.
setST(st)Set a spectral transformation object associated to the eigensolver.
setStoppingTest(stopping[, args, kargs])Set when to stop the outer iteration of the eigensolver.
setTarget(target)Set the value of the target.
setThreshold(thres[, rel])Set the threshold used in the threshold stopping test.
setTolerances([tol, max_it])Set the tolerance and max.
setTrackAll(trackall)Set if the solver must compute the residual of all approximate eigenpairs.
setTrueResidual(trueres)Set if the solver must compute the true residual explicitly or not.
setTwoSided(twosided)Set to use a two-sided variant that also computes left eigenvectors.
setType(eps_type)Set the particular solver to be used in the EPS object.
setUp()Set up all the internal data structures.
setWhichEigenpairs(which)Set which portion of the spectrum is to be sought.
solve()Solve the eigensystem.
updateKrylovSchurSubcommMats([s, a, Au, t, ...])Update the eigenproblem matrices stored internally in the communicator.
valuesView([viewer])Display the computed eigenvalues in a viewer.
vectorsView([viewer])Output computed eigenvectors to a viewer.
view([viewer])Print the EPS data structure.
Attributes Summary
The basis vectors (BV) object associated.
The direct solver (DS) object associated.
The type of extraction technique to be employed.
The maximum iteration count.
The type of the eigenvalue problem.
Eigenvector purification.
The region (RG) object associated.
The spectral transformation (ST) object associated.
The value of the target.
The tolerance.
Compute the residual norm of all approximate eigenpairs.
Compute the true residual explicitly.
Two-sided that also computes left eigenvectors.
The portion of the spectrum to be sought.
Methods Documentation
- appendOptionsPrefix(prefix=None)#
Append to the prefix used for searching for all EPS options in the database.
Logically collective.
- cancelMonitor()#
Clear all monitors for an
EPSobject.Logically collective.
Source code at slepc4py/SLEPc/EPS.pyx:1448
- Return type:
- computeError(i, etype=None)#
Compute the error associated with the i-th computed eigenpair.
Collective.
Compute the error (based on the residual norm) associated with the i-th computed eigenpair.
- Parameters:
- Returns:
The error bound, computed in various ways from the residual norm \(\|Ax-kBx\|_2\) where \(k\) is the eigenvalue and \(x\) is the eigenvector.
- Return type:
Notes
The index
ishould be a value between0andnconv-1(seegetConverged()).
- create(comm=None)#
Create the EPS object.
Collective.
- destroy()#
Destroy the EPS object.
Collective.
Source code at slepc4py/SLEPc/EPS.pyx:314
- Return type:
- errorView(etype=None, viewer=None)#
Display the errors associated with the computed solution.
Collective.
Display the errors and the eigenvalues.
- Parameters:
viewer (petsc4py.PETSc.Viewer | None) – Visualization context; if not provided, the standard output is used.
- Return type:
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_DETAILthen a table with eigenvalues and corresponding errors is printed.
- getArnoldiDelayed()#
Get the type of reorthogonalization used during the Arnoldi iteration.
Not collective.
- Returns:
True if delayed reorthogonalization is to be used.
- Return type:
- getBV()#
Get the basis vector objects associated to the eigensolver.
Not collective.
- Returns:
The basis vectors context.
- Return type:
- getBalance()#
Get the balancing type used by the EPS, and the associated parameters.
Not collective.
- Returns:
- Return type:
- getCISSExtraction()#
Get the extraction technique used in the CISS solver.
Not collective.
- Returns:
The extraction technique.
- Return type:
- getCISSKSPs()#
Get the array of linear solver objects associated with the CISS solver.
Not collective.
- Returns:
The linear solver objects.
- Return type:
Notes
The number of
petsc4py.PETSc.KSPsolvers 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.
- getCISSQuadRule()#
Get the quadrature rule used in the CISS solver.
Not collective.
- Returns:
The quadrature rule.
- Return type:
- getCISSRefinement()#
Get the values of various refinement parameters in the CISS solver.
Not collective.
- Returns:
- Return type:
- getCISSSizes()#
Get the values of various size parameters in the CISS solver.
Not collective.
- Returns:
- Return type:
- getCISSThreshold()#
Get the values of various threshold parameters in the CISS solver.
Not collective.
- Returns:
- Return type:
- getCISSUseST()#
Get the flag indicating the use of the
STobject in the CISS solver.Not collective.
- getConverged()#
Get the number of converged eigenpairs.
Not collective.
- Returns:
Number of converged eigenpairs.
- Return type:
Notes
This function should be called after
solve()has finished.
- getConvergedReason()#
Get the reason why the
solve()iteration was stopped.Not collective.
- Returns:
Negative value indicates diverged, positive value converged.
- Return type:
- getConvergenceTest()#
Get how to compute the error estimate used in the convergence test.
Not collective.
- Returns:
The method used to compute the error estimate used in the convergence test.
- Return type:
- getDS()#
Get the direct solver associated to the eigensolver.
Not collective.
- Returns:
The direct solver context.
- Return type:
- getDimensions()#
Get number of eigenvalues to compute and the dimension of the subspace.
Not collective.
- Returns:
- Return type:
- getEigenpair(i, Vr=None, Vi=None)#
Get the i-th solution of the eigenproblem as computed by
solve().Collective.
The solution consists of both the eigenvalue and the eigenvector.
- Parameters:
- Returns:
e – The computed eigenvalue. It will be a real variable in case of a Hermitian or generalized Hermitian eigenproblem. Otherwise it will be a complex variable (possibly with zero imaginary part).
- Return type:
Notes
The index
ishould be a value between0andnconv-1(seegetConverged()). Eigenpairs are indexed according to the ordering criterion established withsetWhichEigenpairs().
- getEigenvalue(i)#
Get the i-th eigenvalue as computed by
solve().Not collective.
- Parameters:
i (int) – Index of the solution to be obtained.
- Returns:
The computed eigenvalue. It will be a real variable in case of a Hermitian or generalized Hermitian eigenproblem. Otherwise it will be a complex variable (possibly with zero imaginary part).
- Return type:
Notes
The index
ishould be a value between0andnconv-1(seegetConverged()). Eigenpairs are indexed according to the ordering criterion established withsetWhichEigenpairs().
- getEigenvector(i, Vr=None, Vi=None)#
Get the i-th eigenvector as computed by
solve().Collective.
- Parameters:
- Return type:
Notes
The index
ishould be a value between0andnconv-1(seegetConverged()). Eigenpairs are indexed according to the ordering criterion established withsetWhichEigenpairs().
- getErrorEstimate(i)#
Get the error estimate associated to the i-th computed eigenpair.
Not collective.
- Parameters:
i (int) – Index of the solution to be considered.
- Returns:
Error estimate.
- Return type:
Notes
This is the error estimate used internally by the eigensolver. The actual error bound can be computed with
computeError().
- getExtraction()#
Get the extraction type used by the EPS object.
Not collective.
- Returns:
The method of extraction.
- Return type:
- getGDBOrth()#
Get the orthogonalization used in the search subspace.
Not collective.
Get the orthogonalization used in the search subspace in case of generalized Hermitian problems.
- Returns:
Whether to B-orthogonalize the search subspace.
- Return type:
- getGDBlockSize()#
Get the number of vectors to be added to the searching space.
Not collective.
Get the number of vectors to be added to the searching space in every iteration.
- Returns:
The number of vectors added to the search space in every iteration.
- Return type:
- getGDDoubleExpansion()#
Get a flag indicating whether the double expansion variant is active.
Not collective.
Get a flag indicating whether the double expansion variant has been activated or not.
- Returns:
True if using double expansion.
- Return type:
- getGDInitialSize()#
Get the initial size of the searching space.
Not collective.
- Returns:
The number of vectors of the initial searching subspace.
- Return type:
- getGDKrylovStart()#
Get a flag indicating if the search subspace is started with a Krylov basis.
Not collective.
- Returns:
True if starting the search subspace with a Krylov basis.
- Return type:
- getGDRestart()#
Get the number of vectors of the search space after restart.
Not collective.
Get the number of vectors of the search space after restart and the number of vectors saved from the previous iteration.
- Returns:
- Return type:
- getInterval()#
Get the computational interval for spectrum slicing.
Not collective.
- Returns:
- Return type:
Notes
If the interval was not set by the user, then zeros are returned.
- getInvariantSubspace()#
Get an orthonormal basis of the computed invariant subspace.
Collective.
- Returns:
Basis of the invariant subspace.
- Return type:
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
XofA` satisfies ``A xinXfor allxinX(a similar definition applies for generalized eigenproblems).
- getIterationNumber()#
Get the current iteration number.
Not collective.
If the call to
solve()is complete, then it returns the number of iterations carried out by the solution method.- Returns:
Iteration number.
- Return type:
- getJDBOrth()#
Get the orthogonalization used in the search subspace.
Not collective.
Get the orthogonalization used in the search subspace in case of generalized Hermitian problems.
- Returns:
Whether to B-orthogonalize the search subspace.
- Return type:
- getJDBlockSize()#
Get the number of vectors to be added to the searching space.
Not collective.
Get the number of vectors to be added to the searching space in every iteration.
- Returns:
The number of vectors added to the search space in every iteration.
- Return type:
- getJDConstCorrectionTol()#
Get the flag indicating if the dynamic stopping is being used.
Not collective.
Get the flag indicating if the dynamic stopping is being used for solving the correction equation.
- Returns:
True if the dynamic stopping criterion is not being used.
- Return type:
- getJDFix()#
Get the threshold for changing the target in the correction equation.
Not collective.
- Returns:
The threshold for changing the target.
- Return type:
- getJDInitialSize()#
Get the initial size of the searching space.
Not collective.
- Returns:
The number of vectors of the initial searching subspace.
- Return type:
- getJDKrylovStart()#
Get a flag indicating if the search subspace is started with a Krylov basis.
Not collective.
- Returns:
True if starting the search subspace with a Krylov basis.
- Return type:
- getJDRestart()#
Get the number of vectors of the search space after restart.
Not collective.
Get the number of vectors of the search space after restart and the number of vectors saved from the previous iteration.
- Returns:
- Return type:
- getKrylovSchurBSEType()#
Get the method used for BSE structured eigenproblems (Krylov-Schur).
Not collective.
- Returns:
The BSE method.
- Return type:
- getKrylovSchurDetectZeros()#
Get the flag that enforces zero detection in spectrum slicing.
Not collective.
- Returns:
The zero detection flag.
- Return type:
- getKrylovSchurDimensions()#
Get the dimensions used for each subsolve step (spectrum slicing).
Not collective.
Get the dimensions used for each subsolve step in case of doing spectrum slicing for a computational interval.
- Returns:
- Return type:
- getKrylovSchurInertias()#
Get the values of the shifts and their corresponding inertias.
Not collective.
Get the values of the shifts and their corresponding inertias in case of doing spectrum slicing for a computational interval.
- Returns:
- Return type:
- getKrylovSchurKSP()#
Get the linear solver object associated with the internal
EPSobject.Collective.
Get the linear solver object associated with the internal
EPSobject in case of doing spectrum slicing for a computational interval.- Returns:
The linear solver object.
- Return type:
- getKrylovSchurLocking()#
Get the locking flag used in the Krylov-Schur method.
Not collective.
- Returns:
The locking flag.
- Return type:
- getKrylovSchurPartitions()#
Get the number of partitions of the communicator (spectrum slicing).
Not collective.
- Returns:
The number of partitions.
- Return type:
- getKrylovSchurRestart()#
Get the restart parameter used in the Krylov-Schur method.
Not collective.
- Returns:
The number of vectors to be kept at restart.
- Return type:
- getKrylovSchurSubcommInfo()#
Get information related to the case of doing spectrum slicing.
Collective on the subcommunicator (if v is given).
Get information related to the case of doing spectrum slicing for a computational interval with multiple communicators.
- Returns:
k (
int) – Number of the subinterval for the calling process.n (
int) – Number of eigenvalues found in the k-th subinterval.v (
petsc4py.PETSc.Vec) – A vector owned by processes in the subcommunicator with dimensions compatible for locally computed eigenvectors.
- Return type:
Notes
This function is only available for spectrum slicing runs.
The returned Vec should be destroyed by the user.
- getKrylovSchurSubcommMats()#
Get the eigenproblem matrices stored in the subcommunicator.
Collective on the subcommunicator.
Get the eigenproblem matrices stored internally in the subcommunicator to which the calling process belongs.
- Returns:
A (
petsc4py.PETSc.Mat) – The matrix associated with the eigensystem.B (
petsc4py.PETSc.Mat) – The second matrix in the case of generalized eigenproblems.
- Return type:
tuple[petsc4py.PETSc.Mat, petsc4py.PETSc.Mat] | tuple[petsc4py.PETSc.Mat, None]
Notes
This is the analog of
getOperators(), but returns the matrices distributed differently (in the subcommunicator rather than in the parent communicator).These matrices should not be modified by the user.
- getKrylovSchurSubcommPairs(i, V)#
Get the i-th eigenpair stored in the multi-communicator of the process.
Collective on the subcommunicator (if v is given).
Get the i-th eigenpair stored internally in the multi-communicator to which the calling process belongs.
- Parameters:
- Returns:
The computed eigenvalue.
- Return type:
Notes
The index
ishould be a value between0andn-1, wherenis the number of vectors in the local subinterval, seegetKrylovSchurSubcommInfo().
- getKrylovSchurSubintervals()#
Get the points that delimit the subintervals.
Not collective.
Get the points that delimit the subintervals used in spectrum slicing with several partitions.
- Returns:
Real values specifying subintervals
- Return type:
- getLOBPCGBlockSize()#
Get the block size used in the LOBPCG method.
Not collective.
- Returns:
The block size.
- Return type:
- getLOBPCGLocking()#
Get the locking flag used in the LOBPCG method.
Not collective.
- Returns:
The locking flag.
- Return type:
- getLOBPCGRestart()#
Get the restart parameter used in the LOBPCG method.
Not collective.
- Returns:
The restart parameter.
- Return type:
- getLanczosReorthogType()#
Get the type of reorthogonalization used during the Lanczos iteration.
Not collective.
- Returns:
The type of reorthogonalization.
- Return type:
- getLeftEigenvector(i, Wr=None, Wi=None)#
Get the i-th left eigenvector as computed by
solve().Collective.
- Parameters:
- Return type:
Notes
The index
ishould be a value between0andnconv-1(seegetConverged()). Eigensolutions are indexed according to the ordering criterion established withsetWhichEigenpairs().Left eigenvectors are available only if the twosided flag was set with
setTwoSided().
- getLyapIIRanks()#
Get the rank values used for the Lyapunov step.
Not collective.
- Returns:
- Return type:
- getMonitor()#
Get the list of monitor functions.
Source code at slepc4py/SLEPc/EPS.pyx:1444
- Return type:
- getOperators()#
Get the matrices associated with the eigenvalue problem.
Collective.
- Returns:
A (
petsc4py.PETSc.Mat) – The matrix associated with the eigensystem.B (
petsc4py.PETSc.Mat) – The second matrix in the case of generalized eigenproblems.
- Return type:
tuple[petsc4py.PETSc.Mat, petsc4py.PETSc.Mat] | tuple[petsc4py.PETSc.Mat, None]
- getOptionsPrefix()#
Get the prefix used for searching for all EPS options in the database.
Not collective.
- Returns:
The prefix string set for this EPS object.
- Return type:
- getPowerShiftType()#
Get the type of shifts used during the power iteration.
Not collective.
- Returns:
The type of shift.
- Return type:
- getProblemType()#
Get the problem type from the EPS object.
Not collective.
- Returns:
The problem type that was previously set.
- Return type:
- getPurify()#
Get the flag indicating whether purification is activated or not.
Not collective.
- Returns:
Whether purification is activated or not.
- Return type:
- getRG()#
Get the region object associated to the eigensolver.
Not collective.
- Returns:
The region context.
- Return type:
- getRQCGReset()#
Get the reset parameter used in the RQCG method.
Not collective.
- Returns:
The number of iterations between resets.
- Return type:
- getST()#
Get the spectral transformation object associated to the eigensolver.
Not collective.
- Returns:
The spectral transformation.
- Return type:
- getStoppingTest()#
Get the stopping function.
Not collective.
Source code at slepc4py/SLEPc/EPS.pyx:1362
- Return type:
- getTarget()#
Get the value of the target.
Not collective.
- Returns:
The value of the target.
- Return type:
Notes
If the target was not set by the user, then zero is returned.
- getThreshold()#
Get the threshold used in the threshold stopping test.
Not collective.
- Returns:
- Return type:
- getTolerances()#
Get the tolerance and max. iter. count used for convergence tests.
Not collective.
Get the tolerance and iteration limit used by the default EPS convergence tests.
- Returns:
- Return type:
- getTrackAll()#
Get the flag indicating if all residual norms must be computed or not.
Not collective.
- Returns:
Whether the solver compute all residuals or not.
- Return type:
- getTrueResidual()#
Get the flag indicating if true residual must be computed explicitly.
Not collective.
- Returns:
Whether the solver compute all residuals or not.
- Return type:
- getTwoSided()#
Get the flag indicating if a two-sided variant of the algorithm is being used.
Not collective.
- Returns:
Whether the two-sided variant is to be used or not.
- Return type:
- getType()#
Get the EPS type of this object.
Not collective.
- Returns:
The solver currently being used.
- Return type:
- getWhichEigenpairs()#
Get which portion of the spectrum is to be sought.
Not collective.
- Returns:
The portion of the spectrum to be sought by the solver.
- Return type:
- isGeneralized()#
Tell if the EPS object corresponds to a generalized eigenproblem.
Not collective.
- Returns:
True if two matrices were set with
setOperators().- Return type:
- isHermitian()#
Tell if the EPS object corresponds to a Hermitian eigenproblem.
Not collective.
- Returns:
True if the problem type set with
setProblemType()was Hermitian.- Return type:
- isPositive()#
Eigenproblem requiring a positive (semi-) definite matrix \(B\).
Not collective.
Tell if the EPS corresponds to an eigenproblem requiring a positive (semi-) definite matrix \(B\).
- Returns:
True if the problem type set with
setProblemType()was positive.- Return type:
- isStructured()#
Tell if the EPS object corresponds to a structured eigenvalue problem.
Not collective.
- Returns:
True if the problem type set with
setProblemType()was structured.- Return type:
- reset()#
Reset the EPS object.
Collective.
Source code at slepc4py/SLEPc/EPS.pyx:324
- Return type:
- setArbitrarySelection(arbitrary, args=None, kargs=None)#
Set an arbitrary selection criterion function.
Logically collective.
Set a function to look for eigenvalues according to an arbitrary selection criterion. This criterion can be based on a computation involving the current eigenvector approximation.
- setArnoldiDelayed(delayed)#
Set (toggle) delayed reorthogonalization in the Arnoldi iteration.
Logically collective.
Notes
This call is only relevant if the type was set to
EPS.Type.ARNOLDIwithsetType().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.
- setBV(bv)#
Set a basis vectors object associated to the eigensolver.
Collective.
- setBalance(balance=None, iterations=None, cutoff=None)#
Set the balancing technique to be used by the eigensolver.
Logically collective.
Set the balancing technique to be used by the eigensolver, and some parameters associated to it.
- Parameters:
- Return type:
- setCISSExtraction(extraction)#
Set the extraction technique used in the CISS solver.
Logically collective.
- Parameters:
extraction (CISSExtraction) – The extraction technique.
- Return type:
- setCISSQuadRule(quad)#
Set the quadrature rule used in the CISS solver.
Logically collective.
- Parameters:
quad (CISSQuadRule) – The quadrature rule.
- Return type:
- setCISSRefinement(inner=None, blsize=None)#
Set the values of various refinement parameters in the CISS solver.
Logically collective.
- Parameters:
- Return type:
- setCISSSizes(ip=None, bs=None, ms=None, npart=None, bsmax=None, realmats=False)#
Set the values of various size parameters in the CISS solver.
Logically collective.
- Parameters:
- Return type:
Notes
The default number of partitions is 1. This means the internal
petsc4py.PETSc.KSPobject is shared among all processes of theEPScommunicator. Otherwise, the communicator is split into npart communicators, so thatnpartpetsc4py.PETSc.KSPsolves proceed simultaneously.
- setCISSThreshold(delta=None, spur=None)#
Set the values of various threshold parameters in the CISS solver.
Logically collective.
- Parameters:
- Return type:
- setCISSUseST(usest)#
Set a flag indicating that the CISS solver will use the
STobject.Logically collective.
Set a flag indicating that the CISS solver will use the
STobject for the linear solves.
- setConvergenceTest(conv)#
Set how to compute the error estimate used in the convergence test.
Logically collective.
- Parameters:
conv (Conv) – The method used to compute the error estimate used in the convergence test.
- Return type:
- setDS(ds)#
Set a direct solver object associated to the eigensolver.
Collective.
- setDeflationSpace(space)#
Add vectors to the basis of the deflation space.
Collective.
- Parameters:
space (Vec | list[Vec]) – Set of basis vectors to be added to the deflation space.
- Return type:
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 vectors do not need to be mutually orthonormal, since they are explicitly orthonormalized internally.
These vectors do not persist from one
solve()call to the other, so the deflation space should be set every time.
- setDimensions(nev=None, ncv=None, mpd=None)#
Set number of eigenvalues to compute and the dimension of the subspace.
Logically collective.
- Parameters:
- Return type:
Notes
Use
DECIDEforncvandmpdto assign a reasonably good value, which is dependent on the solution method.The parameters
ncvandmpdare intimately related, so that the user is advised to set one of them at most. Normal usage is the following:In cases where
nevis small, the user setsncv(a reasonable default is 2 *nev).In cases where
nevis large, the user setsmpd.
The value of
ncvshould always be betweennevand (nev+mpd), typicallyncv=nev+mpd. Ifnevis not too large,mpd=nevis a reasonable choice, otherwise a smaller value should be used.
- setEigenvalueComparison(comparison, args=None, kargs=None)#
Set an eigenvalue comparison function.
Logically collective.
Specify the eigenvalue comparison function when
setWhichEigenpairs()is set toEPS.Which.USER.
- setExtraction(extraction)#
Set the extraction type used by the EPS object.
Logically collective.
- Parameters:
extraction (Extraction) – The extraction method to be used by the solver.
- Return type:
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()#
Set EPS options from the options database.
Collective.
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
-helpoption.Source code at slepc4py/SLEPc/EPS.pyx:445
- Return type:
- setGDBOrth(borth)#
Set the orthogonalization that will be used in the search subspace.
Logically collective.
Set the orthogonalization that will be used in the search subspace in case of generalized Hermitian problems.
- setGDBlockSize(bs)#
Set the number of vectors to be added to the searching space.
Logically collective.
Set the number of vectors to be added to the searching space in every iteration.
- Parameters:
bs (int) – The number of vectors added to the search space in every iteration.
- Return type:
- setGDDoubleExpansion(doubleexp)#
Set that the search subspace is expanded with double expansion.
Logically collective.
Set a variant where the search subspace is expanded with \(K [A x, B x]\) (double expansion) instead of the classic \(K r\), where K is the preconditioner, x the selected approximate eigenvector and \(r\) its associated residual vector.
- setGDInitialSize(initialsize)#
Set the initial size of the searching space.
Logically collective.
- Parameters:
initialsize (int) – The number of vectors of the initial searching subspace.
- Return type:
- setGDKrylovStart(krylovstart=True)#
Set (toggle) starting the search subspace with a Krylov basis.
Logically collective.
- Parameters:
krylovstart (bool) – True if starting the search subspace with a Krylov basis.
- Return type:
- setGDRestart(minv=None, plusk=None)#
Set the number of vectors of the search space after restart.
Logically collective.
Set the number of vectors of the search space after restart and the number of vectors saved from the previous iteration.
- Parameters:
- Return type:
- setInitialSpace(space)#
Set the initial space from which the eigensolver starts to iterate.
Collective.
Notes
Some solvers start to iterate on a single vector (initial vector). In that case, the other vectors are ignored.
In contrast to
setDeflationSpace(), these vectors do not persist from onesolve()call to the other, so the initial space should be set every time.The vectors do not need to be mutually orthonormal, since they are explicitly orthonormalized internally.
Common usage of this function is when the user can provide a rough approximation of the wanted eigenspace. Then, convergence may be faster.
- setInterval(inta, intb)#
Set the computational interval for spectrum slicing.
Logically collective.
- Parameters:
- Return type:
Notes
Spectrum slicing is a technique employed for computing all eigenvalues of symmetric eigenproblems in a given interval. This function provides the interval to be considered. It must be used in combination with
EPS.Which.ALL, seesetWhichEigenpairs().
- setJDBOrth(borth)#
Set the orthogonalization that will be used in the search subspace.
Logically collective.
Set the orthogonalization that will be used in the search subspace in case of generalized Hermitian problems.
- setJDBlockSize(bs)#
Set the number of vectors to be added to the searching space.
Logically collective.
Set the number of vectors to be added to the searching space in every iteration.
- Parameters:
bs (int) – The number of vectors added to the search space in every iteration.
- Return type:
- setJDConstCorrectionTol(constant)#
Deactivate the dynamic stopping criterion.
Logically collective.
Deactivate the dynamic stopping criterion that sets the
petsc4py.PETSc.KSPrelative tolerance to0.5**i, whereiis the number ofEPSiterations from the last converged value.- Parameters:
constant (bool) – If False, the
petsc4py.PETSc.KSPrelative tolerance is set to0.5**i.- Return type:
- setJDFix(fix)#
Set the threshold for changing the target in the correction equation.
Logically collective.
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.
- setJDInitialSize(initialsize)#
Set the initial size of the searching space.
Logically collective.
- Parameters:
initialsize (int) – The number of vectors of the initial searching subspace.
- Return type:
- setJDKrylovStart(krylovstart=True)#
Set (toggle) starting the search subspace with a Krylov basis.
Logically collective.
- Parameters:
krylovstart (bool) – True if starting the search subspace with a Krylov basis.
- Return type:
- setJDRestart(minv=None, plusk=None)#
Set the number of vectors of the search space after restart.
Logically collective.
Set the number of vectors of the search space after restart and the number of vectors saved from the previous iteration.
- Parameters:
- Return type:
- setKrylovSchurBSEType(bse)#
Set the Krylov-Schur variant used for BSE structured eigenproblems.
Logically collective.
- Parameters:
bse (KrylovSchurBSEType) – The BSE method.
- Return type:
Notes
This call is only relevant if the type was set to
EPS.Type.KRYLOVSCHURwithsetType()and the problem type toEPS.ProblemType.BSEwithsetProblemType().
- setKrylovSchurDetectZeros(detect)#
Set the flag that enforces zero detection in spectrum slicing.
Logically collective.
Set a flag to enforce the detection of zeros during the factorizations throughout the spectrum slicing computation.
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, especially when several partitions are being used. This feature currently requires an external package for factorizations with support for zero detection, e.g. MUMPS.
- setKrylovSchurDimensions(nev=None, ncv=None, mpd=None)#
Set the dimensions used for each subsolve step (spectrum slicing).
Logically collective.
Set 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:
- Return type:
- setKrylovSchurLocking(lock)#
Set (toggle) locking/non-locking variants of the Krylov-Schur method.
Logically collective.
Notes
The default is to lock converged eigenpairs when the method restarts. This behavior can be changed so that all directions are kept in the working subspace even if already converged to working accuracy (the non-locking variant).
- setKrylovSchurPartitions(npart)#
Set the number of partitions of the communicator (spectrum slicing).
Logically collective.
Set the number of partitions for the case of doing spectrum slicing for a computational interval with the communicator split in several sub-communicators.
Notes
By default, npart=1 so all processes in the communicator participate in the processing of the whole interval. If npart>1 then the interval is divided into npart subintervals, each of them being processed by a subset of processes.
- setKrylovSchurRestart(keep)#
Set the restart parameter for the Krylov-Schur method.
Logically collective.
It is the proportion of basis vectors that must be kept after restart.
Notes
Allowed values are in the range [0.1,0.9]. The default is 0.5.
- setKrylovSchurSubintervals(subint)#
Set the subinterval boundaries.
Logically collective.
Set the subinterval boundaries for spectrum slicing with a computational interval.
Notes
This function must be called after setKrylovSchurPartitions(). For npart partitions, the argument subint must contain npart+1 real values sorted in ascending order: subint_0, subint_1, …, subint_npart, where the first and last values must coincide with the interval endpoints set with EPSSetInterval(). The subintervals are then defined by two consecutive points: [subint_0,subint_1], [subint_1,subint_2], and so on.
- setLOBPCGBlockSize(bs)#
Set the block size of the LOBPCG method.
Logically collective.
- setLOBPCGLocking(lock)#
Toggle between locking and non-locking (LOBPCG method).
Logically collective.
Notes
This flag refers to soft locking (converged vectors within the current block iterate), since hard locking is always used (when nev is larger than the block size).
- setLOBPCGRestart(restart)#
Set the restart parameter for the LOBPCG method.
Logically collective.
The meaning of this parameter is the proportion of vectors within the current block iterate that must have converged in order to force a restart with hard locking.
- Parameters:
restart (float) – The percentage of the block of vectors to force a restart.
- Return type:
Notes
Allowed values are in the range [0.1,1.0]. The default is 0.9.
- setLanczosReorthogType(reorthog)#
Set the type of reorthogonalization used during the Lanczos iteration.
Logically collective.
- Parameters:
reorthog (LanczosReorthogType) – The type of reorthogonalization.
- Return type:
Notes
This call is only relevant if the type was set to
EPS.Type.LANCZOSwithsetType().
- setLeftInitialSpace(space)#
Set a left initial space from which the eigensolver starts to iterate.
Collective.
Notes
Left initial vectors are used to initiate the left search space in two-sided eigensolvers. Users should pass here an approximation of the left eigenspace, if available.
The same comments in
setInitialSpace()are applicable here.
- setLyapIIRanks(rkc=None, rkl=None)#
Set the ranks used in the solution of the Lyapunov equation.
Logically collective.
- Parameters:
- Return type:
- setMonitor(monitor, args=None, kargs=None)#
Append a monitor function to the list of monitors.
Logically collective.
- setOperators(A, B=None)#
Set the matrices associated with the eigenvalue problem.
Collective.
- Parameters:
- Return type:
- setOptionsPrefix(prefix=None)#
Set the prefix used for searching for all EPS options in the database.
Logically collective.
- Parameters:
prefix (str | None) – The prefix string to prepend to all EPS option requests.
- Return type:
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_")
- setPowerShiftType(shift)#
Set the type of shifts used during the power iteration.
Logically collective.
This can be used to emulate the Rayleigh Quotient Iteration (RQI) method.
- Parameters:
shift (PowerShiftType) – The type of shift.
- Return type:
Notes
This call is only relevant if the type was set to
EPS.Type.POWERwithsetType().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.RAYLEIGHorEPS.PowerShiftType.WILKINSON). In this case, the iteration behaves rather like a cubic converging method as RQI.
- setProblemType(problem_type)#
Set the type of the eigenvalue problem.
Logically collective.
- Parameters:
problem_type (ProblemType) – The problem type to be set.
- Return type:
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.
- setPurify(purify=True)#
Set (toggle) eigenvector purification.
Logically collective.
- setRG(rg)#
Set a region object associated to the eigensolver.
Collective.
- setRQCGReset(nrest)#
Set the reset parameter of the RQCG iteration.
Logically collective.
Every nrest iterations the solver performs a Rayleigh-Ritz projection step.
- setST(st)#
Set a spectral transformation object associated to the eigensolver.
Collective.
- setStoppingTest(stopping, args=None, kargs=None)#
Set when to stop the outer iteration of the eigensolver.
Logically collective.
- setTarget(target)#
Set the value of the target.
Logically collective.
Notes
The target is a scalar value used to determine the portion of the spectrum of interest. It is used in combination with
setWhichEigenpairs().
- setThreshold(thres, rel=False)#
Set the threshold used in the threshold stopping test.
Logically collective.
- Parameters:
- Return type:
Notes
This function internally sets a special stopping test based on the threshold, where eigenvalues are computed in sequence until one of the computed eigenvalues is below/above the threshold (depending on whether largest or smallest eigenvalues are computed).
- setTolerances(tol=None, max_it=None)#
Set the tolerance and max. iter. used by the default EPS convergence tests.
Logically collective.
- Parameters:
- Return type:
Notes
Use
DECIDEfor maxits to assign a reasonably good value, which is dependent on the solution method.
- setTrackAll(trackall)#
Set if the solver must compute the residual of all approximate eigenpairs.
Logically collective.
- setTrueResidual(trueres)#
Set if the solver must compute the true residual explicitly or not.
Logically collective.
- setTwoSided(twosided)#
Set to use a two-sided variant that also computes left eigenvectors.
Logically collective.
- setType(eps_type)#
Set the particular solver to be used in the EPS object.
Logically collective.
Notes
See
EPS.Typefor available methods. The default isEPS.Type.KRYLOVSCHUR. Normally, it is best to usesetFromOptions()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()#
Set up all the internal data structures.
Collective.
Set 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.Source code at slepc4py/SLEPc/EPS.pyx:1459
- Return type:
- setWhichEigenpairs(which)#
Set which portion of the spectrum is to be sought.
Logically collective.
- Parameters:
which (Which) – The portion of the spectrum to be sought by the solver.
- Return type:
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_IMAGINARYandEPS.Which.SMALLEST_IMAGINARYuse the absolute value of the imaginary part for eigenvalue selection.
- solve()#
Solve the eigensystem.
Collective.
Source code at slepc4py/SLEPc/EPS.pyx:1476
- Return type:
- updateKrylovSchurSubcommMats(s=1.0, a=1.0, Au=None, t=1.0, b=1.0, Bu=None, structure=None, globalup=False)#
Update the eigenproblem matrices stored internally in the communicator.
Collective.
Update the eigenproblem matrices stored internally in the subcommunicator to which the calling process belongs.
- Parameters:
s (Scalar) – Scalar that multiplies the existing A matrix.
a (Scalar) – Scalar used in the axpy operation on A.
Au (petsc4py.PETSc.Mat | None) – The matrix used in the axpy operation on A.
t (Scalar) – Scalar that multiplies the existing B matrix.
b (Scalar) – Scalar used in the axpy operation on B.
Bu (petsc4py.PETSc.Mat | None) – The matrix used in the axpy operation on B.
structure (petsc4py.PETSc.Mat.Structure | None) – Either same, different, or a subset of the non-zero sparsity pattern.
globalup (bool) – Whether global matrices must be updated or not.
- Return type:
Notes
This function modifies the eigenproblem matrices at subcommunicator level, and optionally updates the global matrices in the parent communicator. The updates are expressed as \(A \leftarrow s A + a Au\), \(B \leftarrow t B + b Bu\).
It is possible to update one of the matrices, or both.
The matrices
AuandBumust be equal in all subcommunicators.The
structureflag is passed to thepetsc4py.PETSc.Mat.axpyoperations to perform the updates.If
globalupis True, communication is carried out to reconstruct the updated matrices in the parent communicator.
- valuesView(viewer=None)#
Display the computed eigenvalues in a viewer.
Collective.
- vectorsView(viewer=None)#
Output computed eigenvectors to a viewer.
Collective.
- view(viewer=None)#
Print the EPS data structure.
Collective.
Attributes Documentation
- bv#
The basis vectors (BV) object associated.
- ds#
The direct solver (DS) object associated.
- extraction#
The type of extraction technique to be employed.
- max_it#
The maximum iteration count.
- problem_type#
The type of the eigenvalue problem.
- purify#
Eigenvector purification.
- rg#
The region (RG) object associated.
- st#
The spectral transformation (ST) object associated.
- target#
The value of the target.
- tol#
The tolerance.
- track_all#
Compute the residual norm of all approximate eigenpairs.
- true_residual#
Compute the true residual explicitly.
- two_sided#
Two-sided that also computes left eigenvectors.
- which#
The portion of the spectrum to be sought.