Actual source code: snesngmres.c

      1: #include <../src/snes/impls/ngmres/snesngmres.h>
      2: #include <petscblaslapack.h>
      3: #include <petscdm.h>

      5: const char *const SNESNGMRESRestartTypes[] = {"NONE", "PERIODIC", "DIFFERENCE", "SNESNGMRESRestartType", "SNES_NGMRES_RESTART_", NULL};
      6: const char *const SNESNGMRESSelectTypes[]  = {"NONE", "DIFFERENCE", "LINESEARCH", "SNESNGMRESSelectType", "SNES_NGMRES_SELECT_", NULL};

      8: PetscErrorCode SNESReset_NGMRES(SNES snes)
      9: {
     10:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

     12:   PetscFunctionBegin;
     13:   PetscCall(VecDestroyVecs(ngmres->msize, &ngmres->Fdot));
     14:   PetscCall(VecDestroyVecs(ngmres->msize, &ngmres->Xdot));
     15:   PetscCall(SNESLineSearchDestroy(&ngmres->additive_linesearch));
     16:   PetscFunctionReturn(PETSC_SUCCESS);
     17: }

     19: PetscErrorCode SNESDestroy_NGMRES(SNES snes)
     20: {
     21:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

     23:   PetscFunctionBegin;
     24:   PetscCall(SNESReset_NGMRES(snes));
     25:   PetscCall(PetscFree4(ngmres->h, ngmres->beta, ngmres->xi, ngmres->q));
     26:   PetscCall(PetscFree3(ngmres->xnorms, ngmres->fnorms, ngmres->s));
     27: #if defined(PETSC_USE_COMPLEX)
     28:   PetscCall(PetscFree(ngmres->rwork));
     29: #endif
     30:   PetscCall(PetscFree(ngmres->work));
     31:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetSelectType_C", NULL));
     32:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetRestartType_C", NULL));
     33:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetRestartFmRise_C", NULL));
     34:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESGetRestartFmRise_C", NULL));
     35:   PetscCall(PetscFree(snes->data));
     36:   PetscFunctionReturn(PETSC_SUCCESS);
     37: }

     39: PetscErrorCode SNESSetUp_NGMRES(SNES snes)
     40: {
     41:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;
     42:   PetscInt     msize, hsize;
     43:   DM           dm;

     45:   PetscFunctionBegin;
     46:   PetscCheck(!snes->npc || snes->npcside != PC_LEFT || snes->functype != SNES_FUNCTION_UNPRECONDITIONED, PetscObjectComm((PetscObject)snes), PETSC_ERR_ARG_WRONGSTATE, "SNESNGMRES does not support left preconditioning with unpreconditioned function");
     47:   if (snes->npcside == PC_LEFT && snes->functype == SNES_FUNCTION_DEFAULT) snes->functype = SNES_FUNCTION_PRECONDITIONED;
     48:   PetscCall(SNESSetWorkVecs(snes, 5));

     50:   if (!snes->vec_sol) {
     51:     PetscCall(SNESGetDM(snes, &dm));
     52:     PetscCall(DMCreateGlobalVector(dm, &snes->vec_sol));
     53:   }

     55:   if (!ngmres->Xdot) PetscCall(VecDuplicateVecs(snes->vec_sol, ngmres->msize, &ngmres->Xdot));
     56:   if (!ngmres->Fdot) PetscCall(VecDuplicateVecs(snes->vec_sol, ngmres->msize, &ngmres->Fdot));
     57:   if (!ngmres->setup_called) {
     58:     msize = ngmres->msize; /* restart size */
     59:     hsize = msize * msize;

     61:     /* explicit least squares minimization solve */
     62:     PetscCall(PetscCalloc4(hsize, &ngmres->h, msize, &ngmres->beta, msize, &ngmres->xi, hsize, &ngmres->q));
     63:     PetscCall(PetscMalloc3(msize, &ngmres->xnorms, msize, &ngmres->fnorms, msize, &ngmres->s));
     64:     ngmres->nrhs = 1;
     65:     PetscCall(PetscBLASIntCast(msize, &ngmres->lda));
     66:     PetscCall(PetscBLASIntCast(msize, &ngmres->ldb));
     67:     PetscCall(PetscBLASIntCast(12 * msize, &ngmres->lwork));
     68: #if defined(PETSC_USE_COMPLEX)
     69:     PetscCall(PetscMalloc1(ngmres->lwork, &ngmres->rwork));
     70: #endif
     71:     PetscCall(PetscMalloc1(ngmres->lwork, &ngmres->work));
     72:   }

     74:   ngmres->setup_called = PETSC_TRUE;
     75:   PetscFunctionReturn(PETSC_SUCCESS);
     76: }

     78: static PetscErrorCode SNESSetFromOptions_NGMRES(SNES snes, PetscOptionItems PetscOptionsObject)
     79: {
     80:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;
     81:   PetscBool    debug  = PETSC_FALSE;

     83:   PetscFunctionBegin;
     84:   PetscOptionsHeadBegin(PetscOptionsObject, "SNES NGMRES options");
     85:   PetscCall(PetscOptionsEnum("-snes_ngmres_select_type", "Select type", "SNESNGMRESSetSelectType", SNESNGMRESSelectTypes, (PetscEnum)ngmres->select_type, (PetscEnum *)&ngmres->select_type, NULL));
     86:   PetscCall(PetscOptionsEnum("-snes_ngmres_restart_type", "Restart type", "SNESNGMRESSetRestartType", SNESNGMRESRestartTypes, (PetscEnum)ngmres->restart_type, (PetscEnum *)&ngmres->restart_type, NULL));
     87:   PetscCall(PetscOptionsBool("-snes_ngmres_candidate", "Use candidate storage", "SNES", ngmres->candidate, &ngmres->candidate, NULL));
     88:   PetscCall(PetscOptionsBool("-snes_ngmres_approxfunc", "Linearly approximate the function", "SNES", ngmres->approxfunc, &ngmres->approxfunc, NULL));
     89:   PetscCall(PetscOptionsInt("-snes_ngmres_m", "Number of directions", "SNES", ngmres->msize, &ngmres->msize, NULL));
     90:   PetscCall(PetscOptionsInt("-snes_ngmres_restart", "Iterations before forced restart", "SNES", ngmres->restart_periodic, &ngmres->restart_periodic, NULL));
     91:   PetscCall(PetscOptionsInt("-snes_ngmres_restart_it", "Tolerance iterations before restart", "SNES", ngmres->restart_it, &ngmres->restart_it, NULL));
     92:   PetscCall(PetscOptionsBool("-snes_ngmres_monitor", "Monitor actions of NGMRES", "SNES", ngmres->monitor ? PETSC_TRUE : PETSC_FALSE, &debug, NULL));
     93:   if (debug) ngmres->monitor = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)snes));
     94:   PetscCall(PetscOptionsReal("-snes_ngmres_gammaA", "Residual selection constant", "SNES", ngmres->gammaA, &ngmres->gammaA, NULL));
     95:   PetscCall(PetscOptionsReal("-snes_ngmres_gammaC", "Residual restart constant", "SNES", ngmres->gammaC, &ngmres->gammaC, NULL));
     96:   PetscCall(PetscOptionsReal("-snes_ngmres_epsilonB", "Difference selection constant", "SNES", ngmres->epsilonB, &ngmres->epsilonB, NULL));
     97:   PetscCall(PetscOptionsReal("-snes_ngmres_deltaB", "Difference residual selection constant", "SNES", ngmres->deltaB, &ngmres->deltaB, NULL));
     98:   PetscCall(PetscOptionsBool("-snes_ngmres_restart_fm_rise", "Restart on F_M residual rise", "SNESNGMRESSetRestartFmRise", ngmres->restart_fm_rise, &ngmres->restart_fm_rise, NULL));
     99:   PetscOptionsHeadEnd();
    100:   if (ngmres->gammaA > ngmres->gammaC && ngmres->gammaC > 2.) ngmres->gammaC = ngmres->gammaA;
    101:   if (ngmres->select_type == SNES_NGMRES_SELECT_LINESEARCH) {
    102:     PetscCall(SNESNGMRESGetAdditiveLineSearch_Private(snes, &ngmres->additive_linesearch));
    103:     PetscCall(SNESLineSearchSetFromOptions(ngmres->additive_linesearch));
    104:   }
    105:   PetscFunctionReturn(PETSC_SUCCESS);
    106: }

    108: PetscErrorCode SNESView_NGMRES(SNES snes, PetscViewer viewer)
    109: {
    110:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;
    111:   PetscBool    isascii;

    113:   PetscFunctionBegin;
    114:   PetscCall(PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &isascii));
    115:   if (isascii) {
    116:     PetscCall(PetscViewerASCIIPrintf(viewer, "  Number of stored past updates: %" PetscInt_FMT "\n", ngmres->msize));
    117:     if (ngmres->select_type == SNES_NGMRES_SELECT_DIFFERENCE) {
    118:       PetscCall(PetscViewerASCIIPrintf(viewer, "  Residual selection: gammaA=%1.0e, gammaC=%1.0e\n", (double)ngmres->gammaA, (double)ngmres->gammaC));
    119:       PetscCall(PetscViewerASCIIPrintf(viewer, "  Difference restart: epsilonB=%1.0e, deltaB=%1.0e\n", (double)ngmres->epsilonB, (double)ngmres->deltaB));
    120:       PetscCall(PetscViewerASCIIPrintf(viewer, "  Restart on F_M residual increase: %s\n", PetscBools[ngmres->restart_fm_rise]));
    121:     }
    122:     if (ngmres->additive_linesearch) {
    123:       PetscCall(PetscViewerASCIIPrintf(viewer, "  Additive line-search details:\n"));
    124:       PetscCall(SNESLineSearchView(ngmres->additive_linesearch, viewer));
    125:     }
    126:   }
    127:   PetscFunctionReturn(PETSC_SUCCESS);
    128: }

    130: static PetscErrorCode SNESSolve_NGMRES(SNES snes)
    131: {
    132:   SNES_NGMRES         *ngmres = (SNES_NGMRES *)snes->data;
    133:   Vec                  X, F, B, D, Y;         /* present solution, residual, and preconditioned residual */
    134:   Vec                  XA, FA, XM, FM;        /* candidate linear combination answers */
    135:   PetscReal            fnorm, fMnorm, fAnorm; /* coefficients and RHS to the minimization problem */
    136:   PetscReal            xnorm, xMnorm, xAnorm;
    137:   PetscReal            ynorm, yMnorm, yAnorm;
    138:   PetscInt             k, k_restart, l, ivec, restart_count = 0;
    139:   PetscReal            objmin, objM, objA, obj; /* support for objective functions minimization */
    140:   PetscBool            selectRestart;           /* solution selection data */
    141:   SNESConvergedReason  reason;
    142:   SNESLineSearchReason lssucceed;
    143:   SNESObjectiveFn     *objective;
    144:   /*
    145:       These two variables are initialized to prevent compilers/analyzers from producing false warnings about these variables being passed
    146:       to SNESNGMRESSelect_Private() without being set when SNES_NGMRES_RESTART_DIFFERENCE, the values are not used in the subroutines in that case
    147:       so the code is correct as written.
    148:   */
    149:   PetscReal dnorm = 0.0, dminnorm = 0.0;

    151:   PetscFunctionBegin;
    152:   PetscCheck(!snes->xl && !snes->xu && !snes->ops->computevariablebounds, PetscObjectComm((PetscObject)snes), PETSC_ERR_ARG_WRONGSTATE, "SNES solver %s does not support bounds", ((PetscObject)snes)->type_name);

    154:   PetscCall(PetscCitationsRegister(SNESCitation, &SNEScite));
    155:   /* variable initialization */
    156:   snes->reason = SNES_CONVERGED_ITERATING;
    157:   X            = snes->vec_sol;
    158:   F            = snes->vec_func;
    159:   B            = snes->vec_rhs;
    160:   XA           = snes->work[2];
    161:   FA           = snes->work[0];
    162:   D            = snes->work[1];

    164:   /* work for the line search */
    165:   Y  = snes->vec_sol_update;
    166:   XM = snes->work[3];
    167:   FM = snes->work[4];

    169:   PetscCall(PetscObjectSAWsTakeAccess((PetscObject)snes));
    170:   snes->iter = 0;
    171:   snes->norm = 0.;
    172:   PetscCall(PetscObjectSAWsGrantAccess((PetscObject)snes));

    174:   /* initialization */

    176:   if (snes->npc && snes->npcside == PC_LEFT) {
    177:     PetscCall(SNESApplyNPC(snes, X, NULL, F));
    178:     PetscCall(SNESGetConvergedReason(snes->npc, &reason));
    179:     if (reason < 0 && reason != SNES_DIVERGED_MAX_IT) {
    180:       snes->reason = SNES_DIVERGED_INNER;
    181:       PetscFunctionReturn(PETSC_SUCCESS);
    182:     }
    183:     PetscCall(VecNorm(F, NORM_2, &fnorm));
    184:   } else {
    185:     if (!snes->vec_func_init_set) PetscCall(SNESComputeFunction(snes, X, F));
    186:     else snes->vec_func_init_set = PETSC_FALSE;

    188:     PetscCall(VecNorm(F, NORM_2, &fnorm));
    189:     SNESCheckFunctionNorm(snes, fnorm);
    190:   }
    191:   PetscCall(SNESGetObjective(snes, &objective, NULL));
    192:   objmin = fnorm;
    193:   if (objective) PetscCall(SNESComputeObjective(snes, X, &objmin));
    194:   obj = objmin;

    196:   PetscCall(PetscObjectSAWsTakeAccess((PetscObject)snes));
    197:   snes->norm = fnorm;
    198:   PetscCall(PetscObjectSAWsGrantAccess((PetscObject)snes));
    199:   PetscCall(SNESLogConvergenceHistory(snes, fnorm, 0));
    200:   PetscCall(SNESConverged(snes, 0, 0.0, 0.0, fnorm));
    201:   PetscCall(SNESMonitor(snes, 0, fnorm));
    202:   if (snes->reason) PetscFunctionReturn(PETSC_SUCCESS);
    203:   PetscCall(SNESNGMRESUpdateSubspace_Private(snes, 0, 0, F, fnorm, X));

    205:   k_restart = 1;
    206:   l         = 1;
    207:   ivec      = 0;
    208:   for (k = 1; k < snes->max_its + 1; k++) {
    209:     /* Call general purpose update function */
    210:     PetscTryTypeMethod(snes, update, snes->iter);

    212:     /* Computation of x^M */
    213:     if (snes->npc && snes->npcside == PC_RIGHT) {
    214:       PetscCall(VecCopy(X, XM));
    215:       PetscCall(SNESSetInitialFunction(snes->npc, F));

    217:       PetscCall(PetscLogEventBegin(SNES_NPCSolve, snes->npc, XM, B, 0));
    218:       PetscCall(SNESSolve(snes->npc, B, XM));
    219:       PetscCall(PetscLogEventEnd(SNES_NPCSolve, snes->npc, XM, B, 0));

    221:       PetscCall(SNESGetConvergedReason(snes->npc, &reason));
    222:       if (reason < 0 && reason != SNES_DIVERGED_MAX_IT) {
    223:         snes->reason = SNES_DIVERGED_INNER;
    224:         PetscFunctionReturn(PETSC_SUCCESS);
    225:       }
    226:       PetscCall(SNESGetNPCFunction(snes, FM, &fMnorm));
    227:     } else {
    228:       /* no preconditioner -- just take gradient descent with line search */
    229:       PetscCall(VecCopy(F, Y));
    230:       PetscCall(VecCopy(F, FM));
    231:       PetscCall(VecCopy(X, XM));

    233:       fMnorm = fnorm;

    235:       PetscCall(SNESLineSearchApply(snes->linesearch, XM, FM, &fMnorm, Y));
    236:       PetscCall(SNESLineSearchGetReason(snes->linesearch, &lssucceed));
    237:       if (lssucceed) {
    238:         if (++snes->numFailures >= snes->maxFailures) {
    239:           snes->reason = SNES_DIVERGED_LINE_SEARCH;
    240:           PetscFunctionReturn(PETSC_SUCCESS);
    241:         }
    242:       }
    243:     }
    244:     if (objective) PetscCall(SNESComputeObjective(snes, XM, &objM));
    245:     else objM = fMnorm;
    246:     objmin = PetscMin(objmin, objM);

    248:     PetscCall(SNESNGMRESFormCombinedSolution_Private(snes, ivec, l, XM, FM, fMnorm, X, XA, FA));

    250:     /* differences for selection and restart */
    251:     if (ngmres->restart_type == SNES_NGMRES_RESTART_DIFFERENCE || ngmres->select_type == SNES_NGMRES_SELECT_DIFFERENCE) {
    252:       PetscCall(SNESNGMRESNorms_Private(snes, l, X, F, XM, FM, XA, FA, D, &dnorm, &dminnorm, &xMnorm, NULL, &yMnorm, &xAnorm, &fAnorm, &yAnorm));
    253:     } else {
    254:       PetscCall(SNESNGMRESNorms_Private(snes, l, X, F, XM, FM, XA, FA, D, NULL, NULL, &xMnorm, NULL, &yMnorm, &xAnorm, &fAnorm, &yAnorm));
    255:     }
    256:     if (objective) PetscCall(SNESComputeObjective(snes, XA, &objA));
    257:     else objA = fAnorm;
    258:     SNESCheckFunctionNorm(snes, fnorm);

    260:     /* combination (additive) or selection (multiplicative) of the N-GMRES solution */
    261:     PetscCall(SNESNGMRESSelect_Private(snes, k_restart, XM, FM, xMnorm, fMnorm, yMnorm, objM, XA, FA, xAnorm, fAnorm, yAnorm, objA, dnorm, objmin, dminnorm, X, F, Y, &xnorm, &fnorm, &ynorm));
    262:     if (objective) PetscCall(SNESComputeObjective(snes, X, &obj));
    263:     else obj = fnorm;
    264:     selectRestart = PETSC_FALSE;

    266:     if (ngmres->restart_type == SNES_NGMRES_RESTART_DIFFERENCE) {
    267:       PetscCall(SNESNGMRESSelectRestart_Private(snes, l, obj, objM, objA, dnorm, objmin, dminnorm, &selectRestart));

    269:       /* if the restart conditions persist for more than restart_it iterations, restart. */
    270:       if (selectRestart) restart_count++;
    271:       else restart_count = 0;
    272:     } else if (ngmres->restart_type == SNES_NGMRES_RESTART_PERIODIC) {
    273:       if (k_restart > ngmres->restart_periodic) {
    274:         if (ngmres->monitor) PetscCall(PetscViewerASCIIPrintf(ngmres->monitor, "periodic restart after %" PetscInt_FMT " iterations\n", k_restart));
    275:         restart_count = ngmres->restart_it;
    276:       }
    277:     }

    279:     ivec = k_restart % ngmres->msize; /* replace the last used part of the subspace */

    281:     /* restart after restart conditions have persisted for a fixed number of iterations */
    282:     if (restart_count >= ngmres->restart_it) {
    283:       if (ngmres->monitor) PetscCall(PetscViewerASCIIPrintf(ngmres->monitor, "Restarted at iteration %" PetscInt_FMT "\n", k_restart));
    284:       restart_count = 0;
    285:       k_restart     = 1;
    286:       l             = 1;
    287:       ivec          = 0;
    288:       /* q_{00} = nu */
    289:       PetscCall(SNESNGMRESUpdateSubspace_Private(snes, 0, 0, FM, fMnorm, XM));
    290:     } else {
    291:       /* select the current size of the subspace */
    292:       if (l < ngmres->msize) l++;
    293:       k_restart++;
    294:       /* place the current entry in the list of previous entries */
    295:       if (ngmres->candidate) {
    296:         objmin = PetscMin(objmin, objM);
    297:         PetscCall(SNESNGMRESUpdateSubspace_Private(snes, ivec, l, FM, fMnorm, XM));
    298:       } else {
    299:         objmin = PetscMin(objmin, obj);
    300:         PetscCall(SNESNGMRESUpdateSubspace_Private(snes, ivec, l, F, fnorm, X));
    301:       }
    302:     }

    304:     PetscCall(PetscObjectSAWsTakeAccess((PetscObject)snes));
    305:     snes->iter  = k;
    306:     snes->norm  = fnorm;
    307:     snes->ynorm = ynorm;
    308:     snes->xnorm = xnorm;
    309:     PetscCall(PetscObjectSAWsGrantAccess((PetscObject)snes));
    310:     PetscCall(SNESLogConvergenceHistory(snes, snes->norm, snes->iter));
    311:     PetscCall(SNESConverged(snes, snes->iter, 0, 0, fnorm));
    312:     PetscCall(SNESMonitor(snes, snes->iter, snes->norm));
    313:     if (snes->reason) PetscFunctionReturn(PETSC_SUCCESS);
    314:   }
    315:   snes->reason = SNES_DIVERGED_MAX_IT;
    316:   PetscFunctionReturn(PETSC_SUCCESS);
    317: }

    319: /*@
    320:   SNESNGMRESSetRestartFmRise - Increase the restart count if the step x_M increases the residual F_M inside a `SNESNGMRES` solve

    322:   Input Parameters:
    323: + snes - the `SNES` context.
    324: - flg  - boolean value deciding whether to use the option or not, default is `PETSC_FALSE`

    326:   Options Database Key:
    327: . -snes_ngmres_restart_fm_rise - Increase the restart count if the step x_M increases the residual F_M

    329:   Level: advanced

    331:   Notes:
    332:   If the proposed step x_M increases the residual F_M, it might be trying to get out of a stagnation area.
    333:   To help the solver do that, remove the current stored solutions and residuals whenever F_M increases.

    335:   This option must be used with the `SNESNGMRES` `SNESNGMRESRestartType` of `SNES_NGMRES_RESTART_DIFFERENCE`

    337: .seealso: [](ch_snes), `SNES`, `SNES_NGMRES_RESTART_DIFFERENCE`, `SNESNGMRES`, `SNESNGMRESRestartType`, `SNESNGMRESSetRestartType()`
    338:   @*/
    339: PetscErrorCode SNESNGMRESSetRestartFmRise(SNES snes, PetscBool flg)
    340: {
    341:   PetscErrorCode (*f)(SNES, PetscBool);

    343:   PetscFunctionBegin;
    344:   PetscCall(PetscObjectQueryFunction((PetscObject)snes, "SNESNGMRESSetRestartFmRise_C", &f));
    345:   if (f) PetscCall((f)(snes, flg));
    346:   PetscFunctionReturn(PETSC_SUCCESS);
    347: }

    349: static PetscErrorCode SNESNGMRESSetRestartFmRise_NGMRES(SNES snes, PetscBool flg)
    350: {
    351:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

    353:   PetscFunctionBegin;
    354:   ngmres->restart_fm_rise = flg;
    355:   PetscFunctionReturn(PETSC_SUCCESS);
    356: }

    358: PetscErrorCode SNESNGMRESGetRestartFmRise(SNES snes, PetscBool *flg)
    359: {
    360:   PetscErrorCode (*f)(SNES, PetscBool *);

    362:   PetscFunctionBegin;
    363:   PetscCall(PetscObjectQueryFunction((PetscObject)snes, "SNESNGMRESGetRestartFmRise_C", &f));
    364:   if (f) PetscCall((f)(snes, flg));
    365:   PetscFunctionReturn(PETSC_SUCCESS);
    366: }

    368: static PetscErrorCode SNESNGMRESGetRestartFmRise_NGMRES(SNES snes, PetscBool *flg)
    369: {
    370:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

    372:   PetscFunctionBegin;
    373:   *flg = ngmres->restart_fm_rise;
    374:   PetscFunctionReturn(PETSC_SUCCESS);
    375: }

    377: /*@
    378:   SNESNGMRESSetRestartType - Sets the restart type for `SNESNGMRES`.

    380:   Logically Collective

    382:   Input Parameters:
    383: + snes  - the iterative context
    384: - rtype - restart type, see `SNESNGMRESRestartType`

    386:   Options Database Keys:
    387: + -snes_ngmres_restart_type<difference,periodic,none> - set the restart type
    388: - -snes_ngmres_restart <30>                           - sets the number of iterations before restart for periodic

    390:   Level: intermediate

    392: .seealso: [](ch_snes), `SNES`, `SNES_NGMRES_RESTART_DIFFERENCE`, `SNESNGMRES`, `SNESNGMRESRestartType`, `SNESNGMRESSetRestartFmRise()`,
    393:           `SNESNGMRESSetSelectType()`
    394: @*/
    395: PetscErrorCode SNESNGMRESSetRestartType(SNES snes, SNESNGMRESRestartType rtype)
    396: {
    397:   PetscFunctionBegin;
    399:   PetscTryMethod(snes, "SNESNGMRESSetRestartType_C", (SNES, SNESNGMRESRestartType), (snes, rtype));
    400:   PetscFunctionReturn(PETSC_SUCCESS);
    401: }

    403: /*@
    404:   SNESNGMRESSetSelectType - Sets the selection type for `SNESNGMRES`.  This determines how the candidate solution and
    405:   combined solution are used to create the next iterate.

    407:   Logically Collective

    409:   Input Parameters:
    410: + snes  - the iterative context
    411: - stype - selection type, see `SNESNGMRESSelectType`

    413:   Options Database Key:
    414: . -snes_ngmres_select_type<difference,none,linesearch> - select type

    416:   Level: intermediate

    418:   Note:
    419:   The default line search used is the `SNESLINESEARCHSECANT` line search and it requires two additional function evaluations.

    421: .seealso: [](ch_snes), `SNES`, `SNESNGMRES`, `SNESNGMRESSelectType`, `SNES_NGMRES_SELECT_NONE`, `SNES_NGMRES_SELECT_DIFFERENCE`, `SNES_NGMRES_SELECT_LINESEARCH`,
    422:           `SNESNGMRESSetRestartType()`
    423: @*/
    424: PetscErrorCode SNESNGMRESSetSelectType(SNES snes, SNESNGMRESSelectType stype)
    425: {
    426:   PetscFunctionBegin;
    428:   PetscTryMethod(snes, "SNESNGMRESSetSelectType_C", (SNES, SNESNGMRESSelectType), (snes, stype));
    429:   PetscFunctionReturn(PETSC_SUCCESS);
    430: }

    432: static PetscErrorCode SNESNGMRESSetSelectType_NGMRES(SNES snes, SNESNGMRESSelectType stype)
    433: {
    434:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

    436:   PetscFunctionBegin;
    437:   ngmres->select_type = stype;
    438:   PetscFunctionReturn(PETSC_SUCCESS);
    439: }

    441: static PetscErrorCode SNESNGMRESSetRestartType_NGMRES(SNES snes, SNESNGMRESRestartType rtype)
    442: {
    443:   SNES_NGMRES *ngmres = (SNES_NGMRES *)snes->data;

    445:   PetscFunctionBegin;
    446:   ngmres->restart_type = rtype;
    447:   PetscFunctionReturn(PETSC_SUCCESS);
    448: }

    450: /*MC
    451:   SNESNGMRES - An implementation of the Nonlinear Generalized Minimum Residual method, Nonlinear GMRES, or N-GMRES {cite}`ow1`, {cite}`bruneknepleysmithtu15` for solving
    452:                nonlinear systems with `SNES`.

    454:    Level: beginner

    456:    Options Database Keys:
    457: +  -snes_ngmres_select_type<difference,none,linesearch> - choose the select between candidate and combined solution
    458: .  -snes_ngmres_restart_type<difference,none,periodic>  - choose the restart conditions
    459: .  -snes_ngmres_candidate                               - Use `SNESNGMRES` variant which combines candidate solutions instead of actual solutions
    460: .  -snes_ngmres_m                                       - Number of stored previous solutions and residuals
    461: .  -snes_ngmres_restart_it                              - Number of iterations the restart conditions hold before restart
    462: .  -snes_ngmres_gammaA                                  - Residual tolerance for solution select between the candidate and combination
    463: .  -snes_ngmres_gammaC                                  - Residual tolerance for restart
    464: .  -snes_ngmres_epsilonB                                - Difference tolerance between subsequent solutions triggering restart
    465: .  -snes_ngmres_deltaB                                  - Difference tolerance between residuals triggering restart
    466: .  -snes_ngmres_restart_fm_rise                         - Restart on residual rise from $x_M$ step
    467: .  -snes_ngmres_monitor                                 - Prints relevant information about the nonlinear GNMRES iterations
    468: .  -snes_linesearch_type <basic,l2,cp>                  - Line search type used for the default smoother
    469: -  -snes_ngmres_additive_snes_linesearch_type           - line search type used to select between the candidate and combined solution with additive select type

    471:    Notes:
    472:    The N-GMRES method combines m previous solutions into a minimum-residual solution by solving a small linearized
    473:    optimization problem at each iteration.

    475:    Very similar to the `SNESANDERSON` algorithm.

    477:    Unlike the linear GMRES algorithm this algorithm does not compute a Krylov subspace using the Arnoldi process. Instead it stores a
    478:    collection of previous solutions and the residuals $ F(x) - b $ at those solutions.

    480:    This algorithm ignores any Jacobian provided with `SNESSetJacobian()`

    482:    Only supports left non-linear preconditioning.

    484: .seealso: [](ch_snes), `SNESCreate()`, `SNES`, `SNESSetType()`, `SNESType`, `SNESANDERSON`, `SNESNGMRESSetSelectType()`, `SNESNGMRESSetRestartType()`,
    485:           `SNESNGMRESSetRestartFmRise()`, `SNESNGMRESSelectType`, `SNESNGMRESRestartType`
    486: M*/

    488: PETSC_EXTERN PetscErrorCode SNESCreate_NGMRES(SNES snes)
    489: {
    490:   SNES_NGMRES   *ngmres;
    491:   SNESLineSearch linesearch;

    493:   PetscFunctionBegin;
    494:   snes->ops->destroy        = SNESDestroy_NGMRES;
    495:   snes->ops->setup          = SNESSetUp_NGMRES;
    496:   snes->ops->setfromoptions = SNESSetFromOptions_NGMRES;
    497:   snes->ops->view           = SNESView_NGMRES;
    498:   snes->ops->solve          = SNESSolve_NGMRES;
    499:   snes->ops->reset          = SNESReset_NGMRES;

    501:   snes->usesnpc = PETSC_TRUE;
    502:   snes->usesksp = PETSC_FALSE;
    503:   snes->npcside = PC_RIGHT;

    505:   snes->alwayscomputesfinalresidual = PETSC_TRUE;

    507:   PetscCall(PetscNew(&ngmres));
    508:   snes->data    = (void *)ngmres;
    509:   ngmres->msize = 30;

    511:   PetscCall(SNESParametersInitialize(snes));
    512:   PetscObjectParameterSetDefault(snes, max_funcs, 30000);
    513:   PetscObjectParameterSetDefault(snes, max_its, 10000);

    515:   ngmres->candidate = PETSC_FALSE;

    517:   PetscCall(SNESGetLineSearch(snes, &linesearch));
    518:   if (!((PetscObject)linesearch)->type_name) PetscCall(SNESLineSearchSetType(linesearch, SNESLINESEARCHBASIC));

    520:   ngmres->additive_linesearch = NULL;
    521:   ngmres->approxfunc          = PETSC_FALSE;
    522:   ngmres->restart_it          = 2;
    523:   ngmres->restart_periodic    = 30;
    524:   ngmres->gammaA              = 2.0;
    525:   ngmres->gammaC              = 2.0;
    526:   ngmres->deltaB              = 0.9;
    527:   ngmres->epsilonB            = 0.1;
    528:   ngmres->restart_fm_rise     = PETSC_FALSE;

    530:   ngmres->restart_type = SNES_NGMRES_RESTART_DIFFERENCE;
    531:   ngmres->select_type  = SNES_NGMRES_SELECT_DIFFERENCE;

    533:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetSelectType_C", SNESNGMRESSetSelectType_NGMRES));
    534:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetRestartType_C", SNESNGMRESSetRestartType_NGMRES));
    535:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESSetRestartFmRise_C", SNESNGMRESSetRestartFmRise_NGMRES));
    536:   PetscCall(PetscObjectComposeFunction((PetscObject)snes, "SNESNGMRESGetRestartFmRise_C", SNESNGMRESGetRestartFmRise_NGMRES));
    537:   PetscFunctionReturn(PETSC_SUCCESS);
    538: }