slepc4py.SLEPc.LME — slepc4py 3.24.3 documentation

Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.LME

class slepc4py.SLEPc.LME

  Bases: `Object`

  Linear 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

  `ConvergedReason` | LME convergence reasons.
  `ProblemType` | LME problem type.
  `Type` | LME type.

  Methods Summary

  `appendOptionsPrefix`([prefix]) | Append to the prefix used for searching in the database.
  `cancelMonitor`() | Clear all monitors for an `LME` object.
  `computeError`() | 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.
  `getCoefficients`() | Get the coefficient matrices of the matrix equation.
  `getConvergedReason`() | Get the reason why the `solve()` iteration was stopped.
  `getDimensions`() | Get the dimension of the subspace used by the solver.
  `getErrorEstimate`() | Get the error estimate obtained during the solve.
  `getErrorIfNotConverged`() | Get if `solve()` generates an error if the solver does not converge.
  `getIterationNumber`() | Get the current iteration number.
  `getMonitor`() | Get the list of monitor functions.
  `getOptionsPrefix`() | Get the prefix used for searching for all LME options in the database.
  `getProblemType`() | Get the LME problem type of this object.
  `getRHS`() | Get the right-hand side of the matrix equation.
  `getSolution`() | Get the solution of the matrix equation.
  `getTolerances`() | 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.
  `setFromOptions`() | 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

  `bv` | The basis vectors (`BV`) object associated to the LME object.
  `fn` | The math function (`FN`) object associated to the LME object.
  `max_it` | The maximum iteration count used by the LME convergence tests.
  `tol` | 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.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all LME option requests.

    Return type:

      None

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `LMEAppendOptionsPrefix`

    Source code at slepc4py/SLEPc/LME.pyx:512

  cancelMonitor()

    Clear all monitors for an `LME` object.

    Logically collective.

    See also

    `LMEMonitorCancel`

    Source code at slepc4py/SLEPc/LME.pyx:713

    Return type:

      None

  computeError()

    Compute the error associated with the last equation solved.

    Collective.

    Returns:

      The error.

    Return type:

      `float`

    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

    `getErrorEstimate`, `LMEComputeError`

    Source code at slepc4py/SLEPc/LME.pyx:435

  create(comm=None)

    Create the LME object.

    Collective.

    Parameters:

      comm (Comm | None) – MPI communicator. If not provided, it defaults to all processes.

    Return type:

      Self

    See also

    `LMECreate`

    Source code at slepc4py/SLEPc/LME.pyx:121

  destroy()

    Destroy the LME object.

    Collective.

    See also

    `LMEDestroy`

    Source code at slepc4py/SLEPc/LME.pyx:95

    Return type:

      Self

  getBV()

    Get the basis vector object associated to the LME object.

    Not collective.

    Returns:

      The basis vectors context.

    Return type:

      `BV`

    See also

    `setBV`, `LMEGetBV`

    Source code at slepc4py/SLEPc/LME.pyx:638

  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:

      tuple[Mat, Mat | None, Mat | None, Mat | None]

    See also

    `setCoefficients`, `LMEGetCoefficients`

    Source code at slepc4py/SLEPc/LME.pyx:264

  getConvergedReason()

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

    Not collective.

    Returns:

      Negative value indicates diverged, positive value converged.

    Return type:

      `ConvergedReason`

    See also

    `setTolerances`, `solve`, `setErrorIfNotConverged`, `LMEGetConvergedReason`

    Source code at slepc4py/SLEPc/LME.pyx:780

  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:

      `int`

    See also

    `setDimensions`, `LMEGetDimensions`

    Source code at slepc4py/SLEPc/LME.pyx:601

  getErrorEstimate()

    Get the error estimate obtained during the solve.

    Not collective.

    Returns:

      The error estimate.

    Return type:

      `float`

    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

    `computeError`, `LMEGetErrorEstimate`

    Source code at slepc4py/SLEPc/LME.pyx:410

  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:

      `True` indicates you want the error generated.

    Return type:

      `bool`

    See also

    `setErrorIfNotConverged`, `LMEGetErrorIfNotConverged`

    Source code at slepc4py/SLEPc/LME.pyx:823

  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:

      `int`

    See also

    `getConvergedReason`, `LMEGetIterationNumber`

    Source code at slepc4py/SLEPc/LME.pyx:758

  getMonitor()

    Get the list of monitor functions.

    Not collective.

    Returns:

      The list of monitor functions.

    Return type:

      `LMEMonitorFunction`

    Source code at slepc4py/SLEPc/LME.pyx:700

  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:

      `str`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `LMEGetOptionsPrefix`

    Source code at slepc4py/SLEPc/LME.pyx:462

  getProblemType()

    Get the LME problem type of this object.

    Not collective.

    Returns:

      The problem type currently being used.

    Return type:

      `ProblemType`

    See also

    `setProblemType`, `LMEGetProblemType`

    Source code at slepc4py/SLEPc/LME.pyx:206

  getRHS()

    Get the right-hand side of the matrix equation.

    Collective.

    Returns:

      C – The low-rank matrix.

    Return type:

      `petsc4py.PETSc.Mat`

    See also

    `setRHS`, `LMEGetRHS`

    Source code at slepc4py/SLEPc/LME.pyx:327

  getSolution()

    Get the solution of the matrix equation.

    Collective.

    Returns:

      X – The low-rank matrix.

    Return type:

      `petsc4py.PETSc.Mat`

    Notes

    If called after `solve()`, `X` will contain the solution of the equation.

    The matrix `X` may have been passed by the user via `setSolution()`, although this is not required.

    See also

    `solve`, `setSolution`, `LMEGetSolution`

    Source code at slepc4py/SLEPc/LME.pyx:382

  getTolerances()

    Get the tolerance and maximum iteration count.

    Not collective.

    Returns:

      - tol (`float`) – The convergence tolerance.

      - max_it (`int`) – The maximum number of iterations.

    Return type:

      tuple[float, int]

    See also

    `setTolerances`, `LMEGetTolerances`

    Source code at slepc4py/SLEPc/LME.pyx:553

  getType()

    Get the LME type of this object.

    Not collective.

    Returns:

      The solver currently being used.

    Return type:

      `str`

    See also

    `setType`, `LMEGetType`

    Source code at slepc4py/SLEPc/LME.pyx:169

  reset()

    Reset the LME object.

    Collective.

    See also

    `LMEReset`

    Source code at slepc4py/SLEPc/LME.pyx:109

    Return type:

      None

  setBV(bv)

    Set a basis vector object to the LME object.

    Collective.

    Parameters:

      bv (BV) – The basis vectors context.

    Return type:

      None

    See also

    `getBV`, `LMESetBV`

    Source code at slepc4py/SLEPc/LME.pyx:658

  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:

      - A (Mat) – First coefficient matrix

      - B (Mat | None) – Second coefficient matrix, optional

      - D (Mat | None) – Third coefficient matrix, optional

      - E (Mat | None) – Fourth coefficient matrix, optional

    Return type:

      None

    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 after `setUp()` then the `LME` object is reset.

    See also

    `getCoefficients`, `solve`, `setRHS`, `setUp`, `LMESetCoefficients`

    Source code at slepc4py/SLEPc/LME.pyx:225

  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:

      None

    See also

    `getDimensions`, `LMESetDimensions`

    Source code at slepc4py/SLEPc/LME.pyx:620

  setErrorIfNotConverged(flg=True)

    Set `solve()` to generate an error if the solver has not converged.

    Logically collective.

    Parameters:

      flg (bool) – `True` indicates you want the error generated.

    Return type:

      None

    Notes

    Normally SLEPc continues if the solver fails to converge, you can call `getConvergedReason()` after a `solve()` to determine if it has converged.

    See also

    `getConvergedReason`, `solve`, `LMESetErrorIfNotConverged`

    Source code at slepc4py/SLEPc/LME.pyx:799

  setFromOptions()

    Set LME options from the options database.

    Collective.

    Notes

    To see all options, run your program with the `-help` option.

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

    See also

    `setOptionsPrefix`, `LMESetFromOptions`

    Source code at slepc4py/SLEPc/LME.pyx:534

    Return type:

      None

  setMonitor(monitor, args=None, kargs=None)

    Append a monitor function to the list of monitors.

    Logically collective.

    See also

    `getMonitor`, `cancelMonitor`, `LMEMonitorSet`

    Source code at slepc4py/SLEPc/LME.pyx:675

    Parameters:

      - monitor (LMEMonitorFunction | None)

      - args (tuple[Any, ...] | None)

      - kargs (dict[str, Any] | None)

    Return type:

      None

  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:

      None

    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_")

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `LMEGetOptionsPrefix`

    Source code at slepc4py/SLEPc/LME.pyx:481

  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:

      None

    See also

    `getProblemType`, `LMESetProblemType`

    Source code at slepc4py/SLEPc/LME.pyx:188

  setRHS(C)

    Set the right-hand side of the matrix equation.

    Collective.

    Parameters:

      C (Mat) – The right-hand side matrix

    Return type:

      None

    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 the `LRC` matrix.

    In equation types that require \(C\) to be symmetric, such as Lyapunov, `C` must be created with \(V=U\).

    See also

    `getRHS`, `setSolution`, `LMESetRHS`

    Source code at slepc4py/SLEPc/LME.pyx:298

  setSolution(X=None)

    Set the placeholder for the solution of the matrix equation.

    Collective.

    Parameters:

      X (Mat | None) – The solution matrix

    Return type:

      None

    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.LRC` that stores \(U,V\) and (optionally) \(D\). These factors will be computed during `solve()`.

    In equation types whose solution \(X\) is symmetric, such as Lyapunov, `X` must be created with \(V=U\).

    If the user provides `X` with 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 passing `None` and then calling `getSolution()` after `solve()`.

    See also

    `solve`, `setRHS`, `getSolution`, `LMESetSolution`

    Source code at slepc4py/SLEPc/LME.pyx:347

  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:

      - tol (float | None) – The convergence tolerance.

      - max_it (int | None) – The maximum number of iterations.

    Return type:

      None

    See also

    `getTolerances`, `LMESetTolerances`

    Source code at slepc4py/SLEPc/LME.pyx:575

  setType(lme_type)

    Set the particular solver to be used in the LME object.

    Logically collective.

    Parameters:

      lme_type (Type | str) – The solver to be used.

    Return type:

      None

    Notes

    The default is `KRYLOV`. Normally, it is best to use `setFromOptions()` 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

    `getType`, `LMESetType`

    Source code at slepc4py/SLEPc/LME.pyx:142

  setUp()

    Set up all the internal necessary data structures.

    Collective.

    Set up all the internal data structures necessary for the execution of the eigensolver.

    See also

    `solve`, `LMESetUp`

    Source code at slepc4py/SLEPc/LME.pyx:726

    Return type:

      None

  solve()

    Solve the linear matrix equation.

    Collective.

    Notes

    The matrix coefficients are specified with `setCoefficients()`. The right-hand side is specified with `setRHS()`. The placeholder for the solution is specified with `setSolution()`.

    See also

    `setCoefficients`, `setRHS`, `setSolution`, `LMESolve`

    Source code at slepc4py/SLEPc/LME.pyx:741

    Return type:

      None

  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:

      None

    See also

    `LMEView`

    Source code at slepc4py/SLEPc/LME.pyx:76

  Attributes Documentation

  bv

    The basis vectors (`BV`) object associated to the LME object.

    Source code at slepc4py/SLEPc/LME.pyx:868

  fn

    The math function (`FN`) object associated to the LME object.

    Source code at slepc4py/SLEPc/LME.pyx:861

  max_it

    The maximum iteration count used by the LME convergence tests.

    Source code at slepc4py/SLEPc/LME.pyx:854

  tol

    The tolerance value used by the LME convergence tests.

    Source code at slepc4py/SLEPc/LME.pyx:847