Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.MFN

class slepc4py.SLEPc.MFN

  Bases: `Object`

  Matrix Function.

  Matrix Function (`MFN`) is the object provided by slepc4py for computing the action of a matrix function on a vector. Given a matrix \(A\) and a vector \(b\), the call `mfn.solve(b,x)` computes \(x=f(A)b\), where \(f\) is a function such as the exponential.

  Enumerations

  `ConvergedReason` | MFN convergence reasons.
  `Type` | MFN type.

  Methods Summary

  `appendOptionsPrefix`([prefix]) | Append to the prefix used for searching for all MFN options in the database.
  `cancelMonitor`() | Clear all monitors for an `MFN` object.
  `create`([comm]) | Create the MFN object.
  `destroy`() | Destroy the MFN object.
  `getBV`() | Get the basis vector object associated to the MFN object.
  `getConvergedReason`() | Get the reason why the `solve()` iteration was stopped.
  `getDimensions`() | Get the dimension of the subspace used by the solver.
  `getErrorIfNotConverged`() | Get if `solve()` generates an error if the solver does not converge.
  `getFN`() | Get the math function object associated to the MFN object.
  `getIterationNumber`() | Get the current iteration number.
  `getMonitor`() | Get the list of monitor functions.
  `getOperator`() | Get the matrix associated with the MFN object.
  `getOptionsPrefix`() | Get the prefix used for searching for all MFN options in the database.
  `getTolerances`() | Get the tolerance and maximum iteration count.
  `getType`() | Get the MFN type of this object.
  `reset`() | Reset the MFN object.
  `setBV`(bv) | Set a basis vector object associated to the MFN object.
  `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 does not converge.
  `setFN`(fn) | Set a math function object associated to the MFN object.
  `setFromOptions`() | Set MFN options from the options database.
  `setMonitor`(monitor[, args, kargs]) | Append a monitor function to the list of monitors.
  `setOperator`(A) | Set the matrix associated with the MFN object.
  `setOptionsPrefix`([prefix]) | Set the prefix used for searching for all MFN options in the database.
  `setTolerances`([tol, max_it]) | Set the tolerance and maximum iteration count.
  `setType`(mfn_type) | Set the particular solver to be used in the MFN object.
  `setUp`() | Set up all the necessary internal data structures.
  `solve`(b, x) | Solve the matrix function problem.
  `solveTranspose`(b, x) | Solve the transpose matrix function problem.
  `view`([viewer]) | Print the MFN data structure.

  Attributes Summary

  `bv` | The basis vectors (`BV`) object associated to the MFN object.
  `fn` | The math function (`FN`) object associated to the MFN object.
  `max_it` | The maximum iteration count used by the MFN convergence tests.
  `tol` | The tolerance count used by the MFN convergence tests.

  Methods Documentation

  appendOptionsPrefix(prefix=None)

    Append to the prefix used for searching for all MFN options in the database.

    Logically collective.

    Parameters:

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

    Return type:

      None

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `MFNAppendOptionsPrefix`

    Source code at slepc4py/SLEPc/MFN.pyx:219

  cancelMonitor()

    Clear all monitors for an `MFN` object.

    Logically collective.

    See also

    `MFNMonitorCancel`

    Source code at slepc4py/SLEPc/MFN.pyx:498

    Return type:

      None

  create(comm=None)

    Create the MFN object.

    Collective.

    Parameters:

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

    Return type:

      Self

    See also

    `MFNCreate`

    Source code at slepc4py/SLEPc/MFN.pyx:102

  destroy()

    Destroy the MFN object.

    Logically collective.

    See also

    `MFNDestroy`

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

    Return type:

      Self

  getBV()

    Get the basis vector object associated to the MFN object.

    Not collective.

    Returns:

      The basis vectors context.

    Return type:

      `BV`

    See also

    `setBV`, `MFNGetBV`

    Source code at slepc4py/SLEPc/MFN.pyx:379

  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`, `MFNGetConvergedReason`

    Source code at slepc4py/SLEPc/MFN.pyx:607

  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`, `MFNGetDimensions`

    Source code at slepc4py/SLEPc/MFN.pyx:305

  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`, `MFNGetErrorIfNotConverged`

    Source code at slepc4py/SLEPc/MFN.pyx:650

  getFN()

    Get the math function object associated to the MFN object.

    Not collective.

    Returns:

      The math function context.

    Return type:

      `FN`

    See also

    `setFN`, `MFNGetFN`

    Source code at slepc4py/SLEPc/MFN.pyx:342

  getIterationNumber()

    Get the current iteration number.

    Not collective.

    Get 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:

      Iteration number.

    Return type:

      `int`

    See also

    `getConvergedReason`, `MFNGetIterationNumber`

    Source code at slepc4py/SLEPc/MFN.pyx:584

  getMonitor()

    Get the list of monitor functions.

    Not collective.

    Returns:

      The list of monitor functions.

    Return type:

      `MFNMonitorFunction`

    Source code at slepc4py/SLEPc/MFN.pyx:485

  getOperator()

    Get the matrix associated with the MFN object.

    Collective.

    Returns:

      The matrix for which the matrix function is to be computed.

    Return type:

      `petsc4py.PETSc.Mat`

    See also

    `setOperator`, `MFNGetOperator`

    Source code at slepc4py/SLEPc/MFN.pyx:416

  getOptionsPrefix()

    Get the prefix used for searching for all MFN options in the database.

    Not collective.

    Returns:

      The prefix string set for this MFN object.

    Return type:

      `str`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `MFNGetOptionsPrefix`

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

  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`, `MFNGetTolerances`

    Source code at slepc4py/SLEPc/MFN.pyx:257

  getType()

    Get the MFN type of this object.

    Not collective.

    Returns:

      The solver currently being used.

    Return type:

      `str`

    See also

    `setType`, `MFNGetType`

    Source code at slepc4py/SLEPc/MFN.pyx:150

  reset()

    Reset the MFN object.

    Collective.

    See also

    `MFNReset`

    Source code at slepc4py/SLEPc/MFN.pyx:90

    Return type:

      None

  setBV(bv)

    Set a basis vector object associated to the MFN object.

    Collective.

    Parameters:

      bv (BV) – The basis vectors context.

    Return type:

      None

    See also

    `getBV`, `MFNSetBV`

    Source code at slepc4py/SLEPc/MFN.pyx:399

  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`, `MFNSetDimensions`

    Source code at slepc4py/SLEPc/MFN.pyx:324

  setErrorIfNotConverged(flg=True)

    Set `solve()` to generate an error if the solver does not converge.

    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`, `MFNSetErrorIfNotConverged`

    Source code at slepc4py/SLEPc/MFN.pyx:626

  setFN(fn)

    Set a math function object associated to the MFN object.

    Collective.

    Parameters:

      fn (FN) – The math function context.

    Return type:

      None

    See also

    `getFN`, `MFNSetFN`

    Source code at slepc4py/SLEPc/MFN.pyx:362

  setFromOptions()

    Set MFN 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`, `MFNSetFromOptions`

    Source code at slepc4py/SLEPc/MFN.pyx:238

    Return type:

      None

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

    Append a monitor function to the list of monitors.

    Logically collective.

    See also

    `getMonitor`, `cancelMonitor`, `MFNMonitorSet`

    Source code at slepc4py/SLEPc/MFN.pyx:460

    Parameters:

      - monitor (MFNMonitorFunction | None)

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

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

    Return type:

      None

  setOperator(A)

    Set the matrix associated with the MFN object.

    Collective.

    Parameters:

      A (Mat) – The problem matrix.

    Return type:

      None

    Notes

    This must be called before `setUp()`. If called again after `setUp()` then the `MFN` object is reset.

    See also

    `getOperator`, `MFNSetOperator`

    Source code at slepc4py/SLEPc/MFN.pyx:436

  setOptionsPrefix(prefix=None)

    Set the prefix used for searching for all MFN options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all MFN 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 MFN contexts, one could call:

        M1.setOptionsPrefix("mfn1_")
        M2.setOptionsPrefix("mfn2_")

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `MFNGetOptionsPrefix`

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

  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 MFN convergence tests.

    Parameters:

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

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

    Return type:

      None

    See also

    `getTolerances`, `MFNSetTolerances`

    Source code at slepc4py/SLEPc/MFN.pyx:279

  setType(mfn_type)

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

    Logically collective.

    Parameters:

      mfn_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 MFN 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`, `MFNSetType`

    Source code at slepc4py/SLEPc/MFN.pyx:123

  setUp()

    Set up all the necessary internal data structures.

    Collective.

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

    See also

    `solve`, `MFNSetUp`

    Source code at slepc4py/SLEPc/MFN.pyx:513

    Return type:

      None

  solve(b, x)

    Solve the matrix function problem.

    Collective.

    Given a vector \(b\), the vector \(x = f(A) b\) is returned.

    Parameters:

      - b (Vec) – The right hand side vector.

      - x (Vec) – The solution.

    Return type:

      None

    Notes

    The matrix \(A\) is specified with `setOperator()`. The function \(f\) is specified via the `FN` object obtained with `getFN()` or set with `setFN()`.

    See also

    `setOperator`, `getFN`, `solveTranspose`, `MFNSolve`

    Source code at slepc4py/SLEPc/MFN.pyx:528

  solveTranspose(b, x)

    Solve the transpose matrix function problem.

    Collective.

    Given a vector \(b\), the vector \(x = f(A^T) b\) is returned.

    Parameters:

      - b (Vec) – The right hand side vector.

      - x (Vec) – The solution.

    Return type:

      None

    Notes

    The matrix \(A\) is specified with `setOperator()`. The function \(f\) is specified via the `FN` object obtained with `getFN()` or set with `setFN()`.

    See also

    `setOperator`, `getFN`, `solve`, `MFNSolveTranspose`

    Source code at slepc4py/SLEPc/MFN.pyx:556

  view(viewer=None)

    Print the MFN data structure.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `MFNView`

    Source code at slepc4py/SLEPc/MFN.pyx:57

  Attributes Documentation

  bv

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

    Source code at slepc4py/SLEPc/MFN.pyx:695

  fn

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

    Source code at slepc4py/SLEPc/MFN.pyx:688

  max_it

    The maximum iteration count used by the MFN convergence tests.

    Source code at slepc4py/SLEPc/MFN.pyx:681

  tol

    The tolerance count used by the MFN convergence tests.

    Source code at slepc4py/SLEPc/MFN.pyx:674