slepc4py.SLEPc.FN#

class slepc4py.SLEPc.FN#

Bases: Object

Mathematical Function.

The FN package provides the functionality to represent a simple mathematical function such as an exponential, a polynomial or a rational function. This is used as a building block for defining the function associated to the nonlinear eigenproblem, as well as for specifying which function to use when computing the action of a matrix function on a vector.

Enumerations

`CombineType`	FN type of combination of child functions.
`ParallelType`	FN parallel types.
`Type`	FN type.

Methods Summary

`appendOptionsPrefix`([prefix])	Append to the prefix used for searching for all FN options in the database.
`create`([comm])	Create the FN object.
`destroy`()	Destroy the FN object.
`duplicate`([comm])	Duplicate the FN object copying all parameters.
`evaluateDerivative`(x)	Compute the value of the derivative \(f'(x)\) for a given x.
`evaluateFunction`(x)	Compute the value of the function \(f(x)\) for a given x.
`evaluateFunctionMat`(A[, B])	Compute the value of the function \(f(A)\) for a given matrix A.
`evaluateFunctionMatVec`(A[, v])	Compute the first column of the matrix \(f(A)\).
`getCombineChildren`()	Get the two child functions that constitute this combined function.
`getMethod`()	Get the method currently used for matrix functions.
`getOptionsPrefix`()	Get the prefix used for searching for all FN options in the database.
`getParallel`()	Get the mode of operation in parallel runs.
`getPhiIndex`()	Get the index of the phi-function.
`getRationalDenominator`()	Get the coefficients of the denominator of the rational function.
`getRationalNumerator`()	Get the coefficients of the numerator of the rational function.
`getScale`()	Get the scaling parameters that define the matematical function.
`getType`()	Get the FN type of this object.
`setCombineChildren`(comb, f1, f2)	Set the two child functions that constitute this combined function.
`setFromOptions`()	Set FN options from the options database.
`setMethod`(meth)	Set the method to be used to evaluate functions of matrices.
`setOptionsPrefix`([prefix])	Set the prefix used for searching for all FN options in the database.
`setParallel`(pmode)	Set the mode of operation in parallel runs.
`setPhiIndex`(k)	Set the index of the phi-function.
`setRationalDenominator`(alpha)	Set the coefficients of the denominator of the rational function.
`setRationalNumerator`(alpha)	Set the coefficients of the numerator of the rational function.
`setScale`([alpha, beta])	Set the scaling parameters that define the matematical function.
`setType`(fn_type)	Set the type for the FN object.
`view`([viewer])	Print the FN data structure.

Attributes Summary

`method`	The method to be used to evaluate functions of matrices.
`parallel`	The mode of operation in parallel runs.

Methods Documentation

appendOptionsPrefix(prefix=None)#

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

Logically collective.

Parameters:: prefix (str | None) – The prefix string to prepend to all FN option requests.
Return type:: None

:sources:`Source code at slepc4py/SLEPc/FN.pyx:266 <slepc4py/SLEPc/FN.pyx#L266>`

create(comm=None)#

Create the FN object.

Collective.

Parameters:: comm (Comm | None) – MPI communicator; if not provided, it defaults to all processes.
Return type:: Self

See also

FNCreate

:sources:`Source code at slepc4py/SLEPc/FN.pyx:182 <slepc4py/SLEPc/FN.pyx#L182>`

destroy()#

Destroy the FN object.

Collective.

See also

FNDestroy

:sources:`Source code at slepc4py/SLEPc/FN.pyx:168 <slepc4py/SLEPc/FN.pyx#L168>`

Return type:: Self

duplicate(comm=None)#

Duplicate the FN object copying all parameters.

Collective.

Duplicate the FN object copying all parameters, possibly with a different communicator.

Parameters:: comm (Comm | None) – MPI communicator; if not provided, it defaults to the object’s communicator.
Returns:: The new object.
Return type:: FN

See also

create, FNDuplicate

:sources:`Source code at slepc4py/SLEPc/FN.pyx:321 <slepc4py/SLEPc/FN.pyx#L321>`

evaluateDerivative(x)#

Compute the value of the derivative \(f'(x)\) for a given x.

Not collective.

Parameters:: x (Scalar) – Value where the derivative must be evaluated.
Returns:: The result of \(f'(x)\).
Return type:: Scalar

Notes

Scaling factors are taken into account, so the actual derivative evaluation will return \(ab f'(a x)\).

:sources:`Source code at slepc4py/SLEPc/FN.pyx:382 <slepc4py/SLEPc/FN.pyx#L382>`

evaluateFunction(x)#

Compute the value of the function \(f(x)\) for a given x.

Not collective.

Parameters:: x (Scalar) – Value where the function must be evaluated.
Returns:: The result of \(f(x)\).
Return type:: Scalar

Notes

Scaling factors are taken into account, so the actual function evaluation will return \(b f(a x)\).

:sources:`Source code at slepc4py/SLEPc/FN.pyx:352 <slepc4py/SLEPc/FN.pyx#L352>`

evaluateFunctionMat(A, B=None)#

Compute the value of the function \(f(A)\) for a given matrix A.

Logically collective.

Parameters:

A (Mat) – Matrix on which the function must be evaluated.
B (Mat | None) – Placeholder for the result.

Returns:

The result of \(f(A)\).

Return type:

petsc4py.PETSc.Mat

Notes

Scaling factors are taken into account, so the actual function evaluation will return \(b f(a A)\).

:sources:`Source code at slepc4py/SLEPc/FN.pyx:412 <slepc4py/SLEPc/FN.pyx#L412>`

evaluateFunctionMatVec(A, v=None)#

Compute the first column of the matrix \(f(A)\).

Logically collective.

Parameters:

A (Mat) – Matrix on which the function must be evaluated.
v (Vec | None)

Returns:

The first column of the result \(f(A)\).

Return type:

petsc4py.PETSc.Vec

Notes

This operation is similar to evaluateFunctionMat() but returns only the first column of \(f(A)\), hence saving computations in most cases.

:sources:`Source code at slepc4py/SLEPc/FN.pyx:443 <slepc4py/SLEPc/FN.pyx#L443>`

getCombineChildren()#

Get the two child functions that constitute this combined function.

Not collective.

Get the two child functions that constitute this combined function, and the way they must be combined.

Returns:

comb (CombineType) – How to combine the functions (addition, multiplication, division, composition).
f1 (FN) – First function.
f2 (FN) – Second function.

Return type:

tuple[CombineType, FN, FN]

:sources:`Source code at slepc4py/SLEPc/FN.pyx:725 <slepc4py/SLEPc/FN.pyx#L725>`

getMethod()#

Get the method currently used for matrix functions.

Not collective.

Returns:: An index identifying the method.
Return type:: int

See also

setMethod, FNGetMethod

:sources:`Source code at slepc4py/SLEPc/FN.pyx:546 <slepc4py/SLEPc/FN.pyx#L546>`

getOptionsPrefix()#

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

Not collective.

Returns:: The prefix string set for this FN object.
Return type:: str

:sources:`Source code at slepc4py/SLEPc/FN.pyx:285 <slepc4py/SLEPc/FN.pyx#L285>`

getParallel()#

Get the mode of operation in parallel runs.

Not collective.

Returns:: The parallel mode.
Return type:: ParallelType

See also

setParallel, FNGetParallel

:sources:`Source code at slepc4py/SLEPc/FN.pyx:588 <slepc4py/SLEPc/FN.pyx#L588>`

getPhiIndex()#

Get the index of the phi-function.

Not collective.

Returns:: The index.
Return type:: int

See also

setPhiIndex, FNPhiGetIndex

:sources:`Source code at slepc4py/SLEPc/FN.pyx:778 <slepc4py/SLEPc/FN.pyx#L778>`

getRationalDenominator()#

Get the coefficients of the denominator of the rational function.

Not collective.

Returns:: Coefficients.
Return type:: ArrayScalar

:sources:`Source code at slepc4py/SLEPc/FN.pyx:674 <slepc4py/SLEPc/FN.pyx#L674>`

getRationalNumerator()#

Get the coefficients of the numerator of the rational function.

Not collective.

Returns:: Coefficients.
Return type:: ArrayScalar

:sources:`Source code at slepc4py/SLEPc/FN.pyx:629 <slepc4py/SLEPc/FN.pyx#L629>`

getScale()#

Get the scaling parameters that define the matematical function.

Not collective.

Returns:

alpha (Scalar) – Inner scaling (argument).
beta (Scalar) – Outer scaling (result).

Return type:

tuple[Scalar, Scalar]

See also

setScale, FNGetScale

:sources:`Source code at slepc4py/SLEPc/FN.pyx:496 <slepc4py/SLEPc/FN.pyx#L496>`

getType()#

Get the FN type of this object.

Not collective.

Returns:: The math function type currently being used.
Return type:: str

See also

setType, FNGetType

:sources:`Source code at slepc4py/SLEPc/FN.pyx:222 <slepc4py/SLEPc/FN.pyx#L222>`

setCombineChildren(comb, f1, f2)#

Set the two child functions that constitute this combined function.

Logically collective.

Set the two child functions that constitute this combined function, and the way they must be combined.

Parameters:

comb (CombineType) – How to combine the functions (addition, multiplication, division, composition).
f1 (FN) – First function.
f2 (FN) – Second function.

Return type:

None

:sources:`Source code at slepc4py/SLEPc/FN.pyx:699 <slepc4py/SLEPc/FN.pyx#L699>`

setFromOptions()#

Set FN options from the options database.

Collective.

Notes

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

See also

setOptionsPrefix, FNSetFromOptions

:sources:`Source code at slepc4py/SLEPc/FN.pyx:304 <slepc4py/SLEPc/FN.pyx#L304>`

Return type:: None

setMethod(meth)#

Set the method to be used to evaluate functions of matrices.

Logically collective.

Parameters:: meth (int) – An index identifying the method.
Return type:: None

Notes

In some FN types there are more than one algorithms available for computing matrix functions. In that case, this function allows choosing the wanted method.

If meth is currently set to 0 and the input argument of FN.evaluateFunctionMat() is a symmetric/Hermitian matrix, then the computation is done via the eigendecomposition, rather than with the general algorithm.

See also

getMethod, FNSetMethod

:sources:`Source code at slepc4py/SLEPc/FN.pyx:517 <slepc4py/SLEPc/FN.pyx#L517>`

setOptionsPrefix(prefix=None)#

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

Logically collective.