Skip to main content
`Ctrl`+`K`

# 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

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `FNAppendOptionsPrefix`

    :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)\).

    See also

    `evaluateFunction`, `setScale`, `FNEvaluateDerivative`

    :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)\).

    See also

    `evaluateDerivative`, `evaluateFunctionMat`, `setScale`, `FNEvaluateFunction`

    :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)\).

    See also

    `evaluateFunction`, `evaluateFunctionMatVec`, `FNEvaluateFunctionMat`

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

    See also

    `evaluateFunctionMat`, `FNEvaluateFunctionMatVec`

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

    See also

    `setCombineChildren`, `FNCombineGetChildren`

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

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `FNGetOptionsPrefix`

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

    See also

    `setRationalDenominator`, `FNRationalGetDenominator`

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

    See also

    `setRationalNumerator`, `FNRationalGetNumerator`

    :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

    See also

    `getCombineChildren`, `FNCombineSetChildren`

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

    Parameters:

      prefix (str | None) – The prefix string to prepend to all FN 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.

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `FNGetOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:241 <slepc4py/SLEPc/FN.pyx#L241>`

  setParallel(pmode)

    Set the mode of operation in parallel runs.

    Logically collective.

    Parameters:

      pmode (ParallelType) – The parallel mode.

    Return type:

      None

    Notes

    This is relevant only when the function is evaluated on a matrix, with either `evaluateFunctionMat()` or `evaluateFunctionMatVec()`.

    See also

    `evaluateFunctionMat`, `getParallel`, `FNSetParallel`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:565 <slepc4py/SLEPc/FN.pyx#L565>`

  setPhiIndex(k)

    Set the index of the phi-function.

    Logically collective.

    Parameters:

      k (int) – The index.

    Return type:

      None

    Notes

    If not set, the default index is 1.

    See also

    `getPhiIndex`, `FNPhiSetIndex`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:756 <slepc4py/SLEPc/FN.pyx#L756>`

  setRationalDenominator(alpha)

    Set the coefficients of the denominator of the rational function.

    Logically collective.

    Parameters:

      alpha (Sequence[Scalar]) – Coefficients.

    Return type:

      None

    See also

    `setRationalNumerator`, `FNRationalSetDenominator`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:654 <slepc4py/SLEPc/FN.pyx#L654>`

  setRationalNumerator(alpha)

    Set the coefficients of the numerator of the rational function.

    Logically collective.

    Parameters:

      alpha (Sequence[Scalar]) – Coefficients.

    Return type:

      None

    See also

    `setRationalDenominator`, `FNRationalSetNumerator`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:609 <slepc4py/SLEPc/FN.pyx#L609>`

  setScale(alpha=None, beta=None)

    Set the scaling parameters that define the matematical function.

    Logically collective.

    Parameters:

      - alpha (Scalar | None) – Inner scaling (argument), default is 1.0.

      - beta (Scalar | None) – Outer scaling (result), default is 1.0.

    Return type:

      None

    See also

    `getScale`, `evaluateFunction`, `FNSetScale`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:473 <slepc4py/SLEPc/FN.pyx#L473>`

  setType(fn_type)

    Set the type for the FN object.

    Logically collective.

    Parameters:

      fn_type (Type | str) – The math function type to be used.

    Return type:

      None

    See also

    `getType`, `FNSetType`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:203 <slepc4py/SLEPc/FN.pyx#L203>`

  view(viewer=None)

    Print the FN data structure.

    Collective.

    Parameters:

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

    Return type:

      None

    See also

    `FNView`

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:149 <slepc4py/SLEPc/FN.pyx#L149>`

  Attributes Documentation

  method

    The method to be used to evaluate functions of matrices.

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:799 <slepc4py/SLEPc/FN.pyx#L799>`

  parallel

    The mode of operation in parallel runs.

    :sources:`Source code at slepc4py/SLEPc/FN.pyx:806 <slepc4py/SLEPc/FN.pyx#L806>`