Actual source code: petscsnes.h

      1: /*
      2:     User interface for the nonlinear solvers package.
      3: */
     6:  #include petscksp.h

      9: /*S
     10:      SNES - Abstract PETSc object that manages all nonlinear solves

     12:    Level: beginner

     14:   Concepts: nonlinear solvers

     16: .seealso:  SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC
     17: S*/
     18: typedef struct _p_SNES* SNES;

     20: /*E
     21:     SNESType - String with the name of a PETSc SNES method or the creation function
     22:        with an optional dynamic library name, for example
     23:        http://www.mcs.anl.gov/petsc/lib.a:mysnescreate()

     25:    Level: beginner

     27: .seealso: SNESSetType(), SNES
     28: E*/
     29: #define SNESType const char*
     30: #define SNESLS          "ls"
     31: #define SNESTR          "tr"
     32: #define SNESTEST        "test"

     34: /* Logging support */

     37: EXTERN PetscErrorCode  SNESInitializePackage(const char[]);

     39: EXTERN PetscErrorCode  SNESCreate(MPI_Comm,SNES*);
     40: EXTERN PetscErrorCode  SNESDestroy(SNES);
     41: EXTERN PetscErrorCode  SNESSetType(SNES,SNESType);
     42: EXTERN PetscErrorCode  SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
     43: EXTERN PetscErrorCode  SNESMonitorCancel(SNES);
     44: EXTERN PetscErrorCode  SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth);
     45: EXTERN PetscErrorCode  SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
     46: EXTERN PetscErrorCode  SNESSetUp(SNES);
     47: EXTERN PetscErrorCode  SNESSolve(SNES,Vec,Vec);

     49: EXTERN PetscErrorCode  SNESAddOptionsChecker(PetscErrorCode (*)(SNES));

     51: EXTERN PetscErrorCode  SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
     52: EXTERN PetscErrorCode  SNESDefaultUpdate(SNES, PetscInt);

     55: EXTERN PetscErrorCode  SNESRegisterDestroy(void);
     56: EXTERN PetscErrorCode  SNESRegisterAll(const char[]);

     58: EXTERN PetscErrorCode  SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES));

     60: /*MC
     61:    SNESRegisterDynamic - Adds a method to the nonlinear solver package.

     63:    Synopsis:
     64:    PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES))

     66:    Not collective

     68:    Input Parameters:
     69: +  name_solver - name of a new user-defined solver
     70: .  path - path (either absolute or relative) the library containing this solver
     71: .  name_create - name of routine to create method context
     72: -  routine_create - routine to create method context

     74:    Notes:
     75:    SNESRegisterDynamic() may be called multiple times to add several user-defined solvers.

     77:    If dynamic libraries are used, then the fourth input argument (routine_create)
     78:    is ignored.

     80:    Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
     81:    and others of the form ${any_environmental_variable} occuring in pathname will be
     82:    replaced with appropriate values.

     84:    Sample usage:
     85: .vb
     86:    SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
     87:                 "MySolverCreate",MySolverCreate);
     88: .ve

     90:    Then, your solver can be chosen with the procedural interface via
     91: $     SNESSetType(snes,"my_solver")
     92:    or at runtime via the option
     93: $     -snes_type my_solver

     95:    Level: advanced

     97:     Note: If your function is not being put into a shared library then use SNESRegister() instead

     99: .keywords: SNES, nonlinear, register

    101: .seealso: SNESRegisterAll(), SNESRegisterDestroy()
    102: M*/
    103: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
    104: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
    105: #else
    106: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
    107: #endif

    109: EXTERN PetscErrorCode  SNESGetKSP(SNES,KSP*);
    110: EXTERN PetscErrorCode  SNESSetKSP(SNES,KSP);
    111: EXTERN PetscErrorCode  SNESGetSolution(SNES,Vec*);
    112: EXTERN PetscErrorCode  SNESGetSolutionUpdate(SNES,Vec*);
    113: EXTERN PetscErrorCode  SNESGetFunction(SNES,Vec*,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
    114: EXTERN PetscErrorCode  SNESView(SNES,PetscViewer);

    116: EXTERN PetscErrorCode  SNESSetOptionsPrefix(SNES,const char[]);
    117: EXTERN PetscErrorCode  SNESAppendOptionsPrefix(SNES,const char[]);
    118: EXTERN PetscErrorCode  SNESGetOptionsPrefix(SNES,const char*[]);
    119: EXTERN PetscErrorCode  SNESSetFromOptions(SNES);

    121: EXTERN PetscErrorCode  MatCreateSNESMF(SNES,Mat*);
    122: EXTERN PetscErrorCode  MatMFFDComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

    124: EXTERN PetscErrorCode  MatDAADSetSNES(Mat,SNES);

    126: EXTERN PetscErrorCode  SNESGetType(SNES,SNESType*);
    127: EXTERN PetscErrorCode  SNESMonitorDefault(SNES,PetscInt,PetscReal,void *);
    128: EXTERN PetscErrorCode  SNESMonitorRatio(SNES,PetscInt,PetscReal,void *);
    129: EXTERN PetscErrorCode  SNESMonitorSetRatio(SNES,PetscViewerASCIIMonitor);
    130: EXTERN PetscErrorCode  SNESMonitorSolution(SNES,PetscInt,PetscReal,void *);
    131: EXTERN PetscErrorCode  SNESMonitorResidual(SNES,PetscInt,PetscReal,void *);
    132: EXTERN PetscErrorCode  SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *);
    133: EXTERN PetscErrorCode  SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *);
    134: EXTERN PetscErrorCode  SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
    135: EXTERN PetscErrorCode  SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
    136: EXTERN PetscErrorCode  SNESSetTrustRegionTolerance(SNES,PetscReal);
    137: EXTERN PetscErrorCode  SNESGetFunctionNorm(SNES,PetscReal*);
    138: EXTERN PetscErrorCode  SNESGetIterationNumber(SNES,PetscInt*);

    140: EXTERN PetscErrorCode  SNESGetNonlinearStepFailures(SNES,PetscInt*);
    141: EXTERN PetscErrorCode  SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
    142: EXTERN PetscErrorCode  SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);

    144: EXTERN PetscErrorCode  SNESGetLinearSolveIterations(SNES,PetscInt*);
    145: EXTERN PetscErrorCode  SNESGetLinearSolveFailures(SNES,PetscInt*);
    146: EXTERN PetscErrorCode  SNESSetMaxLinearSolveFailures(SNES,PetscInt);
    147: EXTERN PetscErrorCode  SNESGetMaxLinearSolveFailures(SNES,PetscInt*);

    149: EXTERN PetscErrorCode  SNESKSPSetUseEW(SNES,PetscTruth);
    150: EXTERN PetscErrorCode  SNESKSPGetUseEW(SNES,PetscTruth*);
    151: EXTERN PetscErrorCode  SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
    152: EXTERN PetscErrorCode  SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);

    154: /*
    155:      Reuse the default KSP monitor routines for SNES
    156: */
    157: EXTERN PetscErrorCode  SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
    158: EXTERN PetscErrorCode  SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
    159: EXTERN PetscErrorCode  SNESMonitorLGDestroy(PetscDrawLG);

    161: EXTERN PetscErrorCode  SNESSetApplicationContext(SNES,void *);
    162: EXTERN PetscErrorCode  SNESGetApplicationContext(SNES,void **);

    164: /*E
    165:     SNESConvergedReason - reason a SNES method was said to
    166:          have converged or diverged

    168:    Level: beginner

    170:    Notes: this must match finclude/petscsnes.h

    172:    Developer note: The string versions of these are in
    173:      src/snes/interface/snes.c called convergedreasons.
    174:      If these enums are changed you much change those.

    176: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
    177: E*/
    178: typedef enum {/* converged */
    179:               SNES_CONVERGED_FNORM_ABS         =  2, /* F < F_minabs */
    180:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* F < F_mintol*F_initial */
    181:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* step size small */
    182:               SNES_CONVERGED_ITS               =  5, /* maximum iterations reached */
    183:               SNES_CONVERGED_TR_DELTA          =  7,
    184:               /* diverged */
    185:               SNES_DIVERGED_FUNCTION_DOMAIN    = -1,
    186:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
    187:               SNES_DIVERGED_LINEAR_SOLVE       = -3,
    188:               SNES_DIVERGED_FNORM_NAN          = -4,
    189:               SNES_DIVERGED_MAX_IT             = -5,
    190:               SNES_DIVERGED_LS_FAILURE         = -6,
    191:               SNES_DIVERGED_LOCAL_MIN          = -8,  /* || J^T b || is small, implies converged to local minimum of F() */
    192:               SNES_CONVERGED_ITERATING         =  0} SNESConvergedReason;

    195: /*MC
    196:      SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol

    198:    Level: beginner

    200: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    202: M*/

    204: /*MC
    205:      SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess

    207:    Level: beginner

    209: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    211: M*/

    213: /*MC
    214:      SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current
    215:           solution and xtol is the 4th argument to SNESSetTolerances()

    217:    Level: beginner

    219: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    221: M*/

    223: /*MC
    224:      SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
    225:          argument to SNESSetTolerances()

    227:    Level: beginner

    229: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    231: M*/

    233: /*MC
    234:      SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
    235:       is usually caused by a division of 0 by 0.

    237:    Level: beginner

    239: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    241: M*/

    243: /*MC
    244:      SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested

    246:    Level: beginner

    248: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    250: M*/

    252: /*MC
    253:      SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS

    255:    Level: beginner

    257: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    259: M*/

    261: /*MC
    262:      SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero

    264:    Level: beginner

    266: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    268: M*/

    270: /*MC
    271:      SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()

    273:    Level: beginner

    275: .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()

    277: M*/

    279: EXTERN PetscErrorCode  SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
    280: EXTERN PetscErrorCode  SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    281: EXTERN PetscErrorCode  SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    282: EXTERN PetscErrorCode  SNESConverged_LS(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    283: EXTERN PetscErrorCode  SNESConverged_TR(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    284: EXTERN PetscErrorCode  SNESGetConvergedReason(SNES,SNESConvergedReason*);

    286: EXTERN PetscErrorCode  SNESDAFormFunction(SNES,Vec,Vec,void*);
    287: EXTERN PetscErrorCode  SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    288: EXTERN PetscErrorCode  SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    289: EXTERN PetscErrorCode  SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

    291: /* --------- Solving systems of nonlinear equations --------------- */
    292: EXTERN PetscErrorCode  SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
    293: EXTERN PetscErrorCode  SNESComputeFunction(SNES,Vec,Vec);
    294: EXTERN PetscErrorCode  SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
    295: EXTERN PetscErrorCode  SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **);
    296: EXTERN PetscErrorCode  SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    297: EXTERN PetscErrorCode  SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    298: EXTERN PetscErrorCode  SNESSetRhs(SNES,Vec);
    299: EXTERN PetscErrorCode  SNESGetRhs(SNES,Vec*);

    301: /* --------- Routines specifically for line search methods --------------- */
    302: EXTERN PetscErrorCode  SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
    303: EXTERN PetscErrorCode  SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    304: EXTERN PetscErrorCode  SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    305: EXTERN PetscErrorCode  SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    306: EXTERN PetscErrorCode  SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);

    308: EXTERN PetscErrorCode  SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscTruth*,PetscTruth*),void*);
    309: EXTERN PetscErrorCode  SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscTruth*),void*);
    310: EXTERN PetscErrorCode  SNESLineSearchSetParams(SNES,PetscReal,PetscReal,PetscReal);
    311: EXTERN PetscErrorCode  SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*,PetscReal*);

    313: EXTERN PetscErrorCode  SNESTestLocalMin(SNES);
    314: EXTERN PetscErrorCode  SNESSetSolution(SNES,Vec);

    316: /* Should this routine be private? */
    317: EXTERN PetscErrorCode  SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);

    320: #endif