Actual source code: slepcfn.h

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

      6:    This file is part of SLEPc.
      7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
      8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      9: */
     10: /*
     11:    User interface for the mathematical function object in SLEPc
     12: */

     14: #pragma once

     16: #include <slepcsys.h>

     18: /* SUBMANSEC = FN */

     20: #define FN_MAX_SOLVE 16

     22: SLEPC_EXTERN PetscErrorCode FNInitializePackage(void);
     23: SLEPC_EXTERN PetscErrorCode FNFinalizePackage(void);

     25: /*S
     26:    FN - Abstraction of a mathematical function.

     28:    Level: beginner

     30: .seealso: [](sec:fn), `FNCreate()`
     31: S*/
     32: typedef struct _p_FN* FN;

     34: /*J
     35:    FNType - String with the name of the mathematical function.

     37:    Level: beginner

     39: .seealso: [](sec:fn), `FNSetType()`, `FN`
     40: J*/
     41: typedef const char *FNType;
     42: #define FNRATIONAL "rational"
     43: #define FNEXP      "exp"
     44: #define FNLOG      "log"
     45: #define FNPHI      "phi"
     46: #define FNSQRT     "sqrt"
     47: #define FNINVSQRT  "invsqrt"
     48: #define FNCOMBINE  "combine"

     50: /* Logging support */
     51: SLEPC_EXTERN PetscClassId FN_CLASSID;

     53: /*E
     54:    FNCombineType - Determines how two functions are combined.

     56:    Values:
     57: +  `FN_COMBINE_ADD`      - add the functions
     58: .  `FN_COMBINE_MULTIPLY` - multiply the functions
     59: .  `FN_COMBINE_DIVIDE`   - divide the functions
     60: -  `FN_COMBINE_COMPOSE`  - use function composition

     62:    Level: intermediate

     64: .seealso: [](sec:fn), `FNCombineSetChildren()`
     65: E*/
     66: typedef enum { FN_COMBINE_ADD,
     67:                FN_COMBINE_MULTIPLY,
     68:                FN_COMBINE_DIVIDE,
     69:                FN_COMBINE_COMPOSE } FNCombineType;

     71: /*MC
     72:    FN_COMBINE_ADD - In functions of type `FNCOMBINE`, add the two child functions
     73:    together.

     75:    Level: intermediate

     77: .seealso: [](sec:fn), `FNCombineType`, `FNCombineSetChildren()`, `FN_COMBINE_MULTIPLY`, `FN_COMBINE_DIVIDE`, `FN_COMBINE_COMPOSE`
     78: M*/

     80: /*MC
     81:    FN_COMBINE_MULTIPLY - In functions of type `FNCOMBINE`, multiply the two child functions
     82:    together.

     84:    Level: intermediate

     86: .seealso: [](sec:fn), `FNCombineType`, `FNCombineSetChildren()`, `FN_COMBINE_ADD`, `FN_COMBINE_DIVIDE`, `FN_COMBINE_COMPOSE`
     87: M*/

     89: /*MC
     90:    FN_COMBINE_DIVIDE - In functions of type `FNCOMBINE`, compute the ratio of the
     91:    two child functions (the first one in the numerator).

     93:    Level: intermediate

     95: .seealso: [](sec:fn), `FNCombineType`, `FNCombineSetChildren()`, `FN_COMBINE_ADD`, `FN_COMBINE_MULTIPLY`, `FN_COMBINE_COMPOSE`
     96: M*/

     98: /*MC
     99:    FN_COMBINE_COMPOSE - In functions of type `FNCOMBINE`, compose the two child functions,
    100:    i.e., evaluate the second function on the result of evaluating the first function.

    102:    Level: intermediate

    104: .seealso: [](sec:fn), `FNCombineType`, `FNCombineSetChildren()`, `FN_COMBINE_ADD`, `FN_COMBINE_MULTIPLY`, `FN_COMBINE_DIVIDE`
    105: M*/

    107: /*E
    108:    FNParallelType - Indicates the parallel mode that will be used for matrix
    109:    function evaluation.

    111:    Values:
    112: +  `FN_PARALLEL_REDUNDANT`    - all processes compute redundantly
    113: -  `FN_PARALLEL_SYNCHRONIZED` - only the first MPI process performs the computation

    115:    Level: advanced

    117: .seealso: [](sec:fn), `FNSetParallel()`
    118: E*/
    119: typedef enum { FN_PARALLEL_REDUNDANT,
    120:                FN_PARALLEL_SYNCHRONIZED } FNParallelType;
    121: SLEPC_EXTERN const char *FNParallelTypes[];

    123: /*MC
    124:    FN_PARALLEL_REDUNDANT - In matrix function evaluation, all processes compute
    125:    redundantly.

    127:    Note:
    128:    When this parallel mode is selected, all processes will make the computation
    129:    redundantly, starting from the same data, and producing the same result.
    130:    This result may be slightly different in the different processes if using a
    131:    multithreaded BLAS library, which may cause issues in ill-conditioned problems.

    133:    Level: advanced

    135: .seealso: [](sec:fn), `FNParallelType`, `FNSetParallel()`, `FN_PARALLEL_SYNCHRONIZED`
    136: M*/

    138: /*MC
    139:    FN_PARALLEL_SYNCHRONIZED - In matrix function evaluation, only the first MPI
    140:    process performs the computation.

    142:    Note:
    143:    When this parallel mode is selected, only the first MPI process performs the
    144:    computation and then the computed matrix is broadcast to the other
    145:    processes in the communicator. This communication is done automatically at
    146:    the end of `FNEvaluateFunctionMat()` or `FNEvaluateFunctionMatVec()`.

    148:    Level: advanced

    150: .seealso: [](sec:fn), `FNParallelType`, `FNSetParallel()`, `FN_PARALLEL_REDUNDANT`
    151: M*/

    153: SLEPC_EXTERN PetscErrorCode FNCreate(MPI_Comm,FN*);
    154: SLEPC_EXTERN PetscErrorCode FNSetType(FN,FNType);
    155: SLEPC_EXTERN PetscErrorCode FNGetType(FN,FNType*);
    156: SLEPC_EXTERN PetscErrorCode FNSetOptionsPrefix(FN,const char[]);
    157: SLEPC_EXTERN PetscErrorCode FNAppendOptionsPrefix(FN,const char[]);
    158: SLEPC_EXTERN PetscErrorCode FNGetOptionsPrefix(FN,const char*[]);
    159: SLEPC_EXTERN PetscErrorCode FNSetFromOptions(FN);
    160: SLEPC_EXTERN PetscErrorCode FNView(FN,PetscViewer);
    161: SLEPC_EXTERN PetscErrorCode FNViewFromOptions(FN,PetscObject,const char[]);
    162: SLEPC_EXTERN PetscErrorCode FNDestroy(FN*);
    163: SLEPC_EXTERN PetscErrorCode FNDuplicate(FN,MPI_Comm,FN*);

    165: SLEPC_EXTERN PetscErrorCode FNSetScale(FN,PetscScalar,PetscScalar);
    166: SLEPC_EXTERN PetscErrorCode FNGetScale(FN,PetscScalar*,PetscScalar*);
    167: SLEPC_EXTERN PetscErrorCode FNSetMethod(FN,PetscInt);
    168: SLEPC_EXTERN PetscErrorCode FNGetMethod(FN,PetscInt*);
    169: SLEPC_EXTERN PetscErrorCode FNSetParallel(FN,FNParallelType);
    170: SLEPC_EXTERN PetscErrorCode FNGetParallel(FN,FNParallelType*);

    172: SLEPC_EXTERN PetscErrorCode FNEvaluateFunction(FN,PetscScalar,PetscScalar*);
    173: SLEPC_EXTERN PetscErrorCode FNEvaluateDerivative(FN,PetscScalar,PetscScalar*);
    174: SLEPC_EXTERN PetscErrorCode FNEvaluateFunctionMat(FN,Mat,Mat);
    175: SLEPC_EXTERN PetscErrorCode FNEvaluateFunctionMatVec(FN,Mat,Vec);

    177: SLEPC_EXTERN PetscFunctionList FNList;
    178: SLEPC_EXTERN PetscErrorCode FNRegister(const char[],PetscErrorCode(*)(FN));

    180: /* --------- options specific to particular functions -------- */

    182: SLEPC_EXTERN PetscErrorCode FNRationalSetNumerator(FN,PetscInt,PetscScalar[]);
    183: SLEPC_EXTERN PetscErrorCode FNRationalGetNumerator(FN,PetscInt*,PetscScalar*[]);
    184: SLEPC_EXTERN PetscErrorCode FNRationalSetDenominator(FN,PetscInt,PetscScalar[]);
    185: SLEPC_EXTERN PetscErrorCode FNRationalGetDenominator(FN,PetscInt*,PetscScalar*[]);

    187: SLEPC_EXTERN PetscErrorCode FNCombineSetChildren(FN,FNCombineType,FN,FN);
    188: SLEPC_EXTERN PetscErrorCode FNCombineGetChildren(FN,FNCombineType*,FN*,FN*);

    190: SLEPC_EXTERN PetscErrorCode FNPhiSetIndex(FN,PetscInt);
    191: SLEPC_EXTERN PetscErrorCode FNPhiGetIndex(FN,PetscInt*);