Actual source code: petscsnes.h

  1: /* $Id: petscsnes.h,v 1.111 2001/08/06 21:17:05 bsmith Exp $ */
  2: /*
  3:     User interface for the nonlinear solvers package.
  4: */
 7:  #include petscksp.h
  8: PETSC_EXTERN_CXX_BEGIN

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

 13:    Level: beginner

 15:   Concepts: nonlinear solvers

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

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

 26:    Level: beginner

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

 35: /* Logging support */
 36: extern int SNES_COOKIE;
 37: extern int SNES_Solve, SNES_LineSearch, SNES_FunctionEval, SNES_JacobianEval;


 40: EXTERN int SNESInitializePackage(const char[]);

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

 52: EXTERN int SNESAddOptionsChecker(int (*)(SNES));

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

 61: extern PetscFList SNESList;
 62: EXTERN int SNESRegisterDestroy(void);
 63: EXTERN int SNESRegisterAll(const char[]);

 65: EXTERN int SNESRegister(const char[],const char[],const char[],int(*)(SNES));

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

 70:    Synopsis:
 71:    int SNESRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(SNES))

 73:    Not collective

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

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

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

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

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

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

102:    Level: advanced

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

106: .keywords: SNES, nonlinear, register

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

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

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

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

145: typedef struct _p_MatSNESMFCtx   *MatSNESMFCtx;

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

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

156:    Synopsis:
157:    int MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(MatSNESMF))

159:    Not Collective

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

167:    Level: developer

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

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

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

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

186: .keywords: MatSNESMF, register

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

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

202: EXTERN int MatDAADSetSNES(Mat,SNES);

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

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

231: EXTERN int SNESSetApplicationContext(SNES,void *);
232: EXTERN int SNESGetApplicationContext(SNES,void **);

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

238:    Level: beginner

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

242: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
243: E*/
244: typedef enum {/* converged */
245:               SNES_CONVERGED_FNORM_ABS         =  2, /* F < F_minabs */
246:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* F < F_mintol*F_initial */
247:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* step size small */
248:               SNES_CONVERGED_GNORM_ABS         =  5, /* grad F < grad F_min */
249:               SNES_CONVERGED_TR_REDUCTION      =  6,
250:               SNES_CONVERGED_TR_DELTA          =  7,
251:               /* diverged */
252:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
253:               SNES_DIVERGED_FNORM_NAN          = -4,
254:               SNES_DIVERGED_MAX_IT             = -5,
255:               SNES_DIVERGED_LS_FAILURE         = -6,
256:               SNES_DIVERGED_TR_REDUCTION       = -7,
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: EXTERN int SNESSetConvergenceTest(SNES,int (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
261: EXTERN int SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
262: EXTERN int SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
263: EXTERN int SNESGetConvergedReason(SNES,SNESConvergedReason*);

265: EXTERN int SNESDAFormFunction(SNES,Vec,Vec,void*);
266: EXTERN int SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
267: EXTERN int SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
268: EXTERN int SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

270: /* --------- Solving systems of nonlinear equations --------------- */
271: EXTERN int SNESSetFunction(SNES,Vec,int(*)(SNES,Vec,Vec,void*),void *);
272: EXTERN int SNESComputeFunction(SNES,Vec,Vec);
273: EXTERN int SNESSetJacobian(SNES,Mat,Mat,int(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
274: EXTERN int SNESGetJacobian(SNES,Mat*,Mat*,void **,int(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
275: EXTERN int SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
276: EXTERN int SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

278: EXTERN int SNESSetLineSearch(SNES,int(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*),void*);
279: EXTERN int SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
280: EXTERN int SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
281: EXTERN int SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
282: EXTERN int SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);

284: EXTERN int SNESSetLineSearchCheck(SNES,int(*)(SNES,void*,Vec,PetscTruth*),void*);
285: EXTERN int SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal);
286: EXTERN int SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*);

288: EXTERN int SNESTestLocalMin(SNES snes);

290: /* Should this routine be private? */
291: EXTERN int SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);

293: PETSC_EXTERN_CXX_END
294: #endif