Actual source code: fnphi.c

      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:    Phi functions
     12:       phi_0(x) = exp(x)
     13:       phi_1(x) = (exp(x)-1)/x
     14:       phi_k(x) = (phi_{k-1}(x)-1/(k-1)!)/x
     15: */

     17: #include <slepc/private/fnimpl.h>

     19: typedef struct {
     20:   PetscInt k;    /* index of the phi-function, defaults to k=1 */
     21:   Mat      H;    /* auxiliary matrix of order m+k */
     22:   Mat      F;    /* auxiliary matrix to store exp(H) */
     23: } FN_PHI;

     25: #define MAX_INDEX 10

     27: static const PetscReal rfactorial[MAX_INDEX+2] = { 1, 1, 0.5, 1.0/6, 1.0/24, 1.0/120, 1.0/720, 1.0/5040, 1.0/40320, 1.0/362880, 1.0/3628800, 1.0/39916800 };

     29: static PetscErrorCode FNEvaluateFunction_Phi(FN fn,PetscScalar x,PetscScalar *y)
     30: {
     31:   FN_PHI      *ctx = (FN_PHI*)fn->data;
     32:   PetscInt    i;
     33:   PetscScalar phi[MAX_INDEX+1];

     35:   PetscFunctionBegin;
     36:   if (x==0.0) *y = rfactorial[ctx->k];
     37:   else {
     38:     phi[0] = PetscExpScalar(x);
     39:     for (i=1;i<=ctx->k;i++) phi[i] = (phi[i-1]-rfactorial[i-1])/x;
     40:     *y = phi[ctx->k];
     41:   }
     42:   PetscFunctionReturn(PETSC_SUCCESS);
     43: }

     45: static PetscErrorCode FNEvaluateDerivative_Phi(FN fn,PetscScalar x,PetscScalar *y)
     46: {
     47:   FN_PHI      *ctx = (FN_PHI*)fn->data;
     48:   PetscInt    i;
     49:   PetscScalar phi[MAX_INDEX+2];

     51:   PetscFunctionBegin;
     52:   if (x==0.0) *y = rfactorial[ctx->k+1];
     53:   else {
     54:     phi[0] = PetscExpScalar(x);
     55:     for (i=1;i<=ctx->k+1;i++) phi[i] = (phi[i-1]-rfactorial[i-1])/x;
     56:     *y = phi[ctx->k] - phi[ctx->k+1]*(PetscReal)ctx->k;
     57:   }
     58:   PetscFunctionReturn(PETSC_SUCCESS);
     59: }

     61: static PetscErrorCode FNEvaluateFunctionMatVec_Phi(FN fn,Mat A,Vec v)
     62: {
     63:   FN_PHI            *ctx = (FN_PHI*)fn->data;
     64:   PetscInt          i,j,m,n,nh;
     65:   PetscScalar       *Ha,*va,sfactor=1.0;
     66:   const PetscScalar *Aa,*Fa;

     68:   PetscFunctionBegin;
     69:   PetscCall(MatGetSize(A,&m,NULL));
     70:   n = m+ctx->k;
     71:   if (ctx->H) {
     72:     PetscCall(MatGetSize(ctx->H,&nh,NULL));
     73:     if (n!=nh) {
     74:       PetscCall(MatDestroy(&ctx->H));
     75:       PetscCall(MatDestroy(&ctx->F));
     76:     }
     77:   }
     78:   if (!ctx->H) {
     79:     PetscCall(MatCreateDense(PETSC_COMM_SELF,n,n,n,n,NULL,&ctx->H));
     80:     PetscCall(MatCreateDense(PETSC_COMM_SELF,n,n,n,n,NULL,&ctx->F));
     81:   }
     82:   PetscCall(MatDenseGetArray(ctx->H,&Ha));
     83:   PetscCall(MatDenseGetArrayRead(A,&Aa));
     84:   for (j=0;j<m;j++) PetscCall(PetscArraycpy(Ha+j*n,Aa+j*m,m));
     85:   PetscCall(MatDenseRestoreArrayRead(A,&Aa));
     86:   if (ctx->k) {
     87:     for (j=0;j<m;j++) for (i=m;i<n;i++) Ha[i+j*n] = 0.0;
     88:     for (j=m;j<n;j++) for (i=0;i<n;i++) Ha[i+j*n] = 0.0;
     89:     Ha[0+m*n] = fn->alpha;
     90:     for (j=m+1;j<n;j++) Ha[j-1+j*n] = fn->alpha;
     91:   }
     92:   PetscCall(MatDenseRestoreArray(ctx->H,&Ha));

     94:   PetscCall(FNEvaluateFunctionMat_Exp_Higham(fn,ctx->H,ctx->F));

     96:   PetscCall(MatDenseGetArrayRead(ctx->F,&Fa));
     97:   PetscCall(VecGetArray(v,&va));
     98:   if (ctx->k) {
     99:     sfactor = PetscPowScalarInt(fn->alpha,-ctx->k);
    100:     for (i=0;i<m;i++) va[i] = sfactor*Fa[i+(n-1)*n];
    101:   } else {
    102:     for (i=0;i<m;i++) va[i] = sfactor*Fa[i+0*n];
    103:   }
    104:   PetscCall(VecRestoreArray(v,&va));
    105:   PetscCall(MatDenseRestoreArrayRead(ctx->F,&Fa));
    106:   PetscFunctionReturn(PETSC_SUCCESS);
    107: }

    109: static PetscErrorCode FNPhiSetIndex_Phi(FN fn,PetscInt k)
    110: {
    111:   FN_PHI         *ctx = (FN_PHI*)fn->data;

    113:   PetscFunctionBegin;
    114:   PetscCheck(k>=0,PetscObjectComm((PetscObject)fn),PETSC_ERR_ARG_OUTOFRANGE,"Index cannot be negative");
    115:   PetscCheck(k<=MAX_INDEX,PetscObjectComm((PetscObject)fn),PETSC_ERR_ARG_OUTOFRANGE,"Phi functions only implemented for k<=%d",MAX_INDEX);
    116:   if (k!=ctx->k) {
    117:     ctx->k = k;
    118:     PetscCall(MatDestroy(&ctx->H));
    119:     PetscCall(MatDestroy(&ctx->F));
    120:   }
    121:   PetscFunctionReturn(PETSC_SUCCESS);
    122: }

    124: /*@
    125:    FNPhiSetIndex - Sets the index of the $\varphi$-function.

    127:    Logically Collective

    129:    Input Parameters:
    130: +  fn - the math function context
    131: -  k  - the index

    133:    Notes:
    134:    The $\varphi$-functions are defined as
    135:    $$\begin{align}
    136:      \varphi_0(x)&=e^x,\\
    137:      \varphi_1(x)&=\frac{e^x-1}{x},\\
    138:      \varphi_k(x)&=\frac{\varphi_{k-1}(x)-1/(k-1)!}{x}.
    139:    \end{align}$$
    140:    The default index is $k=1$.

    142:    Level: intermediate

    144: .seealso: [](sec:fn), `FNPHI`, `FNPhiGetIndex()`
    145: @*/
    146: PetscErrorCode FNPhiSetIndex(FN fn,PetscInt k)
    147: {
    148:   PetscFunctionBegin;
    151:   PetscTryMethod(fn,"FNPhiSetIndex_C",(FN,PetscInt),(fn,k));
    152:   PetscFunctionReturn(PETSC_SUCCESS);
    153: }

    155: static PetscErrorCode FNPhiGetIndex_Phi(FN fn,PetscInt *k)
    156: {
    157:   FN_PHI *ctx = (FN_PHI*)fn->data;

    159:   PetscFunctionBegin;
    160:   *k = ctx->k;
    161:   PetscFunctionReturn(PETSC_SUCCESS);
    162: }

    164: /*@
    165:    FNPhiGetIndex - Gets the index of the $\varphi$-function.

    167:    Not Collective

    169:    Input Parameter:
    170: .  fn - the math function context

    172:    Output Parameter:
    173: .  k  - the index

    175:    Level: intermediate

    177: .seealso: [](sec:fn), `FNPHI`, `FNPhiSetIndex()`
    178: @*/
    179: PetscErrorCode FNPhiGetIndex(FN fn,PetscInt *k)
    180: {
    181:   PetscFunctionBegin;
    183:   PetscAssertPointer(k,2);
    184:   PetscUseMethod(fn,"FNPhiGetIndex_C",(FN,PetscInt*),(fn,k));
    185:   PetscFunctionReturn(PETSC_SUCCESS);
    186: }

    188: static PetscErrorCode FNView_Phi(FN fn,PetscViewer viewer)
    189: {
    190:   FN_PHI         *ctx = (FN_PHI*)fn->data;
    191:   PetscBool      isascii;
    192:   char           str[50],strx[50];

    194:   PetscFunctionBegin;
    195:   PetscCall(PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii));
    196:   if (isascii) {
    197:     PetscCall(PetscViewerASCIIPrintf(viewer,"  phi_%" PetscInt_FMT ": ",ctx->k));
    198:     PetscCall(PetscViewerASCIIUseTabs(viewer,PETSC_FALSE));
    199:     if (fn->beta!=(PetscScalar)1.0) {
    200:       PetscCall(SlepcSNPrintfScalar(str,sizeof(str),fn->beta,PETSC_TRUE));
    201:       PetscCall(PetscViewerASCIIPrintf(viewer,"%s*",str));
    202:     }
    203:     if (fn->alpha==(PetscScalar)1.0) PetscCall(PetscSNPrintf(strx,sizeof(strx),"x"));
    204:     else {
    205:       PetscCall(SlepcSNPrintfScalar(str,sizeof(str),fn->alpha,PETSC_TRUE));
    206:       PetscCall(PetscSNPrintf(strx,sizeof(strx),"(%s*x)",str));
    207:     }
    208:     if (!ctx->k) PetscCall(PetscViewerASCIIPrintf(viewer,"exp(%s)\n",strx));
    209:     else if (ctx->k==1) PetscCall(PetscViewerASCIIPrintf(viewer,"(exp(%s)-1)/%s\n",strx,strx));
    210:     else PetscCall(PetscViewerASCIIPrintf(viewer,"(phi_%" PetscInt_FMT "(%s)-1/%" PetscInt_FMT "!)/%s\n",ctx->k-1,strx,ctx->k-1,strx));
    211:     PetscCall(PetscViewerASCIIUseTabs(viewer,PETSC_TRUE));
    212:   }
    213:   PetscFunctionReturn(PETSC_SUCCESS);
    214: }

    216: static PetscErrorCode FNSetFromOptions_Phi(FN fn,PetscOptionItems PetscOptionsObject)
    217: {
    218:   FN_PHI         *ctx = (FN_PHI*)fn->data;
    219:   PetscInt       k;
    220:   PetscBool      flag;

    222:   PetscFunctionBegin;
    223:   PetscOptionsHeadBegin(PetscOptionsObject,"FN Phi Options");

    225:     PetscCall(PetscOptionsInt("-fn_phi_index","Index of the phi-function","FNPhiSetIndex",ctx->k,&k,&flag));
    226:     if (flag) PetscCall(FNPhiSetIndex(fn,k));

    228:   PetscOptionsHeadEnd();
    229:   PetscFunctionReturn(PETSC_SUCCESS);
    230: }

    232: static PetscErrorCode FNDuplicate_Phi(FN fn,MPI_Comm comm,FN *newfn)
    233: {
    234:   FN_PHI *ctx = (FN_PHI*)fn->data,*ctx2 = (FN_PHI*)(*newfn)->data;

    236:   PetscFunctionBegin;
    237:   ctx2->k = ctx->k;
    238:   PetscFunctionReturn(PETSC_SUCCESS);
    239: }

    241: static PetscErrorCode FNDestroy_Phi(FN fn)
    242: {
    243:   FN_PHI         *ctx = (FN_PHI*)fn->data;

    245:   PetscFunctionBegin;
    246:   PetscCall(MatDestroy(&ctx->H));
    247:   PetscCall(MatDestroy(&ctx->F));
    248:   PetscCall(PetscFree(fn->data));
    249:   PetscCall(PetscObjectComposeFunction((PetscObject)fn,"FNPhiSetIndex_C",NULL));
    250:   PetscCall(PetscObjectComposeFunction((PetscObject)fn,"FNPhiGetIndex_C",NULL));
    251:   PetscFunctionReturn(PETSC_SUCCESS);
    252: }

    254: /*MC
    255:    FNPHI - FNPHI = "phi" - One of the $\varphi$-functions $\varphi_0(x)$, $\varphi_1(x)$, ...,
    256:    where the index of the $\varphi$-function is specified with `FNPhiSetIndex()`.

    258:    Level: beginner

    260:    Notes:
    261:    The $\varphi$-functions are defined as
    262:    $$\begin{align}
    263:      \varphi_0(x)&=e^x,\\
    264:      \varphi_1(x)&=\frac{e^x-1}{x},\\
    265:      \varphi_k(x)&=\frac{\varphi_{k-1}(x)-1/(k-1)!}{x}.
    266:    \end{align}$$
    267:    The default index is $k=1$.

    269: .seealso: [](sec:fn), `FN`, `FNType`, `FNSetType()`, `FNPhiSetIndex()`
    270: M*/

    272: SLEPC_EXTERN PetscErrorCode FNCreate_Phi(FN fn)
    273: {
    274:   FN_PHI         *ctx;

    276:   PetscFunctionBegin;
    277:   PetscCall(PetscNew(&ctx));
    278:   fn->data = (void*)ctx;
    279:   ctx->k   = 1;

    281:   fn->ops->evaluatefunction          = FNEvaluateFunction_Phi;
    282:   fn->ops->evaluatederivative        = FNEvaluateDerivative_Phi;
    283:   fn->ops->evaluatefunctionmatvec[0] = FNEvaluateFunctionMatVec_Phi;
    284:   fn->ops->setfromoptions            = FNSetFromOptions_Phi;
    285:   fn->ops->view                      = FNView_Phi;
    286:   fn->ops->duplicate                 = FNDuplicate_Phi;
    287:   fn->ops->destroy                   = FNDestroy_Phi;
    288:   PetscCall(PetscObjectComposeFunction((PetscObject)fn,"FNPhiSetIndex_C",FNPhiSetIndex_Phi));
    289:   PetscCall(PetscObjectComposeFunction((PetscObject)fn,"FNPhiGetIndex_C",FNPhiGetIndex_Phi));
    290:   PetscFunctionReturn(PETSC_SUCCESS);
    291: }