Actual source code: taosolver.c

petsc-3.6.1 2015-08-06
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: +    nls - Newton's method with line search for unconstrained minimization
 28: .    ntr - Newton's method with trust region for unconstrained minimization
 29: .    ntl - Newton's method with trust region, line search for unconstrained minimization
 30: .    lmvm - Limited memory variable metric method for unconstrained minimization
 31: .    cg - Nonlinear conjugate gradient method for unconstrained minimization
 32: .    nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
 33: .    tron - Newton Trust Region method for bound constrained minimization
 34: .    gpcg - Newton Trust Region method for quadratic bound constrained minimization
 35: .    blmvm - Limited memory variable metric method for bound constrained minimization
 36: .    lcl - Linearly constrained Lagrangian method for pde-constrained minimization
 37: -    pounders - Model-based algorithm for nonlinear least squares

 39:    Options Database Keys:
 40: .   -tao_type - select which method TAO should use

 42:    Level: beginner

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

 53:   *newtao = NULL;

 55:   TaoInitializePackage();
 56:   TaoLineSearchInitializePackage();

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

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

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

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

145:   /* These flags prevents algorithms from overriding user options */
146:   tao->max_it_changed   =PETSC_FALSE;
147:   tao->max_funcs_changed=PETSC_FALSE;
148:   tao->fatol_changed    =PETSC_FALSE;
149:   tao->frtol_changed    =PETSC_FALSE;
150:   tao->gatol_changed    =PETSC_FALSE;
151:   tao->grtol_changed    =PETSC_FALSE;
152:   tao->gttol_changed    =PETSC_FALSE;
153:   tao->steptol_changed  =PETSC_FALSE;
154:   tao->trust0_changed   =PETSC_FALSE;
155:   tao->fmin_changed     =PETSC_FALSE;
156:   tao->catol_changed    =PETSC_FALSE;
157:   tao->crtol_changed    =PETSC_FALSE;
158:   TaoResetStatistics(tao);
159:   *newtao = tao;
160:   return(0);
161: }

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

168:   Collective on Tao

170:   Input Parameters:
171: . tao - the Tao context

173:   Notes:
174:   The user must set up the Tao with calls to TaoSetInitialVector(),
175:   TaoSetObjectiveRoutine(),
176:   TaoSetGradientRoutine(), and (if using 2nd order method) TaoSetHessianRoutine().

178:   Level: beginner

180: .seealso: TaoCreate(), TaoSetObjectiveRoutine(), TaoSetGradientRoutine(), TaoSetHessianRoutine()
181:  @*/
182: PetscErrorCode TaoSolve(Tao tao)
183: {
184:   PetscErrorCode   ierr;
185:   static PetscBool set = PETSC_FALSE;

189:   PetscCitationsRegister("@TechReport{tao-user-ref,\n"
190:                                 "title   = {Toolkit for Advanced Optimization (TAO) Users Manual},\n"
191:                                 "author  = {Todd Munson and Jason Sarich and Stefan Wild and Steve Benson and Lois Curfman McInnes},\n"
192:                                 "Institution = {Argonne National Laboratory},\n"
193:                                 "Year   = 2014,\n"
194:                                 "Number = {ANL/MCS-TM-322 - Revision 3.5},\n"
195:                                 "url    = {http://www.mcs.anl.gov/tao}\n}\n",&set);

197:   TaoSetUp(tao);
198:   TaoResetStatistics(tao);
199:   if (tao->linesearch) {
200:     TaoLineSearchReset(tao->linesearch);
201:   }

203:   PetscLogEventBegin(Tao_Solve,tao,0,0,0);
204:   if (tao->ops->solve){ (*tao->ops->solve)(tao); }
205:   PetscLogEventEnd(Tao_Solve,tao,0,0,0);

207:   tao->ntotalits += tao->niter;
208:   TaoViewFromOptions(tao,NULL,"-tao_view");

210:   if (tao->printreason) {
211:     if (tao->reason > 0) {
212:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve converged due to %s iterations %D\n",TaoConvergedReasons[tao->reason],tao->niter);
213:     } else {
214:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve did not converge due to %s iteration %D\n",TaoConvergedReasons[tao->reason],tao->niter);
215:     }
216:   }
217:   return(0);
218: }

222: /*@
223:   TaoSetUp - Sets up the internal data structures for the later use
224:   of a Tao solver

226:   Collective on tao

228:   Input Parameters:
229: . tao - the TAO context

231:   Notes:
232:   The user will not need to explicitly call TaoSetUp(), as it will
233:   automatically be called in TaoSolve().  However, if the user
234:   desires to call it explicitly, it should come after TaoCreate()
235:   and any TaoSetSomething() routines, but before TaoSolve().

237:   Level: advanced

239: .seealso: TaoCreate(), TaoSolve()
240: @*/
241: PetscErrorCode TaoSetUp(Tao tao)
242: {

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

249:   if (!tao->solution) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetInitialVector");
250:   if (tao->ops->setup) {
251:     (*tao->ops->setup)(tao);
252:   }
253:   tao->setupcalled = PETSC_TRUE;
254:   return(0);
255: }

259: /*@
260:   TaoDestroy - Destroys the TAO context that was created with
261:   TaoCreate()

263:   Collective on Tao

265:   Input Parameter:
266: . tao - the Tao context

268:   Level: beginner

270: .seealso: TaoCreate(), TaoSolve()
271: @*/
272: PetscErrorCode TaoDestroy(Tao *tao)
273: {

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

281:   if ((*tao)->ops->destroy) {
282:     (*((*tao))->ops->destroy)(*tao);
283:   }
284:   KSPDestroy(&(*tao)->ksp);
285:   TaoLineSearchDestroy(&(*tao)->linesearch);

287:   if ((*tao)->ops->convergencedestroy) {
288:     (*(*tao)->ops->convergencedestroy)((*tao)->cnvP);
289:     if ((*tao)->jacobian_state_inv) {
290:       MatDestroy(&(*tao)->jacobian_state_inv);
291:     }
292:   }
293:   VecDestroy(&(*tao)->solution);
294:   VecDestroy(&(*tao)->gradient);

296:   VecDestroy(&(*tao)->XL);
297:   VecDestroy(&(*tao)->XU);
298:   VecDestroy(&(*tao)->IL);
299:   VecDestroy(&(*tao)->IU);
300:   VecDestroy(&(*tao)->DE);
301:   VecDestroy(&(*tao)->DI);
302:   VecDestroy(&(*tao)->constraints_equality);
303:   VecDestroy(&(*tao)->constraints_inequality);
304:   VecDestroy(&(*tao)->stepdirection);
305:   MatDestroy(&(*tao)->hessian_pre);
306:   MatDestroy(&(*tao)->hessian);
307:   MatDestroy(&(*tao)->jacobian_pre);
308:   MatDestroy(&(*tao)->jacobian);
309:   MatDestroy(&(*tao)->jacobian_state_pre);
310:   MatDestroy(&(*tao)->jacobian_state);
311:   MatDestroy(&(*tao)->jacobian_state_inv);
312:   MatDestroy(&(*tao)->jacobian_design);
313:   MatDestroy(&(*tao)->jacobian_equality);
314:   MatDestroy(&(*tao)->jacobian_equality_pre);
315:   MatDestroy(&(*tao)->jacobian_inequality);
316:   MatDestroy(&(*tao)->jacobian_inequality_pre);
317:   ISDestroy(&(*tao)->state_is);
318:   ISDestroy(&(*tao)->design_is);
319:   TaoCancelMonitors(*tao);
320:   if ((*tao)->hist_malloc) {
321:     PetscFree((*tao)->hist_obj);
322:     PetscFree((*tao)->hist_resid);
323:     PetscFree((*tao)->hist_cnorm);
324:     PetscFree((*tao)->hist_lits);
325:   }
326:   PetscHeaderDestroy(tao);
327:   return(0);
328: }

332: /*@
333:   TaoSetFromOptions - Sets various Tao parameters from user
334:   options.

336:   Collective on Tao

338:   Input Paremeter:
339: . tao - the Tao solver context

341:   options Database Keys:
342: + -tao_type <type> - The algorithm that TAO uses (lmvm, nls, etc.)
343: . -tao_fatol <fatol> - absolute error tolerance in function value
344: . -tao_frtol <frtol> - relative error tolerance in function value
345: . -tao_gatol <gatol> - absolute error tolerance for ||gradient||
346: . -tao_grtol <grtol> - relative error tolerance for ||gradient||
347: . -tao_gttol <gttol> - reduction of ||gradient|| relative to initial gradient
348: . -tao_max_it <max> - sets maximum number of iterations
349: . -tao_max_funcs <max> - sets maximum number of function evaluations
350: . -tao_fmin <fmin> - stop if function value reaches fmin
351: . -tao_steptol <tol> - stop if trust region radius less than <tol>
352: . -tao_trust0 <t> - initial trust region radius
353: . -tao_monitor - prints function value and residual at each iteration
354: . -tao_smonitor - same as tao_monitor, but truncates very small values
355: . -tao_cmonitor - prints function value, residual, and constraint norm at each iteration
356: . -tao_view_solution - prints solution vector at each iteration
357: . -tao_view_separableobjective - prints separable objective vector at each iteration
358: . -tao_view_step - prints step direction vector at each iteration
359: . -tao_view_gradient - prints gradient vector at each iteration
360: . -tao_draw_solution - graphically view solution vector at each iteration
361: . -tao_draw_step - graphically view step vector at each iteration
362: . -tao_draw_gradient - graphically view gradient at each iteration
363: . -tao_fd_gradient - use gradient computed with finite differences
364: . -tao_cancelmonitors - cancels all monitors (except those set with command line)
365: . -tao_view - prints information about the Tao after solving
366: - -tao_converged_reason - prints the reason TAO stopped iterating

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

372:   Level: beginner
373: @*/
374: PetscErrorCode TaoSetFromOptions(Tao tao)
375: {
377:   const TaoType  default_type = TAOLMVM;
378:   const char     *prefix;
379:   char           type[256], monfilename[PETSC_MAX_PATH_LEN];
380:   PetscViewer    monviewer;
381:   PetscBool      flg;
382:   MPI_Comm       comm;

386:   PetscObjectGetComm((PetscObject)tao,&comm);
387:   TaoGetOptionsPrefix(tao,&prefix);
388:   /* So no warnings are given about unused options */
389:   PetscOptionsHasName(prefix,"-tao_ls_type",&flg);

391:   PetscObjectOptionsBegin((PetscObject)tao);
392:   {
393:     TaoRegisterAll();
394:     if (((PetscObject)tao)->type_name) {
395:       default_type = ((PetscObject)tao)->type_name;
396:     }
397:     /* Check for type from options */
398:     PetscOptionsFList("-tao_type","Tao Solver type","TaoSetType",TaoList,default_type,type,256,&flg);
399:     if (flg) {
400:       TaoSetType(tao,type);
401:     } else if (!((PetscObject)tao)->type_name) {
402:       TaoSetType(tao,default_type);
403:     }

405:     PetscOptionsReal("-tao_fatol","Stop if solution within","TaoSetTolerances",tao->fatol,&tao->fatol,&flg);
406:     if (flg) tao->fatol_changed=PETSC_TRUE;
407:     PetscOptionsReal("-tao_frtol","Stop if relative solution within","TaoSetTolerances",tao->frtol,&tao->frtol,&flg);
408:     if (flg) tao->frtol_changed=PETSC_TRUE;
409:     PetscOptionsReal("-tao_catol","Stop if constraints violations within","TaoSetConstraintTolerances",tao->catol,&tao->catol,&flg);
410:     if (flg) tao->catol_changed=PETSC_TRUE;
411:     PetscOptionsReal("-tao_crtol","Stop if relative contraint violations within","TaoSetConstraintTolerances",tao->crtol,&tao->crtol,&flg);
412:     if (flg) tao->crtol_changed=PETSC_TRUE;
413:     PetscOptionsReal("-tao_gatol","Stop if norm of gradient less than","TaoSetTolerances",tao->gatol,&tao->gatol,&flg);
414:     if (flg) tao->gatol_changed=PETSC_TRUE;
415:     PetscOptionsReal("-tao_grtol","Stop if norm of gradient divided by the function value is less than","TaoSetTolerances",tao->grtol,&tao->grtol,&flg);
416:     if (flg) tao->grtol_changed=PETSC_TRUE;
417:     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);
418:     if (flg) tao->gttol_changed=PETSC_TRUE;
419:     PetscOptionsInt("-tao_max_it","Stop if iteration number exceeds","TaoSetMaximumIterations",tao->max_it,&tao->max_it,&flg);
420:     if (flg) tao->max_it_changed=PETSC_TRUE;
421:     PetscOptionsInt("-tao_max_funcs","Stop if number of function evaluations exceeds","TaoSetMaximumFunctionEvaluations",tao->max_funcs,&tao->max_funcs,&flg);
422:     if (flg) tao->max_funcs_changed=PETSC_TRUE;
423:     PetscOptionsReal("-tao_fmin","Stop if function less than","TaoSetFunctionLowerBound",tao->fmin,&tao->fmin,&flg);
424:     if (flg) tao->fmin_changed=PETSC_TRUE;
425:     PetscOptionsReal("-tao_steptol","Stop if step size or trust region radius less than","",tao->steptol,&tao->steptol,&flg);
426:     if (flg) tao->steptol_changed=PETSC_TRUE;
427:     PetscOptionsReal("-tao_trust0","Initial trust region radius","TaoSetTrustRegionRadius",tao->trust0,&tao->trust0,&flg);
428:     if (flg) tao->trust0_changed=PETSC_TRUE;
429:     PetscOptionsString("-tao_view_solution","view solution vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
430:     if (flg) {
431:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
432:       TaoSetMonitor(tao,TaoSolutionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
433:     }

435:     PetscOptionsBool("-tao_converged_reason","Print reason for TAO converged","TaoSolve",tao->printreason,&tao->printreason,NULL);
436:     PetscOptionsString("-tao_view_gradient","view gradient vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
437:     if (flg) {
438:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
439:       TaoSetMonitor(tao,TaoGradientMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
440:     }

442:     PetscOptionsString("-tao_view_stepdirection","view step direction vector after each iteration","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
443:     if (flg) {
444:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
445:       TaoSetMonitor(tao,TaoStepDirectionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
446:     }

448:     PetscOptionsString("-tao_view_separableobjective","view separable objective vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
449:     if (flg) {
450:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
451:       TaoSetMonitor(tao,TaoSeparableObjectiveMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
452:     }

454:     PetscOptionsString("-tao_monitor","Use the default convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
455:     if (flg) {
456:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
457:       TaoSetMonitor(tao,TaoDefaultMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
458:     }

460:     PetscOptionsString("-tao_smonitor","Use the short convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
461:     if (flg) {
462:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
463:       TaoSetMonitor(tao,TaoDefaultSMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
464:     }

466:     PetscOptionsString("-tao_cmonitor","Use the default convergence monitor with constraint norm","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
467:     if (flg) {
468:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
469:       TaoSetMonitor(tao,TaoDefaultCMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
470:     }


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

477:     flg = PETSC_FALSE;
478:     PetscOptionsBool("-tao_draw_solution","Plot solution vector at each iteration","TaoSetMonitor",flg,&flg,NULL);
479:     if (flg) {
480:       TaoSetMonitor(tao,TaoDrawSolutionMonitor,NULL,NULL);
481:     }

483:     flg = PETSC_FALSE;
484:     PetscOptionsBool("-tao_draw_step","plots step direction at each iteration","TaoSetMonitor",flg,&flg,NULL);
485:     if (flg) {
486:       TaoSetMonitor(tao,TaoDrawStepMonitor,NULL,NULL);
487:     }

489:     flg = PETSC_FALSE;
490:     PetscOptionsBool("-tao_draw_gradient","plots gradient at each iteration","TaoSetMonitor",flg,&flg,NULL);
491:     if (flg) {
492:       TaoSetMonitor(tao,TaoDrawGradientMonitor,NULL,NULL);
493:     }
494:     flg = PETSC_FALSE;
495:     PetscOptionsBool("-tao_fd_gradient","compute gradient using finite differences","TaoDefaultComputeGradient",flg,&flg,NULL);
496:     if (flg) {
497:       TaoSetGradientRoutine(tao,TaoDefaultComputeGradient,NULL);
498:     }
499:     PetscOptionsEnum("-tao_subset_type","subset type", "", TaoSubSetTypes,(PetscEnum)tao->subset_type, (PetscEnum*)&tao->subset_type, 0);

501:     if (tao->ops->setfromoptions) {
502:       (*tao->ops->setfromoptions)(PetscOptionsObject,tao);
503:     }
504:   }
505:   PetscOptionsEnd();
506:   return(0);
507: }

511: /*@C
512:   TaoView - Prints information about the Tao

514:   Collective on Tao

516:   InputParameters:
517: + tao - the Tao context
518: - viewer - visualization context

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

523:   Notes:
524:   The available visualization contexts include
525: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
526: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
527:          output where only the first processor opens
528:          the file.  All other processors send their
529:          data to the first processor to print.

531:   Level: beginner

533: .seealso: PetscViewerASCIIOpen()
534: @*/
535: PetscErrorCode TaoView(Tao tao, PetscViewer viewer)
536: {
537:   PetscErrorCode      ierr;
538:   PetscBool           isascii,isstring;
539:   const TaoType type;

543:   if (!viewer) {
544:     PetscViewerASCIIGetStdout(((PetscObject)tao)->comm,&viewer);
545:   }

549:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
550:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSTRING,&isstring);
551:   if (isascii) {
552:     PetscObjectPrintClassNamePrefixType((PetscObject)tao,viewer);
553:     PetscViewerASCIIPushTab(viewer);

555:     if (tao->ops->view) {
556:       PetscViewerASCIIPushTab(viewer);
557:       (*tao->ops->view)(tao,viewer);
558:       PetscViewerASCIIPopTab(viewer);
559:     }
560:     if (tao->linesearch) {
561:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->linesearch),viewer);
562:     }
563:     if (tao->ksp) {
564:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->ksp),viewer);
565:       PetscViewerASCIIPrintf(viewer,"total KSP iterations: %D\n",tao->ksp_tot_its);
566:     }
567:     if (tao->XL || tao->XU) {
568:       PetscViewerASCIIPrintf(viewer,"Active Set subset type: %s\n",TaoSubSetTypes[tao->subset_type]);
569:     }

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

574:     ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: gatol=%g,",(double)tao->gatol);
575:     ierr=PetscViewerASCIIPrintf(viewer," steptol=%g,",(double)tao->steptol);
576:     ierr=PetscViewerASCIIPrintf(viewer," gttol=%g\n",(double)tao->gttol);

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

580:     if (tao->cnorm>0 || tao->catol>0 || tao->crtol>0){
581:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances:");
582:       ierr=PetscViewerASCIIPrintf(viewer," catol=%g,",(double)tao->catol);
583:       ierr=PetscViewerASCIIPrintf(viewer," crtol=%g\n",(double)tao->crtol);
584:       PetscViewerASCIIPrintf(viewer,"Residual in Constraints:=%g\n",(double)tao->cnorm);
585:     }

587:     if (tao->trust < tao->steptol){
588:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: steptol=%g\n",(double)tao->steptol);
589:       ierr=PetscViewerASCIIPrintf(viewer,"Final trust region radius:=%g\n",(double)tao->trust);
590:     }

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

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

600:     if (tao->nfuncs>0){
601:       PetscViewerASCIIPrintf(viewer,"total number of function evaluations=%D,",tao->nfuncs);
602:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
603:     }
604:     if (tao->ngrads>0){
605:       PetscViewerASCIIPrintf(viewer,"total number of gradient evaluations=%D,",tao->ngrads);
606:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
607:     }
608:     if (tao->nfuncgrads>0){
609:       PetscViewerASCIIPrintf(viewer,"total number of function/gradient evaluations=%D,",tao->nfuncgrads);
610:       PetscViewerASCIIPrintf(viewer,"    (max: %D)\n",tao->max_funcs);
611:     }
612:     if (tao->nhess>0){
613:       PetscViewerASCIIPrintf(viewer,"total number of Hessian evaluations=%D\n",tao->nhess);
614:     }
615:     /*  if (tao->linear_its>0){
616:      PetscViewerASCIIPrintf(viewer,"  total Krylov method iterations=%D\n",tao->linear_its);
617:      }*/
618:     if (tao->nconstraints>0){
619:       PetscViewerASCIIPrintf(viewer,"total number of constraint function evaluations=%D\n",tao->nconstraints);
620:     }
621:     if (tao->njac>0){
622:       PetscViewerASCIIPrintf(viewer,"total number of Jacobian evaluations=%D\n",tao->njac);
623:     }

625:     if (tao->reason>0){
626:       PetscViewerASCIIPrintf(viewer,    "Solution converged: ");
627:       switch (tao->reason) {
628:       case TAO_CONVERGED_FATOL:
629:         PetscViewerASCIIPrintf(viewer,"estimated f(x)-f(X*) <= fatol\n");
630:         break;
631:       case TAO_CONVERGED_FRTOL:
632:         PetscViewerASCIIPrintf(viewer,"estimated |f(x)-f(X*)|/|f(X*)| <= frtol\n");
633:         break;
634:       case TAO_CONVERGED_GATOL:
635:         PetscViewerASCIIPrintf(viewer," ||g(X)|| <= gatol\n");
636:         break;
637:       case TAO_CONVERGED_GRTOL:
638:         PetscViewerASCIIPrintf(viewer," ||g(X)||/|f(X)| <= grtol\n");
639:         break;
640:       case TAO_CONVERGED_GTTOL:
641:         PetscViewerASCIIPrintf(viewer," ||g(X)||/||g(X0)|| <= gttol\n");
642:         break;
643:       case TAO_CONVERGED_STEPTOL:
644:         PetscViewerASCIIPrintf(viewer," Steptol -- step size small\n");
645:         break;
646:       case TAO_CONVERGED_MINF:
647:         PetscViewerASCIIPrintf(viewer," Minf --  f < fmin\n");
648:         break;
649:       case TAO_CONVERGED_USER:
650:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
651:         break;
652:       default:
653:         PetscViewerASCIIPrintf(viewer,"\n");
654:         break;
655:       }

657:     } else {
658:       PetscViewerASCIIPrintf(viewer,"Solver terminated: %D",tao->reason);
659:       switch (tao->reason) {
660:       case TAO_DIVERGED_MAXITS:
661:         PetscViewerASCIIPrintf(viewer," Maximum Iterations\n");
662:         break;
663:       case TAO_DIVERGED_NAN:
664:         PetscViewerASCIIPrintf(viewer," NAN or Inf encountered\n");
665:         break;
666:       case TAO_DIVERGED_MAXFCN:
667:         PetscViewerASCIIPrintf(viewer," Maximum Function Evaluations\n");
668:         break;
669:       case TAO_DIVERGED_LS_FAILURE:
670:         PetscViewerASCIIPrintf(viewer," Line Search Failure\n");
671:         break;
672:       case TAO_DIVERGED_TR_REDUCTION:
673:         PetscViewerASCIIPrintf(viewer," Trust Region too small\n");
674:         break;
675:       case TAO_DIVERGED_USER:
676:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
677:         break;
678:       default:
679:         PetscViewerASCIIPrintf(viewer,"\n");
680:         break;
681:       }
682:     }
683:     PetscViewerASCIIPopTab(viewer);
684:   } else if (isstring) {
685:     TaoGetType(tao,&type);
686:     PetscViewerStringSPrintf(viewer," %-3.3s",type);
687:   }
688:   return(0);
689: }

693: /*@
694:   TaoSetTolerances - Sets parameters used in TAO convergence tests

696:   Logically collective on Tao

698:   Input Parameters:
699: + tao - the Tao context
700: . fatol - absolute convergence tolerance
701: . frtol - relative convergence tolerance
702: . gatol - stop if norm of gradient is less than this
703: . grtol - stop if relative norm of gradient is less than this
704: - gttol - stop if norm of gradient is reduced by this factor

706:   Options Database Keys:
707: + -tao_fatol <fatol> - Sets fatol
708: . -tao_frtol <frtol> - Sets frtol
709: . -tao_gatol <gatol> - Sets gatol
710: . -tao_grtol <grtol> - Sets grtol
711: - -tao_gttol <gttol> - Sets gttol

713:   Stopping Criteria:
714: $ f(X) - f(X*) (estimated)            <= fatol
715: $ |f(X) - f(X*)| (estimated) / |f(X)| <= frtol
716: $ ||g(X)||                            <= gatol
717: $ ||g(X)|| / |f(X)|                   <= grtol
718: $ ||g(X)|| / ||g(X0)||                <= gttol

720:   Notes:
721:   Use PETSC_DEFAULT to leave one or more tolerances unchanged.

723:   Level: beginner

725: .seealso: TaoGetTolerances()

727: @*/
728: PetscErrorCode TaoSetTolerances(Tao tao, PetscReal fatol, PetscReal frtol, PetscReal gatol, PetscReal grtol, PetscReal gttol)
729: {


735:   if (fatol != PETSC_DEFAULT) {
736:     if (fatol<0) {
737:       PetscInfo(tao,"Tried to set negative fatol -- ignored.\n");
738:     } else {
739:       tao->fatol = PetscMax(0,fatol);
740:       tao->fatol_changed=PETSC_TRUE;
741:     }
742:   }
743:   if (frtol != PETSC_DEFAULT) {
744:     if (frtol<0) {
745:       PetscInfo(tao,"Tried to set negative frtol -- ignored.\n");
746:     } else {
747:       tao->frtol = PetscMax(0,frtol);
748:       tao->frtol_changed=PETSC_TRUE;
749:     }
750:   }

752:   if (gatol != PETSC_DEFAULT) {
753:     if (gatol<0) {
754:       PetscInfo(tao,"Tried to set negative gatol -- ignored.\n");
755:     } else {
756:       tao->gatol = PetscMax(0,gatol);
757:       tao->gatol_changed=PETSC_TRUE;
758:     }
759:   }

761:   if (grtol != PETSC_DEFAULT) {
762:     if (grtol<0) {
763:       PetscInfo(tao,"Tried to set negative grtol -- ignored.\n");
764:     } else {
765:       tao->grtol = PetscMax(0,grtol);
766:       tao->grtol_changed=PETSC_TRUE;
767:     }
768:   }

770:   if (gttol != PETSC_DEFAULT) {
771:     if (gttol<0) {
772:       PetscInfo(tao,"Tried to set negative gttol -- ignored.\n");
773:     } else {
774:       tao->gttol = PetscMax(0,gttol);
775:       tao->gttol_changed=PETSC_TRUE;
776:     }
777:   }
778:   return(0);
779: }

783: /*@
784:   TaoSetConstraintTolerances - Sets constraint tolerance parameters used in TAO  convergence tests

786:   Logically collective on Tao

788:   Input Parameters:
789: + tao - the Tao context
790: . catol - absolute constraint tolerance, constraint norm must be less than catol for used for fatol, gatol convergence criteria
791: - crtol - relative contraint tolerance, constraint norm must be less than crtol for used for fatol, gatol, gttol convergence criteria

793:   Options Database Keys:
794: + -tao_catol <catol> - Sets catol
795: - -tao_crtol <crtol> - Sets crtol

797:   Notes:
798:   Use PETSC_DEFAULT to leave any tolerance unchanged.

800:   Level: intermediate

802: .seealso: TaoGetTolerances(), TaoGetConstraintTolerances(), TaoSetTolerances()

804: @*/
805: PetscErrorCode TaoSetConstraintTolerances(Tao tao, PetscReal catol, PetscReal crtol)
806: {


812:   if (catol != PETSC_DEFAULT) {
813:     if (catol<0) {
814:       PetscInfo(tao,"Tried to set negative catol -- ignored.\n");
815:     } else {
816:       tao->catol = PetscMax(0,catol);
817:       tao->catol_changed=PETSC_TRUE;
818:     }
819:   }

821:   if (crtol != PETSC_DEFAULT) {
822:     if (crtol<0) {
823:       PetscInfo(tao,"Tried to set negative crtol -- ignored.\n");
824:     } else {
825:       tao->crtol = PetscMax(0,crtol);
826:       tao->crtol_changed=PETSC_TRUE;
827:     }
828:   }
829:   return(0);
830: }

834: /*@
835:   TaoGetConstraintTolerances - Gets constraint tolerance parameters used in TAO  convergence tests

837:   Not ollective

839:   Input Parameter:
840: . tao - the Tao context

842:   Output Parameter:
843: + catol - absolute constraint tolerance, constraint norm must be less than catol for used for fatol, gatol convergence criteria
844: - crtol - relative contraint tolerance, constraint norm must be less than crtol for used for fatol, gatol, gttol convergence criteria

846:   Level: intermediate

848: .seealso: TaoGetTolerances(), TaoSetTolerances(), TaoSetConstraintTolerances()

850: @*/
851: PetscErrorCode TaoGetConstraintTolerances(Tao tao, PetscReal *catol, PetscReal *crtol)
852: {
855:   if (catol) *catol = tao->catol;
856:   if (crtol) *crtol = tao->crtol;
857:   return(0);
858: }

862: /*@
863:    TaoSetFunctionLowerBound - Sets a bound on the solution objective value.
864:    When an approximate solution with an objective value below this number
865:    has been found, the solver will terminate.

867:    Logically Collective on Tao

869:    Input Parameters:
870: +  tao - the Tao solver context
871: -  fmin - the tolerance

873:    Options Database Keys:
874: .    -tao_fmin <fmin> - sets the minimum function value

876:    Level: intermediate

878: .seealso: TaoSetTolerances()
879: @*/
880: PetscErrorCode TaoSetFunctionLowerBound(Tao tao,PetscReal fmin)
881: {
884:   tao->fmin = fmin;
885:   tao->fmin_changed=PETSC_TRUE;
886:   return(0);
887: }

891: /*@
892:    TaoGetFunctionLowerBound - Sets a bound on the solution objective value.
893:    When an approximate solution with an objective value below this number
894:    has been found, the solver will terminate.

896:    Not collective on Tao

898:    Input Parameters:
899: .  tao - the Tao solver context

901:    OutputParameters:
902: .  fmin - the minimum function value

904:    Level: intermediate

906: .seealso: TaoSetFunctionLowerBound()
907: @*/
908: PetscErrorCode TaoGetFunctionLowerBound(Tao tao,PetscReal *fmin)
909: {
912:   *fmin = tao->fmin;
913:   return(0);
914: }

918: /*@
919:    TaoSetMaximumFunctionEvaluations - Sets a maximum number of
920:    function evaluations.

922:    Logically Collective on Tao

924:    Input Parameters:
925: +  tao - the Tao solver context
926: -  nfcn - the maximum number of function evaluations (>=0)

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

931:    Level: intermediate

933: .seealso: TaoSetTolerances(), TaoSetMaximumIterations()
934: @*/

936: PetscErrorCode TaoSetMaximumFunctionEvaluations(Tao tao,PetscInt nfcn)
937: {
940:   tao->max_funcs = PetscMax(0,nfcn);
941:   tao->max_funcs_changed=PETSC_TRUE;
942:   return(0);
943: }

947: /*@
948:    TaoGetMaximumFunctionEvaluations - Sets a maximum number of
949:    function evaluations.

951:    Not Collective

953:    Input Parameters:
954: .  tao - the Tao solver context

956:    Output Parameters:
957: .  nfcn - the maximum number of function evaluations

959:    Level: intermediate

961: .seealso: TaoSetMaximumFunctionEvaluations(), TaoGetMaximumIterations()
962: @*/

964: PetscErrorCode TaoGetMaximumFunctionEvaluations(Tao tao,PetscInt *nfcn)
965: {
968:   *nfcn = tao->max_funcs;
969:   return(0);
970: }

974: /*@
975:    TaoGetCurrentFunctionEvaluations - Get current number of
976:    function evaluations.

978:    Not Collective

980:    Input Parameters:
981: .  tao - the Tao solver context

983:    Output Parameters:
984: .  nfuncs - the current number of function evaluations

986:    Level: intermediate

988: .seealso: TaoSetMaximumFunctionEvaluations(), TaoGetMaximumFunctionEvaluations(), TaoGetMaximumIterations()
989: @*/

991: PetscErrorCode TaoGetCurrentFunctionEvaluations(Tao tao,PetscInt *nfuncs)
992: {
995:   *nfuncs=PetscMax(tao->nfuncs,tao->nfuncgrads);
996:   return(0);
997: }

1001: /*@
1002:    TaoSetMaximumIterations - Sets a maximum number of iterates.

1004:    Logically Collective on Tao

1006:    Input Parameters:
1007: +  tao - the Tao solver context
1008: -  maxits - the maximum number of iterates (>=0)

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

1013:    Level: intermediate

1015: .seealso: TaoSetTolerances(), TaoSetMaximumFunctionEvaluations()
1016: @*/
1017: PetscErrorCode TaoSetMaximumIterations(Tao tao,PetscInt maxits)
1018: {
1021:   tao->max_it = PetscMax(0,maxits);
1022:   tao->max_it_changed=PETSC_TRUE;
1023:   return(0);
1024: }

1028: /*@
1029:    TaoGetMaximumIterations - Sets a maximum number of iterates.

1031:    Not Collective

1033:    Input Parameters:
1034: .  tao - the Tao solver context

1036:    Output Parameters:
1037: .  maxits - the maximum number of iterates

1039:    Level: intermediate

1041: .seealso: TaoSetMaximumIterations(), TaoGetMaximumFunctionEvaluations()
1042: @*/
1043: PetscErrorCode TaoGetMaximumIterations(Tao tao,PetscInt *maxits)
1044: {
1047:   *maxits = tao->max_it;
1048:   return(0);
1049: }

1053: /*@
1054:    TaoSetInitialTrustRegionRadius - Sets the initial trust region radius.

1056:    Logically collective on Tao

1058:    Input Parameter:
1059: +  tao - a TAO optimization solver
1060: -  radius - the trust region radius

1062:    Level: intermediate

1064:    Options Database Key:
1065: .  -tao_trust0 <t0> - sets initial trust region radius

1067: .seealso: TaoGetTrustRegionRadius(), TaoSetTrustRegionTolerance()
1068: @*/
1069: PetscErrorCode TaoSetInitialTrustRegionRadius(Tao tao, PetscReal radius)
1070: {
1073:   tao->trust0 = PetscMax(0.0,radius);
1074:   tao->trust0_changed=PETSC_TRUE;
1075:   return(0);
1076: }

1080: /*@
1081:    TaoGetInitialTrustRegionRadius - Sets the initial trust region radius.

1083:    Not Collective

1085:    Input Parameter:
1086: .  tao - a TAO optimization solver

1088:    Output Parameter:
1089: .  radius - the trust region radius

1091:    Level: intermediate

1093: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetCurrentTrustRegionRadius()
1094: @*/
1095: PetscErrorCode TaoGetInitialTrustRegionRadius(Tao tao, PetscReal *radius)
1096: {
1099:   *radius = tao->trust0;
1100:   return(0);
1101: }

1105: /*@
1106:    TaoGetCurrentTrustRegionRadius - Gets the current trust region radius.

1108:    Not Collective

1110:    Input Parameter:
1111: .  tao - a TAO optimization solver

1113:    Output Parameter:
1114: .  radius - the trust region radius

1116:    Level: intermediate

1118: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetInitialTrustRegionRadius()
1119: @*/
1120: PetscErrorCode TaoGetCurrentTrustRegionRadius(Tao tao, PetscReal *radius)
1121: {
1124:   *radius = tao->trust;
1125:   return(0);
1126: }

1130: /*@
1131:   TaoGetTolerances - gets the current values of tolerances

1133:   Not Collective

1135:   Input Parameters:
1136: . tao - the Tao context

1138:   Output Parameters:
1139: + fatol - absolute convergence tolerance
1140: . frtol - relative convergence tolerance
1141: . gatol - stop if norm of gradient is less than this
1142: . grtol - stop if relative norm of gradient is less than this
1143: - gttol - stop if norm of gradient is reduced by a this factor

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

1147: .seealso TaoSetTolerances()

1149:   Level: intermediate
1150: @*/
1151: PetscErrorCode TaoGetTolerances(Tao tao, PetscReal *fatol, PetscReal *frtol, PetscReal *gatol, PetscReal *grtol, PetscReal *gttol)
1152: {
1155:   if (fatol) *fatol=tao->fatol;
1156:   if (frtol) *frtol=tao->frtol;
1157:   if (gatol) *gatol=tao->gatol;
1158:   if (grtol) *grtol=tao->grtol;
1159:   if (gttol) *gttol=tao->gttol;
1160:   return(0);
1161: }

1165: /*@
1166:   TaoGetKSP - Gets the linear solver used by the optimization solver.
1167:   Application writers should use TaoGetKSP if they need direct access
1168:   to the PETSc KSP object.

1170:   Not Collective

1172:    Input Parameters:
1173: .  tao - the TAO solver

1175:    Output Parameters:
1176: .  ksp - the KSP linear solver used in the optimization solver

1178:    Level: intermediate

1180: @*/
1181: PetscErrorCode TaoGetKSP(Tao tao, KSP *ksp)
1182: {
1184:   *ksp = tao->ksp;
1185:   return(0);
1186: }

1190: /*@
1191:    TaoGetLinearSolveIterations - Gets the total number of linear iterations
1192:    used by the TAO solver

1194:    Not Collective

1196:    Input Parameter:
1197: .  tao - TAO context

1199:    Output Parameter:
1200: .  lits - number of linear iterations

1202:    Notes:
1203:    This counter is reset to zero for each successive call to TaoSolve()

1205:    Level: intermediate

1207: .keywords: TAO

1209: .seealso:  TaoGetKSP()
1210: @*/
1211: PetscErrorCode  TaoGetLinearSolveIterations(Tao tao,PetscInt *lits)
1212: {
1216:   *lits = tao->ksp_tot_its;
1217:   return(0);
1218: }

1222: /*@
1223:   TaoGetLineSearch - Gets the line search used by the optimization solver.
1224:   Application writers should use TaoGetLineSearch if they need direct access
1225:   to the TaoLineSearch object.

1227:   Not Collective

1229:    Input Parameters:
1230: .  tao - the TAO solver

1232:    Output Parameters:
1233: .  ls - the line search used in the optimization solver

1235:    Level: intermediate

1237: @*/
1238: PetscErrorCode TaoGetLineSearch(Tao tao, TaoLineSearch *ls)
1239: {
1241:   *ls = tao->linesearch;
1242:   return(0);
1243: }

1247: /*@
1248:   TaoAddLineSearchCounts - Adds the number of function evaluations spent
1249:   in the line search to the running total.

1251:    Input Parameters:
1252: +  tao - the TAO solver
1253: -  ls - the line search used in the optimization solver

1255:    Level: developer

1257: .seealso: TaoLineSearchApply()
1258: @*/
1259: PetscErrorCode TaoAddLineSearchCounts(Tao tao)
1260: {
1262:   PetscBool      flg;
1263:   PetscInt       nfeval,ngeval,nfgeval;

1267:   if (tao->linesearch) {
1268:     TaoLineSearchIsUsingTaoRoutines(tao->linesearch,&flg);
1269:     if (!flg) {
1270:       TaoLineSearchGetNumberFunctionEvaluations(tao->linesearch,&nfeval,&ngeval,&nfgeval);
1271:       tao->nfuncs+=nfeval;
1272:       tao->ngrads+=ngeval;
1273:       tao->nfuncgrads+=nfgeval;
1274:     }
1275:   }
1276:   return(0);
1277: }

1281: /*@
1282:   TaoGetSolutionVector - Returns the vector with the current TAO solution

1284:   Not Collective

1286:   Input Parameter:
1287: . tao - the Tao context

1289:   Output Parameter:
1290: . X - the current solution

1292:   Level: intermediate

1294:   Note:  The returned vector will be the same object that was passed into TaoSetInitialVector()
1295: @*/
1296: PetscErrorCode TaoGetSolutionVector(Tao tao, Vec *X)
1297: {
1300:   *X = tao->solution;
1301:   return(0);
1302: }

1306: /*@
1307:   TaoGetGradientVector - Returns the vector with the current TAO gradient

1309:   Not Collective

1311:   Input Parameter:
1312: . tao - the Tao context

1314:   Output Parameter:
1315: . G - the current solution

1317:   Level: intermediate
1318: @*/
1319: PetscErrorCode TaoGetGradientVector(Tao tao, Vec *G)
1320: {
1323:   *G = tao->gradient;
1324:   return(0);
1325: }

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

1334:    Collective on Tao

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

1339:    Level: developer

1341: .seealso: TaoCreate(), TaoSolve()
1342: @*/
1343: PetscErrorCode TaoResetStatistics(Tao tao)
1344: {
1347:   tao->niter        = 0;
1348:   tao->nfuncs       = 0;
1349:   tao->nfuncgrads   = 0;
1350:   tao->ngrads       = 0;
1351:   tao->nhess        = 0;
1352:   tao->njac         = 0;
1353:   tao->nconstraints = 0;
1354:   tao->ksp_its      = 0;
1355:   tao->ksp_tot_its      = 0;
1356:   tao->reason       = TAO_CONTINUE_ITERATING;
1357:   tao->residual     = 0.0;
1358:   tao->cnorm        = 0.0;
1359:   tao->step         = 0.0;
1360:   tao->lsflag       = PETSC_FALSE;
1361:   if (tao->hist_reset) tao->hist_len=0;
1362:   return(0);
1363: }

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

1372:   Logically Collective on Tao

1374:   Input Parameters:
1375: + tao - the Tao object
1376: . conv - the routine to test for convergence
1377: - ctx - [optional] context for private data for the convergence routine
1378:         (may be NULL)

1380:   Calling sequence of conv:
1381: $   PetscErrorCode conv(Tao tao, void *ctx)

1383: + tao - the Tao object
1384: - ctx - [optional] convergence context

1386:   Note: The new convergence testing routine should call TaoSetConvergedReason().

1388:   Level: advanced

1390: .seealso: TaoSetConvergedReason(), TaoGetSolutionStatus(), TaoGetTolerances(), TaoSetMonitor

1392: @*/
1393: PetscErrorCode TaoSetConvergenceTest(Tao tao, PetscErrorCode (*conv)(Tao,void*), void *ctx)
1394: {
1397:   (tao)->ops->convergencetest = conv;
1398:   (tao)->cnvP = ctx;
1399:   return(0);
1400: }

1404: /*@C
1405:    TaoSetMonitor - Sets an ADDITIONAL function that is to be used at every
1406:    iteration of the solver to display the iteration's
1407:    progress.

1409:    Logically Collective on Tao

1411:    Input Parameters:
1412: +  tao - the Tao solver context
1413: .  mymonitor - monitoring routine
1414: -  mctx - [optional] user-defined context for private data for the
1415:           monitor routine (may be NULL)

1417:    Calling sequence of mymonitor:
1418: $     int mymonitor(Tao tao,void *mctx)

1420: +    tao - the Tao solver context
1421: -    mctx - [optional] monitoring context


1424:    Options Database Keys:
1425: +    -tao_monitor        - sets TaoDefaultMonitor()
1426: .    -tao_smonitor       - sets short monitor
1427: .    -tao_cmonitor       - same as smonitor plus constraint norm
1428: .    -tao_view_solution   - view solution at each iteration
1429: .    -tao_view_gradient   - view gradient at each iteration
1430: .    -tao_view_separableobjective - view separable objective function at each iteration
1431: -    -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.


1434:    Notes:
1435:    Several different monitoring routines may be set by calling
1436:    TaoSetMonitor() multiple times; all will be called in the
1437:    order in which they were set.

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

1441:    Level: intermediate

1443: .seealso: TaoDefaultMonitor(), TaoCancelMonitors(),  TaoSetDestroyRoutine()
1444: @*/
1445: PetscErrorCode TaoSetMonitor(Tao tao, PetscErrorCode (*func)(Tao, void*), void *ctx,PetscErrorCode (*dest)(void**))
1446: {
1448:   PetscInt       i;

1452:   if (tao->numbermonitors >= MAXTAOMONITORS) SETERRQ1(PETSC_COMM_SELF,1,"Cannot attach another monitor -- max=",MAXTAOMONITORS);

1454:   for (i=0; i<tao->numbermonitors;i++) {
1455:     if (func == tao->monitor[i] && dest == tao->monitordestroy[i] && ctx == tao->monitorcontext[i]) {
1456:       if (dest) {
1457:         (*dest)(&ctx);
1458:       }
1459:       return(0);
1460:     }
1461:   }
1462:   tao->monitor[tao->numbermonitors] = func;
1463:   tao->monitorcontext[tao->numbermonitors] = ctx;
1464:   tao->monitordestroy[tao->numbermonitors] = dest;
1465:   ++tao->numbermonitors;
1466:   return(0);
1467: }

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

1474:    Logically Collective on Tao

1476:    Input Parameters:
1477: .  tao - the Tao solver context

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

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

1487:    Level: advanced

1489: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1490: @*/
1491: PetscErrorCode TaoCancelMonitors(Tao tao)
1492: {
1493:   PetscInt       i;

1498:   for (i=0;i<tao->numbermonitors;i++) {
1499:     if (tao->monitordestroy[i]) {
1500:       (*tao->monitordestroy[i])(&tao->monitorcontext[i]);
1501:     }
1502:   }
1503:   tao->numbermonitors=0;
1504:   return(0);
1505: }

1509: /*@
1510:    TaoDefaultMonitor - Default routine for monitoring progress of the
1511:    Tao solvers (default).  This monitor prints the function value and gradient
1512:    norm at each iteration.  It can be turned on from the command line using the
1513:    -tao_monitor option

1515:    Collective on Tao

1517:    Input Parameters:
1518: +  tao - the Tao context
1519: -  ctx - PetscViewer context or NULL

1521:    Options Database Keys:
1522: .  -tao_monitor

1524:    Level: advanced

1526: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1527: @*/
1528: PetscErrorCode TaoDefaultMonitor(Tao tao, void *ctx)
1529: {
1531:   PetscInt       its;
1532:   PetscReal      fct,gnorm;
1533:   PetscViewer    viewer;

1536:   if (ctx) {
1537:     viewer = (PetscViewer)ctx;
1538:   } else {
1539:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1540:   }
1541:   its=tao->niter;
1542:   fct=tao->fc;
1543:   gnorm=tao->residual;
1544:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
1545:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
1546:   if (gnorm >= PETSC_INFINITY) {
1547:     ierr=PetscViewerASCIIPrintf(viewer,"  Residual: Inf \n");
1548:   } else {
1549:     ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g \n",(double)gnorm);
1550:   }
1551:   return(0);
1552: }

1556: /*@
1557:    TaoDefaultSMonitor - Default routine for monitoring progress of the
1558:    solver. Same as TaoDefaultMonitor() except
1559:    it prints fewer digits of the residual as the residual gets smaller.
1560:    This is because the later digits are meaningless and are often
1561:    different on different machines; by using this routine different
1562:    machines will usually generate the same output. It can be turned on
1563:    by using the -tao_smonitor option

1565:    Collective on Tao

1567:    Input Parameters:
1568: +  tao - the Tao context
1569: -  ctx - PetscViewer context or NULL

1571:    Options Database Keys:
1572: .  -tao_smonitor

1574:    Level: advanced

1576: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1577: @*/
1578: PetscErrorCode TaoDefaultSMonitor(Tao tao, void *ctx)
1579: {
1581:   PetscInt       its;
1582:   PetscReal      fct,gnorm;
1583:   PetscViewer    viewer;

1586:   if (ctx) {
1587:     viewer = (PetscViewer)ctx;
1588:   } else {
1589:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1590:   }
1591:   its=tao->niter;
1592:   fct=tao->fc;
1593:   gnorm=tao->residual;
1594:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
1595:   ierr=PetscViewerASCIIPrintf(viewer," Function value %g,",(double)fct);
1596:   if (gnorm >= PETSC_INFINITY/2) {
1597:     ierr=PetscViewerASCIIPrintf(viewer," Residual: Inf \n");
1598:   } else if (gnorm > 1.e-6) {
1599:     ierr=PetscViewerASCIIPrintf(viewer," Residual: %g \n",(double)gnorm);
1600:   } else if (gnorm > 1.e-11) {
1601:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-6 \n");
1602:   } else {
1603:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-11 \n");
1604:   }
1605:   return(0);
1606: }

1610: /*@
1611:    TaoDefaultCMonitor - same as TaoDefaultMonitor() except
1612:    it prints the norm of the constraints function. It can be turned on
1613:    from the command line using the -tao_cmonitor option

1615:    Collective on Tao

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

1621:    Options Database Keys:
1622: .  -tao_cmonitor

1624:    Level: advanced

1626: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
1627: @*/
1628: PetscErrorCode TaoDefaultCMonitor(Tao tao, void *ctx)
1629: {
1631:   PetscInt       its;
1632:   PetscReal      fct,gnorm;
1633:   PetscViewer    viewer;

1636:   if (ctx) {
1637:     viewer = (PetscViewer)ctx;
1638:   } else {
1639:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1640:   }
1641:   its=tao->niter;
1642:   fct=tao->fc;
1643:   gnorm=tao->residual;
1644:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %D,",its);
1645:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
1646:   ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g ",(double)gnorm);
1647:   PetscViewerASCIIPrintf(viewer,"  Constraint: %g \n",(double)tao->cnorm);
1648:   return(0);
1649: }

1653: /*@C
1654:    TaoSolutionMonitor - Views the solution at each iteration
1655:    It can be turned on from the command line using the
1656:    -tao_view_solution option

1658:    Collective on Tao

1660:    Input Parameters:
1661: +  tao - the Tao context
1662: -  ctx - PetscViewer context or NULL

1664:    Options Database Keys:
1665: .  -tao_view_solution

1667:    Level: advanced

1669: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1670: @*/
1671: PetscErrorCode TaoSolutionMonitor(Tao tao, void *ctx)
1672: {
1674:   PetscViewer viewer;

1677:   if (ctx) {
1678:     viewer = (PetscViewer)ctx;
1679:   } else {
1680:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1681:   }
1682:   VecView(tao->solution, viewer);
1683:   return(0);
1684: }

1688: /*@C
1689:    TaoGradientMonitor - Views the gradient at each iteration
1690:    It can be turned on from the command line using the
1691:    -tao_view_gradient option

1693:    Collective on Tao

1695:    Input Parameters:
1696: +  tao - the Tao context
1697: -  ctx - PetscViewer context or NULL

1699:    Options Database Keys:
1700: .  -tao_view_gradient

1702:    Level: advanced

1704: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1705: @*/
1706: PetscErrorCode TaoGradientMonitor(Tao tao, void *ctx)
1707: {
1709:   PetscViewer viewer;

1712:   if (ctx) {
1713:     viewer = (PetscViewer)ctx;
1714:   } else {
1715:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1716:   }
1717:   VecView(tao->gradient, viewer);
1718:   return(0);
1719: }

1723: /*@C
1724:    TaoStepDirectionMonitor - Views the gradient at each iteration
1725:    It can be turned on from the command line using the
1726:    -tao_view_gradient option

1728:    Collective on Tao

1730:    Input Parameters:
1731: +  tao - the Tao context
1732: -  ctx - PetscViewer context or NULL

1734:    Options Database Keys:
1735: .  -tao_view_gradient

1737:    Level: advanced

1739: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1740: @*/
1741: PetscErrorCode TaoStepDirectionMonitor(Tao tao, void *ctx)
1742: {
1744:   PetscViewer viewer;
1746:   if (ctx) {
1747:     viewer = (PetscViewer)ctx;
1748:   } else {
1749:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1750:   }
1751:   VecView(tao->stepdirection, viewer);
1752:   return(0);
1753: }

1757: /*@C
1758:    TaoDrawSolutionMonitor - Plots the solution at each iteration
1759:    It can be turned on from the command line using the
1760:    -tao_draw_solution option

1762:    Collective on Tao

1764:    Input Parameters:
1765: +  tao - the Tao context
1766: -  ctx - PetscViewer context or NULL

1768:    Options Database Keys:
1769: .  -tao_draw_solution

1771:    Level: advanced

1773: .seealso: TaoSolutionMonitor(), TaoSetMonitor(), TaoDrawGradientMonitor
1774: @*/
1775: PetscErrorCode TaoDrawSolutionMonitor(Tao tao, void *ctx)
1776: {
1778:   PetscViewer    viewer = (PetscViewer) ctx;
1779:   MPI_Comm       comm;

1782:   if (!viewer) {
1783:     PetscObjectGetComm((PetscObject)tao,&comm);
1784:     viewer = PETSC_VIEWER_DRAW_(comm);
1785:   }
1786:   VecView(tao->solution, viewer);
1787:   return(0);
1788: }

1792: /*@C
1793:    TaoDrawGradientMonitor - Plots the gradient at each iteration
1794:    It can be turned on from the command line using the
1795:    -tao_draw_gradient option

1797:    Collective on Tao

1799:    Input Parameters:
1800: +  tao - the Tao context
1801: -  ctx - PetscViewer context or NULL

1803:    Options Database Keys:
1804: .  -tao_draw_gradient

1806:    Level: advanced

1808: .seealso: TaoGradientMonitor(), TaoSetMonitor(), TaoDrawSolutionMonitor
1809: @*/
1810: PetscErrorCode TaoDrawGradientMonitor(Tao tao, void *ctx)
1811: {
1813:   PetscViewer    viewer = (PetscViewer)ctx;
1814:   MPI_Comm       comm;

1817:   if (!viewer) {
1818:     PetscObjectGetComm((PetscObject)tao,&comm);
1819:     viewer = PETSC_VIEWER_DRAW_(comm);
1820:   }
1821:   VecView(tao->gradient, viewer);
1822:   return(0);
1823: }

1827: /*@C
1828:    TaoDrawStepMonitor - Plots the step direction at each iteration
1829:    It can be turned on from the command line using the
1830:    -tao_draw_step option

1832:    Collective on Tao

1834:    Input Parameters:
1835: +  tao - the Tao context
1836: -  ctx - PetscViewer context or NULL

1838:    Options Database Keys:
1839: .  -tao_draw_step

1841:    Level: advanced

1843: .seealso: TaoSetMonitor(), TaoDrawSolutionMonitor
1844: @*/
1845: PetscErrorCode TaoDrawStepMonitor(Tao tao, void *ctx)
1846: {
1848:   PetscViewer    viewer = (PetscViewer)(ctx);
1849:   MPI_Comm       comm;

1852:   if (!viewer) {
1853:     PetscObjectGetComm((PetscObject)tao,&comm);
1854:     viewer = PETSC_VIEWER_DRAW_(comm);
1855:   }
1856:   VecView(tao->stepdirection, viewer);
1857:   return(0);
1858: }

1862: /*@C
1863:    TaoSeparableObjectiveMonitor - Views the separable objective function at each iteration
1864:    It can be turned on from the command line using the
1865:    -tao_view_separableobjective option

1867:    Collective on Tao

1869:    Input Parameters:
1870: +  tao - the Tao context
1871: -  ctx - PetscViewer context or NULL

1873:    Options Database Keys:
1874: .  -tao_view_separableobjective

1876:    Level: advanced

1878: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
1879: @*/
1880: PetscErrorCode TaoSeparableObjectiveMonitor(Tao tao, void *ctx)
1881: {
1883:   PetscViewer    viewer;

1886:   if (ctx) {
1887:     viewer = (PetscViewer)ctx;
1888:   } else {
1889:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
1890:   }
1891:   VecView(tao->sep_objective,viewer);
1892:   return(0);
1893: }

1897: /*@
1898:    TaoDefaultConvergenceTest - Determines whether the solver should continue iterating
1899:    or terminate.

1901:    Collective on Tao

1903:    Input Parameters:
1904: +  tao - the Tao context
1905: -  dummy - unused dummy context

1907:    Output Parameter:
1908: .  reason - for terminating

1910:    Notes:
1911:    This routine checks the residual in the optimality conditions, the
1912:    relative residual in the optimity conditions, the number of function
1913:    evaluations, and the function value to test convergence.  Some
1914:    solvers may use different convergence routines.

1916:    Level: developer

1918: .seealso: TaoSetTolerances(),TaoGetConvergedReason(),TaoSetConvergedReason()
1919: @*/

1921: PetscErrorCode TaoDefaultConvergenceTest(Tao tao,void *dummy)
1922: {
1923:   PetscInt           niter=tao->niter, nfuncs=PetscMax(tao->nfuncs,tao->nfuncgrads);
1924:   PetscInt           max_funcs=tao->max_funcs;
1925:   PetscReal          gnorm=tao->residual, gnorm0=tao->gnorm0;
1926:   PetscReal          f=tao->fc, steptol=tao->steptol,trradius=tao->step;
1927:   PetscReal          gatol=tao->gatol,grtol=tao->grtol,gttol=tao->gttol;
1928:   PetscReal          fatol=tao->fatol,frtol=tao->frtol,catol=tao->catol,crtol=tao->crtol;
1929:   PetscReal          fmin=tao->fmin, cnorm=tao->cnorm, cnorm0=tao->cnorm0;
1930:   PetscReal          gnorm2;
1931:   TaoConvergedReason reason=tao->reason;
1932:   PetscErrorCode     ierr;

1936:   if (reason != TAO_CONTINUE_ITERATING) {
1937:     return(0);
1938:   }
1939:   gnorm2=gnorm*gnorm;

1941:   if (PetscIsInfOrNanReal(f)) {
1942:     PetscInfo(tao,"Failed to converged, function value is Inf or NaN\n");
1943:     reason = TAO_DIVERGED_NAN;
1944:   } else if (f <= fmin && cnorm <=catol) {
1945:     PetscInfo2(tao,"Converged due to function value %g < minimum function value %g\n", (double)f,(double)fmin);
1946:     reason = TAO_CONVERGED_MINF;
1947:   } else if (gnorm2 <= fatol && cnorm <=catol) {
1948:     PetscInfo2(tao,"Converged due to estimated f(X) - f(X*) = %g < %g\n",(double)gnorm2,(double)fatol);
1949:     reason = TAO_CONVERGED_FATOL;
1950:   } else if (f != 0 && gnorm2 / PetscAbsReal(f)<= frtol && cnorm/PetscMax(cnorm0,1.0) <= crtol) {
1951:     PetscInfo2(tao,"Converged due to estimated |f(X)-f(X*)|/f(X) = %g < %g\n",(double)(gnorm2/PetscAbsReal(f)),(double)frtol);
1952:     reason = TAO_CONVERGED_FRTOL;
1953:   } else if (gnorm<= gatol && cnorm <=catol) {
1954:     PetscInfo2(tao,"Converged due to residual norm ||g(X)||=%g < %g\n",(double)gnorm,(double)gatol);
1955:     reason = TAO_CONVERGED_GATOL;
1956:   } else if ( f!=0 && PetscAbsReal(gnorm/f) <= grtol && cnorm <= crtol) {
1957:     PetscInfo2(tao,"Converged due to residual ||g(X)||/|f(X)| =%g < %g\n",(double)(gnorm/f),(double)grtol);
1958:     reason = TAO_CONVERGED_GRTOL;
1959:   } else if (gnorm0 != 0 && gnorm/gnorm0 <= gttol && cnorm <= crtol) {
1960:     PetscInfo2(tao,"Converged due to relative residual norm ||g(X)||/||g(X0)|| = %g < %g\n",(double)(gnorm/gnorm0),(double)gttol);
1961:     reason = TAO_CONVERGED_GTTOL;
1962:   } else if (nfuncs > max_funcs){
1963:     PetscInfo2(tao,"Exceeded maximum number of function evaluations: %D > %D\n", nfuncs,max_funcs);
1964:     reason = TAO_DIVERGED_MAXFCN;
1965:   } else if ( tao->lsflag != 0 ){
1966:     PetscInfo(tao,"Tao Line Search failure.\n");
1967:     reason = TAO_DIVERGED_LS_FAILURE;
1968:   } else if (trradius < steptol && niter > 0){
1969:     PetscInfo2(tao,"Trust region/step size too small: %g < %g\n", (double)trradius,(double)steptol);
1970:     reason = TAO_CONVERGED_STEPTOL;
1971:   } else if (niter > tao->max_it) {
1972:     PetscInfo2(tao,"Exceeded maximum number of iterations: %D > %D\n",niter,tao->max_it);
1973:     reason = TAO_DIVERGED_MAXITS;
1974:   } else {
1975:     reason = TAO_CONTINUE_ITERATING;
1976:   }
1977:   tao->reason = reason;
1978:   return(0);
1979: }

1983: /*@C
1984:    TaoSetOptionsPrefix - Sets the prefix used for searching for all
1985:    TAO options in the database.


1988:    Logically Collective on Tao

1990:    Input Parameters:
1991: +  tao - the Tao context
1992: -  prefix - the prefix string to prepend to all TAO option requests

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

1998:    For example, to distinguish between the runtime options for two
1999:    different TAO solvers, one could call
2000: .vb
2001:       TaoSetOptionsPrefix(tao1,"sys1_")
2002:       TaoSetOptionsPrefix(tao2,"sys2_")
2003: .ve

2005:    This would enable use of different options for each system, such as
2006: .vb
2007:       -sys1_tao_method blmvm -sys1_tao_gtol 1.e-3
2008:       -sys2_tao_method lmvm  -sys2_tao_gtol 1.e-4
2009: .ve


2012:    Level: advanced

2014: .seealso: TaoAppendOptionsPrefix(), TaoGetOptionsPrefix()
2015: @*/

2017: PetscErrorCode TaoSetOptionsPrefix(Tao tao, const char p[])
2018: {

2022:   PetscObjectSetOptionsPrefix((PetscObject)tao,p);
2023:   if (tao->linesearch) {
2024:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
2025:   }
2026:   if (tao->ksp) {
2027:     KSPSetOptionsPrefix(tao->ksp,p);
2028:   }
2029:   return(0);
2030: }

2034: /*@C
2035:    TaoAppendOptionsPrefix - Appends to the prefix used for searching for all
2036:    TAO options in the database.


2039:    Logically Collective on Tao

2041:    Input Parameters:
2042: +  tao - the Tao solver context
2043: -  prefix - the prefix string to prepend to all TAO option requests

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


2050:    Level: advanced

2052: .seealso: TaoSetOptionsPrefix(), TaoGetOptionsPrefix()
2053: @*/
2054: PetscErrorCode TaoAppendOptionsPrefix(Tao tao, const char p[])
2055: {

2059:   PetscObjectAppendOptionsPrefix((PetscObject)tao,p);
2060:   if (tao->linesearch) {
2061:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
2062:   }
2063:   if (tao->ksp) {
2064:     KSPSetOptionsPrefix(tao->ksp,p);
2065:   }
2066:   return(0);
2067: }

2071: /*@C
2072:   TaoGetOptionsPrefix - Gets the prefix used for searching for all
2073:   TAO options in the database

2075:   Not Collective

2077:   Input Parameters:
2078: . tao - the Tao context

2080:   Output Parameters:
2081: . prefix - pointer to the prefix string used is returned

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

2086:   Level: advanced

2088: .seealso: TaoSetOptionsPrefix(), TaoAppendOptionsPrefix()
2089: @*/
2090: PetscErrorCode TaoGetOptionsPrefix(Tao tao, const char *p[])
2091: {
2092:    return PetscObjectGetOptionsPrefix((PetscObject)tao,p);
2093: }

2097: /*@C
2098:    TaoSetType - Sets the method for the unconstrained minimization solver.

2100:    Collective on Tao

2102:    Input Parameters:
2103: +  solver - the Tao solver context
2104: -  type - a known method

2106:    Options Database Key:
2107: .  -tao_type <type> - Sets the method; use -help for a list
2108:    of available methods (for instance, "-tao_type lmvm" or "-tao_type tron")

2110:    Available methods include:
2111: +    nls - Newton's method with line search for unconstrained minimization
2112: .    ntr - Newton's method with trust region for unconstrained minimization
2113: .    ntl - Newton's method with trust region, line search for unconstrained minimization
2114: .    lmvm - Limited memory variable metric method for unconstrained minimization
2115: .    cg - Nonlinear conjugate gradient method for unconstrained minimization
2116: .    nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
2117: .    tron - Newton Trust Region method for bound constrained minimization
2118: .    gpcg - Newton Trust Region method for quadratic bound constrained minimization
2119: .    blmvm - Limited memory variable metric method for bound constrained minimization
2120: -    pounders - Model-based algorithm pounder extended for nonlinear least squares

2122:   Level: intermediate

2124: .seealso: TaoCreate(), TaoGetType(), TaoType

2126: @*/
2127: PetscErrorCode TaoSetType(Tao tao, const TaoType type)
2128: {
2130:   PetscErrorCode (*create_xxx)(Tao);
2131:   PetscBool      issame;


2136:   PetscObjectTypeCompare((PetscObject)tao,type,&issame);
2137:   if (issame) return(0);

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

2142:   /* Destroy the existing solver information */
2143:   if (tao->ops->destroy) {
2144:     (*tao->ops->destroy)(tao);
2145:   }
2146:   KSPDestroy(&tao->ksp);
2147:   TaoLineSearchDestroy(&tao->linesearch);
2148:   VecDestroy(&tao->gradient);
2149:   VecDestroy(&tao->stepdirection);

2151:   tao->ops->setup = 0;
2152:   tao->ops->solve = 0;
2153:   tao->ops->view  = 0;
2154:   tao->ops->setfromoptions = 0;
2155:   tao->ops->destroy = 0;

2157:   tao->setupcalled = PETSC_FALSE;

2159:   (*create_xxx)(tao);
2160:   PetscObjectChangeTypeName((PetscObject)tao,type);
2161:   return(0);
2162: }

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

2169:    Synopsis:
2170:    TaoRegister(char *name_solver,char *path,char *name_Create,int (*routine_Create)(Tao))

2172:    Not collective

2174:    Input Parameters:
2175: +  sname - name of a new user-defined solver
2176: -  func - routine to Create method context

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

2181:    Sample usage:
2182: .vb
2183:    TaoRegister("my_solver",MySolverCreate);
2184: .ve

2186:    Then, your solver can be chosen with the procedural interface via
2187: $     TaoSetType(tao,"my_solver")
2188:    or at runtime via the option
2189: $     -tao_type my_solver

2191:    Level: advanced

2193: .seealso: TaoRegisterAll(), TaoRegisterDestroy()
2194: M*/
2195: PetscErrorCode TaoRegister(const char sname[], PetscErrorCode (*func)(Tao))
2196: {

2200:   PetscFunctionListAdd(&TaoList,sname, (void (*)(void))func);
2201:   return(0);
2202: }

2206: /*@C
2207:    TaoRegisterDestroy - Frees the list of minimization solvers that were
2208:    registered by TaoRegisterDynamic().

2210:    Not Collective

2212:    Level: advanced

2214: .seealso: TaoRegisterAll(), TaoRegister()
2215: @*/
2216: PetscErrorCode TaoRegisterDestroy(void)
2217: {
2220:   PetscFunctionListDestroy(&TaoList);
2221:   TaoRegisterAllCalled = PETSC_FALSE;
2222:   return(0);
2223: }

2227: /*@
2228:    TaoGetIterationNumber - Gets the number of Tao iterations completed
2229:    at this time.

2231:    Not Collective

2233:    Input Parameter:
2234: .  tao - Tao context

2236:    Output Parameter:
2237: .  iter - iteration number

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


2243:    Level: intermediate

2245: .keywords: Tao, nonlinear, get, iteration, number,

2247: .seealso:   TaoGetLinearSolveIterations()
2248: @*/
2249: PetscErrorCode  TaoGetIterationNumber(Tao tao,PetscInt *iter)
2250: {
2254:   *iter = tao->niter;
2255:   return(0);
2256: }

2260: /*@
2261:    TaoSetIterationNumber - Sets the current iteration number.

2263:    Not Collective

2265:    Input Parameter:
2266: .  tao - Tao context
2267: .  iter - iteration number

2269:    Level: developer

2271: .keywords: Tao, nonlinear, set, iteration, number,

2273: .seealso:   TaoGetLinearSolveIterations()
2274: @*/
2275: PetscErrorCode  TaoSetIterationNumber(Tao tao,PetscInt iter)
2276: {

2281:   PetscObjectSAWsTakeAccess((PetscObject)tao);
2282:   tao->niter = iter;
2283:   PetscObjectSAWsGrantAccess((PetscObject)tao);
2284:   return(0);
2285: }

2289: /*@
2290:    TaoGetTotalIterationNumber - Gets the total number of Tao iterations
2291:    completed. This number keeps accumulating if multiple solves
2292:    are called with the Tao object.

2294:    Not Collective

2296:    Input Parameter:
2297: .  tao - Tao context

2299:    Output Parameter:
2300: .  iter - iteration number

2302:    Notes:
2303:    The total iteration count is updated after each solve, if there is a current
2304:    TaoSolve() in progress then those iterations are not yet counted.

2306:    Level: intermediate

2308: .keywords: Tao, nonlinear, get, iteration, number,

2310: .seealso:   TaoGetLinearSolveIterations()
2311: @*/
2312: PetscErrorCode  TaoGetTotalIterationNumber(Tao tao,PetscInt *iter)
2313: {
2317:   *iter = tao->ntotalits;
2318:   return(0);
2319: }

2323: /*@
2324:    TaoSetTotalIterationNumber - Sets the current total iteration number.

2326:    Not Collective

2328:    Input Parameter:
2329: .  tao - Tao context
2330: .  iter - iteration number

2332:    Level: developer

2334: .keywords: Tao, nonlinear, set, iteration, number,

2336: .seealso:   TaoGetLinearSolveIterations()
2337: @*/
2338: PetscErrorCode  TaoSetTotalIterationNumber(Tao tao,PetscInt iter)
2339: {

2344:   PetscObjectSAWsTakeAccess((PetscObject)tao);
2345:   tao->ntotalits = iter;
2346:   PetscObjectSAWsGrantAccess((PetscObject)tao);
2347:   return(0);
2348: }

2352: /*@
2353:   TaoSetConvergedReason - Sets the termination flag on a Tao object

2355:   Logically Collective on Tao

2357:   Input Parameters:
2358: + tao - the Tao context
2359: - reason - one of
2360: $     TAO_CONVERGED_ATOL (2),
2361: $     TAO_CONVERGED_RTOL (3),
2362: $     TAO_CONVERGED_STEPTOL (4),
2363: $     TAO_CONVERGED_MINF (5),
2364: $     TAO_CONVERGED_USER (6),
2365: $     TAO_DIVERGED_MAXITS (-2),
2366: $     TAO_DIVERGED_NAN (-4),
2367: $     TAO_DIVERGED_MAXFCN (-5),
2368: $     TAO_DIVERGED_LS_FAILURE (-6),
2369: $     TAO_DIVERGED_TR_REDUCTION (-7),
2370: $     TAO_DIVERGED_USER (-8),
2371: $     TAO_CONTINUE_ITERATING (0)

2373:    Level: intermediate

2375: @*/
2376: PetscErrorCode TaoSetConvergedReason(Tao tao, TaoConvergedReason reason)
2377: {
2380:   tao->reason = reason;
2381:   return(0);
2382: }

2386: /*@
2387:    TaoGetConvergedReason - Gets the reason the Tao iteration was stopped.

2389:    Not Collective

2391:    Input Parameter:
2392: .  tao - the Tao solver context

2394:    Output Parameter:
2395: .  reason - one of
2396: $  TAO_CONVERGED_FATOL (1)           f(X)-f(X*) <= fatol
2397: $  TAO_CONVERGED_FRTOL (2)           |f(X) - f(X*)|/|f(X)| < frtol
2398: $  TAO_CONVERGED_GATOL (3)           ||g(X)|| < gatol
2399: $  TAO_CONVERGED_GRTOL (4)           ||g(X)|| / f(X)  < grtol
2400: $  TAO_CONVERGED_GTTOL (5)           ||g(X)|| / ||g(X0)|| < gttol
2401: $  TAO_CONVERGED_STEPTOL (6)         step size small
2402: $  TAO_CONVERGED_MINF (7)            F < F_min
2403: $  TAO_CONVERGED_USER (8)            User defined
2404: $  TAO_DIVERGED_MAXITS (-2)          its > maxits
2405: $  TAO_DIVERGED_NAN (-4)             Numerical problems
2406: $  TAO_DIVERGED_MAXFCN (-5)          fevals > max_funcsals
2407: $  TAO_DIVERGED_LS_FAILURE (-6)      line search failure
2408: $  TAO_DIVERGED_TR_REDUCTION (-7)    trust region failure
2409: $  TAO_DIVERGED_USER(-8)             (user defined)
2410:  $  TAO_CONTINUE_ITERATING (0)

2412:    where
2413: +  X - current solution
2414: .  X0 - initial guess
2415: .  f(X) - current function value
2416: .  f(X*) - true solution (estimated)
2417: .  g(X) - current gradient
2418: .  its - current iterate number
2419: .  maxits - maximum number of iterates
2420: .  fevals - number of function evaluations
2421: -  max_funcsals - maximum number of function evaluations

2423:    Level: intermediate

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

2427: @*/
2428: PetscErrorCode TaoGetConvergedReason(Tao tao, TaoConvergedReason *reason)
2429: {
2433:   *reason = tao->reason;
2434:   return(0);
2435: }

2439: /*@
2440:   TaoGetSolutionStatus - Get the current iterate, objective value,
2441:   residual, infeasibility, and termination

2443:   Not Collective

2445:    Input Parameters:
2446: .  tao - the Tao context

2448:    Output Parameters:
2449: +  iterate - the current iterate number (>=0)
2450: .  f - the current function value
2451: .  gnorm - the square of the gradient norm, duality gap, or other measure indicating distance from optimality.
2452: .  cnorm - the infeasibility of the current solution with regard to the constraints.
2453: .  xdiff - the step length or trust region radius of the most recent iterate.
2454: -  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

2456:    Level: intermediate

2458:    Note:
2459:    TAO returns the values set by the solvers in the routine TaoMonitor().

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

2464: .seealso: TaoMonitor(), TaoGetConvergedReason()
2465: @*/
2466: PetscErrorCode TaoGetSolutionStatus(Tao tao, PetscInt *its, PetscReal *f, PetscReal *gnorm, PetscReal *cnorm, PetscReal *xdiff, TaoConvergedReason *reason)
2467: {
2469:   if (its) *its=tao->niter;
2470:   if (f) *f=tao->fc;
2471:   if (gnorm) *gnorm=tao->residual;
2472:   if (cnorm) *cnorm=tao->cnorm;
2473:   if (reason) *reason=tao->reason;
2474:   if (xdiff) *xdiff=tao->step;
2475:   return(0);
2476: }

2480: /*@C
2481:    TaoGetType - Gets the current Tao algorithm.

2483:    Not Collective

2485:    Input Parameter:
2486: .  tao - the Tao solver context

2488:    Output Parameter:
2489: .  type - Tao method

2491:    Level: intermediate

2493: @*/
2494: PetscErrorCode TaoGetType(Tao tao, const TaoType *type)
2495: {
2499:   *type=((PetscObject)tao)->type_name;
2500:   return(0);
2501: }

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

2510:    Input Parameters:
2511: +  tao - the Tao context
2512: .  its - the current iterate number (>=0)
2513: .  f - the current objective function value
2514: .  res - the gradient norm, square root of the duality gap, or other measure indicating distince from optimality.  This measure will be recorded and
2515:           used for some termination tests.
2516: .  cnorm - the infeasibility of the current solution with regard to the constraints.
2517: -  steplength - multiple of the step direction added to the previous iterate.

2519:    Output Parameters:
2520: .  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

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

2525: .seealso TaoGetConvergedReason(), TaoDefaultMonitor(), TaoSetMonitor()

2527:    Level: developer

2529: @*/
2530: PetscErrorCode TaoMonitor(Tao tao, PetscInt its, PetscReal f, PetscReal res, PetscReal cnorm, PetscReal steplength, TaoConvergedReason *reason)
2531: {
2533:   PetscInt       i;

2537:   tao->fc = f;
2538:   tao->residual = res;
2539:   tao->cnorm = cnorm;
2540:   tao->step = steplength;
2541:   if (its == 0) {
2542:     tao->cnorm0 = cnorm; tao->gnorm0 = res;
2543:   }
2544:   TaoLogConvergenceHistory(tao,f,res,cnorm,tao->ksp_its);
2545:   if (PetscIsInfOrNanReal(f) || PetscIsInfOrNanReal(res)) SETERRQ(PETSC_COMM_SELF,1, "User provided compute function generated Inf or NaN");
2546:   if (tao->ops->convergencetest) {
2547:     (*tao->ops->convergencetest)(tao,tao->cnvP);
2548:   }
2549:   for (i=0;i<tao->numbermonitors;i++) {
2550:     (*tao->monitor[i])(tao,tao->monitorcontext[i]);
2551:   }
2552:   *reason = tao->reason;
2553:   return(0);
2554: }

2558: /*@
2559:    TaoSetConvergenceHistory - Sets the array used to hold the convergence history.

2561:    Logically Collective on Tao

2563:    Input Parameters:
2564: +  tao - the Tao solver context
2565: .  obj   - array to hold objective value history
2566: .  resid - array to hold residual history
2567: .  cnorm - array to hold constraint violation history
2568: .  lits - integer array holds the number of linear iterations for each Tao iteration
2569: .  na  - size of obj, resid, and cnorm
2570: -  reset - PetscTrue indicates each new minimization resets the history counter to zero,
2571:            else it continues storing new values for new minimizations after the old ones

2573:    Notes:
2574:    If set, TAO will fill the given arrays with the indicated
2575:    information at each iteration.  If 'obj','resid','cnorm','lits' are
2576:    *all* NULL then space (using size na, or 1000 if na is PETSC_DECIDE or
2577:    PETSC_DEFAULT) is allocated for the history.
2578:    If not all are NULL, then only the non-NULL information categories
2579:    will be stored, the others will be ignored.

2581:    Any convergence information after iteration number 'na' will not be stored.

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

2587:    Level: intermediate

2589: .seealso: TaoGetConvergenceHistory()

2591: @*/
2592: PetscErrorCode TaoSetConvergenceHistory(Tao tao, PetscReal *obj, PetscReal *resid, PetscReal *cnorm, PetscInt *lits, PetscInt na,PetscBool reset)
2593: {


2603:   if (na == PETSC_DECIDE || na == PETSC_DEFAULT) na = 1000;
2604:   if (!obj && !resid && !cnorm && !lits) {
2605:     PetscCalloc1(na,&obj);
2606:     PetscCalloc1(na,&resid);
2607:     PetscCalloc1(na,&cnorm);
2608:     PetscCalloc1(na,&lits);
2609:     tao->hist_malloc=PETSC_TRUE;
2610:   }

2612:   tao->hist_obj = obj;
2613:   tao->hist_resid = resid;
2614:   tao->hist_cnorm = cnorm;
2615:   tao->hist_lits = lits;
2616:   tao->hist_max   = na;
2617:   tao->hist_reset = reset;
2618:   tao->hist_len = 0;
2619:   return(0);
2620: }

2624: /*@C
2625:    TaoGetConvergenceHistory - Gets the arrays used to hold the convergence history.

2627:    Collective on Tao

2629:    Input Parameter:
2630: .  tao - the Tao context

2632:    Output Parameters:
2633: +  obj   - array used to hold objective value history
2634: .  resid - array used to hold residual history
2635: .  cnorm - array used to hold constraint violation history
2636: .  lits  - integer array used to hold linear solver iteration count
2637: -  nhist  - size of obj, resid, cnorm, and lits (will be less than or equal to na given in TaoSetHistory)

2639:    Notes:
2640:     This routine must be preceded by calls to TaoSetConvergenceHistory()
2641:     and TaoSolve(), otherwise it returns useless information.

2643:     The calling sequence for this routine in Fortran is
2644: $   call TaoGetConvergenceHistory(Tao tao, PetscInt nhist, PetscErrorCode ierr)

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

2650:    Level: advanced

2652: .seealso: TaoSetConvergenceHistory()

2654: @*/
2655: PetscErrorCode TaoGetConvergenceHistory(Tao tao, PetscReal **obj, PetscReal **resid, PetscReal **cnorm, PetscInt **lits, PetscInt *nhist)
2656: {
2659:   if (obj)   *obj   = tao->hist_obj;
2660:   if (cnorm) *cnorm = tao->hist_cnorm;
2661:   if (resid) *resid = tao->hist_resid;
2662:   if (nhist) *nhist   = tao->hist_len;
2663:   return(0);
2664: }

2668: /*@
2669:    TaoSetApplicationContext - Sets the optional user-defined context for
2670:    a solver.

2672:    Logically Collective on Tao

2674:    Input Parameters:
2675: +  tao  - the Tao context
2676: -  usrP - optional user context

2678:    Level: intermediate

2680: .seealso: TaoGetApplicationContext(), TaoSetApplicationContext()
2681: @*/
2682: PetscErrorCode  TaoSetApplicationContext(Tao tao,void *usrP)
2683: {
2686:   tao->user = usrP;
2687:   return(0);
2688: }

2692: /*@
2693:    TaoGetApplicationContext - Gets the user-defined context for a
2694:    TAO solvers.

2696:    Not Collective

2698:    Input Parameter:
2699: .  tao  - Tao context

2701:    Output Parameter:
2702: .  usrP - user context

2704:    Level: intermediate

2706: .seealso: TaoSetApplicationContext()
2707: @*/
2708: PetscErrorCode  TaoGetApplicationContext(Tao tao,void *usrP)
2709: {
2712:   *(void**)usrP = tao->user;
2713:   return(0);
2714: }