Actual source code: snes.c

  1: #define PETSCSNES_DLL

 3:  #include include/private/snesimpl.h

  5: PetscTruth SNESRegisterAllCalled = PETSC_FALSE;
  6: PetscFList SNESList              = PETSC_NULL;

  8: /* Logging support */
  9: PetscCookie  SNES_COOKIE = 0;
 10: PetscEvent  SNES_Solve = 0, SNES_LineSearch = 0, SNES_FunctionEval = 0, SNES_JacobianEval = 0;

 14: /*@C
 15:    SNESView - Prints the SNES data structure.

 17:    Collective on SNES

 19:    Input Parameters:
 20: +  SNES - the SNES context
 21: -  viewer - visualization context

 23:    Options Database Key:
 24: .  -snes_view - Calls SNESView() at end of SNESSolve()

 26:    Notes:
 27:    The available visualization contexts include
 28: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
 29: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
 30:          output where only the first processor opens
 31:          the file.  All other processors send their 
 32:          data to the first processor to print. 

 34:    The user can open an alternative visualization context with
 35:    PetscViewerASCIIOpen() - output to a specified file.

 37:    Level: beginner

 39: .keywords: SNES, view

 41: .seealso: PetscViewerASCIIOpen()
 42: @*/
 43: PetscErrorCode  SNESView(SNES snes,PetscViewer viewer)
 44: {
 45:   SNES_KSP_EW_ConvCtx *kctx;
 46:   PetscErrorCode      ierr;
 47:   KSP                 ksp;
 48:   SNESType            type;
 49:   PetscTruth          iascii,isstring;

 53:   if (!viewer) {
 54:     PetscViewerASCIIGetStdout(snes->comm,&viewer);
 55:   }

 59:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
 60:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_STRING,&isstring);
 61:   if (iascii) {
 62:     if (snes->prefix) {
 63:       PetscViewerASCIIPrintf(viewer,"SNES Object:(%s)\n",snes->prefix);
 64:     } else {
 65:       PetscViewerASCIIPrintf(viewer,"SNES Object:\n");
 66:     }
 67:     SNESGetType(snes,&type);
 68:     if (type) {
 69:       PetscViewerASCIIPrintf(viewer,"  type: %s\n",type);
 70:     } else {
 71:       PetscViewerASCIIPrintf(viewer,"  type: not set yet\n");
 72:     }
 73:     if (snes->ops->view) {
 74:       PetscViewerASCIIPushTab(viewer);
 75:       (*snes->ops->view)(snes,viewer);
 76:       PetscViewerASCIIPopTab(viewer);
 77:     }
 78:     PetscViewerASCIIPrintf(viewer,"  maximum iterations=%D, maximum function evaluations=%D\n",snes->max_its,snes->max_funcs);
 79:     PetscViewerASCIIPrintf(viewer,"  tolerances: relative=%G, absolute=%G, solution=%G\n",
 80:                  snes->rtol,snes->abstol,snes->xtol);
 81:     PetscViewerASCIIPrintf(viewer,"  total number of linear solver iterations=%D\n",snes->linear_its);
 82:     PetscViewerASCIIPrintf(viewer,"  total number of function evaluations=%D\n",snes->nfuncs);
 83:     if (snes->ksp_ewconv) {
 84:       kctx = (SNES_KSP_EW_ConvCtx *)snes->kspconvctx;
 85:       if (kctx) {
 86:         PetscViewerASCIIPrintf(viewer,"  Eisenstat-Walker computation of KSP relative tolerance (version %D)\n",kctx->version);
 87:         PetscViewerASCIIPrintf(viewer,"    rtol_0=%G, rtol_max=%G, threshold=%G\n",kctx->rtol_0,kctx->rtol_max,kctx->threshold);
 88:         PetscViewerASCIIPrintf(viewer,"    gamma=%G, alpha=%G, alpha2=%G\n",kctx->gamma,kctx->alpha,kctx->alpha2);
 89:       }
 90:     }
 91:   } else if (isstring) {
 92:     SNESGetType(snes,&type);
 93:     PetscViewerStringSPrintf(viewer," %-3.3s",type);
 94:   }
 95:   SNESGetKSP(snes,&ksp);
 96:   PetscViewerASCIIPushTab(viewer);
 97:   KSPView(ksp,viewer);
 98:   PetscViewerASCIIPopTab(viewer);
 99:   return(0);
100: }

102: /*
103:   We retain a list of functions that also take SNES command 
104:   line options. These are called at the end SNESSetFromOptions()
105: */
106: #define MAXSETFROMOPTIONS 5
107: static PetscInt numberofsetfromoptions;
108: static PetscErrorCode (*othersetfromoptions[MAXSETFROMOPTIONS])(SNES);

112: /*@C
113:   SNESAddOptionsChecker - Adds an additional function to check for SNES options.

115:   Not Collective

117:   Input Parameter:
118: . snescheck - function that checks for options

120:   Level: developer

122: .seealso: SNESSetFromOptions()
123: @*/
124: PetscErrorCode  SNESAddOptionsChecker(PetscErrorCode (*snescheck)(SNES))
125: {
127:   if (numberofsetfromoptions >= MAXSETFROMOPTIONS) {
128:     SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE, "Too many options checkers, only %D allowed", MAXSETFROMOPTIONS);
129:   }
130:   othersetfromoptions[numberofsetfromoptions++] = snescheck;
131:   return(0);
132: }

136: /*@
137:    SNESSetFromOptions - Sets various SNES and KSP parameters from user options.

139:    Collective on SNES

141:    Input Parameter:
142: .  snes - the SNES context

144:    Options Database Keys:
145: +  -snes_type <type> - ls, tr, umls, umtr, test
146: .  -snes_stol - convergence tolerance in terms of the norm
147:                 of the change in the solution between steps
148: .  -snes_atol <abstol> - absolute tolerance of residual norm
149: .  -snes_rtol <rtol> - relative decrease in tolerance norm from initial
150: .  -snes_max_it <max_it> - maximum number of iterations
151: .  -snes_max_funcs <max_funcs> - maximum number of function evaluations
152: .  -snes_max_fail <max_fail> - maximum number of failures
153: .  -snes_trtol <trtol> - trust region tolerance
154: .  -snes_no_convergence_test - skip convergence test in nonlinear 
155:                                solver; hence iterations will continue until max_it
156:                                or some other criterion is reached. Saves expense
157:                                of convergence test
158: .  -snes_monitor <optional filename> - prints residual norm at each iteration. if no
159:                                        filename given prints to stdout
160: .  -snes_monitor_solution - plots solution at each iteration
161: .  -snes_monitor_residual - plots residual (not its norm) at each iteration
162: .  -snes_monitor_solution_update - plots update to solution at each iteration 
163: .  -snes_monitor_draw - plots residual norm at each iteration 
164: .  -snes_fd - use finite differences to compute Jacobian; very slow, only for testing
165: .  -snes_mf_ksp_monitor - if using matrix-free multiply then print h at each KSP iteration
166: -  -snes_converged_reason - print the reason for convergence/divergence after each solve

168:     Options Database for Eisenstat-Walker method:
169: +  -snes_ksp_ew_conv - use Eisenstat-Walker method for determining linear system convergence
170: .  -snes_ksp_ew_version ver - version of  Eisenstat-Walker method
171: .  -snes_ksp_ew_rtol0 <rtol0> - Sets rtol0
172: .  -snes_ksp_ew_rtolmax <rtolmax> - Sets rtolmax
173: .  -snes_ksp_ew_gamma <gamma> - Sets gamma
174: .  -snes_ksp_ew_alpha <alpha> - Sets alpha
175: .  -snes_ksp_ew_alpha2 <alpha2> - Sets alpha2 
176: -  -snes_ksp_ew_threshold <threshold> - Sets threshold

178:    Notes:
179:    To see all options, run your program with the -help option or consult
180:    the users manual.

182:    Level: beginner

184: .keywords: SNES, nonlinear, set, options, database

186: .seealso: SNESSetOptionsPrefix()
187: @*/
188: PetscErrorCode  SNESSetFromOptions(SNES snes)
189: {
190:   KSP                     ksp;
191:   SNES_KSP_EW_ConvCtx     *kctx = (SNES_KSP_EW_ConvCtx *)snes->kspconvctx;
192:   PetscTruth              flg;
193:   PetscErrorCode          ierr;
194:   PetscInt                i;
195:   const char              *deft;
196:   char                    type[256], monfilename[PETSC_MAX_PATH_LEN];
197:   PetscViewerASCIIMonitor monviewer;


202:   PetscOptionsBegin(snes->comm,snes->prefix,"Nonlinear solver (SNES) options","SNES");
203:     if (snes->type_name) {
204:       deft = snes->type_name;
205:     } else {
206:       deft = SNESLS;
207:     }

209:     if (!SNESRegisterAllCalled) {SNESRegisterAll(PETSC_NULL);}
210:     PetscOptionsList("-snes_type","Nonlinear solver method","SNESSetType",SNESList,deft,type,256,&flg);
211:     if (flg) {
212:       SNESSetType(snes,type);
213:     } else if (!snes->type_name) {
214:       SNESSetType(snes,deft);
215:     }
216:     PetscOptionsName("-snes_view","Print detailed information on solver used","SNESView",0);

218:     PetscOptionsReal("-snes_stol","Stop if step length less then","SNESSetTolerances",snes->xtol,&snes->xtol,0);
219:     PetscOptionsReal("-snes_atol","Stop if function norm less then","SNESSetTolerances",snes->abstol,&snes->abstol,0);

221:     PetscOptionsReal("-snes_rtol","Stop if decrease in function norm less then","SNESSetTolerances",snes->rtol,&snes->rtol,0);
222:     PetscOptionsInt("-snes_max_it","Maximum iterations","SNESSetTolerances",snes->max_its,&snes->max_its,PETSC_NULL);
223:     PetscOptionsInt("-snes_max_funcs","Maximum function evaluations","SNESSetTolerances",snes->max_funcs,&snes->max_funcs,PETSC_NULL);
224:     PetscOptionsInt("-snes_max_fail","Maximum failures","SNESSetTolerances",snes->maxFailures,&snes->maxFailures,PETSC_NULL);
225:     PetscOptionsName("-snes_converged_reason","Print reason for converged or diverged","SNESSolve",&flg);
226:     if (flg) {
227:       snes->printreason = PETSC_TRUE;
228:     }

230:     PetscOptionsTruth("-snes_ksp_ew_conv","Use Eisentat-Walker linear system convergence test","SNES_KSP_SetParametersEW",snes->ksp_ewconv,&snes->ksp_ewconv,PETSC_NULL);

232:     PetscOptionsInt("-snes_ksp_ew_version","Version 1, 2 or 3","SNES_KSP_SetParametersEW",kctx->version,&kctx->version,0);
233:     PetscOptionsReal("-snes_ksp_ew_rtol0","0 <= rtol0 < 1","SNES_KSP_SetParametersEW",kctx->rtol_0,&kctx->rtol_0,0);
234:     PetscOptionsReal("-snes_ksp_ew_rtolmax","0 <= rtolmax < 1","SNES_KSP_SetParametersEW",kctx->rtol_max,&kctx->rtol_max,0);
235:     PetscOptionsReal("-snes_ksp_ew_gamma","0 <= gamma <= 1","SNES_KSP_SetParametersEW",kctx->gamma,&kctx->gamma,0);
236:     PetscOptionsReal("-snes_ksp_ew_alpha","1 < alpha <= 2","SNES_KSP_SetParametersEW",kctx->alpha,&kctx->alpha,0);
237:     PetscOptionsReal("-snes_ksp_ew_alpha2","alpha2","SNES_KSP_SetParametersEW",kctx->alpha2,&kctx->alpha2,0);
238:     PetscOptionsReal("-snes_ksp_ew_threshold","0 < threshold < 1","SNES_KSP_SetParametersEW",kctx->threshold,&kctx->threshold,0);

240:     PetscOptionsName("-snes_no_convergence_test","Don't test for convergence","None",&flg);
241:     if (flg) {snes->ops->converged = 0;}
242:     PetscOptionsName("-snes_monitor_cancel","Remove all monitors","SNESMonitorCancel",&flg);
243:     if (flg) {SNESMonitorCancel(snes);}

245:     PetscOptionsString("-snes_monitor","Monitor norm of function","SNESMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
246:     if (flg) {
247:       PetscViewerASCIIMonitorCreate(snes->comm,monfilename,0,&monviewer);
248:       SNESMonitorSet(snes,SNESMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
249:     }

251:     PetscOptionsString("-snes_ratiomonitor","Monitor ratios of norms of function","SNESMonitorSetRatio","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
252:     if (flg) {
253:       PetscViewerASCIIMonitorCreate(snes->comm,monfilename,0,&monviewer);
254:       SNESMonitorSetRatio(snes,monviewer);
255:     }

257:     PetscOptionsString("-snes_monitor_short","Monitor norm of function (fewer digits)","SNESMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
258:     if (flg) {
259:       PetscViewerASCIIMonitorCreate(snes->comm,monfilename,0,&monviewer);
260:       SNESMonitorSet(snes,SNESMonitorDefaultShort,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
261:     }

263:     PetscOptionsName("-snes_monitor_solution","Plot solution at each iteration","SNESMonitorSolution",&flg);
264:     if (flg) {SNESMonitorSet(snes,SNESMonitorSolution,0,0);}
265:     PetscOptionsName("-snes_monitor_solution_update","Plot correction at each iteration","SNESMonitorSolutionUpdate",&flg);
266:     if (flg) {SNESMonitorSet(snes,SNESMonitorSolutionUpdate,0,0);}
267:     PetscOptionsName("-snes_monitor_residual","Plot residual at each iteration","SNESMonitorResidual",&flg);
268:     if (flg) {SNESMonitorSet(snes,SNESMonitorResidual,0,0);}
269:     PetscOptionsName("-snes_monitor_draw","Plot function norm at each iteration","SNESMonitorLG",&flg);
270:     if (flg) {SNESMonitorSet(snes,SNESMonitorLG,PETSC_NULL,PETSC_NULL);}

272:     PetscOptionsName("-snes_fd","Use finite differences (slow) to compute Jacobian","SNESDefaultComputeJacobian",&flg);
273:     if (flg) {
274:       SNESSetJacobian(snes,snes->jacobian,snes->jacobian_pre,SNESDefaultComputeJacobian,snes->funP);
275:       PetscInfo(snes,"Setting default finite difference Jacobian matrix\n");
276:     }

278:     for(i = 0; i < numberofsetfromoptions; i++) {
279:       (*othersetfromoptions[i])(snes);
280:     }

282:     if (snes->ops->setfromoptions) {
283:       (*snes->ops->setfromoptions)(snes);
284:     }
285:   PetscOptionsEnd();

287:   SNESGetKSP(snes,&ksp);
288:   KSPSetFromOptions(ksp);

290:   return(0);
291: }


296: /*@
297:    SNESSetApplicationContext - Sets the optional user-defined context for 
298:    the nonlinear solvers.  

300:    Collective on SNES

302:    Input Parameters:
303: +  snes - the SNES context
304: -  usrP - optional user context

306:    Level: intermediate

308: .keywords: SNES, nonlinear, set, application, context

310: .seealso: SNESGetApplicationContext()
311: @*/
312: PetscErrorCode  SNESSetApplicationContext(SNES snes,void *usrP)
313: {
316:   snes->user                = usrP;
317:   return(0);
318: }

322: /*@C
323:    SNESGetApplicationContext - Gets the user-defined context for the 
324:    nonlinear solvers.  

326:    Not Collective

328:    Input Parameter:
329: .  snes - SNES context

331:    Output Parameter:
332: .  usrP - user context

334:    Level: intermediate

336: .keywords: SNES, nonlinear, get, application, context

338: .seealso: SNESSetApplicationContext()
339: @*/
340: PetscErrorCode  SNESGetApplicationContext(SNES snes,void **usrP)
341: {
344:   *usrP = snes->user;
345:   return(0);
346: }

350: /*@
351:    SNESGetIterationNumber - Gets the number of nonlinear iterations completed
352:    at this time.

354:    Not Collective

356:    Input Parameter:
357: .  snes - SNES context

359:    Output Parameter:
360: .  iter - iteration number

362:    Notes:
363:    For example, during the computation of iteration 2 this would return 1.

365:    This is useful for using lagged Jacobians (where one does not recompute the 
366:    Jacobian at each SNES iteration). For example, the code
367: .vb
368:       SNESGetIterationNumber(snes,&it);
369:       if (!(it % 2)) {
370:         [compute Jacobian here]
371:       }
372: .ve
373:    can be used in your ComputeJacobian() function to cause the Jacobian to be
374:    recomputed every second SNES iteration.

376:    Level: intermediate

378: .keywords: SNES, nonlinear, get, iteration, number, 

380: .seealso:   SNESGetFunctionNorm(), SNESGetNumberLinearIterations()
381: @*/
382: PetscErrorCode  SNESGetIterationNumber(SNES snes,PetscInt* iter)
383: {
387:   *iter = snes->iter;
388:   return(0);
389: }

393: /*@
394:    SNESGetFunctionNorm - Gets the norm of the current function that was set
395:    with SNESSSetFunction().

397:    Collective on SNES

399:    Input Parameter:
400: .  snes - SNES context

402:    Output Parameter:
403: .  fnorm - 2-norm of function

405:    Level: intermediate

407: .keywords: SNES, nonlinear, get, function, norm

409: .seealso: SNESGetFunction(), SNESGetIterationNumber(), SNESGetNumberLinearIterations()
410: @*/
411: PetscErrorCode  SNESGetFunctionNorm(SNES snes,PetscScalar *fnorm)
412: {
416:   *fnorm = snes->norm;
417:   return(0);
418: }

422: /*@
423:    SNESGetNumberUnsuccessfulSteps - Gets the number of unsuccessful steps
424:    attempted by the nonlinear solver.

426:    Not Collective

428:    Input Parameter:
429: .  snes - SNES context

431:    Output Parameter:
432: .  nfails - number of unsuccessful steps attempted

434:    Notes:
435:    This counter is reset to zero for each successive call to SNESSolve().

437:    Level: intermediate

439: .keywords: SNES, nonlinear, get, number, unsuccessful, steps
440: @*/
441: PetscErrorCode  SNESGetNumberUnsuccessfulSteps(SNES snes,PetscInt* nfails)
442: {
446:   *nfails = snes->numFailures;
447:   return(0);
448: }

452: /*@
453:    SNESSetMaximumUnsuccessfulSteps - Sets the maximum number of unsuccessful steps
454:    attempted by the nonlinear solver before it gives up.

456:    Not Collective

458:    Input Parameters:
459: +  snes     - SNES context
460: -  maxFails - maximum of unsuccessful steps

462:    Level: intermediate

464: .keywords: SNES, nonlinear, set, maximum, unsuccessful, steps
465: @*/
466: PetscErrorCode  SNESSetMaximumUnsuccessfulSteps(SNES snes, PetscInt maxFails)
467: {
470:   snes->maxFailures = maxFails;
471:   return(0);
472: }

476: /*@
477:    SNESGetMaximumUnsuccessfulSteps - Gets the maximum number of unsuccessful steps
478:    attempted by the nonlinear solver before it gives up.

480:    Not Collective

482:    Input Parameter:
483: .  snes     - SNES context

485:    Output Parameter:
486: .  maxFails - maximum of unsuccessful steps

488:    Level: intermediate

490: .keywords: SNES, nonlinear, get, maximum, unsuccessful, steps
491: @*/
492: PetscErrorCode  SNESGetMaximumUnsuccessfulSteps(SNES snes, PetscInt *maxFails)
493: {
497:   *maxFails = snes->maxFailures;
498:   return(0);
499: }

503: /*@
504:    SNESGetLinearSolveFailures - Gets the number of failed (non-converged)
505:    linear solvers.

507:    Not Collective

509:    Input Parameter:
510: .  snes - SNES context

512:    Output Parameter:
513: .  nfails - number of failed solves

515:    Notes:
516:    This counter is reset to zero for each successive call to SNESSolve().

518:    Level: intermediate

520: .keywords: SNES, nonlinear, get, number, unsuccessful, steps
521: @*/
522: PetscErrorCode  SNESGetLinearSolveFailures(SNES snes,PetscInt* nfails)
523: {
527:   *nfails = snes->numLinearSolveFailures;
528:   return(0);
529: }

533: /*@
534:    SNESSetMaxLinearSolveFailures - the number of failed linear solve attempts
535:    allowed before SNES returns with a diverged reason of SNES_DIVERGED_LINEAR_SOLVE

537:    Collective on SNES

539:    Input Parameters:
540: +  snes     - SNES context
541: -  maxFails - maximum allowed linear solve failures

543:    Level: intermediate

545:    Notes: By default this is 1; that is SNES returns on the first failed linear solve

547: .keywords: SNES, nonlinear, set, maximum, unsuccessful, steps

549: .seealso: SNESGetLinearSolveFailures(), SNESGetMaxLinearSolveFailures()
550: @*/
551: PetscErrorCode  SNESSetMaxLinearSolveFailures(SNES snes, PetscInt maxFails)
552: {
555:   snes->maxLinearSolveFailures = maxFails;
556:   return(0);
557: }

561: /*@
562:    SNESGetMaxLinearSolveFailures - gets the maximum number of linear solve failures that
563:      are allowed before SNES terminates

565:    Not Collective

567:    Input Parameter:
568: .  snes     - SNES context

570:    Output Parameter:
571: .  maxFails - maximum of unsuccessful solves allowed

573:    Level: intermediate

575:    Notes: By default this is 1; that is SNES returns on the first failed linear solve

577: .keywords: SNES, nonlinear, get, maximum, unsuccessful, steps

579: .seealso: SNESGetLinearSolveFailures(), SNESGetMaxLinearSolveFailures()
580: @*/
581: PetscErrorCode  SNESGetMaxLinearSolveFailures(SNES snes, PetscInt *maxFails)
582: {
586:   *maxFails = snes->maxLinearSolveFailures;
587:   return(0);
588: }

592: /*@
593:    SNESGetNumberLinearIterations - Gets the total number of linear iterations
594:    used by the nonlinear solver.

596:    Not Collective

598:    Input Parameter:
599: .  snes - SNES context

601:    Output Parameter:
602: .  lits - number of linear iterations

604:    Notes:
605:    This counter is reset to zero for each successive call to SNESSolve().

607:    Level: intermediate

609: .keywords: SNES, nonlinear, get, number, linear, iterations

611: .seealso:  SNESGetIterationNumber(), SNESGetFunctionNorm()
612: @*/
613: PetscErrorCode  SNESGetNumberLinearIterations(SNES snes,PetscInt* lits)
614: {
618:   *lits = snes->linear_its;
619:   return(0);
620: }

624: /*@
625:    SNESGetKSP - Returns the KSP context for a SNES solver.

627:    Not Collective, but if SNES object is parallel, then KSP object is parallel

629:    Input Parameter:
630: .  snes - the SNES context

632:    Output Parameter:
633: .  ksp - the KSP context

635:    Notes:
636:    The user can then directly manipulate the KSP context to set various
637:    options, etc.  Likewise, the user can then extract and manipulate the 
638:    PC contexts as well.

640:    Level: beginner

642: .keywords: SNES, nonlinear, get, KSP, context

644: .seealso: KSPGetPC(), SNESCreate(), KSPCreate(), SNESSetKSP()
645: @*/
646: PetscErrorCode  SNESGetKSP(SNES snes,KSP *ksp)
647: {
651:   *ksp = snes->ksp;
652:   return(0);
653: }

657: /*@
658:    SNESSetKSP - Sets a KSP context for the SNES object to use

660:    Not Collective, but the SNES and KSP objects must live on the same MPI_Comm

662:    Input Parameters:
663: +  snes - the SNES context
664: -  ksp - the KSP context

666:    Notes:
667:    The SNES object already has its KSP object, you can obtain with SNESGetKSP()
668:    so this routine is rarely needed.

670:    The KSP object that is already in the SNES object has its reference count
671:    decreased by one.

673:    Level: developer

675: .keywords: SNES, nonlinear, get, KSP, context

677: .seealso: KSPGetPC(), SNESCreate(), KSPCreate(), SNESSetKSP()
678: @*/
679: PetscErrorCode  SNESSetKSP(SNES snes,KSP ksp)
680: {

687:   PetscObjectReference((PetscObject)ksp);
688:   if (snes->ksp) {PetscObjectDereference((PetscObject)snes->ksp);}
689:   snes->ksp = ksp;
690:   return(0);
691: }

695: static PetscErrorCode SNESPublish_Petsc(PetscObject obj)
696: {
698:   return(0);
699: }

701: /* -----------------------------------------------------------*/
704: /*@
705:    SNESCreate - Creates a nonlinear solver context.

707:    Collective on MPI_Comm

709:    Input Parameters:
710: .  comm - MPI communicator

712:    Output Parameter:
713: .  outsnes - the new SNES context

715:    Options Database Keys:
716: +   -snes_mf - Activates default matrix-free Jacobian-vector products,
717:                and no preconditioning matrix
718: .   -snes_mf_operator - Activates default matrix-free Jacobian-vector
719:                products, and a user-provided preconditioning matrix
720:                as set by SNESSetJacobian()
721: -   -snes_fd - Uses (slow!) finite differences to compute Jacobian

723:    Level: beginner

725: .keywords: SNES, nonlinear, create, context

727: .seealso: SNESSolve(), SNESDestroy(), SNES
728: @*/
729: PetscErrorCode  SNESCreate(MPI_Comm comm,SNES *outsnes)
730: {
731:   PetscErrorCode      ierr;
732:   SNES                snes;
733:   SNES_KSP_EW_ConvCtx *kctx;

737:   *outsnes = PETSC_NULL;
738: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
739:   SNESInitializePackage(PETSC_NULL);
740: #endif

742:   PetscHeaderCreate(snes,_p_SNES,struct _SNESOps,SNES_COOKIE,0,"SNES",comm,SNESDestroy,SNESView);
743:   snes->bops->publish     = SNESPublish_Petsc;
744:   snes->max_its           = 50;
745:   snes->max_funcs          = 10000;
746:   snes->norm                  = 0.0;
747:   snes->rtol                  = 1.e-8;
748:   snes->ttol              = 0.0;
749:   snes->abstol                  = 1.e-50;
750:   snes->xtol                  = 1.e-8;
751:   snes->deltatol          = 1.e-12;
752:   snes->nfuncs            = 0;
753:   snes->numFailures       = 0;
754:   snes->maxFailures       = 1;
755:   snes->linear_its        = 0;
756:   snes->numbermonitors    = 0;
757:   snes->data              = 0;
758:   snes->ops->view         = 0;
759:   snes->setupcalled       = PETSC_FALSE;
760:   snes->ksp_ewconv        = PETSC_FALSE;
761:   snes->vwork             = 0;
762:   snes->nwork             = 0;
763:   snes->conv_hist_len     = 0;
764:   snes->conv_hist_max     = 0;
765:   snes->conv_hist         = PETSC_NULL;
766:   snes->conv_hist_its     = PETSC_NULL;
767:   snes->conv_hist_reset   = PETSC_TRUE;
768:   snes->reason            = SNES_CONVERGED_ITERATING;

770:   snes->numLinearSolveFailures = 0;
771:   snes->maxLinearSolveFailures = 1;

773:   /* Create context to compute Eisenstat-Walker relative tolerance for KSP */
774:   PetscNew(SNES_KSP_EW_ConvCtx,&kctx);
775:   PetscLogObjectMemory(snes,sizeof(SNES_KSP_EW_ConvCtx));
776:   snes->kspconvctx  = (void*)kctx;
777:   kctx->version     = 2;
778:   kctx->rtol_0      = .3; /* Eisenstat and Walker suggest rtol_0=.5, but 
779:                              this was too large for some test cases */
780:   kctx->rtol_last   = 0;
781:   kctx->rtol_max    = .9;
782:   kctx->gamma       = 1.0;
783:   kctx->alpha2      = .5*(1.0 + sqrt(5.0));
784:   kctx->alpha       = kctx->alpha2;
785:   kctx->threshold   = .1;
786:   kctx->lresid_last = 0;
787:   kctx->norm_last   = 0;

789:   KSPCreate(comm,&snes->ksp);
790:   PetscLogObjectParent(snes,snes->ksp);

792:   *outsnes = snes;
793:   PetscPublishAll(snes);
794:   return(0);
795: }

799: /*@C
800:    SNESSetFunction - Sets the function evaluation routine and function 
801:    vector for use by the SNES routines in solving systems of nonlinear
802:    equations.

804:    Collective on SNES

806:    Input Parameters:
807: +  snes - the SNES context
808: .  r - vector to store function value
809: .  func - function evaluation routine
810: -  ctx - [optional] user-defined context for private data for the 
811:          function evaluation routine (may be PETSC_NULL)

813:    Calling sequence of func:
814: $    func (SNES snes,Vec x,Vec f,void *ctx);

816: .  f - function vector
817: -  ctx - optional user-defined function context 

819:    Notes:
820:    The Newton-like methods typically solve linear systems of the form
821: $      f'(x) x = -f(x),
822:    where f'(x) denotes the Jacobian matrix and f(x) is the function.

824:    Level: beginner

826: .keywords: SNES, nonlinear, set, function

828: .seealso: SNESGetFunction(), SNESComputeFunction(), SNESSetJacobian()
829: @*/
830: PetscErrorCode  SNESSetFunction(SNES snes,Vec r,PetscErrorCode (*func)(SNES,Vec,Vec,void*),void *ctx)
831: {

837:   snes->ops->computefunction = func;
838:   snes->vec_func             = snes->vec_func_always = r;
839:   snes->funP                 = ctx;
840:   return(0);
841: }

843: /* --------------------------------------------------------------- */
846: /*@C
847:    SNESSetRhs - Sets the vector for solving F(x) = rhs. If rhs is not set
848:    it assumes a zero right hand side.

850:    Collective on SNES

852:    Input Parameters:
853: +  snes - the SNES context
854: -  rhs - the right hand side vector or PETSC_NULL for a zero right hand side

856:    Level: intermediate

858: .keywords: SNES, nonlinear, set, function, right hand side

860: .seealso: SNESGetRhs(), SNESGetFunction(), SNESComputeFunction(), SNESSetJacobian(), SNESSetFunction()
861: @*/
862: PetscErrorCode  SNESSetRhs(SNES snes,Vec rhs)
863: {

868:   if (rhs) {
871:     PetscObjectReference((PetscObject)rhs);
872:   }
873:   if (snes->afine) {
874:     VecDestroy(snes->afine);
875:   }
876:   snes->afine = rhs;
877:   return(0);
878: }

882: /*@C
883:    SNESGetRhs - Gets the vector for solving F(x) = rhs. If rhs is not set
884:    it assumes a zero right hand side.

886:    Collective on SNES

888:    Input Parameter:
889: .  snes - the SNES context

891:    Output Parameter:
892: .  rhs - the right hand side vector or PETSC_NULL for a zero right hand side

894:    Level: intermediate

896: .keywords: SNES, nonlinear, get, function, right hand side

898: .seealso: SNESSetRhs(), SNESGetFunction(), SNESComputeFunction(), SNESSetJacobian(), SNESSetFunction()
899: @*/
900: PetscErrorCode  SNESGetRhs(SNES snes,Vec *rhs)
901: {
905:   *rhs = snes->afine;
906:   return(0);
907: }

911: /*@
912:    SNESComputeFunction - Calls the function that has been set with
913:                          SNESSetFunction().  

915:    Collective on SNES

917:    Input Parameters:
918: +  snes - the SNES context
919: -  x - input vector

921:    Output Parameter:
922: .  y - function vector, as set by SNESSetFunction()

924:    Notes:
925:    SNESComputeFunction() is typically used within nonlinear solvers
926:    implementations, so most users would not generally call this routine
927:    themselves.

929:    Level: developer

931: .keywords: SNES, nonlinear, compute, function

933: .seealso: SNESSetFunction(), SNESGetFunction()
934: @*/
935: PetscErrorCode  SNESComputeFunction(SNES snes,Vec x,Vec y)
936: {


947:   if (snes->ops->computefunction) {
948:     PetscStackPush("SNES user function");
949:     CHKMEMQ;
950:     (*snes->ops->computefunction)(snes,x,y,snes->funP);
951:     CHKMEMQ;
952:     PetscStackPop;
953:     if (PetscExceptionValue(ierr)) {
955:     }
956: 
957:   } else if (snes->afine) {
958:     MatMult(snes->jacobian, x, y);
959:   } else {
960:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Must call SNESSetFunction() before SNESComputeFunction(), likely called from SNESSolve().");
961:   }
962:   if (snes->afine) {
963:     VecAXPY(y,-1.0,snes->afine);
964:   }
965:   snes->nfuncs++;
967:   return(0);
968: }

972: /*@
973:    SNESComputeJacobian - Computes the Jacobian matrix that has been
974:    set with SNESSetJacobian().

976:    Collective on SNES and Mat

978:    Input Parameters:
979: +  snes - the SNES context
980: -  x - input vector

982:    Output Parameters:
983: +  A - Jacobian matrix
984: .  B - optional preconditioning matrix
985: -  flag - flag indicating matrix structure (one of, SAME_NONZERO_PATTERN,DIFFERENT_NONZERO_PATTERN,SAME_PRECONDITIONER)

987:    Notes: 
988:    Most users should not need to explicitly call this routine, as it 
989:    is used internally within the nonlinear solvers. 

991:    See KSPSetOperators() for important information about setting the
992:    flag parameter.

994:    Level: developer

996: .keywords: SNES, compute, Jacobian, matrix

998: .seealso:  SNESSetJacobian(), KSPSetOperators(), MatStructure
999: @*/
1000: PetscErrorCode  SNESComputeJacobian(SNES snes,Vec X,Mat *A,Mat *B,MatStructure *flg)
1001: {

1009:   if (!snes->ops->computejacobian) return(0);
1011:   *flg = DIFFERENT_NONZERO_PATTERN;
1012:   PetscStackPush("SNES user Jacobian function");
1013:   CHKMEMQ;
1014:   (*snes->ops->computejacobian)(snes,X,A,B,flg,snes->jacP);
1015:   CHKMEMQ;
1016:   PetscStackPop;
1018:   /* make sure user returned a correct Jacobian and preconditioner */
1021:   return(0);
1022: }

1026: /*@C
1027:    SNESSetJacobian - Sets the function to compute Jacobian as well as the
1028:    location to store the matrix.

1030:    Collective on SNES and Mat

1032:    Input Parameters:
1033: +  snes - the SNES context
1034: .  A - Jacobian matrix
1035: .  B - preconditioner matrix (usually same as the Jacobian)
1036: .  func - Jacobian evaluation routine
1037: -  ctx - [optional] user-defined context for private data for the 
1038:          Jacobian evaluation routine (may be PETSC_NULL)

1040:    Calling sequence of func:
1041: $     func (SNES snes,Vec x,Mat *A,Mat *B,int *flag,void *ctx);

1043: +  x - input vector
1044: .  A - Jacobian matrix
1045: .  B - preconditioner matrix, usually the same as A
1046: .  flag - flag indicating information about the preconditioner matrix
1047:    structure (same as flag in KSPSetOperators()), one of SAME_NONZERO_PATTERN,DIFFERENT_NONZERO_PATTERN,SAME_PRECONDITIONER
1048: -  ctx - [optional] user-defined Jacobian context

1050:    Notes: 
1051:    See KSPSetOperators() for important information about setting the flag
1052:    output parameter in the routine func().  Be sure to read this information!

1054:    The routine func() takes Mat * as the matrix arguments rather than Mat.  
1055:    This allows the Jacobian evaluation routine to replace A and/or B with a 
1056:    completely new new matrix structure (not just different matrix elements)
1057:    when appropriate, for instance, if the nonzero structure is changing
1058:    throughout the global iterations.

1060:    Level: beginner

1062: .keywords: SNES, nonlinear, set, Jacobian, matrix

1064: .seealso: KSPSetOperators(), SNESSetFunction(), MatSNESMFComputeJacobian(), SNESDefaultComputeJacobianColor(), MatStructure
1065: @*/
1066: PetscErrorCode  SNESSetJacobian(SNES snes,Mat A,Mat B,PetscErrorCode (*func)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *ctx)
1067: {

1076:    if (func) snes->ops->computejacobian = func;
1077:    if (ctx)  snes->jacP                 = ctx;
1078:   if (A) {
1079:     PetscObjectReference((PetscObject)A);
1080:     if (snes->jacobian) {MatDestroy(snes->jacobian);}
1081:     snes->jacobian = A;
1082:   }
1083:   if (B) {
1084:     PetscObjectReference((PetscObject)B);
1085:     if (snes->jacobian_pre) {MatDestroy(snes->jacobian_pre);}
1086:     snes->jacobian_pre = B;
1087:   }
1088:   return(0);
1089: }

1093: /*@C
1094:    SNESGetJacobian - Returns the Jacobian matrix and optionally the user 
1095:    provided context for evaluating the Jacobian.

1097:    Not Collective, but Mat object will be parallel if SNES object is

1099:    Input Parameter:
1100: .  snes - the nonlinear solver context

1102:    Output Parameters:
1103: +  A - location to stash Jacobian matrix (or PETSC_NULL)
1104: .  B - location to stash preconditioner matrix (or PETSC_NULL)
1105: .  func - location to put Jacobian function (or PETSC_NULL)
1106: -  ctx - location to stash Jacobian ctx (or PETSC_NULL)

1108:    Level: advanced

1110: .seealso: SNESSetJacobian(), SNESComputeJacobian()
1111: @*/
1112: PetscErrorCode  SNESGetJacobian(SNES snes,Mat *A,Mat *B,PetscErrorCode (**func)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **ctx)
1113: {
1116:   if (A)    *A    = snes->jacobian;
1117:   if (B)    *B    = snes->jacobian_pre;
1118:   if (func) *func = snes->ops->computejacobian;
1119:   if (ctx)  *ctx  = snes->jacP;
1120:   return(0);
1121: }

1123: /* ----- Routines to initialize and destroy a nonlinear solver ---- */
1124: EXTERN PetscErrorCode  SNESDefaultMatrixFreeCreate2(SNES,Vec,Mat*);

1128: /*@
1129:    SNESSetUp - Sets up the internal data structures for the later use
1130:    of a nonlinear solver.

1132:    Collective on SNES

1134:    Input Parameters:
1135: .  snes - the SNES context

1137:    Notes:
1138:    For basic use of the SNES solvers the user need not explicitly call
1139:    SNESSetUp(), since these actions will automatically occur during
1140:    the call to SNESSolve().  However, if one wishes to control this
1141:    phase separately, SNESSetUp() should be called after SNESCreate()
1142:    and optional routines of the form SNESSetXXX(), but before SNESSolve().  

1144:    Level: advanced

1146: .keywords: SNES, nonlinear, setup

1148: .seealso: SNESCreate(), SNESSolve(), SNESDestroy()
1149: @*/
1150: PetscErrorCode  SNESSetUp(SNES snes)
1151: {
1153:   PetscTruth     flg, iseqtr;

1157:   if (snes->setupcalled) return(0);

1159:   PetscOptionsHasName(snes->prefix,"-snes_mf_operator",&flg);
1160:   /*
1161:       This version replaces the user provided Jacobian matrix with a
1162:       matrix-free version but still employs the user-provided preconditioner matrix
1163:   */
1164:   if (flg) {
1165:     Mat J;
1166:     MatCreateSNESMF(snes,snes->vec_sol,&J);
1167:     MatSNESMFSetFromOptions(J);
1168:     PetscInfo(snes,"Setting default matrix-free operator routines\n");
1169:     SNESSetJacobian(snes,J,0,0,0);
1170:     MatDestroy(J);
1171:   }

1173: #if !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE) && !defined(PETSC_USE_MAT_SINGLE) && !defined(PETSC_USE_LONG_DOUBLE) && !defined(PETSC_USE_INT)
1174:   PetscOptionsHasName(snes->prefix,"-snes_mf_operator2",&flg);
1175:   if (flg) {
1176:     Mat J;
1177:     SNESDefaultMatrixFreeCreate2(snes,snes->vec_sol,&J);
1178:     SNESSetJacobian(snes,J,0,0,0);
1179:     MatDestroy(J);
1180:   }
1181: #endif

1183:   PetscOptionsHasName(snes->prefix,"-snes_mf",&flg);
1184:   /*
1185:       This version replaces both the user-provided Jacobian and the user-
1186:       provided preconditioner matrix with the default matrix free version.
1187:    */
1188:   if (flg) {
1189:     Mat  J;
1190:     KSP ksp;
1191:     PC   pc;

1193:     MatCreateSNESMF(snes,snes->vec_sol,&J);
1194:     MatSNESMFSetFromOptions(J);
1195:     PetscInfo(snes,"Setting default matrix-free operator and preconditioner routines;\nThat is no preconditioner is being used.\n");
1196:     SNESSetJacobian(snes,J,J,MatSNESMFComputeJacobian,snes->funP);
1197:     MatDestroy(J);

1199:     /* force no preconditioner */
1200:     SNESGetKSP(snes,&ksp);
1201:     KSPGetPC(ksp,&pc);
1202:     PetscTypeCompare((PetscObject)pc,PCSHELL,&flg);
1203:     if (!flg) {
1204:       PCSetType(pc,PCNONE);
1205:     }
1206:   }

1208:   if (!snes->vec_func && !snes->afine) {
1209:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetFunction() first");
1210:   }
1211:   if (!snes->ops->computefunction && !snes->afine) {
1212:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetFunction() first");
1213:   }
1214:   if (!snes->jacobian) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetJacobian() first \n or use -snes_mf option");
1215:   if (snes->vec_func == snes->vec_sol) {
1216:     SETERRQ(PETSC_ERR_ARG_IDN,"Solution vector cannot be function vector");
1217:   }

1219:   /* Set the KSP stopping criterion to use the Eisenstat-Walker method */
1220:   PetscTypeCompare((PetscObject)snes,SNESTR,&iseqtr);
1221:   if (snes->ksp_ewconv && !iseqtr) {
1222:     KSP ksp;
1223:     SNESGetKSP(snes,&ksp);
1224:     KSPSetConvergenceTest(ksp,SNES_KSP_EW_Converged_Private,snes);
1225:   }
1226: 
1227:   if (!snes->type_name) {
1228:     SNESSetType(snes,SNESLS);
1229:   }
1230:   if (snes->ops->setup) {
1231:     (*snes->ops->setup)(snes);
1232:   }
1233:   snes->setupcalled = PETSC_TRUE;
1234:   return(0);
1235: }

1239: /*@
1240:    SNESDestroy - Destroys the nonlinear solver context that was created
1241:    with SNESCreate().

1243:    Collective on SNES

1245:    Input Parameter:
1246: .  snes - the SNES context

1248:    Level: beginner

1250: .keywords: SNES, nonlinear, destroy

1252: .seealso: SNESCreate(), SNESSolve()
1253: @*/
1254: PetscErrorCode  SNESDestroy(SNES snes)
1255: {

1260:   if (--snes->refct > 0) return(0);

1262:   /* if memory was published with AMS then destroy it */
1263:   PetscObjectDepublish(snes);

1265:   if (snes->ops->destroy) {(*(snes)->ops->destroy)(snes);}
1266:   PetscFree(snes->kspconvctx);
1267:   if (snes->jacobian) {MatDestroy(snes->jacobian);}
1268:   if (snes->jacobian_pre) {MatDestroy(snes->jacobian_pre);}
1269:   if (snes->afine) {VecDestroy(snes->afine);}
1270:   KSPDestroy(snes->ksp);
1271:   if (snes->vwork) {VecDestroyVecs(snes->vwork,snes->nvwork);}
1272:   SNESMonitorCancel(snes);
1273:   PetscHeaderDestroy(snes);
1274:   return(0);
1275: }

1277: /* ----------- Routines to set solver parameters ---------- */

1281: /*@
1282:    SNESSetTolerances - Sets various parameters used in convergence tests.

1284:    Collective on SNES

1286:    Input Parameters:
1287: +  snes - the SNES context
1288: .  abstol - absolute convergence tolerance
1289: .  rtol - relative convergence tolerance
1290: .  stol -  convergence tolerance in terms of the norm
1291:            of the change in the solution between steps
1292: .  maxit - maximum number of iterations
1293: -  maxf - maximum number of function evaluations

1295:    Options Database Keys: 
1296: +    -snes_atol <abstol> - Sets abstol
1297: .    -snes_rtol <rtol> - Sets rtol
1298: .    -snes_stol <stol> - Sets stol
1299: .    -snes_max_it <maxit> - Sets maxit
1300: -    -snes_max_funcs <maxf> - Sets maxf

1302:    Notes:
1303:    The default maximum number of iterations is 50.
1304:    The default maximum number of function evaluations is 1000.

1306:    Level: intermediate

1308: .keywords: SNES, nonlinear, set, convergence, tolerances

1310: .seealso: SNESSetTrustRegionTolerance()
1311: @*/
1312: PetscErrorCode  SNESSetTolerances(SNES snes,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)
1313: {
1316:   if (abstol != PETSC_DEFAULT)  snes->abstol      = abstol;
1317:   if (rtol != PETSC_DEFAULT)  snes->rtol      = rtol;
1318:   if (stol != PETSC_DEFAULT)  snes->xtol      = stol;
1319:   if (maxit != PETSC_DEFAULT) snes->max_its   = maxit;
1320:   if (maxf != PETSC_DEFAULT)  snes->max_funcs = maxf;
1321:   return(0);
1322: }

1326: /*@
1327:    SNESGetTolerances - Gets various parameters used in convergence tests.

1329:    Not Collective

1331:    Input Parameters:
1332: +  snes - the SNES context
1333: .  abstol - absolute convergence tolerance
1334: .  rtol - relative convergence tolerance
1335: .  stol -  convergence tolerance in terms of the norm
1336:            of the change in the solution between steps
1337: .  maxit - maximum number of iterations
1338: -  maxf - maximum number of function evaluations

1340:    Notes:
1341:    The user can specify PETSC_NULL for any parameter that is not needed.

1343:    Level: intermediate

1345: .keywords: SNES, nonlinear, get, convergence, tolerances

1347: .seealso: SNESSetTolerances()
1348: @*/
1349: PetscErrorCode  SNESGetTolerances(SNES snes,PetscReal *abstol,PetscReal *rtol,PetscReal *stol,PetscInt *maxit,PetscInt *maxf)
1350: {
1353:   if (abstol)  *abstol  = snes->abstol;
1354:   if (rtol)  *rtol  = snes->rtol;
1355:   if (stol)  *stol  = snes->xtol;
1356:   if (maxit) *maxit = snes->max_its;
1357:   if (maxf)  *maxf  = snes->max_funcs;
1358:   return(0);
1359: }

1363: /*@
1364:    SNESSetTrustRegionTolerance - Sets the trust region parameter tolerance.  

1366:    Collective on SNES

1368:    Input Parameters:
1369: +  snes - the SNES context
1370: -  tol - tolerance
1371:    
1372:    Options Database Key: 
1373: .  -snes_trtol <tol> - Sets tol

1375:    Level: intermediate

1377: .keywords: SNES, nonlinear, set, trust region, tolerance

1379: .seealso: SNESSetTolerances()
1380: @*/
1381: PetscErrorCode  SNESSetTrustRegionTolerance(SNES snes,PetscReal tol)
1382: {
1385:   snes->deltatol = tol;
1386:   return(0);
1387: }

1389: /* 
1390:    Duplicate the lg monitors for SNES from KSP; for some reason with 
1391:    dynamic libraries things don't work under Sun4 if we just use 
1392:    macros instead of functions
1393: */
1396: PetscErrorCode  SNESMonitorLG(SNES snes,PetscInt it,PetscReal norm,void *ctx)
1397: {

1402:   KSPMonitorLG((KSP)snes,it,norm,ctx);
1403:   return(0);
1404: }

1408: PetscErrorCode  SNESMonitorLGCreate(const char host[],const char label[],int x,int y,int m,int n,PetscDrawLG *draw)
1409: {

1413:   KSPMonitorLGCreate(host,label,x,y,m,n,draw);
1414:   return(0);
1415: }

1419: PetscErrorCode  SNESMonitorLGDestroy(PetscDrawLG draw)
1420: {

1424:   KSPMonitorLGDestroy(draw);
1425:   return(0);
1426: }

1428: /* ------------ Routines to set performance monitoring options ----------- */

1432: /*@C
1433:    SNESMonitorSet - Sets an ADDITIONAL function that is to be used at every
1434:    iteration of the nonlinear solver to display the iteration's 
1435:    progress.   

1437:    Collective on SNES

1439:    Input Parameters:
1440: +  snes - the SNES context
1441: .  func - monitoring routine
1442: .  mctx - [optional] user-defined context for private data for the 
1443:           monitor routine (use PETSC_NULL if no context is desired)
1444: -  monitordestroy - [optional] routine that frees monitor context
1445:           (may be PETSC_NULL)

1447:    Calling sequence of func:
1448: $     int func(SNES snes,PetscInt its, PetscReal norm,void *mctx)

1450: +    snes - the SNES context
1451: .    its - iteration number
1452: .    norm - 2-norm function value (may be estimated)
1453: -    mctx - [optional] monitoring context

1455:    Options Database Keys:
1456: +    -snes_monitor        - sets SNESMonitorDefault()
1457: .    -snes_monitor_draw    - sets line graph monitor,
1458:                             uses SNESMonitorLGCreate()
1459: _    -snes_monitor_cancel - cancels all monitors that have
1460:                             been hardwired into a code by 
1461:                             calls to SNESMonitorSet(), but
1462:                             does not cancel those set via
1463:                             the options database.

1465:    Notes: 
1466:    Several different monitoring routines may be set by calling
1467:    SNESMonitorSet() multiple times; all will be called in the 
1468:    order in which they were set.

1470:    Level: intermediate

1472: .keywords: SNES, nonlinear, set, monitor

1474: .seealso: SNESMonitorDefault(), SNESMonitorCancel()
1475: @*/
1476: PetscErrorCode  SNESMonitorSet(SNES snes,PetscErrorCode (*func)(SNES,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1477: {
1480:   if (snes->numbermonitors >= MAXSNESMONITORS) {
1481:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many monitors set");
1482:   }
1483:   snes->monitor[snes->numbermonitors]           = func;
1484:   snes->monitordestroy[snes->numbermonitors]    = monitordestroy;
1485:   snes->monitorcontext[snes->numbermonitors++]  = (void*)mctx;
1486:   return(0);
1487: }

1491: /*@C
1492:    SNESMonitorCancel - Clears all the monitor functions for a SNES object.

1494:    Collective on SNES

1496:    Input Parameters:
1497: .  snes - the SNES context

1499:    Options Database Key:
1500: .  -snes_monitor_cancel - cancels all monitors that have been hardwired
1501:     into a code by calls to SNESMonitorSet(), but does not cancel those 
1502:     set via the options database

1504:    Notes: 
1505:    There is no way to clear one specific monitor from a SNES object.

1507:    Level: intermediate

1509: .keywords: SNES, nonlinear, set, monitor

1511: .seealso: SNESMonitorDefault(), SNESMonitorSet()
1512: @*/
1513: PetscErrorCode  SNESMonitorCancel(SNES snes)
1514: {
1516:   PetscInt       i;

1520:   for (i=0; i<snes->numbermonitors; i++) {
1521:     if (snes->monitordestroy[i]) {
1522:       (*snes->monitordestroy[i])(snes->monitorcontext[i]);
1523:     }
1524:   }
1525:   snes->numbermonitors = 0;
1526:   return(0);
1527: }

1531: /*@C
1532:    SNESSetConvergenceTest - Sets the function that is to be used 
1533:    to test for convergence of the nonlinear iterative solution.   

1535:    Collective on SNES

1537:    Input Parameters:
1538: +  snes - the SNES context
1539: .  func - routine to test for convergence
1540: -  cctx - [optional] context for private data for the convergence routine 
1541:           (may be PETSC_NULL)

1543:    Calling sequence of func:
1544: $     PetscErrorCode func (SNES snes,PetscInt it,PetscReal xnorm,PetscReal gnorm,PetscReal f,SNESConvergedReason *reason,void *cctx)

1546: +    snes - the SNES context
1547: .    it - current iteration (0 is the first and is before any Newton step)
1548: .    cctx - [optional] convergence context
1549: .    reason - reason for convergence/divergence
1550: .    xnorm - 2-norm of current iterate
1551: .    gnorm - 2-norm of current step
1552: -    f - 2-norm of function

1554:    Level: advanced

1556: .keywords: SNES, nonlinear, set, convergence, test

1558: .seealso: SNESConverged_LS(), SNESConverged_TR()
1559: @*/
1560: PetscErrorCode  SNESSetConvergenceTest(SNES snes,PetscErrorCode (*func)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void *cctx)
1561: {
1564:   (snes)->ops->converged = func;
1565:   (snes)->cnvP           = cctx;
1566:   return(0);
1567: }

1571: /*@
1572:    SNESGetConvergedReason - Gets the reason the SNES iteration was stopped.

1574:    Not Collective

1576:    Input Parameter:
1577: .  snes - the SNES context

1579:    Output Parameter:
1580: .  reason - negative value indicates diverged, positive value converged, see petscsnes.h or the 
1581:             manual pages for the individual convergence tests for complete lists

1583:    Level: intermediate

1585:    Notes: Can only be called after the call the SNESSolve() is complete.

1587: .keywords: SNES, nonlinear, set, convergence, test

1589: .seealso: SNESSetConvergenceTest(), SNESConverged_LS(), SNESConverged_TR(), SNESConvergedReason
1590: @*/
1591: PetscErrorCode  SNESGetConvergedReason(SNES snes,SNESConvergedReason *reason)
1592: {
1596:   *reason = snes->reason;
1597:   return(0);
1598: }

1602: /*@
1603:    SNESSetConvergenceHistory - Sets the array used to hold the convergence history.

1605:    Collective on SNES

1607:    Input Parameters:
1608: +  snes - iterative context obtained from SNESCreate()
1609: .  a   - array to hold history
1610: .  its - integer array holds the number of linear iterations for each solve.
1611: .  na  - size of a and its
1612: -  reset - PETSC_TRUE indicates each new nonlinear solve resets the history counter to zero,
1613:            else it continues storing new values for new nonlinear solves after the old ones

1615:    Notes:
1616:    If set, this array will contain the function norms computed
1617:    at each step.

1619:    This routine is useful, e.g., when running a code for purposes
1620:    of accurate performance monitoring, when no I/O should be done
1621:    during the section of code that is being timed.

1623:    Level: intermediate

1625: .keywords: SNES, set, convergence, history

1627: .seealso: SNESGetConvergenceHistory()

1629: @*/
1630: PetscErrorCode  SNESSetConvergenceHistory(SNES snes,PetscReal a[],PetscInt *its,PetscInt na,PetscTruth reset)
1631: {
1635:   snes->conv_hist       = a;
1636:   snes->conv_hist_its   = its;
1637:   snes->conv_hist_max   = na;
1638:   snes->conv_hist_reset = reset;
1639:   return(0);
1640: }

1644: /*@C
1645:    SNESGetConvergenceHistory - Gets the array used to hold the convergence history.

1647:    Collective on SNES

1649:    Input Parameter:
1650: .  snes - iterative context obtained from SNESCreate()

1652:    Output Parameters:
1653: .  a   - array to hold history
1654: .  its - integer array holds the number of linear iterations (or
1655:          negative if not converged) for each solve.
1656: -  na  - size of a and its

1658:    Notes:
1659:     The calling sequence for this routine in Fortran is
1660: $   call SNESGetConvergenceHistory(SNES snes, integer na, integer ierr)

1662:    This routine is useful, e.g., when running a code for purposes
1663:    of accurate performance monitoring, when no I/O should be done
1664:    during the section of code that is being timed.

1666:    Level: intermediate

1668: .keywords: SNES, get, convergence, history

1670: .seealso: SNESSetConvergencHistory()

1672: @*/
1673: PetscErrorCode  SNESGetConvergenceHistory(SNES snes,PetscReal *a[],PetscInt *its[],PetscInt *na)
1674: {
1677:   if (a)   *a   = snes->conv_hist;
1678:   if (its) *its = snes->conv_hist_its;
1679:   if (na) *na   = snes->conv_hist_len;
1680:   return(0);
1681: }

1685: /*@C
1686:   SNESSetUpdate - Sets the general-purpose update function called
1687:   at the beginning o every iteration of the nonlinear solve. Specifically
1688:   it is called just before the Jacobian is "evaluated".

1690:   Collective on SNES

1692:   Input Parameters:
1693: . snes - The nonlinear solver context
1694: . func - The function

1696:   Calling sequence of func:
1697: . func (SNES snes, PetscInt step);

1699: . step - The current step of the iteration

1701:   Level: intermediate

1703: .keywords: SNES, update

1705: .seealso SNESDefaultUpdate(), SNESSetRhsBC(), SNESSetSolutionBC()
1706: @*/
1707: PetscErrorCode  SNESSetUpdate(SNES snes, PetscErrorCode (*func)(SNES, PetscInt))
1708: {
1711:   snes->ops->update = func;
1712:   return(0);
1713: }

1717: /*@
1718:   SNESDefaultUpdate - The default update function which does nothing.

1720:   Not collective

1722:   Input Parameters:
1723: . snes - The nonlinear solver context
1724: . step - The current step of the iteration

1726:   Level: intermediate

1728: .keywords: SNES, update
1729: .seealso SNESSetUpdate(), SNESDefaultRhsBC(), SNESDefaultShortolutionBC()
1730: @*/
1731: PetscErrorCode  SNESDefaultUpdate(SNES snes, PetscInt step)
1732: {
1734:   return(0);
1735: }

1739: /*
1740:    SNESScaleStep_Private - Scales a step so that its length is less than the
1741:    positive parameter delta.

1743:     Input Parameters:
1744: +   snes - the SNES context
1745: .   y - approximate solution of linear system
1746: .   fnorm - 2-norm of current function
1747: -   delta - trust region size

1749:     Output Parameters:
1750: +   gpnorm - predicted function norm at the new point, assuming local 
1751:     linearization.  The value is zero if the step lies within the trust 
1752:     region, and exceeds zero otherwise.
1753: -   ynorm - 2-norm of the step

1755:     Note:
1756:     For non-trust region methods such as SNESLS, the parameter delta 
1757:     is set to be the maximum allowable step size.  

1759: .keywords: SNES, nonlinear, scale, step
1760: */
1761: PetscErrorCode SNESScaleStep_Private(SNES snes,Vec y,PetscReal *fnorm,PetscReal *delta,PetscReal *gpnorm,PetscReal *ynorm)
1762: {
1763:   PetscReal      nrm;
1764:   PetscScalar    cnorm;


1772:   VecNorm(y,NORM_2,&nrm);
1773:   if (nrm > *delta) {
1774:      nrm = *delta/nrm;
1775:      *gpnorm = (1.0 - nrm)*(*fnorm);
1776:      cnorm = nrm;
1777:      VecScale(y,cnorm);
1778:      *ynorm = *delta;
1779:   } else {
1780:      *gpnorm = 0.0;
1781:      *ynorm = nrm;
1782:   }
1783:   return(0);
1784: }

1788: /*@C
1789:    SNESSolve - Solves a nonlinear system F(x) = b.
1790:    Call SNESSolve() after calling SNESCreate() and optional routines of the form SNESSetXXX().

1792:    Collective on SNES

1794:    Input Parameters:
1795: +  snes - the SNES context
1796: .  b - the constant part of the equation, or PETSC_NULL to use zero.
1797: -  x - the solution vector, or PETSC_NULL if it was set with SNESSetSolution()

1799:    Notes:
1800:    The user should initialize the vector,x, with the initial guess
1801:    for the nonlinear solve prior to calling SNESSolve.  In particular,
1802:    to employ an initial guess of zero, the user should explicitly set
1803:    this vector to zero by calling VecSet().

1805:    Level: beginner

1807: .keywords: SNES, nonlinear, solve

1809: .seealso: SNESCreate(), SNESDestroy(), SNESSetFunction(), SNESSetJacobian(), SNESSetRhs(), SNESSetSolution()
1810: @*/
1811: PetscErrorCode  SNESSolve(SNES snes,Vec b,Vec x)
1812: {
1814:   PetscTruth     flg;
1815:   char           filename[PETSC_MAX_PATH_LEN];
1816:   PetscViewer    viewer;

1820:   if (!snes->ops->solve) SETERRQ(PETSC_ERR_ORDER,"SNESSetType() or SNESSetFromOptions() must be called before SNESSolve()");

1822:   if (b) {
1823:     SNESSetRhs(snes, b);
1824:     if (!snes->vec_func) {
1825:       Vec r;

1827:       VecDuplicate(b, &r);
1828:       SNESSetFunction(snes, r, PETSC_NULL, PETSC_NULL);
1829:     }
1830:   }
1831:   if (x) {
1834:   } else {
1835:     SNESGetSolution(snes, &x);
1836:     if (!x) {
1837:       VecDuplicate(snes->vec_func_always, &x);
1838:     }
1839:   }
1840:   snes->vec_sol = snes->vec_sol_always = x;
1841:   if (!snes->setupcalled) {
1842:     SNESSetUp(snes);
1843:   }
1844:   if (snes->conv_hist_reset) snes->conv_hist_len = 0;
1846:   snes->nfuncs = 0; snes->linear_its = 0; snes->numFailures = 0;

1848:   PetscExceptionTry1((*(snes)->ops->solve)(snes),PETSC_ERR_ARG_DOMAIN);
1849:   if (PetscExceptionValue(ierr)) {
1850:     /* this means that a caller above me has also tryed this exception so I don't handle it here, pass it up */
1852:   } else if (PetscExceptionCaught(ierr,PETSC_ERR_ARG_DOMAIN)) {
1853:     /* translate exception into SNES not converged reason */
1854:     snes->reason = SNES_DIVERGED_FUNCTION_DOMAIN;
1855:     0;
1856:   }
1857: 

1860:   PetscOptionsGetString(snes->prefix,"-snes_view",filename,PETSC_MAX_PATH_LEN,&flg);
1861:   if (flg && !PetscPreLoadingOn) {
1862:     PetscViewerASCIIOpen(snes->comm,filename,&viewer);
1863:     SNESView(snes,viewer);
1864:     PetscViewerDestroy(viewer);
1865:   }

1867:   PetscOptionsHasName(snes->prefix,"-snes_test_local_min",&flg);
1868:   if (flg && !PetscPreLoadingOn) { SNESTestLocalMin(snes); }
1869:   if (snes->printreason) {
1870:     if (snes->reason > 0) {
1871:       PetscPrintf(snes->comm,"Nonlinear solve converged due to %s\n",SNESConvergedReasons[snes->reason]);
1872:     } else {
1873:       PetscPrintf(snes->comm,"Nonlinear solve did not converge due to %s\n",SNESConvergedReasons[snes->reason]);
1874:     }
1875:   }

1877:   return(0);
1878: }

1880: /* --------- Internal routines for SNES Package --------- */

1884: /*@C
1885:    SNESSetType - Sets the method for the nonlinear solver.  

1887:    Collective on SNES

1889:    Input Parameters:
1890: +  snes - the SNES context
1891: -  type - a known method

1893:    Options Database Key:
1894: .  -snes_type <type> - Sets the method; use -help for a list
1895:    of available methods (for instance, ls or tr)

1897:    Notes:
1898:    See "petsc/include/petscsnes.h" for available methods (for instance)
1899: +    SNESLS - Newton's method with line search
1900:      (systems of nonlinear equations)
1901: .    SNESTR - Newton's method with trust region
1902:      (systems of nonlinear equations)

1904:   Normally, it is best to use the SNESSetFromOptions() command and then
1905:   set the SNES solver type from the options database rather than by using
1906:   this routine.  Using the options database provides the user with
1907:   maximum flexibility in evaluating the many nonlinear solvers.
1908:   The SNESSetType() routine is provided for those situations where it
1909:   is necessary to set the nonlinear solver independently of the command
1910:   line or options database.  This might be the case, for example, when
1911:   the choice of solver changes during the execution of the program,
1912:   and the user's application is taking responsibility for choosing the
1913:   appropriate method.

1915:   Level: intermediate

1917: .keywords: SNES, set, type

1919: .seealso: SNESType, SNESCreate()

1921: @*/
1922: PetscErrorCode  SNESSetType(SNES snes,SNESType type)
1923: {
1924:   PetscErrorCode ierr,(*r)(SNES);
1925:   PetscTruth     match;


1931:   PetscTypeCompare((PetscObject)snes,type,&match);
1932:   if (match) return(0);

1934:   if (snes->setupcalled) {
1935:     snes->setupcalled = PETSC_FALSE;
1936:     (*(snes)->ops->destroy)(snes);
1937:     snes->data        = 0;
1938:   }

1940:   /* Get the function pointers for the iterative method requested */
1941:   if (!SNESRegisterAllCalled) {SNESRegisterAll(PETSC_NULL);}
1942:    PetscFListFind(snes->comm,SNESList,type,(void (**)(void)) &r);
1943:   if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested SNES type %s",type);
1944:   PetscFree(snes->data);
1945:   snes->data = 0;
1946:   (*r)(snes);
1947:   PetscObjectChangeTypeName((PetscObject)snes,type);
1948:   return(0);
1949: }


1952: /* --------------------------------------------------------------------- */
1955: /*@
1956:    SNESRegisterDestroy - Frees the list of nonlinear solvers that were
1957:    registered by SNESRegisterDynamic().

1959:    Not Collective

1961:    Level: advanced

1963: .keywords: SNES, nonlinear, register, destroy

1965: .seealso: SNESRegisterAll(), SNESRegisterAll()
1966: @*/
1967: PetscErrorCode  SNESRegisterDestroy(void)
1968: {

1972:   if (SNESList) {
1973:     PetscFListDestroy(&SNESList);
1974:     SNESList = 0;
1975:   }
1976:   SNESRegisterAllCalled = PETSC_FALSE;
1977:   return(0);
1978: }

1982: /*@C
1983:    SNESGetType - Gets the SNES method type and name (as a string).

1985:    Not Collective

1987:    Input Parameter:
1988: .  snes - nonlinear solver context

1990:    Output Parameter:
1991: .  type - SNES method (a character string)

1993:    Level: intermediate

1995: .keywords: SNES, nonlinear, get, type, name
1996: @*/
1997: PetscErrorCode  SNESGetType(SNES snes,SNESType *type)
1998: {
2002:   *type = snes->type_name;
2003:   return(0);
2004: }

2008: /*@
2009:    SNESGetSolution - Returns the vector where the approximate solution is
2010:    stored.

2012:    Not Collective, but Vec is parallel if SNES is parallel

2014:    Input Parameter:
2015: .  snes - the SNES context

2017:    Output Parameter:
2018: .  x - the solution

2020:    Level: intermediate

2022: .keywords: SNES, nonlinear, get, solution

2024: .seealso: SNESSetSolution(), SNESGetFunction(), SNESGetSolutionUpdate()
2025: @*/
2026: PetscErrorCode  SNESGetSolution(SNES snes,Vec *x)
2027: {
2031:   *x = snes->vec_sol_always;
2032:   return(0);
2033: }

2037: /*@
2038:    SNESSetSolution - Sets the vector where the approximate solution is stored.

2040:    Not Collective, but Vec is parallel if SNES is parallel

2042:    Input Parameters:
2043: +  snes - the SNES context
2044: -  x - the solution

2046:    Output Parameter:

2048:    Level: intermediate

2050:    Notes: this is not normally used, rather one simply calls SNESSolve() with 
2051:           the appropriate solution vector.

2053: .keywords: SNES, nonlinear, set, solution

2055: .seealso: SNESGetSolution(), SNESGetFunction(), SNESGetSolutionUpdate()
2056: @*/
2057: PetscErrorCode  SNESSetSolution(SNES snes,Vec x)
2058: {
2063:   snes->vec_sol_always = x;
2064:   return(0);
2065: }

2069: /*@
2070:    SNESGetSolutionUpdate - Returns the vector where the solution update is
2071:    stored. 

2073:    Not Collective, but Vec is parallel if SNES is parallel

2075:    Input Parameter:
2076: .  snes - the SNES context

2078:    Output Parameter:
2079: .  x - the solution update

2081:    Level: advanced

2083: .keywords: SNES, nonlinear, get, solution, update

2085: .seealso: SNESGetSolution(), SNESGetFunction
2086: @*/
2087: PetscErrorCode  SNESGetSolutionUpdate(SNES snes,Vec *x)
2088: {
2092:   *x = snes->vec_sol_update_always;
2093:   return(0);
2094: }

2098: /*@C
2099:    SNESGetFunction - Returns the vector where the function is stored.

2101:    Not Collective, but Vec is parallel if SNES is parallel

2103:    Input Parameter:
2104: .  snes - the SNES context

2106:    Output Parameter:
2107: +  r - the function (or PETSC_NULL)
2108: .  func - the function (or PETSC_NULL)
2109: -  ctx - the function context (or PETSC_NULL)

2111:    Level: advanced

2113: .keywords: SNES, nonlinear, get, function

2115: .seealso: SNESSetFunction(), SNESGetSolution()
2116: @*/
2117: PetscErrorCode  SNESGetFunction(SNES snes,Vec *r,PetscErrorCode (**func)(SNES,Vec,Vec,void*),void **ctx)
2118: {
2121:   if (r)    *r    = snes->vec_func_always;
2122:   if (func) *func = snes->ops->computefunction;
2123:   if (ctx)  *ctx  = snes->funP;
2124:   return(0);
2125: }

2129: /*@C
2130:    SNESSetOptionsPrefix - Sets the prefix used for searching for all 
2131:    SNES options in the database.

2133:    Collective on SNES

2135:    Input Parameter:
2136: +  snes - the SNES context
2137: -  prefix - the prefix to prepend to all option names

2139:    Notes:
2140:    A hyphen (-) must NOT be given at the beginning of the prefix name.
2141:    The first character of all runtime options is AUTOMATICALLY the hyphen.

2143:    Level: advanced

2145: .keywords: SNES, set, options, prefix, database

2147: .seealso: SNESSetFromOptions()
2148: @*/
2149: PetscErrorCode  SNESSetOptionsPrefix(SNES snes,const char prefix[])
2150: {

2155:   PetscObjectSetOptionsPrefix((PetscObject)snes,prefix);
2156:   KSPSetOptionsPrefix(snes->ksp,prefix);
2157:   return(0);
2158: }

2162: /*@C
2163:    SNESAppendOptionsPrefix - Appends to the prefix used for searching for all 
2164:    SNES options in the database.

2166:    Collective on SNES

2168:    Input Parameters:
2169: +  snes - the SNES context
2170: -  prefix - the prefix to prepend to all option names

2172:    Notes:
2173:    A hyphen (-) must NOT be given at the beginning of the prefix name.
2174:    The first character of all runtime options is AUTOMATICALLY the hyphen.

2176:    Level: advanced

2178: .keywords: SNES, append, options, prefix, database

2180: .seealso: SNESGetOptionsPrefix()
2181: @*/
2182: PetscErrorCode  SNESAppendOptionsPrefix(SNES snes,const char prefix[])
2183: {
2185: 
2188:   PetscObjectAppendOptionsPrefix((PetscObject)snes,prefix);
2189:   KSPAppendOptionsPrefix(snes->ksp,prefix);
2190:   return(0);
2191: }

2195: /*@C
2196:    SNESGetOptionsPrefix - Sets the prefix used for searching for all 
2197:    SNES options in the database.

2199:    Not Collective

2201:    Input Parameter:
2202: .  snes - the SNES context

2204:    Output Parameter:
2205: .  prefix - pointer to the prefix string used

2207:    Notes: On the fortran side, the user should pass in a string 'prifix' of
2208:    sufficient length to hold the prefix.

2210:    Level: advanced

2212: .keywords: SNES, get, options, prefix, database

2214: .seealso: SNESAppendOptionsPrefix()
2215: @*/
2216: PetscErrorCode  SNESGetOptionsPrefix(SNES snes,const char *prefix[])
2217: {

2222:   PetscObjectGetOptionsPrefix((PetscObject)snes,prefix);
2223:   return(0);
2224: }


2229: /*@C
2230:   SNESRegister - See SNESRegisterDynamic()

2232:   Level: advanced
2233: @*/
2234: PetscErrorCode  SNESRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(SNES))
2235: {
2236:   char           fullname[PETSC_MAX_PATH_LEN];

2240:   PetscFListConcat(path,name,fullname);
2241:   PetscFListAdd(&SNESList,sname,fullname,(void (*)(void))function);
2242:   return(0);
2243: }

2247: PetscErrorCode  SNESTestLocalMin(SNES snes)
2248: {
2250:   PetscInt       N,i,j;
2251:   Vec            u,uh,fh;
2252:   PetscScalar    value;
2253:   PetscReal      norm;

2256:   SNESGetSolution(snes,&u);
2257:   VecDuplicate(u,&uh);
2258:   VecDuplicate(u,&fh);

2260:   /* currently only works for sequential */
2261:   PetscPrintf(PETSC_COMM_WORLD,"Testing FormFunction() for local min\n");
2262:   VecGetSize(u,&N);
2263:   for (i=0; i<N; i++) {
2264:     VecCopy(u,uh);
2265:     PetscPrintf(PETSC_COMM_WORLD,"i = %D\n",i);
2266:     for (j=-10; j<11; j++) {
2267:       value = PetscSign(j)*exp(PetscAbs(j)-10.0);
2268:       VecSetValue(uh,i,value,ADD_VALUES);
2269:       SNESComputeFunction(snes,uh,fh);
2270:       VecNorm(fh,NORM_2,&norm);
2271:       PetscPrintf(PETSC_COMM_WORLD,"       j norm %D %18.16e\n",j,norm);
2272:       value = -value;
2273:       VecSetValue(uh,i,value,ADD_VALUES);
2274:     }
2275:   }
2276:   VecDestroy(uh);
2277:   VecDestroy(fh);
2278:   return(0);
2279: }