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 petscsles.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, SLES, 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: typedef char *SNESType;

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


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

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

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

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

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

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

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

 69:    Synopsis:
 70:    int SNESRegisterDynamic(char *name_solver,char *path,char *name_create,int (*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 int SNESGetSLES(SNES,SLES*);
116: EXTERN int SNESGetSolution(SNES,Vec*);
117: EXTERN int SNESGetSolutionUpdate(SNES,Vec*);
118: EXTERN int SNESGetFunction(SNES,Vec*,void**,int(**)(SNES,Vec,Vec,void*));
119: EXTERN int SNESView(SNES,PetscViewer);

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

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

144: typedef struct _p_MatSNESMFCtx   *MatSNESMFCtx;

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

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

155:    Synopsis:
156:    int MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,int (*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 int MatSNESMFRegisterAll(const char[]);
196: EXTERN int MatSNESMFRegisterDestroy(void);
197: EXTERN int MatSNESMFDefaultSetUmin(Mat,PetscReal);
198: EXTERN int MatSNESMFWPSetComputeNormA(Mat,PetscTruth);
199: EXTERN int MatSNESMFWPSetComputeNormU(Mat,PetscTruth);

201: EXTERN int MatDAADSetSNES(Mat,SNES);

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

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

230: EXTERN int SNESSetApplicationContext(SNES,void *);
231: EXTERN int 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: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
242: E*/
243: typedef enum {/* converged */
244:               SNES_CONVERGED_FNORM_ABS         =  2, /* F < F_minabs */
245:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* F < F_mintol*F_initial */
246:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* step size small */
247:               SNES_CONVERGED_GNORM_ABS         =  5, /* grad F < grad F_min */
248:               SNES_CONVERGED_TR_REDUCTION      =  6,
249:               SNES_CONVERGED_TR_DELTA          =  7,
250:               /* diverged */
251:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
252:               SNES_DIVERGED_FNORM_NAN          = -4,
253:               SNES_DIVERGED_MAX_IT             = -5,
254:               SNES_DIVERGED_LS_FAILURE         = -6,
255:               SNES_DIVERGED_TR_REDUCTION       = -7,
256:               SNES_DIVERGED_LOCAL_MIN          = -8,  /* || J^T b || is small, implies converged to local minimum of F() */
257:               SNES_CONVERGED_ITERATING         =  0} SNESConvergedReason;

259: EXTERN int SNESSetConvergenceTest(SNES,int (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
260: EXTERN int SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
261: EXTERN int SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
262: EXTERN int SNESGetConvergedReason(SNES,SNESConvergedReason*);

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

269: /* --------- Solving systems of nonlinear equations --------------- */
270: EXTERN int SNESSetFunction(SNES,Vec,int(*)(SNES,Vec,Vec,void*),void *);
271: EXTERN int SNESComputeFunction(SNES,Vec,Vec);
272: EXTERN int SNESSetJacobian(SNES,Mat,Mat,int(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
273: EXTERN int SNESGetJacobian(SNES,Mat*,Mat*,void **,int(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
274: EXTERN int SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
275: EXTERN int SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
276: EXTERN int SNESSetLineSearch(SNES,int(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*),void*);
277: EXTERN int SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
278: EXTERN int SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
279: EXTERN int SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
280: EXTERN int SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*);
281: EXTERN int SNESSetLineSearchCheck(SNES,int(*)(SNES,void*,Vec,PetscTruth*),void*);
282: EXTERN int SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal);
283: EXTERN int SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*);

285: EXTERN int SNESTestLocalMin(SNES snes);

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

290: #endif