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*);