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 SNESLS          "ls"
     30: #define SNESTR          "tr"
     31: #define SNESTEST        "test"
     32: #define SNESType char*

     34: /* Logging support */

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

     41: EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*);
     42: EXTERN PetscErrorCode SNESDestroy(SNES);
     43: EXTERN PetscErrorCode SNESSetType(SNES,const SNESType);
     44: EXTERN PetscErrorCode SNESSetMonitor(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
     45: EXTERN PetscErrorCode SNESClearMonitor(SNES);
     46: EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth);
     47: EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
     48: EXTERN PetscErrorCode SNESSetUp(SNES,Vec);
     49: EXTERN PetscErrorCode SNESSolve(SNES,Vec);

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

     53: EXTERN PetscErrorCode SNESSetRhsBC(SNES, PetscErrorCode (*)(SNES, Vec, void *));
     54: EXTERN PetscErrorCode SNESDefaultRhsBC(SNES, Vec, void *);
     55: EXTERN PetscErrorCode SNESSetSolutionBC(SNES, PetscErrorCode (*)(SNES, Vec, void *));
     56: EXTERN PetscErrorCode SNESDefaultSolutionBC(SNES, Vec, void *);
     57: EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
     58: EXTERN PetscErrorCode SNESDefaultUpdate(SNES, PetscInt);

     61: EXTERN PetscErrorCode SNESRegisterDestroy(void);
     62: EXTERN PetscErrorCode SNESRegisterAll(const char[]);

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

     66: /*MC
     67:    SNESRegisterDynamic - Adds a method to the nonlinear solver package.

     69:    Synopsis:
     70:    PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES))

     72:    Not collective

     74:    Input Parameters:
     75: +  name_solver - name of a new user-defined solver
     76: .  path - path (either absolute or relative) the library containing this solver
     77: .  name_create - name of routine to create method context
     78: -  routine_create - routine to create method context

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

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

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

     90:    Sample usage:
     91: .vb
     92:    SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
     93:                 "MySolverCreate",MySolverCreate);
     94: .ve

     96:    Then, your solver can be chosen with the procedural interface via
     97: $     SNESSetType(snes,"my_solver")
     98:    or at runtime via the option
     99: $     -snes_type my_solver

    101:    Level: advanced

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

    105: .keywords: SNES, nonlinear, register

    107: .seealso: SNESRegisterAll(), SNESRegisterDestroy()
    108: M*/
    109: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
    110: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
    111: #else
    112: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
    113: #endif

    115: EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*);
    116: EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*);
    117: EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*);
    118: EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,void**,PetscErrorCode(**)(SNES,Vec,Vec,void*));
    119: EXTERN PetscErrorCode SNESView(SNES,PetscViewer);

    121: EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]);
    122: EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]);
    123: EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,char*[]);
    124: EXTERN PetscErrorCode SNESSetFromOptions(SNES);

    126: EXTERN PetscErrorCode MatCreateSNESMF(SNES,Vec,Mat*);
    127: EXTERN PetscErrorCode MatCreateMF(Vec,Mat*);
    128: EXTERN PetscErrorCode MatSNESMFSetBase(Mat,Vec);
    129: EXTERN PetscErrorCode MatSNESMFComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    130: EXTERN PetscErrorCode MatSNESMFSetFunction(Mat,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
    131: EXTERN PetscErrorCode MatSNESMFSetFunctioni(Mat,PetscErrorCode (*)(PetscInt,Vec,PetscScalar*,void*));
    132: EXTERN PetscErrorCode MatSNESMFSetFunctioniBase(Mat,PetscErrorCode (*)(Vec,void*));
    133: EXTERN PetscErrorCode MatSNESMFAddNullSpace(Mat,MatNullSpace);
    134: EXTERN PetscErrorCode MatSNESMFSetHHistory(Mat,PetscScalar[],PetscInt);
    135: EXTERN PetscErrorCode MatSNESMFResetHHistory(Mat);
    136: EXTERN PetscErrorCode MatSNESMFSetFunctionError(Mat,PetscReal);
    137: EXTERN PetscErrorCode MatSNESMFSetPeriod(Mat,PetscInt);
    138: EXTERN PetscErrorCode MatSNESMFGetH(Mat,PetscScalar *);
    139: EXTERN PetscErrorCode MatSNESMFKSPMonitor(KSP,PetscInt,PetscReal,void *);
    140: EXTERN PetscErrorCode MatSNESMFSetFromOptions(Mat);
    141: EXTERN PetscErrorCode MatSNESMFCheckPositivity(Vec,Vec,PetscScalar*,void*);
    142: EXTERN PetscErrorCode MatSNESMFSetCheckh(Mat,PetscErrorCode (*)(Vec,Vec,PetscScalar*,void*),void*);

    144: typedef struct _p_MatSNESMFCtx   *MatSNESMFCtx;

    146: #define MATSNESMF_DEFAULT "default"
    147: #define MATSNESMF_WP      "wp"
    148: #define MatSNESMFType char*
    149: EXTERN PetscErrorCode MatSNESMFSetType(Mat,const MatSNESMFType);
    150: EXTERN PetscErrorCode MatSNESMFRegister(const char[],const char[],const char[],PetscErrorCode (*)(MatSNESMFCtx));

    152: /*MC
    153:    MatSNESMFRegisterDynamic - Adds a method to the MatSNESMF registry.

    155:    Synopsis:
    156:    PetscErrorCode MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(MatSNESMF))

    158:    Not Collective

    160:    Input Parameters:
    161: +  name_solver - name of a new user-defined compute-h module
    162: .  path - path (either absolute or relative) the library containing this solver
    163: .  name_create - name of routine to create method context
    164: -  routine_create - routine to create method context

    166:    Level: developer

    168:    Notes:
    169:    MatSNESMFRegisterDynamic) may be called multiple times to add several user-defined solvers.

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

    174:    Sample usage:
    175: .vb
    176:    MatSNESMFRegisterDynamic"my_h",/home/username/my_lib/lib/libO/solaris/mylib.a,
    177:                "MyHCreate",MyHCreate);
    178: .ve

    180:    Then, your solver can be chosen with the procedural interface via
    181: $     MatSNESMFSetType(mfctx,"my_h")
    182:    or at runtime via the option
    183: $     -snes_mf_type my_h

    185: .keywords: MatSNESMF, register

    187: .seealso: MatSNESMFRegisterAll(), MatSNESMFRegisterDestroy()
    188: M*/
    189: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
    190: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0)
    191: #else
    192: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d)
    193: #endif

    195: EXTERN PetscErrorCode MatSNESMFRegisterAll(const char[]);
    196: EXTERN PetscErrorCode MatSNESMFRegisterDestroy(void);
    197: EXTERN PetscErrorCode MatSNESMFDefaultSetUmin(Mat,PetscReal);
    198: EXTERN PetscErrorCode MatSNESMFWPSetComputeNormA(Mat,PetscTruth);
    199: EXTERN PetscErrorCode MatSNESMFWPSetComputeNormU(Mat,PetscTruth);

    201: EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);

    203: EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
    204: EXTERN PetscErrorCode SNESDefaultMonitor(SNES,PetscInt,PetscReal,void *);
    205: EXTERN PetscErrorCode SNESRatioMonitor(SNES,PetscInt,PetscReal,void *);
    206: EXTERN PetscErrorCode SNESSetRatioMonitor(SNES);
    207: EXTERN PetscErrorCode SNESVecViewMonitor(SNES,PetscInt,PetscReal,void *);
    208: EXTERN PetscErrorCode SNESVecViewResidualMonitor(SNES,PetscInt,PetscReal,void *);
    209: EXTERN PetscErrorCode SNESVecViewUpdateMonitor(SNES,PetscInt,PetscReal,void *);
    210: EXTERN PetscErrorCode SNESDefaultSMonitor(SNES,PetscInt,PetscReal,void *);
    211: EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
    212: EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
    213: EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
    214: EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
    215: EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscScalar*);
    216: EXTERN PetscErrorCode SNESGetNumberUnsuccessfulSteps(SNES,PetscInt*);
    217: EXTERN PetscErrorCode SNESSetMaximumUnsuccessfulSteps(SNES,PetscInt);
    218: EXTERN PetscErrorCode SNESGetMaximumUnsuccessfulSteps(SNES,PetscInt*);
    219: EXTERN PetscErrorCode SNESGetNumberLinearIterations(SNES,PetscInt*);
    220: EXTERN PetscErrorCode SNES_KSP_SetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
    221: EXTERN PetscErrorCode SNES_KSP_SetConvergenceTestEW(SNES);

    223: /*
    224:      Reuse the default KSP monitor routines for SNES
    225: */
    226: EXTERN PetscErrorCode SNESLGMonitorCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
    227: EXTERN PetscErrorCode SNESLGMonitor(SNES,PetscInt,PetscReal,void*);
    228: EXTERN PetscErrorCode SNESLGMonitorDestroy(PetscDrawLG);

    230: EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
    231: EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **);

    233: /*E
    234:     SNESConvergedReason - reason a SNES method was said to
    235:          have converged or diverged

    237:    Level: beginner

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

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

    245: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
    246: E*/
    247: typedef enum {/* converged */
    248:               SNES_CONVERGED_FNORM_ABS         =  2, /* F < F_minabs */
    249:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* F < F_mintol*F_initial */
    250:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* step size small */
    251:               SNES_CONVERGED_TR_DELTA          =  7,
    252:               /* diverged */
    253:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
    254:               SNES_DIVERGED_FNORM_NAN          = -4,
    255:               SNES_DIVERGED_MAX_IT             = -5,
    256:               SNES_DIVERGED_LS_FAILURE         = -6,
    257:               SNES_DIVERGED_LOCAL_MIN          = -8,  /* || J^T b || is small, implies converged to local minimum of F() */
    258:               SNES_CONVERGED_ITERATING         =  0} SNESConvergedReason;

    260: /*MC
    261:      SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol

    263:    Level: beginner

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

    267: M*/

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

    272:    Level: beginner

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

    276: M*/

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

    282:    Level: beginner

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

    286: M*/

    288: /*MC
    289:      SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
    290:          argument to SNESSetTolerances()

    292:    Level: beginner

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

    296: M*/

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

    302:    Level: beginner

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

    306: M*/

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

    311:    Level: beginner

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

    315: M*/

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

    320:    Level: beginner

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

    324: M*/

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

    329:    Level: beginner

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

    333: M*/

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

    338:    Level: beginner

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

    342: M*/

    344: EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
    345: EXTERN PetscErrorCode SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    346: EXTERN PetscErrorCode SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
    347: EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);

    349: EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*);
    350: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    351: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    352: EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

    354: /* --------- Solving systems of nonlinear equations --------------- */
    355: EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
    356: EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
    357: EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
    358: EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,void **,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
    359: EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    360: EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    361: EXTERN PetscErrorCode SNESSetRhs(SNES,Vec);
    362: EXTERN PetscErrorCode SNESSetLineSearch(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
    363: EXTERN PetscErrorCode SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    364: EXTERN PetscErrorCode SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    365: EXTERN PetscErrorCode SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
    366: EXTERN PetscErrorCode SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);

    368: EXTERN PetscErrorCode SNESSetLineSearchCheck(SNES,PetscErrorCode(*)(SNES,void*,Vec,PetscTruth*),void*);
    369: EXTERN PetscErrorCode SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal);
    370: EXTERN PetscErrorCode SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*);

    372: EXTERN PetscErrorCode SNESTestLocalMin(SNES snes);

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

    378: #endif