Actual source code: taosolver.c

petsc-dev 2014-02-02
Report Typos and Errors
  1: #define TAO_DLL

  3: #include <petsc-private/taoimpl.h> /*I "petsctao.h" I*/

  5: PetscBool TaoRegisterAllCalled = PETSC_FALSE;
  6: PetscFunctionList TaoList = NULL;

  8: PetscClassId TAO_CLASSID;
  9: PetscLogEvent Tao_Solve, Tao_ObjectiveEval, Tao_GradientEval, Tao_ObjGradientEval, Tao_HessianEval, Tao_ConstraintsEval, Tao_JacobianEval;

 11: const char *TaoSubSetTypes[] = {  "subvec","mask","matrixfree","TaoSubSetType","TAO_SUBSET_",0};

 15: /*@
 16:   TaoCreate - Creates a TAO solver

 18:   Collective on MPI_Comm

 20:   Input Parameter:
 21: . comm - MPI communicator

 23:   Output Parameter:
 24: . newtao - the new Tao context

 26:   Available methods include:
 27: +    tao_nls - Newton's method with line search for unconstrained minimization
 28: .    tao_ntr - Newton's method with trust region for unconstrained minimization
 29: .    tao_ntl - Newton's method with trust region, line search for unconstrained minimization
 30: .    tao_lmvm - Limited memory variable metric method for unconstrained minimization
 31: .    tao_cg - Nonlinear conjugate gradient method for unconstrained minimization
 32: .    tao_nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
 33: .    tao_tron - Newton Trust Region method for bound constrained minimization
 34: .    tao_gpcg - Newton Trust Region method for quadratic bound constrained minimization
 35: .    tao_blmvm - Limited memory variable metric method for bound constrained minimization
 36: .    tao_lcl - Linearly constrained Lagrangian method for pde-constrained minimization
 37: -    tao_pounders - Model-based algorithm for nonlinear least squares

 39:    Options Database Keys:
 40: +   -tao_method - select which method TAO should use
 41: -   -tao_type - identical to -tao_method

 43:    Level: beginner

 45: .seealso: TaoSolve(), TaoDestroy()
 46: @*/
 47: PetscErrorCode TaoCreate(MPI_Comm comm, Tao *newtao)
 48: {
 50:   Tao            tao;

 54:   *newtao = NULL;

 56:   TaoInitializePackage();
 57:   TaoLineSearchInitializePackage();

 59:   PetscHeaderCreate(tao,_p_Tao, struct _TaoOps, TAO_CLASSID,"Tao",0,0,comm,TaoDestroy,TaoView);
 60:   tao->ops->computeobjective=0;
 61:   tao->ops->computeobjectiveandgradient=0;
 62:   tao->ops->computegradient=0;
 63:   tao->ops->computehessian=0;
 64:   tao->ops->computeseparableobjective=0;
 65:   tao->ops->computeconstraints=0;
 66:   tao->ops->computejacobian=0;
 67:   tao->ops->computejacobianequality=0;
 68:   tao->ops->computejacobianinequality=0;
 69:   tao->ops->computeequalityconstraints=0;
 70:   tao->ops->computeinequalityconstraints=0;
 71:   tao->ops->convergencetest=TaoDefaultConvergenceTest;
 72:   tao->ops->convergencedestroy=0;
 73:   tao->ops->computedual=0;
 74:   tao->ops->setup=0;
 75:   tao->ops->solve=0;
 76:   tao->ops->view=0;
 77:   tao->ops->setfromoptions=0;
 78:   tao->ops->destroy=0;

 80:   tao->solution=NULL;
 81:   tao->gradient=NULL;
 82:   tao->sep_objective = NULL;
 83:   tao->constraints=NULL;
 84:   tao->constraints_equality=NULL;
 85:   tao->constraints_inequality=NULL;
 86:   tao->stepdirection=NULL;
 87:   tao->XL = NULL;
 88:   tao->XU = NULL;
 89:   tao->IL = NULL;
 90:   tao->IU = NULL;
 91:   tao->DI = NULL;
 92:   tao->DE = NULL;
 93:   tao->hessian = NULL;
 94:   tao->hessian_pre = NULL;
 95:   tao->jacobian = NULL;
 96:   tao->jacobian_pre = NULL;
 97:   tao->jacobian_state = NULL;
 98:   tao->jacobian_state_pre = NULL;
 99:   tao->jacobian_state_inv = NULL;
100:   tao->jacobian_design = NULL;
101:   tao->jacobian_design_pre = NULL;
102:   tao->jacobian_equality = NULL;
103:   tao->jacobian_equality_pre = NULL;
104:   tao->jacobian_inequality = NULL;
105:   tao->jacobian_inequality_pre = NULL;
106:   tao->state_is = NULL;
107:   tao->design_is = NULL;

109:   tao->max_it     = 10000;
110:   tao->max_funcs   = 10000;
111: #if defined(PETSC_USE_REAL_SINGLE)
112:   tao->fatol       = 1e-5;
113:   tao->frtol       = 1e-5;
114:   tao->gatol       = 1e-5;
115:   tao->grtol       = 1e-5;
116: #else
117:   tao->fatol       = 1e-8;
118:   tao->frtol       = 1e-8;
119:   tao->gatol       = 1e-8;
120:   tao->grtol       = 1e-8;
121: #endif
122:   tao->gttol       = 0.0;
123:   tao->catol       = 0.0;
124:   tao->crtol       = 0.0;
125:   tao->xtol        = 0.0;
126:   tao->steptol     = 0.0;
127:   tao->trust0      = PETSC_INFINITY;
128:   tao->fmin        = PETSC_NINFINITY;
129:   tao->hist_reset = PETSC_TRUE;
130:   tao->hist_max = 0;
131:   tao->hist_len = 0;
132:   tao->hist_obj = NULL;
133:   tao->hist_resid = NULL;
134:   tao->hist_cnorm = NULL;

136:   tao->numbermonitors=0;
137:   tao->viewsolution=PETSC_FALSE;
138:   tao->viewhessian=PETSC_FALSE;
139:   tao->viewgradient=PETSC_FALSE;
140:   tao->viewjacobian=PETSC_FALSE;
141:   tao->viewconstraints = PETSC_FALSE;
142:   tao->viewtao = PETSC_FALSE;

144:   TaoResetStatistics(tao);
145:   *newtao = tao;
146:   return(0);
147: }

151: /*@
152:   TaoSolve - Solves an optimization problem min F(x) s.t. l <= x <= u

154:   Collective on Tao

156:   Input Parameters:
157: . tao - the Tao context

159:   Notes:
160:   The user must set up the Tao with calls to TaoSetInitialVector(),
161:   TaoSetObjectiveRoutine(),
162:   TaoSetGradientRoutine(), and (if using 2nd order method) TaoSetHessianRoutine().

164:   Level: beginner

166: .seealso: TaoCreate(), TaoSetObjectiveRoutine(), TaoSetGradientRoutine(), TaoSetHessianRoutine()
167:  @*/
168: PetscErrorCode TaoSolve(Tao tao)
169: {
171:   char           filename[PETSC_MAX_PATH_LEN];
172:   PetscBool      flg;
173:   PetscViewer    viewer;

177:   TaoSetUp(tao);
178:   TaoResetStatistics(tao);
179:   if (tao->linesearch) {
180:     TaoLineSearchReset(tao->linesearch);
181:   }

183:   PetscLogEventBegin(Tao_Solve,tao,0,0,0);
184:   if (tao->ops->solve){ (*tao->ops->solve)(tao); }
185:   PetscLogEventEnd(Tao_Solve,tao,0,0,0);

187:   PetscOptionsGetString(((PetscObject)tao)->prefix,"-tao_view",filename,PETSC_MAX_PATH_LEN,&flg);
188:   if (flg && !PetscPreLoadingOn) {
189:     PetscViewerASCIIOpen(((PetscObject)tao)->comm,filename,&viewer);
190:     TaoView(tao,viewer);
191:     PetscViewerDestroy(&viewer);
192:   }

194:   if (tao->printreason) {
195:     if (tao->reason > 0) {
196:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve converged due to %s\n",TaoTerminationReasons[tao->reason]);
197:     } else {
198:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve did not converge due to %s\n",TaoTerminationReasons[tao->reason]);
199:     }
200:   }
201:   return(0);
202: }

206: /*@
207:   TaoSetUp - Sets up the internal data structures for the later use
208:   of a Tao solver

210:   Collective on tao

212:   Input Parameters:
213: . tao - the TAO context

215:   Notes:
216:   The user will not need to explicitly call TaoSetUp(), as it will
217:   automatically be called in TaoSolve().  However, if the user
218:   desires to call it explicitly, it should come after TaoCreate()
219:   and any TaoSetSomething() routines, but before TaoSolve().

221:   Level: advanced

223: .seealso: TaoCreate(), TaoSolve()
224: @*/
225: PetscErrorCode TaoSetUp(Tao tao)
226: {

231:   if (tao->setupcalled) return(0);

233:   if (!tao->solution) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetInitialVector");
234:   if (tao->ops->setup) {
235:     (*tao->ops->setup)(tao);
236:   }
237:   tao->setupcalled = PETSC_TRUE;
238:   return(0);
239: }

243: /*@
244:   TaoDestroy - Destroys the TAO context that was created with
245:   TaoCreate()

247:   Collective on Tao

249:   Input Parameter:
250: . tao - the Tao context

252:   Level: beginner

254: .seealso: TaoCreate(), TaoSolve()
255: @*/
256: PetscErrorCode TaoDestroy(Tao *tao)
257: {

261:   if (!*tao) return(0);
263:   if (--((PetscObject)*tao)->refct > 0) {*tao=0;return(0);}

265:   if ((*tao)->ops->destroy) {
266:     (*((*tao))->ops->destroy)(*tao);
267:   }
268:   KSPDestroy(&(*tao)->ksp);
269:   TaoLineSearchDestroy(&(*tao)->linesearch);

271:   if ((*tao)->ops->convergencedestroy) {
272:     (*(*tao)->ops->convergencedestroy)((*tao)->cnvP);
273:     if ((*tao)->jacobian_state_inv) {
274:       MatDestroy(&(*tao)->jacobian_state_inv);
275:     }
276:   }
277:   VecDestroy(&(*tao)->solution);
278:   VecDestroy(&(*tao)->gradient);

280:   VecDestroy(&(*tao)->XL);
281:   VecDestroy(&(*tao)->XU);
282:   VecDestroy(&(*tao)->IL);
283:   VecDestroy(&(*tao)->IU);
284:   VecDestroy(&(*tao)->DE);
285:   VecDestroy(&(*tao)->DI);
286:   VecDestroy(&(*tao)->constraints_equality);
287:   VecDestroy(&(*tao)->constraints_inequality);
288:   VecDestroy(&(*tao)->stepdirection);
289:   MatDestroy(&(*tao)->hessian_pre);
290:   MatDestroy(&(*tao)->hessian);
291:   MatDestroy(&(*tao)->jacobian_pre);
292:   MatDestroy(&(*tao)->jacobian);
293:   MatDestroy(&(*tao)->jacobian_state_pre);
294:   MatDestroy(&(*tao)->jacobian_state);
295:   MatDestroy(&(*tao)->jacobian_state_inv);
296:   MatDestroy(&(*tao)->jacobian_design);
297:   MatDestroy(&(*tao)->jacobian_equality);
298:   MatDestroy(&(*tao)->jacobian_equality_pre);
299:   MatDestroy(&(*tao)->jacobian_inequality);
300:   MatDestroy(&(*tao)->jacobian_inequality_pre);
301:   ISDestroy(&(*tao)->state_is);
302:   ISDestroy(&(*tao)->design_is);
303:   TaoCancelMonitors(*tao);
304:   PetscHeaderDestroy(tao);
305:   return(0);
306: }

310: /*@
311:   TaoSetFromOptions - Sets various Tao parameters from user
312:   options.

314:   Collective on Tao

316:   Input Paremeter:
317: . tao - the Tao solver context

319:   options Database Keys:
320: + -tao_method <type> - The algorithm that TAO uses (tao_lmvm, tao_nls, etc.)
321: . -tao_fatol <fatol> - absolute error tolerance in function value
322: . -tao_frtol <frtol> - relative error tolerance in function value
323: . -tao_gatol <gatol> - absolute error tolerance for ||gradient||
324: . -tao_grtol <grtol> - relative error tolerance for ||gradient||
325: . -tao_gttol <gttol> - reduction of ||gradient|| relative to initial gradient
326: . -tao_max_it <max> - sets maximum number of iterations
327: . -tao_max_funcs <max> - sets maximum number of function evaluations
328: . -tao_fmin <fmin> - stop if function value reaches fmin
329: . -tao_steptol <tol> - stop if trust region radius less than <tol>
330: . -tao_trust0 <t> - initial trust region radius
331: . -tao_monitor - prints function value and residual at each iteration
332: . -tao_smonitor - same as tao_monitor, but truncates very small values
333: . -tao_cmonitor - prints function value, residual, and constraint norm at each iteration
334: . -tao_view_solution - prints solution vector at each iteration
335: . -tao_view_separableobjective - prints separable objective vector at each iteration
336: . -tao_view_step - prints step direction vector at each iteration
337: . -tao_view_gradient - prints gradient vector at each iteration
338: . -tao_draw_solution - graphically view solution vector at each iteration
339: . -tao_draw_step - graphically view step vector at each iteration
340: . -tao_draw_gradient - graphically view gradient at each iteration
341: . -tao_fd_gradient - use gradient computed with finite differences
342: . -tao_cancelmonitors - cancels all monitors (except those set with command line)
343: . -tao_view - prints information about the Tao after solving
344: - -tao_converged_reason - prints the reason TAO stopped iterating

346:   Notes:
347:   To see all options, run your program with the -help option or consult the
348:   user's manual. Should be called after TaoCreate() but before TaoSolve()

350:   Level: beginner
351: @*/
352: PetscErrorCode TaoSetFromOptions(Tao tao)
353: {
355:   const TaoType  default_type = "tao_lmvm";
356:   const char     *prefix;
357:   char           type[256], monfilename[PETSC_MAX_PATH_LEN];
358:   PetscViewer    monviewer;
359:   PetscBool      flg;
360:   MPI_Comm       comm;

364:   PetscObjectGetComm((PetscObject)tao,&comm);
365:   TaoGetOptionsPrefix(tao,&prefix);
366:   /* So no warnings are given about unused options */
367:   PetscOptionsHasName(prefix,"-tao_ls_type",&flg);

369:   PetscObjectOptionsBegin((PetscObject)tao);
370:   {
371:     if (!TaoRegisterAllCalled) {
372:       TaoRegisterAll();
373:     }
374:     if (((PetscObject)tao)->type_name) {
375:       default_type = ((PetscObject)tao)->type_name;
376:     }
377:     /* Check for type from options */
378:     PetscOptionsFList("-tao_type","Tao Solver type","TaoSetType",TaoList,default_type,type,256,&flg);
379:     if (flg) {
380:       TaoSetType(tao,type);
381:     } else {
382:       PetscOptionsFList("-tao_method","Tao Solver type","TaoSetType",TaoList,default_type,type,256,&flg);
383:       if (flg) {
384:         TaoSetType(tao,type);
385:       } else if (!((PetscObject)tao)->type_name) {
386:         TaoSetType(tao,default_type);
387:       }
388:     }

390:     PetscOptionsBool("-tao_view","view Tao info after each minimization has completed","TaoView",PETSC_FALSE,&tao->viewtao,&flg);
391:     PetscOptionsReal("-tao_fatol","Stop if solution within","TaoSetTolerances",tao->fatol,&tao->fatol,&flg);
392:     PetscOptionsReal("-tao_frtol","Stop if relative solution within","TaoSetTolerances",tao->frtol,&tao->frtol,&flg);
393:     PetscOptionsReal("-tao_catol","Stop if constraints violations within","TaoSetConstraintTolerances",tao->catol,&tao->catol,&flg);
394:     PetscOptionsReal("-tao_crtol","Stop if relative contraint violations within","TaoSetConstraintTolerances",tao->crtol,&tao->crtol,&flg);
395:     PetscOptionsReal("-tao_gatol","Stop if norm of gradient less than","TaoSetTolerances",tao->gatol,&tao->gatol,&flg);
396:     PetscOptionsReal("-tao_grtol","Stop if norm of gradient divided by the function value is less than","TaoSetTolerances",tao->grtol,&tao->grtol,&flg);
397:     PetscOptionsReal("-tao_gttol","Stop if the norm of the gradient is less than the norm of the initial gradient times tol","TaoSetTolerances",tao->gttol,&tao->gttol,&flg);
398:     PetscOptionsInt("-tao_max_it","Stop if iteration number exceeds","TaoSetMaximumIterations",tao->max_it,&tao->max_it,&flg);
399:     PetscOptionsInt("-tao_max_funcs","Stop if number of function evaluations exceeds","TaoSetMaximumFunctionEvaluations",tao->max_funcs,&tao->max_funcs,&flg);
400:     PetscOptionsReal("-tao_fmin","Stop if function less than","TaoSetFunctionLowerBound",tao->fmin,&tao->fmin,&flg);
401:     PetscOptionsReal("-tao_steptol","Stop if step size or trust region radius less than","",tao->steptol,&tao->steptol,&flg);
402:     PetscOptionsReal("-tao_trust0","Initial trust region radius","TaoSetTrustRegionRadius",tao->trust0,&tao->trust0,&flg);

404:     PetscOptionsString("-tao_view_solution","view solution vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
405:     if (flg) {
406:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
407:       TaoSetMonitor(tao,TaoSolutionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
408:     }

410:     PetscOptionsBool("-tao_converged_reason","Print reason for TAO termination","TaoSolve",flg,&flg,NULL);
411:     if (flg) {
412:       tao->printreason = PETSC_TRUE;
413:     }
414:     PetscOptionsString("-tao_view_gradient","view gradient vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
415:     if (flg) {
416:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
417:       TaoSetMonitor(tao,TaoGradientMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
418:     }

420:     PetscOptionsString("-tao_view_stepdirection","view step direction vector after each iteration","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
421:     if (flg) {
422:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
423:       TaoSetMonitor(tao,TaoStepDirectionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
424:     }

426:     PetscOptionsString("-tao_view_separableobjective","view separable objective vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
427:     if (flg) {
428:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
429:       TaoSetMonitor(tao,TaoSeparableObjectiveMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
430:     }

432:     PetscOptionsString("-tao_monitor","Use the default convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
433:     if (flg) {
434:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
435:       TaoSetMonitor(tao,TaoDefaultMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
436:     }

438:     PetscOptionsString("-tao_smonitor","Use the short convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
439:     if (flg) {
440:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
441:       TaoSetMonitor(tao,TaoDefaultSMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
442:     }

444:     PetscOptionsString("-tao_cmonitor","Use the default convergence monitor with constraint norm","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
445:     if (flg) {
446:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
447:       TaoSetMonitor(tao,TaoDefaultCMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
448:     }


451:     PetscOptionsBool("-tao_cancelmonitors","cancel all monitors and call any registered destroy routines","TaoCancelMonitors",PETSC_FALSE,&flg,NULL);
452:     if (flg) {TaoCancelMonitors(tao);}

454:     PetscOptionsBool("-tao_draw_solution","Plot solution vector at each iteration","TaoSetMonitor",PETSC_FALSE,&flg,NULL);
455:     if (flg) {
456:       TaoSetMonitor(tao,TaoDrawSolutionMonitor,NULL,NULL);
457:     }

459:     PetscOptionsBool("-tao_draw_step","plots step direction at each iteration","TaoSetMonitor",PETSC_FALSE,&flg,NULL);
460:     if (flg) {
461:       TaoSetMonitor(tao,TaoDrawStepMonitor,NULL,NULL);
462:     }

464:     PetscOptionsBool("-tao_draw_gradient","plots gradient at each iteration","TaoSetMonitor",PETSC_FALSE,&flg,NULL);
465:     if (flg) {
466:       TaoSetMonitor(tao,TaoDrawGradientMonitor,NULL,NULL);
467:     }
468:     PetscOptionsBool("-tao_fd_gradient","compute gradient using finite differences","TaoDefaultComputeGradient",PETSC_FALSE,&flg,NULL);
469:     if (flg) {
470:       TaoSetGradientRoutine(tao,TaoDefaultComputeGradient,NULL);
471:     }
472:     PetscOptionsEnum("-tao_subset_type","subset type", "", TaoSubSetTypes,(PetscEnum)tao->subset_type, (PetscEnum*)&tao->subset_type, 0);

474:     if (tao->ops->setfromoptions) {
475:       (*tao->ops->setfromoptions)(tao);
476:     }
477:   }
478:   PetscOptionsEnd();
479:   return(0);
480: }

484: /*@C
485:   TaoView - Prints information about the Tao

487:   Collective on Tao

489:   InputParameters:
490: + tao - the Tao context
491: - viewer - visualization context

493:   Options Database Key:
494: . -tao_view - Calls TaoView() at the end of TaoSolve()

496:   Notes:
497:   The available visualization contexts include
498: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
499: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
500:          output where only the first processor opens
501:          the file.  All other processors send their
502:          data to the first processor to print.

504:   Level: beginner

506: .seealso: PetscViewerASCIIOpen()
507: @*/
508: PetscErrorCode TaoView(Tao tao, PetscViewer viewer)
509: {
510:   PetscErrorCode      ierr;
511:   PetscBool           isascii,isstring;
512:   const TaoType type;

516:   if (!viewer) {
517:     PetscViewerASCIIGetStdout(((PetscObject)tao)->comm,&viewer);
518:   }

522:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
523:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSTRING,&isstring);
524:   if (isascii) {
525:     PetscObjectPrintClassNamePrefixType((PetscObject)tao,viewer);
526:     PetscViewerASCIIPushTab(viewer);

528:     if (tao->ops->view) {
529:       PetscViewerASCIIPushTab(viewer);
530:       (*tao->ops->view)(tao,viewer);
531:       PetscViewerASCIIPopTab(viewer);
532:     }
533:     if (tao->linesearch) {
534:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->linesearch),viewer);
535:     }
536:     if (tao->ksp) {
537:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->ksp),viewer);
538:       PetscViewerASCIIPrintf(viewer,"total KSP iterations: %D\n",tao->ksp_its);
539:     }
540:     if (tao->XL || tao->XU) {
541:       PetscViewerASCIIPrintf(viewer,"Active Set subset type: %s\n",TaoSubSetTypes[tao->subset_type]);
542:     }

544:     ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: fatol=%g,",(double)tao->fatol);
545:     ierr=PetscViewerASCIIPrintf(viewer," frtol=%g\n",(double)tao->frtol);

547:     ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: gatol=%g,",(double)tao->gatol);
548:     ierr=PetscViewerASCIIPrintf(viewer," steptol=%g,",(double)tao->steptol);
549:     ierr=PetscViewerASCIIPrintf(viewer," gttol=%g\n",(double)tao->gttol);

551:     PetscViewerASCIIPrintf(viewer,"Residual in Function/Gradient:=%g\n",(double)tao->residual);

553:     if (tao->cnorm>0 || tao->catol>0 || tao->crtol>0){
554:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances:");
555:       ierr=PetscViewerASCIIPrintf(viewer," catol=%g,",(double)tao->catol);
556:       ierr=PetscViewerASCIIPrintf(viewer," crtol=%g\n",(double)tao->crtol);
557:       PetscViewerASCIIPrintf(viewer,"Residual in Constraints:=%g\n",(double)tao->cnorm);
558:     }

560:     if (tao->trust < tao->steptol){
561:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: steptol=%g\n",(double)tao->steptol);
562:       ierr=PetscViewerASCIIPrintf(viewer,"Final trust region radius:=%g\n",(double)tao->trust);
563:     }

565:     if (tao->fmin>-1.e25){
566:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: function minimum=%g\n",(double)tao->fmin);
567:     }
568:     PetscViewerASCIIPrintf(viewer,"Objective value=%g\n",(double)tao->fc);

570:     PetscViewerASCIIPrintf(viewer,"total number of iterations=%D,          ",tao->niter);
571:     PetscViewerASCIIPrintf(viewer,"              (max: %D)\n",tao->max_it);

573:     if (tao->nfuncs>0){
574:       PetscViewerASCIIPrintf(viewer,"total number of function evaluations=%D,",tao->nfuncs);
575:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
576:     }
577:     if (tao->ngrads>0){
578:       PetscViewerASCIIPrintf(viewer,"total number of gradient evaluations=%D,",tao->ngrads);
579:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
580:     }
581:     if (tao->nfuncgrads>0){
582:       PetscViewerASCIIPrintf(viewer,"total number of function/gradient evaluations=%D,",tao->nfuncgrads);
583:       PetscViewerASCIIPrintf(viewer,"    (max: %D)\n",tao->max_funcs);
584:     }
585:     if (tao->nhess>0){
586:       PetscViewerASCIIPrintf(viewer,"total number of Hessian evaluations=%D\n",tao->nhess);
587:     }
588:     /*  if (tao->linear_its>0){
589:      PetscViewerASCIIPrintf(viewer,"  total Krylov method iterations=%D\n",tao->linear_its);
590:      }*/
591:     if (tao->nconstraints>0){
592:       PetscViewerASCIIPrintf(viewer,"total number of constraint function evaluations=%D\n",tao->nconstraints);
593:     }
594:     if (tao->njac>0){
595:       PetscViewerASCIIPrintf(viewer,"total number of Jacobian evaluations=%D\n",tao->njac);
596:     }

598:     if (tao->reason>0){
599:       PetscViewerASCIIPrintf(viewer,    "Solution converged: ");
600:       switch (tao->reason) {
601:       case TAO_CONVERGED_FATOL:
602:         PetscViewerASCIIPrintf(viewer,"estimated f(x)-f(X*) <= fatol\n");
603:         break;
604:       case TAO_CONVERGED_FRTOL:
605:         PetscViewerASCIIPrintf(viewer,"estimated |f(x)-f(X*)|/|f(X*)| <= frtol\n");
606:         break;
607:       case TAO_CONVERGED_GATOL:
608:         PetscViewerASCIIPrintf(viewer," ||g(X)|| <= gatol\n");
609:         break;
610:       case TAO_CONVERGED_GRTOL:
611:         PetscViewerASCIIPrintf(viewer," ||g(X)||/|f(X)| <= grtol\n");
612:         break;
613:       case TAO_CONVERGED_GTTOL:
614:         PetscViewerASCIIPrintf(viewer," ||g(X)||/||g(X0)|| <= gttol\n");
615:         break;
616:       case TAO_CONVERGED_STEPTOL:
617:         PetscViewerASCIIPrintf(viewer," Steptol -- step size small\n");
618:         break;
619:       case TAO_CONVERGED_MINF:
620:         PetscViewerASCIIPrintf(viewer," Minf --  f < fmin\n");
621:         break;
622:       case TAO_CONVERGED_USER:
623:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
624:         break;
625:       default:
626:         PetscViewerASCIIPrintf(viewer,"\n");
627:         break;
628:       }

630:     } else {
631:       PetscViewerASCIIPrintf(viewer,"Solver terminated: %D",tao->reason);
632:       switch (tao->reason) {
633:       case TAO_DIVERGED_MAXITS:
634:         PetscViewerASCIIPrintf(viewer," Maximum Iterations\n");
635:         break;
636:       case TAO_DIVERGED_NAN:
637:         PetscViewerASCIIPrintf(viewer," NAN or Inf encountered\n");
638:         break;
639:       case TAO_DIVERGED_MAXFCN:
640:         PetscViewerASCIIPrintf(viewer," Maximum Function Evaluations\n");
641:         break;
642:       case TAO_DIVERGED_LS_FAILURE:
643:         PetscViewerASCIIPrintf(viewer," Line Search Failure\n");
644:         break;
645:       case TAO_DIVERGED_TR_REDUCTION:
646:         PetscViewerASCIIPrintf(viewer," Trust Region too small\n");
647:         break;
648:       case TAO_DIVERGED_USER:
649:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
650:         break;
651:       default:
652:         PetscViewerASCIIPrintf(viewer,"\n");
653:         break;
654:       }
655:     }
656:     PetscViewerASCIIPopTab(viewer);
657:   } else if (isstring) {
658:     TaoGetType(tao,&type);
659:     PetscViewerStringSPrintf(viewer," %-3.3s",type);
660:   }
661:   return(0);
662: }

666: /*@
667:   TaoSetTolerances - Sets parameters used in TAO convergence tests

669:   Logically collective on Tao

671:   Input Parameters:
672: + tao - the Tao context
673: . fatol - absolute convergence tolerance
674: . frtol - relative convergence tolerance
675: . gatol - stop if norm of gradient is less than this
676: . grtol - stop if relative norm of gradient is less than this
677: - gttol - stop if norm of gradient is reduced by this factor

679:   Options Database Keys:
680: + -tao_fatol <fatol> - Sets fatol
681: . -tao_frtol <frtol> - Sets frtol
682: . -tao_gatol <gatol> - Sets gatol
683: . -tao_grtol <grtol> - Sets grtol
684: - -tao_gttol <gttol> - Sets gttol

686:   Stopping Criteria:
687: $ f(X) - f(X*) (estimated)            <= fatol
688: $ |f(X) - f(X*)| (estimated) / |f(X)| <= frtol
689: $ ||g(X)||                            <= gatol
690: $ ||g(X)|| / |f(X)|                   <= grtol
691: $ ||g(X)|| / ||g(X0)||                <= gttol

693:   Notes:
694:   Use PETSC_DEFAULT to leave one or more tolerances unchanged.

696:   Level: beginner

698: .seealso: TaoGetTolerances()

700: @*/
701: PetscErrorCode TaoSetTolerances(Tao tao, PetscReal fatol, PetscReal frtol, PetscReal gatol, PetscReal grtol, PetscReal gttol)
702: {


708:   if (fatol != PETSC_DEFAULT) {
709:     if (fatol<0) {
710:       PetscInfo(tao,"Tried to set negative fatol -- ignored.");
711:     } else {
712:       tao->fatol = PetscMax(0,fatol);
713:     }
714:   }
715:   if (frtol != PETSC_DEFAULT) {
716:     if (frtol<0) {
717:       PetscInfo(tao,"Tried to set negative frtol -- ignored.");
718:     } else {
719:       tao->frtol = PetscMax(0,frtol);
720:     }
721:   }

723:   if (gatol != PETSC_DEFAULT) {
724:     if (gatol<0) {
725:       PetscInfo(tao,"Tried to set negative gatol -- ignored.");
726:     } else {
727:       tao->gatol = PetscMax(0,gatol);
728:     }
729:   }

731:   if (grtol != PETSC_DEFAULT) {
732:     if (grtol<0) {
733:       PetscInfo(tao,"Tried to set negative grtol -- ignored.");
734:     } else {
735:       tao->grtol = PetscMax(0,grtol);
736:     }
737:   }

739:   if (gttol != PETSC_DEFAULT) {
740:     if (gttol<0) {
741:       PetscInfo(tao,"Tried to set negative gttol -- ignored.");
742:     } else {
743:       tao->gttol = PetscMax(0,gttol);
744:     }
745:   }
746:   return(0);
747: }

751: /*@
752:   TaoSetConstraintTolerances - Sets contraint tolerance parameters used in TAO
753:   convergence tests

755:   Logically collective on Tao

757:   Input Parameters:
758: + tao - the Tao context
759: . catol - absolute constraint tolerance, constraint norm must be less than catol for used for fatol, gatol convergence criteria
760: - crtol - relative contraint tolerance, constraint norm must be less than crtol for used for fatol, gatol, gttol convergence criteria

762:   Options Database Keys:
763: + -tao_catol <catol> - Sets catol
764: - -tao_crtol <crtol> - Sets crtol

766:   Level: intermediate

768: .seealso: TaoGetTolerances()

770: @*/
771: PetscErrorCode TaoSetConstraintTolerances(Tao tao, PetscReal catol, PetscReal crtol)
772: {


778:   if (catol != PETSC_DEFAULT) {
779:     if (catol<0) {
780:       PetscInfo(tao,"Tried to set negative catol -- ignored.");
781:     } else {
782:       tao->catol = PetscMax(0,catol);
783:     }
784:   }

786:   if (crtol != PETSC_DEFAULT) {
787:     if (crtol<0) {
788:       PetscInfo(tao,"Tried to set negative crtol -- ignored.");
789:     } else {
790:       tao->crtol = PetscMax(0,crtol);
791:     }
792:   }
793:   return(0);
794: }

798: /*@
799:    TaoSetFunctionLowerBound - Sets a bound on the solution objective value.
800:    When an approximate solution with an objective value below this number
801:    has been found, the solver will terminate.

803:    Logically Collective on Tao

805:    Input Parameters:
806: +  tao - the Tao solver context
807: -  fmin - the tolerance

809:    Options Database Keys:
810: .    -tao_fmin <fmin> - sets the minimum function value

812:    Level: intermediate

814: .seealso: TaoSetTolerances()
815: @*/
816: PetscErrorCode TaoSetFunctionLowerBound(Tao tao,PetscReal fmin)
817: {
820:   tao->fmin = fmin;
821:   return(0);
822: }

826: /*@
827:    TaoGetFunctionLowerBound - Sets a bound on the solution objective value.
828:    When an approximate solution with an objective value below this number
829:    has been found, the solver will terminate.

831:    Not collective on Tao

833:    Input Parameters:
834: .  tao - the Tao solver context

836:    OutputParameters:
837: .  fmin - the minimum function value

839:    Level: intermediate

841: .seealso: TaoSetFunctionLowerBound()
842: @*/
843: PetscErrorCode TaoGetFunctionLowerBound(Tao tao,PetscReal *fmin)
844: {
847:   *fmin = tao->fmin;
848:   return(0);
849: }

853: /*@
854:    TaoSetMaximumFunctionEvaluations - Sets a maximum number of
855:    function evaluations.

857:    Logically Collective on Tao

859:    Input Parameters:
860: +  tao - the Tao solver context
861: -  nfcn - the maximum number of function evaluations (>=0)

863:    Options Database Keys:
864: .    -tao_max_funcs <nfcn> - sets the maximum number of function evaluations

866:    Level: intermediate

868: .seealso: TaoSetTolerances(), TaoSetMaximumIterations()
869: @*/

871: PetscErrorCode TaoSetMaximumFunctionEvaluations(Tao tao,PetscInt nfcn)
872: {
875:   tao->max_funcs = PetscMax(0,nfcn);
876:   return(0);
877: }

881: /*@
882:    TaoGetMaximumFunctionEvaluations - Sets a maximum number of
883:    function evaluations.

885:    Not Collective

887:    Input Parameters:
888: .  tao - the Tao solver context

890:    Output Parameters:
891: .  nfcn - the maximum number of function evaluations

893:    Level: intermediate

895: .seealso: TaoSetMaximumFunctionEvaluations(), TaoGetMaximumIterations()
896: @*/

898: PetscErrorCode TaoGetMaximumFunctionEvaluations(Tao tao,PetscInt *nfcn)
899: {
902:   *nfcn = tao->max_funcs;
903:   return(0);
904: }

908: /*@
909:    TaoSetMaximumIterations - Sets a maximum number of iterates.

911:    Logically Collective on Tao

913:    Input Parameters:
914: +  tao - the Tao solver context
915: -  maxits - the maximum number of iterates (>=0)

917:    Options Database Keys:
918: .    -tao_max_it <its> - sets the maximum number of iterations

920:    Level: intermediate

922: .seealso: TaoSetTolerances(), TaoSetMaximumFunctionEvaluations()
923: @*/
924: PetscErrorCode TaoSetMaximumIterations(Tao tao,PetscInt maxits)
925: {
928:   tao->max_it = PetscMax(0,maxits);
929:   return(0);
930: }

934: /*@
935:    TaoGetMaximumIterations - Sets a maximum number of iterates.

937:    Not Collective

939:    Input Parameters:
940: .  tao - the Tao solver context

942:    Output Parameters:
943: .  maxits - the maximum number of iterates

945:    Level: intermediate

947: .seealso: TaoSetMaximumIterations(), TaoGetMaximumFunctionEvaluations()
948: @*/
949: PetscErrorCode TaoGetMaximumIterations(Tao tao,PetscInt *maxits)
950: {
953:   *maxits = tao->max_it;
954:   return(0);
955: }

959: /*@
960:    TaoSetInitialTrustRegionRadius - Sets the initial trust region radius.

962:    Logically collective on Tao

964:    Input Parameter:
965: +  tao - a TAO optimization solver
966: -  radius - the trust region radius

968:    Level: intermediate

970:    Options Database Key:
971: .  -tao_trust0 <t0> - sets initial trust region radius

973: .seealso: TaoGetTrustRegionRadius(), TaoSetTrustRegionTolerance()
974: @*/
975: PetscErrorCode TaoSetInitialTrustRegionRadius(Tao tao, PetscReal radius)
976: {
979:   tao->trust0 = PetscMax(0.0,radius);
980:   return(0);
981: }

985: /*@
986:    TaoGetInitialTrustRegionRadius - Sets the initial trust region radius.

988:    Not Collective

990:    Input Parameter:
991: .  tao - a TAO optimization solver

993:    Output Parameter:
994: .  radius - the trust region radius

996:    Level: intermediate

998: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetCurrentTrustRegionRadius()
999: @*/
1000: PetscErrorCode TaoGetInitialTrustRegionRadius(Tao tao, PetscReal *radius)
1001: {
1004:   *radius = tao->trust0;
1005:   return(0);
1006: }

1010: /*@
1011:    TaoGetCurrentTrustRegionRadius - Gets the current trust region radius.

1013:    Not Collective

1015:    Input Parameter:
1016: .  tao - a TAO optimization solver

1018:    Output Parameter:
1019: .  radius - the trust region radius

1021:    Level: intermediate

1023: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetInitialTrustRegionRadius()
1024: @*/
1025: PetscErrorCode TaoGetCurrentTrustRegionRadius(Tao tao, PetscReal *radius)
1026: {
1029:   *radius = tao->trust;
1030:   return(0);
1031: }

1035: /*@
1036:   TaoGetTolerances - gets the current values of tolerances

1038:   Not Collective

1040:   Input Parameters:
1041: . tao - the Tao context

1043:   Output Parameters:
1044: + fatol - absolute convergence tolerance
1045: . frtol - relative convergence tolerance
1046: . gatol - stop if norm of gradient is less than this
1047: . grtol - stop if relative norm of gradient is less than this
1048: - gttol - stop if norm of gradient is reduced by a this factor

1050:   Note: NULL can be used as an argument if not all tolerances values are needed

1052: .seealso TaoSetTolerances()

1054:   Level: intermediate
1055: @*/
1056: PetscErrorCode TaoGetTolerances(Tao tao, PetscReal *fatol, PetscReal *frtol, PetscReal *gatol, PetscReal *grtol, PetscReal *gttol)
1057: {
1060:   if (fatol) *fatol=tao->fatol;
1061:   if (frtol) *frtol=tao->frtol;
1062:   if (gatol) *gatol=tao->gatol;
1063:   if (grtol) *grtol=tao->grtol;
1064:   if (gttol) *gttol=tao->gttol;
1065:   return(0);
1066: }

1070: /*@
1071:   TaoGetKSP - Gets the linear solver used by the optimization solver.
1072:   Application writers should use TaoGetKSP if they need direct access
1073:   to the PETSc KSP object.

1075:   Not Collective

1077:    Input Parameters:
1078: .  tao - the TAO solver

1080:    Output Parameters:
1081: .  ksp - the KSP linear solver used in the optimization solver

1083:    Level: intermediate

1085: @*/
1086: PetscErrorCode TaoGetKSP(Tao tao, KSP *ksp)
1087: {
1089:   *ksp = tao->ksp;
1090:   return(0);
1091: }

1095: /*@
1096:   TaoGetLineSearch - Gets the line search used by the optimization solver.
1097:   Application writers should use TaoGetLineSearch if they need direct access
1098:   to the TaoLineSearch object.

1100:   Not Collective

1102:    Input Parameters:
1103: .  tao - the TAO solver

1105:    Output Parameters:
1106: .  ls - the line search used in the optimization solver

1108:    Level: intermediate

1110: @*/
1111: PetscErrorCode TaoGetLineSearch(Tao tao, TaoLineSearch *ls)
1112: {
1114:   *ls = tao->linesearch;
1115:   return(0);
1116: }

1120: /*@
1121:   TaoAddLineSearchCounts - Adds the number of function evaluations spent
1122:   in the line search to the running total.

1124:    Input Parameters:
1125: +  tao - the TAO solver
1126: -  ls - the line search used in the optimization solver

1128:    Level: developer

1130: .seealso: TaoLineSearchApply()
1131: @*/
1132: PetscErrorCode TaoAddLineSearchCounts(Tao tao)
1133: {
1135:   PetscBool      flg;
1136:   PetscInt       nfeval,ngeval,nfgeval;

1140:   if (tao->linesearch) {
1141:     TaoLineSearchIsUsingTaoRoutines(tao->linesearch,&flg);
1142:     if (flg == PETSC_FALSE) {
1143:       TaoLineSearchGetNumberFunctionEvaluations(tao->linesearch,&nfeval,&ngeval,&nfgeval);
1144:       tao->nfuncs+=nfeval;
1145:       tao->ngrads+=ngeval;
1146:       tao->nfuncgrads+=nfgeval;
1147:     }
1148:   }
1149:   return(0);
1150: }

1154: /*@
1155:   TaoGetSolutionVector - Returns the vector with the current TAO solution

1157:   Not Collective

1159:   Input Parameter:
1160: . tao - the Tao context

1162:   Output Parameter:
1163: . X - the current solution

1165:   Level: intermediate

1167:   Note:  The returned vector will be the same object that was passed into TaoSetInitialVector()
1168: @*/
1169: PetscErrorCode TaoGetSolutionVector(Tao tao, Vec *X)
1170: {
1173:   *X = tao->solution;
1174:   return(0);
1175: }

1179: /*@
1180:   TaoGetGradientVector - Returns the vector with the current TAO gradient

1182:   Not Collective

1184:   Input Parameter:
1185: . tao - the Tao context

1187:   Output Parameter:
1188: . G - the current solution

1190:   Level: intermediate
1191: @*/
1192: PetscErrorCode TaoGetGradientVector(Tao tao, Vec *G)
1193: {
1196:   *G = tao->gradient;
1197:   return(0);
1198: }

1202: /*@
1203:    TaoResetStatistics - Initialize the statistics used by TAO for all of the solvers.
1204:    These statistics include the iteration number, residual norms, and convergence status.
1205:    This routine gets called before solving each optimization problem.

1207:    Collective on Tao

1209:    Input Parameters:
1210: .  solver - the Tao context

1212:    Level: developer

1214: .seealso: TaoCreate(), TaoSolve()
1215: @*/
1216: PetscErrorCode TaoResetStatistics(Tao tao)
1217: {
1220:   tao->niter        = 0;
1221:   tao->nfuncs       = 0;
1222:   tao->nfuncgrads   = 0;
1223:   tao->ngrads       = 0;
1224:   tao->nhess        = 0;
1225:   tao->njac         = 0;
1226:   tao->nconstraints = 0;
1227:   tao->ksp_its      = 0;
1228:   tao->reason       = TAO_CONTINUE_ITERATING;
1229:   tao->residual     = 0.0;
1230:   tao->cnorm        = 0.0;
1231:   tao->step         = 0.0;
1232:   tao->lsflag       = PETSC_FALSE;
1233:   if (tao->hist_reset) tao->hist_len=0;
1234:   return(0);
1235: }

1239: /*@C
1240:   TaoSetConvergenceTest - Sets the function that is to be used to test
1241:   for convergence o fthe iterative minimization solution.  The new convergence
1242:   testing routine will replace TAO's default convergence test.

1244:   Logically Collective on Tao

1246:   Input Parameters:
1247: + tao - the Tao object
1248: . conv - the routine to test for convergence
1249: - ctx - [optional] context for private data for the convergence routine
1250:         (may be NULL)

1252:   Calling sequence of conv:
1253: $   PetscErrorCode conv(Tao tao, void *ctx)

1255: + tao - the Tao object
1256: - ctx - [optional] convergence context

1258:   Note: The new convergence testing routine should call TaoSetTerminationReason().

1260:   Level: advanced

1262: .seealso: TaoSetTerminationReason(), TaoGetSolutionStatus(), TaoGetTolerances(), TaoSetMonitor

1264: @*/
1265: PetscErrorCode TaoSetConvergenceTest(Tao tao, PetscErrorCode (*conv)(Tao,void*), void *ctx)
1266: {
1269:   (tao)->ops->convergencetest = conv;
1270:   (tao)->cnvP = ctx;
1271:   return(0);
1272: }

1276: /*@C
1277:    TaoSetMonitor - Sets an ADDITIONAL function that is to be used at every
1278:    iteration of the solver to display the iteration's
1279:    progress.

1281:    Logically Collective on Tao

1283:    Input Parameters:
1284: +  tao - the Tao solver context
1285: .  mymonitor - monitoring routine
1286: -  mctx - [optional] user-defined context for private data for the
1287:           monitor routine (may be NULL)

1289:    Calling sequence of mymonitor:
1290: $     int mymonitor(Tao tao,void *mctx)

1292: +    tao - the Tao solver context
1293: -    mctx - [optional] monitoring context


1296:    Options Database Keys:
1297: +    -tao_monitor        - sets TaoDefaultMonitor()
1298: .    -tao_smonitor       - sets short monitor
1299: .    -tao_cmonitor       - same as smonitor plus constraint norm
1300: .    -tao_view_solution   - view solution at each iteration
1301: .    -tao_view_gradient   - view gradient at each iteration
1302: .    -tao_view_separableobjective - view separable objective function at each iteration
1303: -    -tao_cancelmonitors - cancels all monitors that have been hardwired into a code by calls to TaoSetMonitor(), but does not cancel those set via the options database.


1306:    Notes:
1307:    Several different monitoring routines may be set by calling
1308:    TaoSetMonitor() multiple times; all will be called in the
1309:    order in which they were set.

1311:    Fortran Notes: Only one monitor function may be set

1313:    Level: intermediate

1315: .seealso: TaoDefaultMonitor(), TaoCancelMonitors(),  TaoSetDestroyRoutine()
1316: @*/
1317: PetscErrorCode TaoSetMonitor(Tao tao, PetscErrorCode (*func)(Tao, void*), void *ctx,PetscErrorCode (*dest)(void**))
1318: {
1321:   if (tao->numbermonitors >= MAXTAOMONITORS) SETERRQ1(PETSC_COMM_SELF,1,"Cannot attach another monitor -- max=",MAXTAOMONITORS);
1322:   tao->monitor[tao->numbermonitors] = func;
1323:   tao->monitorcontext[tao->numbermonitors] = ctx;
1324:   tao->monitordestroy[tao->numbermonitors] = dest;
1325:   ++tao->numbermonitors;
1326:   return(0);
1327: }

1331: /*@
1332:    TaoCancelMonitors - Clears all the monitor functions for a Tao object.

1334:    Logically Collective on Tao

1336:    Input Parameters:
1337: .  tao - the Tao solver context

1339:    Options Database:
1340: .  -tao_cancelmonitors - cancels all monitors that have been hardwired
1341:     into a code by calls to TaoSetMonitor(), but does not cancel those
1342:     set via the options database

1344:    Notes:
1345:    There is no way to clear one specific monitor from a Tao object.

1347:    Level: advanced

1349: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1350: @*/
1351: PetscErrorCode TaoCancelMonitors(Tao tao)
1352: {
1353:   PetscInt       i;

1358:   for (i=0;i<tao->numbermonitors;i++) {
1359:     if (tao->monitordestroy[i]) {
1360:       (*tao->monitordestroy[i])(&tao->monitorcontext[i]);
1361:     }
1362:   }
1363:   tao->numbermonitors=0;
1364:   return(0);
1365: }

1369: /*@C
1370:    TaoDefaultMonitor - Default routine for monitoring progress of the
1371:    Tao solvers (default).  This monitor prints the function value and gradient
1372:    norm at each iteration.  It can be turned on from the command line using the
1373:    -tao_monitor option

1375:    Collective on Tao

1377:    Input Parameters:
1378: +  tao - the Tao context
1379: -  ctx - PetscViewer context or NULL

1381:    Options Database Keys:
1382: .  -tao_monitor

1384:    Level: advanced

1386: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1387: @*/
1388: PetscErrorCode TaoDefaultMonitor(Tao tao, void *ctx)
1389: {
1391:   PetscInt       its;
1392:   PetscReal      fct,gnorm;
1393:   PetscViewer    viewer;

1396:   if (ctx) {
1397:     viewer = (PetscViewer)ctx;
1398:   } else {
1399:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1400:   }
1401:   its=tao->niter;
1402:   fct=tao->fc;
1403:   gnorm=tao->residual;
1404:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
1405:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
1406:   ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g \n",(double)gnorm);
1407:   return(0);
1408: }

1412: /*@C
1413:    TaoDefaultSMonitor - Default routine for monitoring progress of the
1414:    solver. Same as TaoDefaultMonitor() except
1415:    it prints fewer digits of the residual as the residual gets smaller.
1416:    This is because the later digits are meaningless and are often
1417:    different on different machines; by using this routine different
1418:    machines will usually generate the same output. It can be turned on
1419:    by using the -tao_smonitor option

1421:    Collective on Tao

1423:    Input Parameters:
1424: +  tao - the Tao context
1425: -  ctx - PetscViewer context or NULL

1427:    Options Database Keys:
1428: .  -tao_smonitor

1430:    Level: advanced

1432: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1433: @*/
1434: PetscErrorCode TaoDefaultSMonitor(Tao tao, void *ctx)
1435: {
1437:   PetscInt       its;
1438:   PetscReal      fct,gnorm;
1439:   PetscViewer    viewer;

1442:   if (ctx) {
1443:     viewer = (PetscViewer)ctx;
1444:   } else {
1445:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1446:   }
1447:   its=tao->niter;
1448:   fct=tao->fc;
1449:   gnorm=tao->residual;
1450:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
1451:   ierr=PetscViewerASCIIPrintf(viewer," Function value %g,",(double)fct);
1452:   if (gnorm > 1.e-6) {
1453:     ierr=PetscViewerASCIIPrintf(viewer," Residual: %g \n",(double)gnorm);
1454:   } else if (gnorm > 1.e-11) {
1455:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-6 \n");
1456:   } else {
1457:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-11 \n");
1458:   }
1459:   return(0);
1460: }

1464: /*@C
1465:    TaoDefaultCMonitor - same as TaoDefaultMonitor() except
1466:    it prints the norm of the constraints function. It can be turned on
1467:    from the command line using the -tao_cmonitor option

1469:    Collective on Tao

1471:    Input Parameters:
1472: +  tao - the Tao context
1473: -  ctx - PetscViewer context or NULL

1475:    Options Database Keys:
1476: .  -tao_cmonitor

1478:    Level: advanced

1480: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1481: @*/
1482: PetscErrorCode TaoDefaultCMonitor(Tao tao, void *ctx)
1483: {
1485:   PetscInt       its;
1486:   PetscReal      fct,gnorm;
1487:   PetscViewer    viewer;

1490:   if (ctx) {
1491:     viewer = (PetscViewer)ctx;
1492:   } else {
1493:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1494:   }
1495:   its=tao->niter;
1496:   fct=tao->fc;
1497:   gnorm=tao->residual;
1498:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %D,",its);
1499:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
1500:   ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g ",(double)gnorm);
1501:   PetscViewerASCIIPrintf(viewer,"  Constraint: %g \n",(double)tao->cnorm);
1502:   return(0);
1503: }

1507: /*@C
1508:    TaoSolutionMonitor - Views the solution at each iteration
1509:    It can be turned on from the command line using the
1510:    -tao_view_solution option

1512:    Collective on Tao

1514:    Input Parameters:
1515: +  tao - the Tao context
1516: -  ctx - PetscViewer context or NULL

1518:    Options Database Keys:
1519: .  -tao_view_solution

1521:    Level: advanced

1523: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1524: @*/
1525: PetscErrorCode TaoSolutionMonitor(Tao tao, void *ctx)
1526: {
1528:   PetscViewer viewer;

1531:   if (ctx) {
1532:     viewer = (PetscViewer)ctx;
1533:   } else {
1534:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1535:   }
1536:   VecView(tao->solution, viewer);
1537:   return(0);
1538: }

1542: /*@C
1543:    TaoGradientMonitor - Views the gradient at each iteration
1544:    It can be turned on from the command line using the
1545:    -tao_view_gradient option

1547:    Collective on Tao

1549:    Input Parameters:
1550: +  tao - the Tao context
1551: -  ctx - PetscViewer context or NULL

1553:    Options Database Keys:
1554: .  -tao_view_gradient

1556:    Level: advanced

1558: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1559: @*/
1560: PetscErrorCode TaoGradientMonitor(Tao tao, void *ctx)
1561: {
1563:   PetscViewer viewer;

1566:   if (ctx) {
1567:     viewer = (PetscViewer)ctx;
1568:   } else {
1569:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1570:   }
1571:   VecView(tao->gradient, viewer);
1572:   return(0);
1573: }

1577: /*@C
1578:    TaoStepDirectionMonitor - Views the gradient at each iteration
1579:    It can be turned on from the command line using the
1580:    -tao_view_gradient option

1582:    Collective on Tao

1584:    Input Parameters:
1585: +  tao - the Tao context
1586: -  ctx - PetscViewer context or NULL

1588:    Options Database Keys:
1589: .  -tao_view_gradient

1591:    Level: advanced

1593: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1594: @*/
1595: PetscErrorCode TaoStepDirectionMonitor(Tao tao, void *ctx)
1596: {
1598:   PetscViewer viewer;
1600:   if (ctx) {
1601:     viewer = (PetscViewer)ctx;
1602:   } else {
1603:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1604:   }
1605:   VecView(tao->stepdirection, viewer);
1606:   return(0);
1607: }

1611: /*@C
1612:    TaoDrawSolutionMonitor - Plots the solution at each iteration
1613:    It can be turned on from the command line using the
1614:    -tao_draw_solution option

1616:    Collective on Tao

1618:    Input Parameters:
1619: +  tao - the Tao context
1620: -  ctx - PetscViewer context or NULL

1622:    Options Database Keys:
1623: .  -tao_draw_solution

1625:    Level: advanced

1627: .seealso: TaoSolutionMonitor(), TaoSetMonitor(), TaoDrawGradientMonitor
1628: @*/
1629: PetscErrorCode TaoDrawSolutionMonitor(Tao tao, void *ctx)
1630: {
1632:   PetscViewer    viewer = (PetscViewer) ctx;
1633:   MPI_Comm       comm;

1636:   if (!viewer) {
1637:     PetscObjectGetComm((PetscObject)tao,&comm);
1638:     viewer = PETSC_VIEWER_DRAW_(comm);
1639:   }
1640:   VecView(tao->solution, viewer);
1641:   return(0);
1642: }

1646: /*@C
1647:    TaoDrawGradientMonitor - Plots the gradient at each iteration
1648:    It can be turned on from the command line using the
1649:    -tao_draw_gradient option

1651:    Collective on Tao

1653:    Input Parameters:
1654: +  tao - the Tao context
1655: -  ctx - PetscViewer context or NULL

1657:    Options Database Keys:
1658: .  -tao_draw_gradient

1660:    Level: advanced

1662: .seealso: TaoGradientMonitor(), TaoSetMonitor(), TaoDrawSolutionMonitor
1663: @*/
1664: PetscErrorCode TaoDrawGradientMonitor(Tao tao, void *ctx)
1665: {
1667:   PetscViewer    viewer = (PetscViewer)ctx;
1668:   MPI_Comm       comm;

1671:   if (!viewer) {
1672:     PetscObjectGetComm((PetscObject)tao,&comm);
1673:     viewer = PETSC_VIEWER_DRAW_(comm);
1674:   }
1675:   VecView(tao->gradient, viewer);
1676:   return(0);
1677: }

1681: /*@C
1682:    TaoDrawStepMonitor - Plots the step direction at each iteration
1683:    It can be turned on from the command line using the
1684:    -tao_draw_step option

1686:    Collective on Tao

1688:    Input Parameters:
1689: +  tao - the Tao context
1690: -  ctx - PetscViewer context or NULL

1692:    Options Database Keys:
1693: .  -tao_draw_step

1695:    Level: advanced

1697: .seealso: TaoSetMonitor(), TaoDrawSolutionMonitor
1698: @*/
1699: PetscErrorCode TaoDrawStepMonitor(Tao tao, void *ctx)
1700: {
1702:   PetscViewer    viewer = (PetscViewer)(ctx);
1703:   MPI_Comm       comm;

1706:   if (!viewer) {
1707:     PetscObjectGetComm((PetscObject)tao,&comm);
1708:     viewer = PETSC_VIEWER_DRAW_(comm);
1709:   }
1710:   VecView(tao->stepdirection, viewer);
1711:   return(0);
1712: }

1716: /*@C
1717:    TaoSeparableObjectiveMonitor - Views the separable objective function at each iteration
1718:    It can be turned on from the command line using the
1719:    -tao_view_separableobjective option

1721:    Collective on Tao

1723:    Input Parameters:
1724: +  tao - the Tao context
1725: -  ctx - PetscViewer context or NULL

1727:    Options Database Keys:
1728: .  -tao_view_separableobjective

1730:    Level: advanced

1732: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1733: @*/
1734: PetscErrorCode TaoSeparableObjectiveMonitor(Tao tao, void *ctx)
1735: {
1737:   PetscViewer    viewer;

1740:   if (ctx) {
1741:     viewer = (PetscViewer)ctx;
1742:   } else {
1743:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1744:   }
1745:   VecView(tao->sep_objective,viewer);
1746:   return(0);
1747: }

1751: /*@C
1752:    TaoDefaultConvergenceTest - Determines whether the solver should continue iterating
1753:    or terminate.

1755:    Collective on Tao

1757:    Input Parameters:
1758: +  tao - the Tao context
1759: -  dummy - unused dummy context

1761:    Output Parameter:
1762: .  reason - for terminating

1764:    Notes:
1765:    This routine checks the residual in the optimality conditions, the
1766:    relative residual in the optimity conditions, the number of function
1767:    evaluations, and the function value to test convergence.  Some
1768:    solvers may use different convergence routines.

1770:    Level: developer

1772: .seealso: TaoSetTolerances(),TaoGetTerminationReason(),TaoSetTerminationReason()
1773: @*/

1775: PetscErrorCode TaoDefaultConvergenceTest(Tao tao,void *dummy)
1776: {
1777:   PetscInt             niter=tao->niter, nfuncs=PetscMax(tao->nfuncs,tao->nfuncgrads);
1778:   PetscInt             max_funcs=tao->max_funcs;
1779:   PetscReal            gnorm=tao->residual, gnorm0=tao->gnorm0;
1780:   PetscReal            f=tao->fc, steptol=tao->steptol,trradius=tao->step;
1781:   PetscReal            gatol=tao->gatol,grtol=tao->grtol,gttol=tao->gttol;
1782:   PetscReal            fatol=tao->fatol,frtol=tao->frtol,catol=tao->catol,crtol=tao->crtol;
1783:   PetscReal            fmin=tao->fmin, cnorm=tao->cnorm, cnorm0=tao->cnorm0;
1784:   PetscReal            gnorm2;
1785:   TaoTerminationReason reason=tao->reason;
1786:   PetscErrorCode       ierr;

1790:   if (reason != TAO_CONTINUE_ITERATING) {
1791:     return(0);
1792:   }
1793:   gnorm2=gnorm*gnorm;

1795:   if (PetscIsInfOrNanReal(f)) {
1796:     PetscInfo(tao,"Failed to converged, function value is Inf or NaN\n");
1797:     reason = TAO_DIVERGED_NAN;
1798:   } else if (f <= fmin && cnorm <=catol) {
1799:     PetscInfo2(tao,"Converged due to function value %g < minimum function value %g\n", (double)f,(double)fmin);
1800:     reason = TAO_CONVERGED_MINF;
1801:   } else if (gnorm2 <= fatol && cnorm <=catol) {
1802:     PetscInfo2(tao,"Converged due to estimated f(X) - f(X*) = %g < %g\n",(double)gnorm2,(double)fatol);
1803:     reason = TAO_CONVERGED_FATOL;
1804:   } else if (f != 0 && gnorm2 / PetscAbsReal(f)<= frtol && cnorm/PetscMax(cnorm0,1.0) <= crtol) {
1805:     PetscInfo2(tao,"Converged due to estimated |f(X)-f(X*)|/f(X) = %g < %g\n",(double)(gnorm2/PetscAbsReal(f)),(double)frtol);
1806:     reason = TAO_CONVERGED_FRTOL;
1807:   } else if (gnorm<= gatol && cnorm <=catol) {
1808:     PetscInfo2(tao,"Converged due to residual norm ||g(X)||=%g < %g\n",(double)gnorm,(double)gatol);
1809:     reason = TAO_CONVERGED_GATOL;
1810:   } else if ( f!=0 && PetscAbsReal(gnorm/f) <= grtol && cnorm <= crtol) {
1811:     PetscInfo2(tao,"Converged due to residual ||g(X)||/|f(X)| =%g < %g\n",(double)(gnorm/f),(double)grtol);
1812:     reason = TAO_CONVERGED_GRTOL;
1813:   } else if (gnorm0 != 0 && gnorm/gnorm0 <= gttol && cnorm <= crtol) {
1814:     PetscInfo2(tao,"Converged due to relative residual norm ||g(X)||/||g(X0)|| = %g < %g\n",(double)(gnorm/gnorm0),(double)gttol);
1815:     reason = TAO_CONVERGED_GTTOL;
1816:   } else if (nfuncs > max_funcs){
1817:     PetscInfo2(tao,"Exceeded maximum number of function evaluations: %D > %D\n", nfuncs,max_funcs);
1818:     reason = TAO_DIVERGED_MAXFCN;
1819:   } else if ( tao->lsflag != 0 ){
1820:     PetscInfo(tao,"Tao Line Search failure.\n");
1821:     reason = TAO_DIVERGED_LS_FAILURE;
1822:   } else if (trradius < steptol && niter > 0){
1823:     PetscInfo2(tao,"Trust region/step size too small: %g < %g\n", (double)trradius,(double)steptol);
1824:     reason = TAO_CONVERGED_STEPTOL;
1825:   } else if (niter > tao->max_it) {
1826:     PetscInfo2(tao,"Exceeded maximum number of iterations: %D > %D\n",niter,tao->max_it);
1827:     reason = TAO_DIVERGED_MAXITS;
1828:   } else {
1829:     reason = TAO_CONTINUE_ITERATING;
1830:   }
1831:   tao->reason = reason;
1832:   return(0);
1833: }

1837: /*@C
1838:    TaoSetOptionsPrefix - Sets the prefix used for searching for all
1839:    TAO options in the database.


1842:    Logically Collective on Tao

1844:    Input Parameters:
1845: +  tao - the Tao context
1846: -  prefix - the prefix string to prepend to all TAO option requests

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

1852:    For example, to distinguish between the runtime options for two
1853:    different TAO solvers, one could call
1854: .vb
1855:       TaoSetOptionsPrefix(tao1,"sys1_")
1856:       TaoSetOptionsPrefix(tao2,"sys2_")
1857: .ve

1859:    This would enable use of different options for each system, such as
1860: .vb
1861:       -sys1_tao_method blmvm -sys1_tao_gtol 1.e-3
1862:       -sys2_tao_method lmvm  -sys2_tao_gtol 1.e-4
1863: .ve


1866:    Level: advanced

1868: .seealso: TaoAppendOptionsPrefix(), TaoGetOptionsPrefix()
1869: @*/

1871: PetscErrorCode TaoSetOptionsPrefix(Tao tao, const char p[])
1872: {

1876:   PetscObjectSetOptionsPrefix((PetscObject)tao,p);
1877:   if (tao->linesearch) {
1878:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
1879:   }
1880:   if (tao->ksp) {
1881:     KSPSetOptionsPrefix(tao->ksp,p);
1882:   }
1883:   return(0);
1884: }

1888: /*@C
1889:    TaoAppendOptionsPrefix - Appends to the prefix used for searching for all
1890:    TAO options in the database.


1893:    Logically Collective on Tao

1895:    Input Parameters:
1896: +  tao - the Tao solver context
1897: -  prefix - the prefix string to prepend to all TAO option requests

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


1904:    Level: advanced

1906: .seealso: TaoSetOptionsPrefix(), TaoGetOptionsPrefix()
1907: @*/
1908: PetscErrorCode TaoAppendOptionsPrefix(Tao tao, const char p[])
1909: {

1913:   PetscObjectAppendOptionsPrefix((PetscObject)tao,p);
1914:   if (tao->linesearch) {
1915:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
1916:   }
1917:   if (tao->ksp) {
1918:     KSPSetOptionsPrefix(tao->ksp,p);
1919:   }
1920:   return(0);
1921: }

1925: /*@C
1926:   TaoGetOptionsPrefix - Gets the prefix used for searching for all
1927:   TAO options in the database

1929:   Not Collective

1931:   Input Parameters:
1932: . tao - the Tao context

1934:   Output Parameters:
1935: . prefix - pointer to the prefix string used is returned

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

1940:   Level: advanced

1942: .seealso: TaoSetOptionsPrefix(), TaoAppendOptionsPrefix()
1943: @*/
1944: PetscErrorCode TaoGetOptionsPrefix(Tao tao, const char *p[])
1945: {
1946:    return PetscObjectGetOptionsPrefix((PetscObject)tao,p);
1947: }

1951: /*@C
1952:    TaoSetType - Sets the method for the unconstrained minimization solver.

1954:    Collective on Tao

1956:    Input Parameters:
1957: +  solver - the Tao solver context
1958: -  type - a known method

1960:    Options Database Key:
1961: +  -tao_method <type> - Sets the method; use -help for a list
1962:    of available methods (for instance, "-tao_method tao_lmvm" or
1963:    "-tao_method tao_tron")
1964: -  -tao_type <type> - identical to -tao_method

1966:    Available methods include:
1967: +    tao_nls - Newton's method with line search for unconstrained minimization
1968: .    tao_ntr - Newton's method with trust region for unconstrained minimization
1969: .    tao_ntl - Newton's method with trust region, line search for unconstrained minimization
1970: .    tao_lmvm - Limited memory variable metric method for unconstrained minimization
1971: .    tao_cg - Nonlinear conjugate gradient method for unconstrained minimization
1972: .    tao_nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
1973: .    tao_tron - Newton Trust Region method for bound constrained minimization
1974: .    tao_gpcg - Newton Trust Region method for quadratic bound constrained minimization
1975: .    tao_blmvm - Limited memory variable metric method for bound constrained minimization
1976: +    tao_pounders - Model-based algorithm pounder extended for nonlinear least squares

1978:   Level: intermediate

1980: .seealso: TaoCreate(), TaoGetType()

1982: @*/
1983: PetscErrorCode TaoSetType(Tao tao, const TaoType type)
1984: {
1986:     PetscErrorCode (*create_xxx)(Tao);
1987:     PetscBool      issame;


1992:     PetscObjectTypeCompare((PetscObject)tao,type,&issame);
1993:     if (issame) return(0);

1995:     PetscFunctionListFind(TaoList, type, (void(**)(void))&create_xxx);
1996:     if (!create_xxx) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested Tao type %s",type);

1998:     /* Destroy the existing solver information */
1999:     if (tao->ops->destroy) {
2000:         (*tao->ops->destroy)(tao);
2001:     }
2002:     KSPDestroy(&tao->ksp);
2003:     TaoLineSearchDestroy(&tao->linesearch);
2004:     VecDestroy(&tao->gradient);
2005:     VecDestroy(&tao->stepdirection);

2007:     tao->ops->setup = 0;
2008:     tao->ops->solve = 0;
2009:     tao->ops->view  = 0;
2010:     tao->ops->setfromoptions = 0;
2011:     tao->ops->destroy = 0;

2013:     tao->setupcalled = PETSC_FALSE;

2015:     (*create_xxx)(tao);
2016:     PetscObjectChangeTypeName((PetscObject)tao,type);
2017:     return(0);
2018: }

2022: /*MC
2023:    TaoRegister - Adds a method to the TAO package for unconstrained minimization.

2025:    Synopsis:
2026:    TaoRegister(char *name_solver,char *path,char *name_Create,int (*routine_Create)(Tao))

2028:    Not collective

2030:    Input Parameters:
2031: +  sname - name of a new user-defined solver
2032: -  func - routine to Create method context

2034:    Notes:
2035:    TaoRegister() may be called multiple times to add several user-defined solvers.

2037:    Sample usage:
2038: .vb
2039:    TaoRegister("my_solver",MySolverCreate);
2040: .ve

2042:    Then, your solver can be chosen with the procedural interface via
2043: $     TaoSetType(tao,"my_solver")
2044:    or at runtime via the option
2045: $     -tao_method my_solver

2047:    Level: advanced

2049: .seealso: TaoRegisterAll(), TaoRegisterDestroy()
2050: M*/
2051: PetscErrorCode TaoRegister(const char sname[], PetscErrorCode (*func)(Tao))
2052: {

2056:   PetscFunctionListAdd(&TaoList,sname, (void (*)(void))func);
2057:   return(0);
2058: }

2062: /*@C
2063:    TaoRegisterDestroy - Frees the list of minimization solvers that were
2064:    registered by TaoRegisterDynamic().

2066:    Not Collective

2068:    Level: advanced

2070: .seealso: TaoRegisterAll(), TaoRegister()
2071: @*/
2072: PetscErrorCode TaoRegisterDestroy(void)
2073: {
2076:   PetscFunctionListDestroy(&TaoList);
2077:   TaoRegisterAllCalled = PETSC_FALSE;
2078:   return(0);
2079: }

2083: /*@
2084:   TaoSetTerminationReason - Sets the termination flag on a Tao object

2086:   Logically Collective on Tao

2088:   Input Parameters:
2089: + tao - the Tao context
2090: - reason - one of
2091: $     TAO_CONVERGED_ATOL (2),
2092: $     TAO_CONVERGED_RTOL (3),
2093: $     TAO_CONVERGED_STEPTOL (4),
2094: $     TAO_CONVERGED_MINF (5),
2095: $     TAO_CONVERGED_USER (6),
2096: $     TAO_DIVERGED_MAXITS (-2),
2097: $     TAO_DIVERGED_NAN (-4),
2098: $     TAO_DIVERGED_MAXFCN (-5),
2099: $     TAO_DIVERGED_LS_FAILURE (-6),
2100: $     TAO_DIVERGED_TR_REDUCTION (-7),
2101: $     TAO_DIVERGED_USER (-8),
2102: $     TAO_CONTINUE_ITERATING (0)

2104:    Level: intermediate

2106: @*/
2107: PetscErrorCode TaoSetTerminationReason(Tao tao, TaoTerminationReason reason)
2108: {
2111:   tao->reason = reason;
2112:   return(0);
2113: }

2117: /*@
2118:    TaoGetTerminationReason - Gets the reason the Tao iteration was stopped.

2120:    Not Collective

2122:    Input Parameter:
2123: .  tao - the Tao solver context

2125:    Output Parameter:
2126: .  reason - one of


2129: $  TAO_CONVERGED_FATOL (1)           f(X)-f(X*) <= fatol
2130: $  TAO_CONVERGED_FRTOL (2)           |f(X) - f(X*)|/|f(X)| < frtol
2131: $  TAO_CONVERGED_GATOL (3)           ||g(X)|| < gatol
2132: $  TAO_CONVERGED_GRTOL (4)           ||g(X)|| / f(X)  < grtol
2133: $  TAO_CONVERGED_GTTOL (5)           ||g(X)|| / ||g(X0)|| < gttol
2134: $  TAO_CONVERGED_STEPTOL (6)         step size small
2135: $  TAO_CONVERGED_MINF (7)            F < F_min
2136: $  TAO_CONVERGED_USER (8)            User defined

2138: $  TAO_DIVERGED_MAXITS (-2)          its > maxits
2139: $  TAO_DIVERGED_NAN (-4)             Numerical problems
2140: $  TAO_DIVERGED_MAXFCN (-5)          fevals > max_funcsals
2141: $  TAO_DIVERGED_LS_FAILURE (-6)      line search failure
2142: $  TAO_DIVERGED_TR_REDUCTION (-7)    trust region failure
2143: $  TAO_DIVERGED_USER(-8)             (user defined)

2145: $  TAO_CONTINUE_ITERATING (0)

2147:    where
2148: +  X - current solution
2149: .  X0 - initial guess
2150: .  f(X) - current function value
2151: .  f(X*) - true solution (estimated)
2152: .  g(X) - current gradient
2153: .  its - current iterate number
2154: .  maxits - maximum number of iterates
2155: .  fevals - number of function evaluations
2156: -  max_funcsals - maximum number of function evaluations

2158:    Level: intermediate

2160: .seealso: TaoSetConvergenceTest(), TaoSetTolerances()

2162: @*/
2163: PetscErrorCode TaoGetTerminationReason(Tao tao, TaoTerminationReason *reason)
2164: {
2168:   *reason = tao->reason;
2169:   return(0);
2170: }

2174: /*@
2175:   TaoGetSolutionStatus - Get the current iterate, objective value,
2176:   residual, infeasibility, and termination

2178:   Not Collective

2180:    Input Parameters:
2181: .  tao - the Tao context

2183:    Output Parameters:
2184: +  iterate - the current iterate number (>=0)
2185: .  f - the current function value
2186: .  gnorm - the square of the gradient norm, duality gap, or other measure
2187: indicating distance from optimality.
2188: .  cnorm - the infeasibility of the current solution with regard to the constraints.
2189: .  xdiff - the step length or trust region radius of the most recent iterate.
2190: -  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

2192:    Level: intermediate

2194:    Note:
2195:    TAO returns the values set by the solvers in the routine TaoMonitor().

2197:    Note:
2198:    If any of the output arguments are set to NULL, no corresponding value will be returned.


2201: .seealso: TaoMonitor(), TaoGetTerminationReason()
2202: @*/
2203: PetscErrorCode TaoGetSolutionStatus(Tao tao, PetscInt *its, PetscReal *f, PetscReal *gnorm, PetscReal *cnorm, PetscReal *xdiff, TaoTerminationReason *reason)
2204: {
2206:   if (its) *its=tao->niter;
2207:   if (f) *f=tao->fc;
2208:   if (gnorm) *gnorm=tao->residual;
2209:   if (cnorm) *cnorm=tao->cnorm;
2210:   if (reason) *reason=tao->reason;
2211:   if (xdiff) *xdiff=tao->step;
2212:   return(0);
2213: }


2218: /*@C
2219:    TaoGetType - Gets the current Tao algorithm.

2221:    Not Collective

2223:    Input Parameter:
2224: .  tao - the Tao solver context

2226:    Output Parameter:
2227: .  type - Tao method

2229:    Level: intermediate

2231: @*/
2232: PetscErrorCode TaoGetType(Tao tao, const TaoType *type)
2233: {
2237:   *type=((PetscObject)tao)->type_name;
2238:   return(0);
2239: }

2243: /*@C
2244:   TaoMonitor - Monitor the solver and the current solution.  This
2245:   routine will record the iteration number and residual statistics,
2246:   call any monitors specified by the user, and calls the convergence-check routine.

2248:    Input Parameters:
2249: +  tao - the Tao context
2250: .  its - the current iterate number (>=0)
2251: .  f - the current objective function value
2252: .  res - the gradient norm, square root of the duality gap, or other measure
2253: indicating distince from optimality.  This measure will be recorded and
2254: used for some termination tests.
2255: .  cnorm - the infeasibility of the current solution with regard to the constraints.
2256: -  steplength - multiple of the step direction added to the previous iterate.

2258:    Output Parameters:
2259: .  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

2261:    Options Database Key:
2262: .  -tao_monitor - Use the default monitor, which prints statistics to standard output

2264: .seealso TaoGetTerminationReason(), TaoDefaultMonitor(), TaoSetMonitor()

2266:    Level: developer

2268: @*/
2269: PetscErrorCode TaoMonitor(Tao tao, PetscInt its, PetscReal f, PetscReal res, PetscReal cnorm, PetscReal steplength, TaoTerminationReason *reason)
2270: {
2272:   PetscInt       i;

2276:   tao->fc = f;
2277:   tao->residual = res;
2278:   tao->cnorm = cnorm;
2279:   tao->step = steplength;
2280:   tao->niter=its;
2281:   if (its == 0) {
2282:     tao->cnorm0 = cnorm; tao->gnorm0 = res;
2283:   }
2284:   TaoLogHistory(tao,f,res,cnorm);
2285:   if (PetscIsInfOrNanReal(f) || PetscIsInfOrNanReal(res)) SETERRQ(PETSC_COMM_SELF,1, "User provided compute function generated Inf or NaN");
2286:   if (tao->ops->convergencetest) {
2287:     (*tao->ops->convergencetest)(tao,tao->cnvP);
2288:   }
2289:   for (i=0;i<tao->numbermonitors;i++) {
2290:     (*tao->monitor[i])(tao,tao->monitorcontext[i]);
2291:   }
2292:   *reason = tao->reason;
2293:   return(0);
2294: }

2298: /*@
2299:    TaoSetHistory - Sets the array used to hold the convergence history.

2301:    Logically Collective on Tao

2303:    Input Parameters:
2304: +  tao - the Tao solver context
2305: .  obj   - array to hold objective value history
2306: .  resid - array to hold residual history
2307: .  cnorm - array to hold constraint violation history
2308: .  na  - size of obj, resid, and cnorm
2309: -  reset - PetscTrue indicates each new minimization resets the history counter to zero,
2310:            else it continues storing new values for new minimizations after the old ones

2312:    Notes:
2313:    If set, TAO will fill the given arrays with the indicated
2314:    information at each iteration.  If no information is desired
2315:    for a given array, then NULL may be used.

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

2321:    Level: intermediate

2323: .seealso: TaoGetHistory()

2325: @*/
2326: PetscErrorCode TaoSetHistory(Tao tao, PetscReal *obj, PetscReal *resid, PetscReal *cnorm, PetscInt na,PetscBool reset)
2327: {
2330:   tao->hist_obj = obj;
2331:   tao->hist_resid = resid;
2332:   tao->hist_cnorm = cnorm;
2333:   tao->hist_max   = na;
2334:   tao->hist_reset = reset;
2335:   return(0);
2336: }

2340: /*@C
2341:    TaoGetHistory - Gets the array used to hold the convergence history.

2343:    Collective on Tao

2345:    Input Parameter:
2346: .  tao - the Tao context

2348:    Output Parameters:
2349: +  obj   - array used to hold objective value history
2350: .  resid - array used to hold residual history
2351: .  cnorm - array used to hold constraint violation history
2352: -  nhist  - size of obj, resid, and cnorm (will be less than or equal to na given in TaoSetHistory)


2355:    Notes:
2356:     The calling sequence for this routine in Fortran is
2357: $   call TaoGetHistory(Tao tao, integer nhist, integer info)

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

2363:    Level: advanced

2365: .seealso: TaoSetHistory()

2367: @*/
2368: PetscErrorCode TaoGetHistory(Tao tao, PetscReal **obj, PetscReal **resid, PetscReal **cnorm, PetscInt *nhist)
2369: {
2372:   if (obj)   *obj   = tao->hist_obj;
2373:   if (cnorm) *cnorm = tao->hist_cnorm;
2374:   if (resid) *resid = tao->hist_resid;
2375:   if (nhist) *nhist   = tao->hist_len;
2376:   return(0);
2377: }

2381: /*@
2382:    TaoSetApplicationContext - Sets the optional user-defined context for
2383:    a solver.

2385:    Logically Collective on Tao

2387:    Input Parameters:
2388: +  tao  - the Tao context
2389: -  usrP - optional user context

2391:    Level: intermediate

2393: .seealso: TaoGetApplicationContext(), TaoSetApplicationContext()
2394: @*/
2395: PetscErrorCode  TaoSetApplicationContext(Tao tao,void *usrP)
2396: {
2399:   tao->user = usrP;
2400:   return(0);
2401: }

2405: /*@
2406:    TaoGetApplicationContext - Gets the user-defined context for a
2407:    TAO solvers.

2409:    Not Collective

2411:    Input Parameter:
2412: .  tao  - Tao context

2414:    Output Parameter:
2415: .  usrP - user context

2417:    Level: intermediate

2419: .seealso: TaoSetApplicationContext()
2420: @*/
2421: PetscErrorCode  TaoGetApplicationContext(Tao tao,void *usrP)
2422: {
2425:   *(void**)usrP = tao->user;
2426:   return(0);
2427: }