slepc4py.SLEPc.LME#
- class slepc4py.SLEPc.LME#
Bases:
ObjectLinear Matrix Equation.
Linear Matrix Equation (
LME) is the object provided by slepc4py for solving linear matrix equations such as Lyapunov or Sylvester where the solution has low rank.Enumerations
LME convergence reasons.
LME problem type.
LME type.
Methods Summary
appendOptionsPrefix([prefix])Append to the prefix used for searching in the database.
Clear all monitors for an
LMEobject.Compute the error associated with the last equation solved.
create([comm])Create the LME object.
destroy()Destroy the LME object.
getBV()Get the basis vector object associated to the LME object.
Get the coefficient matrices of the matrix equation.
Get the reason why the
solve()iteration was stopped.Get the dimension of the subspace used by the solver.
Get the error estimate obtained during the solve.
Get if
solve()generates an error if the solver does not converge.Get the current iteration number.
Get the list of monitor functions.
Get the prefix used for searching for all LME options in the database.
Get the LME problem type of this object.
getRHS()Get the right-hand side of the matrix equation.
Get the solution of the matrix equation.
Get the tolerance and maximum iteration count.
getType()Get the LME type of this object.
reset()Reset the LME object.
setBV(bv)Set a basis vector object to the LME object.
setCoefficients(A[, B, D, E])Set the coefficient matrices.
setDimensions(ncv)Set the dimension of the subspace to be used by the solver.
setErrorIfNotConverged([flg])Set
solve()to generate an error if the solver has not converged.Set LME options from the options database.
setMonitor(monitor[, args, kargs])Append a monitor function to the list of monitors.
setOptionsPrefix([prefix])Set the prefix used for searching for all LME options in the database.
setProblemType(lme_problem_type)Set the LME problem type of this object.
setRHS(C)Set the right-hand side of the matrix equation.
setSolution([X])Set the placeholder for the solution of the matrix equation.
setTolerances([tol, max_it])Set the tolerance and maximum iteration count.
setType(lme_type)Set the particular solver to be used in the LME object.
setUp()Set up all the internal necessary data structures.
solve()Solve the linear matrix equation.
view([viewer])Print the LME data structure.
Attributes Summary
The basis vectors (
BV) object associated to the LME object.The math function (
FN) object associated to the LME object.The maximum iteration count used by the LME convergence tests.
The tolerance value used by the LME convergence tests.
Methods Documentation
- appendOptionsPrefix(prefix=None)#
Append to the prefix used for searching in the database.
Logically collective.
Append to the prefix used for searching for all LME options in the database.
- cancelMonitor()#
Clear all monitors for an
LMEobject.Logically collective.
See also
Source code at slepc4py/SLEPc/LME.pyx:713
- Return type:
- computeError()#
Compute the error associated with the last equation solved.
Collective.
- Returns:
The error.
- Return type:
Notes
The error is based on the residual norm.
This function is not scalable (in terms of memory or parallel communication), so it should not be called except in the case of small problem size. For large equations, use
getErrorEstimate().See also
- create(comm=None)#
Create the LME object.
Collective.
- Parameters:
comm (Comm | None) – MPI communicator. If not provided, it defaults to all processes.
- Return type:
See also
- destroy()#
Destroy the LME object.
Collective.
See also
Source code at slepc4py/SLEPc/LME.pyx:95
- Return type:
- getBV()#
Get the basis vector object associated to the LME object.
Not collective.
- Returns:
The basis vectors context.
- Return type:
- getCoefficients()#
Get the coefficient matrices of the matrix equation.
Collective.
- Returns:
A (
petsc4py.PETSc.Mat) – First coefficient matrix.B (
petsc4py.PETSc.Mat) – Second coefficient matrix, if available.D (
petsc4py.PETSc.Mat) – Third coefficient matrix, if available.E (
petsc4py.PETSc.Mat) – Fourth coefficient matrix, if available.
- Return type:
See also
- getConvergedReason()#
Get the reason why the
solve()iteration was stopped.Not collective.
- Returns:
Negative value indicates diverged, positive value converged.
- Return type:
- getDimensions()#
Get the dimension of the subspace used by the solver.
Not collective.
- Returns:
Maximum dimension of the subspace to be used by the solver.
- Return type:
See also
- getErrorEstimate()#
Get the error estimate obtained during the solve.
Not collective.
- Returns:
The error estimate.
- Return type:
Notes
This is the error estimated internally by the solver. The actual error bound can be computed with
computeError(). Note that some solvers may not be able to provide an error estimate.See also
- getErrorIfNotConverged()#
Get if
solve()generates an error if the solver does not converge.Not collective.
Get a flag indicating whether
solve()will generate an error if the solver does not converge.- Returns:
Trueindicates you want the error generated.- Return type:
- 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:
See also
- getMonitor()#
Get the list of monitor functions.
Not collective.
- Returns:
The list of monitor functions.
- Return type:
- getOptionsPrefix()#
Get the prefix used for searching for all LME options in the database.
Not collective.
- Returns:
The prefix string set for this LME object.
- Return type:
- getProblemType()#
Get the LME problem type of this object.
Not collective.
- Returns:
The problem type currently being used.
- Return type:
See also
- getRHS()#
Get the right-hand side of the matrix equation.
Collective.
- Returns:
C – The low-rank matrix.
- Return type:
- getSolution()#
Get the solution of the matrix equation.
Collective.
- Returns:
X – The low-rank matrix.
- Return type:
Notes
If called after
solve(),Xwill contain the solution of the equation.The matrix
Xmay have been passed by the user viasetSolution(), although this is not required.See also
- getTolerances()#
Get the tolerance and maximum iteration count.
Not collective.
- Returns:
- Return type:
See also
- getType()#
Get the LME type of this object.
Not collective.
- Returns:
The solver currently being used.
- Return type:
See also
- reset()#
Reset the LME object.
Collective.
See also
Source code at slepc4py/SLEPc/LME.pyx:109
- Return type:
- setBV(bv)#
Set a basis vector object to the LME object.
Collective.
- setCoefficients(A, B=None, D=None, E=None)#
Set the coefficient matrices.
Collective.
Set the coefficient matrices that define the linear matrix equation to be solved.
- Parameters:
- Return type:
Notes
The matrix equation takes the general form \(AXE+DXB=C\), where matrix \(C\) is not provided here but with
setRHS(). Not all four matrices must be passed.This must be called before
setUp(). If called again aftersetUp()then theLMEobject is reset.See also
- setDimensions(ncv)#
Set the dimension of the subspace to be used by the solver.
Logically collective.
- Parameters:
ncv (int) – Maximum dimension of the subspace to be used by the solver.
- Return type:
See also
- setErrorIfNotConverged(flg=True)#
Set
solve()to generate an error if the solver has not converged.Logically collective.
Notes
Normally SLEPc continues if the solver fails to converge, you can call
getConvergedReason()after asolve()to determine if it has converged.See also
- setFromOptions()#
Set LME options from the options database.
Collective.
Notes
To see all options, run your program with the
-helpoption.This routine must be called before
setUp()if the user is to be allowed to set the solver type.See also
Source code at slepc4py/SLEPc/LME.pyx:534
- Return type:
- setMonitor(monitor, args=None, kargs=None)#
Append a monitor function to the list of monitors.
Logically collective.
See also
- setOptionsPrefix(prefix=None)#
Set the prefix used for searching for all LME options in the database.
Logically collective.
- Parameters:
prefix (str | None) – The prefix string to prepend to all LME 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 LME contexts, one could call:
L1.setOptionsPrefix("lme1_") L2.setOptionsPrefix("lme2_")
- setProblemType(lme_problem_type)#
Set the LME problem type of this object.
Logically collective.
- Parameters:
lme_problem_type (ProblemType | str) – The problem type to be used.
- Return type:
See also
- setRHS(C)#
Set the right-hand side of the matrix equation.
Collective.
Notes
The matrix equation takes the general form \(AXE+DXB=C\), where matrix \(C\) is given with this function. It must be a low-rank matrix of type
petsc4py.PETSc.Mat.Type.LRC, that is, \(C = UDV^*\) where \(D\) is diagonal of order \(k\), and \(U,V\) are dense tall-skinny matrices with \(k\) columns. No sparse matrix must be provided when creating theLRCmatrix.In equation types that require \(C\) to be symmetric, such as Lyapunov,
Cmust be created with \(V=U\).See also
- setSolution(X=None)#
Set the placeholder for the solution of the matrix equation.
Collective.
Notes
The matrix equation takes the general form \(AXE+DXB=C\), where the solution matrix is of low rank and is written in factored form \(X = UDV^*\). This function provides a matrix object of type
petsc4py.PETSc.Mat.Type.LRCthat stores \(U,V\) and (optionally) \(D\). These factors will be computed duringsolve().In equation types whose solution \(X\) is symmetric, such as Lyapunov,
Xmust be created with \(V=U\).If the user provides
Xwith this function, then the solver will return a solution with rank at most the number of columns of \(U\). Alternatively, it is possible to let the solver choose the rank of the solution, by passingNoneand then callinggetSolution()aftersolve().See also
- setTolerances(tol=None, max_it=None)#
Set the tolerance and maximum iteration count.
Logically collective.
Set the tolerance and maximum iteration count used by the default LME convergence tests.
- Parameters:
- Return type:
See also
- setType(lme_type)#
Set the particular solver to be used in the LME object.
Logically collective.
Notes
The default is
KRYLOV. Normally, it is best to usesetFromOptions()and then set the LME 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.See also
- setUp()#
Set up all the internal necessary data structures.
Collective.
Set up all the internal data structures necessary for the execution of the eigensolver.
Source code at slepc4py/SLEPc/LME.pyx:726
- Return type:
- solve()#
Solve the linear matrix equation.
Collective.
Notes
The matrix coefficients are specified with
setCoefficients(). The right-hand side is specified withsetRHS(). The placeholder for the solution is specified withsetSolution().See also
Source code at slepc4py/SLEPc/LME.pyx:741
- Return type:
- view(viewer=None)#
Print the LME data structure.
Collective.
- Parameters:
viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.
- Return type:
See also
Attributes Documentation
- max_it#
The maximum iteration count used by the LME convergence tests.
- tol#
The tolerance value used by the LME convergence tests.