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