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

 35: /* Logging support */

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

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

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

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

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

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

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

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

 67:    Not collective

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

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

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

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

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

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

 96:    Level: advanced

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

100: .keywords: SNES, nonlinear, register

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

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

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

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

125: EXTERN PetscErrorCode  MatDAADSetSNES(Mat,SNES);

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

142: EXTERN PetscErrorCode  SNESGetNonlinearStepFailures(SNES,PetscInt*);
143: EXTERN PetscErrorCode  SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
144: EXTERN PetscErrorCode  SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
145: EXTERN PetscErrorCode  SNESGetNumberFunctionEvals(SNES,PetscInt*);

147: EXTERN PetscErrorCode  SNESSetLagPreconditioner(SNES,PetscInt);
148: EXTERN PetscErrorCode  SNESGetLagPreconditioner(SNES,PetscInt*);
149: EXTERN PetscErrorCode  SNESSetLagJacobian(SNES,PetscInt);
150: EXTERN PetscErrorCode  SNESGetLagJacobian(SNES,PetscInt*);

152: EXTERN PetscErrorCode  SNESGetLinearSolveIterations(SNES,PetscInt*);
153: EXTERN PetscErrorCode  SNESGetLinearSolveFailures(SNES,PetscInt*);
154: EXTERN PetscErrorCode  SNESSetMaxLinearSolveFailures(SNES,PetscInt);
155: EXTERN PetscErrorCode  SNESGetMaxLinearSolveFailures(SNES,PetscInt*);

157: EXTERN PetscErrorCode  SNESKSPSetUseEW(SNES,PetscTruth);
158: EXTERN PetscErrorCode  SNESKSPGetUseEW(SNES,PetscTruth*);
159: EXTERN PetscErrorCode  SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
160: EXTERN PetscErrorCode  SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);

162: EXTERN PetscErrorCode  SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
163: EXTERN PetscErrorCode  SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
164: EXTERN PetscErrorCode  SNESMonitorLGDestroy(PetscDrawLG);
165: EXTERN PetscErrorCode  SNESMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
166: EXTERN PetscErrorCode  SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*);
167: EXTERN PetscErrorCode  SNESMonitorLGRangeDestroy(PetscDrawLG);

169: EXTERN PetscErrorCode  SNESSetApplicationContext(SNES,void *);
170: EXTERN PetscErrorCode  SNESGetApplicationContext(SNES,void **);

172: EXTERN PetscErrorCode  SNESPythonSetType(SNES,const char[]);

174: EXTERN PetscErrorCode  SNESSetFunctionDomainError(SNES);
175: /*E
176:     SNESConvergedReason - reason a SNES method was said to 
177:          have converged or diverged

179:    Level: beginner

181:    The two most common reasons for divergence are 
182: $   1) an incorrectly coded or computed Jacobian or 
183: $   2) failure or lack of convergence in the linear system (in this case we recommend
184: $      testing with -pc_type lu to eliminate the linear solver as the cause of the problem).

186:    Diverged Reasons:
187: .    SNES_DIVERGED_LOCAL_MIN - this can only occur when using the line-search variant of SNES.
188:        The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2  this occurs
189:        at Q'(alpha) = s^T F'(x+alpha s)^T F(x+alpha s) = 0. If s is the Newton direction - F'(x)^(-1)F(x) then
190:        you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0
191:        Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton
192:        direction is a descent direction and the line search should succeed if alpha is small enough.

194:        If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction 
195:        is NOT a descent direction so the line search will fail. All one can do at this point
196:        is change the initial guess and try again.

198:        An alternative explanation: Newton's method can be regarded as replacing the function with
199:        its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s
200:        so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then
201:        s = - F'(x)^(-1)F(x) otherwise F'(x)^T F'(x) s = -F'(x)^T F(x). If F'(x)^T F(x) is NOT zero then there
202:        exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is 
203:        s = - [F'(x)^T F'(x)]^(-1) F'(x)^T F(x) so Q'(0) = - F(x)^T F'(x) [F'(x)^T F'(x)]^(-T) F'(x)^T F(x)
204:        = - (F'(x)^T F(x)) [F'(x)^T F'(x)]^(-T) (F'(x)^T F(x)). Since we are assuming (F'(x)^T F(x)) != 0
205:        and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line
206:        search should succeed for small enough alpha.

208:        Note that this RARELY happens in practice. Far more likely the linear system is not being solved
209:        (well enough?) or the Jacobian is wrong.
210:      
211:    SNES_DIVERGED_MAX_IT means that the solver reached the maximum number of iterations without satisfying any
212:    convergence criteria. SNES_CONVERGED_ITS means that SNESSkipConverged() was chosen as the convergence test;
213:    thus the usual convergence criteria have not been checked and may or may not be satisfied.

215:    Developer Notes: this must match finclude/petscsnes.h 

217:        The string versions of these are in SNESConvergedReason, if you change any value here you must
218:      also adjust that array.

220:    Each reason has its own manual page.

222: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
223: E*/
224: typedef enum {/* converged */
225:               SNES_CONVERGED_FNORM_ABS         =  2, /* ||F|| < atol */
226:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* ||F|| < rtol*||F_initial|| */
227:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* Newton computed step size small; || delta x || < stol */
228:               SNES_CONVERGED_ITS               =  5, /* maximum iterations reached */
229:               SNES_CONVERGED_TR_DELTA          =  7,
230:               /* diverged */
231:               SNES_DIVERGED_FUNCTION_DOMAIN    = -1, /* the new x location passed the function is not in the domain of F */
232:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
233:               SNES_DIVERGED_LINEAR_SOLVE       = -3, /* the linear solve failed */
234:               SNES_DIVERGED_FNORM_NAN          = -4,
235:               SNES_DIVERGED_MAX_IT             = -5,
236:               SNES_DIVERGED_LS_FAILURE         = -6, /* the line search failed */
237:               SNES_DIVERGED_LOCAL_MIN          = -8, /* || J^T b || is small, implies converged to local minimum of F() */
238:               SNES_CONVERGED_ITERATING         =  0} SNESConvergedReason;

241: /*MC
242:      SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol

244:    Level: beginner

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

248: M*/

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

253:    Level: beginner

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

257: M*/

259: /*MC
260:      SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= stol * 2-norm(x) where x is the current
261:           solution and stol is the 4th argument to SNESSetTolerances()

263:    Level: beginner

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

267: M*/

269: /*MC
270:      SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
271:          argument to SNESSetTolerances()

273:    Level: beginner

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

277: M*/

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

283:    Level: beginner

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

287: M*/

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

292:    Level: beginner

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

296: M*/

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

301:    Level: beginner

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

305: M*/

307: /*MC
308:      SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero. 
309:         See the manual page for SNESConvergedReason for more details

311:    Level: beginner

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

315: M*/

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

320:    Level: beginner

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

324: M*/

326: EXTERN PetscErrorCode  SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
327: EXTERN PetscErrorCode  SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
328: EXTERN PetscErrorCode  SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
329: EXTERN PetscErrorCode  SNESGetConvergedReason(SNES,SNESConvergedReason*);

331: EXTERN PetscErrorCode  SNESDAFormFunction(SNES,Vec,Vec,void*);
332: EXTERN PetscErrorCode  SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
333: EXTERN PetscErrorCode  SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
334: EXTERN PetscErrorCode  SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

336: /* --------- Solving systems of nonlinear equations --------------- */
337: EXTERN PetscErrorCode  SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
338: EXTERN PetscErrorCode  SNESComputeFunction(SNES,Vec,Vec);
339: EXTERN PetscErrorCode  SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
340: EXTERN PetscErrorCode  SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **);
341: EXTERN PetscErrorCode  SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
342: EXTERN PetscErrorCode  SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
343: EXTERN PetscErrorCode  SNESGetRhs(SNES,Vec*);

345: /* --------- Routines specifically for line search methods --------------- */
346: EXTERN PetscErrorCode  SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
347: EXTERN PetscErrorCode  SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
348: EXTERN PetscErrorCode  SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
349: EXTERN PetscErrorCode  SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
350: EXTERN PetscErrorCode  SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);

352: EXTERN PetscErrorCode  SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscTruth*,PetscTruth*),void*);
353: EXTERN PetscErrorCode  SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscTruth*),void*);
354: EXTERN PetscErrorCode  SNESLineSearchSetParams(SNES,PetscReal,PetscReal);
355: EXTERN PetscErrorCode  SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*);

357: EXTERN PetscErrorCode  SNESTestLocalMin(SNES);

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

363: #endif