Date: 2026-07-30T21:14:20+00:00

Actual source code: snespc.c

      1: #include <petsc/private/snesimpl.h>

      3: /*@
      4:   SNESApplyNPC - Calls `SNESSolve()` on the preconditioner for the `SNES`

      6:   Collective

      8:   Input Parameters:
      9: + snes - the `SNES` context
     10: . x    - input vector
     11: - f    - optional; the function evaluation on `x`

     13:   Output Parameter:
     14: . y - function vector, as set by `SNESSetFunction()`

     16:   Level: developer

     18:   Note:
     19:   `SNESComputeFunction()` should be called on `x` before `SNESApplyNPC()` is called, as it is
     20:   with `SNESComuteJacobian()`.

     22: .seealso: [](ch_snes), `SNES`, `SNESGetNPC()`, `SNESSetNPC()`, `SNESComputeFunction()`
     23: @*/
     24: PetscErrorCode SNESApplyNPC(SNES snes, Vec x, Vec f, Vec y)
     25: {
     26:   PetscFunctionBegin;
     30:   PetscCheckSameComm(snes, 1, x, 2);
     31:   PetscCheckSameComm(snes, 1, y, 4);
     32:   PetscCall(VecValidValues_Internal(x, 2, PETSC_TRUE));
     33:   if (snes->npc) {
     34:     if (f) PetscCall(SNESSetInitialFunction(snes->npc, f));
     35:     PetscCall(VecCopy(x, y));
     36:     PetscCall(PetscLogEventBegin(SNES_NPCSolve, snes->npc, x, y, 0));
     37:     PetscCall(SNESSolve(snes->npc, snes->vec_rhs, y));
     38:     PetscCall(PetscLogEventEnd(SNES_NPCSolve, snes->npc, x, y, 0));
     39:     PetscCall(VecAYPX(y, -1.0, x));
     40:   }
     41:   PetscFunctionReturn(PETSC_SUCCESS);
     42: }

     44: /*@
     45:   SNESComputeFunctionDefaultNPC - Compute the residual by applying the attached nonlinear preconditioner when one is present, otherwise defer to `SNESComputeFunction()`

     47:   Collective

     49:   Input Parameters:
     50: + snes - the `SNES` context
     51: - X    - the current iterate

     53:   Output Parameter:
     54: . F - the residual vector produced by the nonlinear preconditioner (or the standard function evaluation)

     56:   Level: developer

     58:   Note:
     59:   Used as the residual callback for `SNESMF` when a nonlinear preconditioner is set on the outer `SNES`.

     61: .seealso: [](ch_snes), `SNES`, `SNESSetNPC()`, `SNESApplyNPC()`, `SNESComputeFunction()`, `SNESGetNPCFunction()`
     62: @*/
     63: PetscErrorCode SNESComputeFunctionDefaultNPC(SNES snes, Vec X, Vec F)
     64: {
     65:   /* This is to be used as an argument to SNESMF -- NOT as a "function" */
     66:   SNESConvergedReason reason;

     68:   PetscFunctionBegin;
     69:   if (snes->npc) {
     70:     PetscCall(SNESApplyNPC(snes, X, NULL, F));
     71:     PetscCall(SNESGetConvergedReason(snes->npc, &reason));
     72:     if (reason < 0 && reason != SNES_DIVERGED_MAX_IT) PetscCall(SNESSetFunctionDomainError(snes));
     73:   } else {
     74:     PetscCall(SNESComputeFunction(snes, X, F));
     75:   }
     76:   PetscFunctionReturn(PETSC_SUCCESS);
     77: }

     79: /*@
     80:   SNESGetNPCFunction - Gets the current function value (for the callback function provided by `SNESSetFunction()`,
     81:   and its norm from a nonlinear preconditioner after `SNESSolve()` has been called on that `SNES`

     83:   Collective

     85:   Input Parameter:
     86: . snes - the `SNES` context

     88:   Output Parameters:
     89: + F     - function vector
     90: - fnorm - the norm of `F`

     92:   Level: developer

     94: .seealso: [](ch_snes), `SNES`, `SNESGetNPC()`, `SNESSetNPC()`, `SNESComputeFunction()`, `SNESApplyNPC()`, `SNESSolve()`
     95: @*/
     96: PetscErrorCode SNESGetNPCFunction(SNES snes, Vec F, PetscReal *fnorm)
     97: {
     98:   PCSide           npcside;
     99:   SNESFunctionType functype;
    100:   SNESNormSchedule normschedule;
    101:   Vec              FPC, XPC;

    103:   PetscFunctionBegin;
    105:   if (fnorm) PetscAssertPointer(fnorm, 3);
    106:   PetscCheck(snes->npc, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "No nonlinear preconditioner set");
    107:   PetscCall(SNESGetNPCSide(snes->npc, &npcside));
    108:   PetscCall(SNESGetFunctionType(snes->npc, &functype));
    109:   PetscCall(SNESGetNormSchedule(snes->npc, &normschedule));

    111:   /* check if the function is valid based upon how the inner solver is preconditioned */
    112:   if (normschedule != SNES_NORM_NONE && normschedule != SNES_NORM_INITIAL_ONLY && (npcside == PC_RIGHT || functype == SNES_FUNCTION_UNPRECONDITIONED)) {
    113:     PetscCall(SNESGetFunction(snes->npc, &FPC, NULL, NULL));
    114:     PetscCheck(FPC, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Nonlinear preconditioner has no function");
    115:     if (fnorm) PetscCall(VecNorm(FPC, NORM_2, fnorm));
    116:     PetscCall(VecCopy(FPC, F));
    117:   } else {
    118:     PetscCall(SNESGetSolution(snes->npc, &XPC));
    119:     PetscCheck(XPC, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Nonlinear preconditioner has no solution");
    120:     PetscCall(SNESComputeFunction(snes->npc, XPC, F));
    121:     if (fnorm) PetscCall(VecNorm(F, NORM_2, fnorm));
    122:   }
    123:   PetscFunctionReturn(PETSC_SUCCESS);
    124: }