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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:219 <slepc4py/SLEPc/MFN.pyx#L219>`

cancelMonitor()#

Clear all monitors for an MFN object.

Logically collective.

See also

MFNMonitorCancel

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:498 <slepc4py/SLEPc/MFN.pyx#L498>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:102 <slepc4py/SLEPc/MFN.pyx#L102>`

destroy()#

Destroy the MFN object.

Logically collective.

See also

MFNDestroy

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:76 <slepc4py/SLEPc/MFN.pyx#L76>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:379 <slepc4py/SLEPc/MFN.pyx#L379>`

getConvergedReason()#

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

Not collective.

Returns:: Negative value indicates diverged, positive value converged.
Return type:: ConvergedReason

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:607 <slepc4py/SLEPc/MFN.pyx#L607>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:305 <slepc4py/SLEPc/MFN.pyx#L305>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:650 <slepc4py/SLEPc/MFN.pyx#L650>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:342 <slepc4py/SLEPc/MFN.pyx#L342>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:584 <slepc4py/SLEPc/MFN.pyx#L584>`

getMonitor()#

Get the list of monitor functions.

Not collective.

Returns:: The list of monitor functions.
Return type:: MFNMonitorFunction

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:485 <slepc4py/SLEPc/MFN.pyx#L485>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:416 <slepc4py/SLEPc/MFN.pyx#L416>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:169 <slepc4py/SLEPc/MFN.pyx#L169>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:257 <slepc4py/SLEPc/MFN.pyx#L257>`

getType()#

Get the MFN type of this object.

Not collective.

Returns:: The solver currently being used.
Return type:: str

See also

setType, MFNGetType

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:150 <slepc4py/SLEPc/MFN.pyx#L150>`

reset()#

Reset the MFN object.

Collective.

See also

MFNReset

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:90 <slepc4py/SLEPc/MFN.pyx#L90>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:399 <slepc4py/SLEPc/MFN.pyx#L399>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:324 <slepc4py/SLEPc/MFN.pyx#L324>`

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.

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:626 <slepc4py/SLEPc/MFN.pyx#L626>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:362 <slepc4py/SLEPc/MFN.pyx#L362>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:238 <slepc4py/SLEPc/MFN.pyx#L238>`

Return type:: None

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

Append a monitor function to the list of monitors.

Logically collective.

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:460 <slepc4py/SLEPc/MFN.pyx#L460>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:436 <slepc4py/SLEPc/MFN.pyx#L436>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:188 <slepc4py/SLEPc/MFN.pyx#L188>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:279 <slepc4py/SLEPc/MFN.pyx#L279>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:123 <slepc4py/SLEPc/MFN.pyx#L123>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:513 <slepc4py/SLEPc/MFN.pyx#L513>`

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

:sources:`Source code at slepc4py/SLEPc/MFN.pyx:528 <slepc4py/SLEPc/MFN.pyx#L528>`

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