Actual source code: taolinesearch.c

petsc-3.7.3 2016-08-01
Report Typos and Errors
  1: #include <petsctaolinesearch.h> /*I "petsctaolinesearch.h" I*/
  2: #include <petsc/private/taolinesearchimpl.h>

  4: PetscBool TaoLineSearchInitialized = PETSC_FALSE;
  5: PetscFunctionList TaoLineSearchList = NULL;

  7: PetscClassId TAOLINESEARCH_CLASSID=0;
  8: PetscLogEvent TaoLineSearch_ApplyEvent = 0, TaoLineSearch_EvalEvent=0;

 12: /*@C
 13:   TaoLineSearchView - Prints information about the TaoLineSearch

 15:   Collective on TaoLineSearch

 17:   InputParameters:
 18: + ls - the Tao context
 19: - viewer - visualization context

 21:   Options Database Key:
 22: . -tao_ls_view - Calls TaoLineSearchView() at the end of each line search

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

 32:   Level: beginner

 34: .seealso: PetscViewerASCIIOpen()
 35: @*/

 37: PetscErrorCode TaoLineSearchView(TaoLineSearch ls, PetscViewer viewer)
 38: {
 39:   PetscErrorCode          ierr;
 40:   PetscBool               isascii, isstring;
 41:   const TaoLineSearchType type;

 45:   if (!viewer) {
 46:     PetscViewerASCIIGetStdout(((PetscObject)ls)->comm, &viewer);
 47:   }

 51:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
 52:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSTRING,&isstring);
 53:   if (isascii) {
 54:     if (((PetscObject)ls)->prefix) {
 55:       PetscViewerASCIIPrintf(viewer,"TaoLineSearch Object:(%s)\n",((PetscObject)ls)->prefix);
 56:     } else {
 57:       PetscViewerASCIIPrintf(viewer,"TaoLineSearch Object:\n");
 58:     }
 59:     PetscViewerASCIIPushTab(viewer);
 60:     TaoLineSearchGetType(ls,&type);
 61:     if (type) {
 62:       PetscViewerASCIIPrintf(viewer,"type: %s\n",type);
 63:     } else {
 64:       PetscViewerASCIIPrintf(viewer,"type: not set yet\n");
 65:     }
 66:     if (ls->ops->view) {
 67:       PetscViewerASCIIPushTab(viewer);
 68:       (*ls->ops->view)(ls,viewer);
 69:       PetscViewerASCIIPopTab(viewer);
 70:     }
 71:     PetscViewerASCIIPrintf(viewer,"maximum function evaluations=%D\n",ls->max_funcs);
 72:     PetscViewerASCIIPrintf(viewer,"tolerances: ftol=%g, rtol=%g, gtol=%g\n",(double)ls->ftol,(double)ls->rtol,(double)ls->gtol);
 73:     PetscViewerASCIIPrintf(viewer,"total number of function evaluations=%D\n",ls->nfeval);
 74:     PetscViewerASCIIPrintf(viewer,"total number of gradient evaluations=%D\n",ls->ngeval);
 75:     PetscViewerASCIIPrintf(viewer,"total number of function/gradient evaluations=%D\n",ls->nfgeval);

 77:     if (ls->bounded) {
 78:       PetscViewerASCIIPrintf(viewer,"using variable bounds\n");
 79:     }
 80:     PetscViewerASCIIPrintf(viewer,"Termination reason: %d\n",(int)ls->reason);
 81:     PetscViewerASCIIPopTab(viewer);

 83:   } else if (isstring) {
 84:     TaoLineSearchGetType(ls,&type);
 85:     PetscViewerStringSPrintf(viewer," %-3.3s",type);
 86:   }
 87:   return(0);
 88: }

 92: /*@C
 93:   TaoLineSearchCreate - Creates a TAO Line Search object.  Algorithms in TAO that use
 94:   line-searches will automatically create one.

 96:   Collective on MPI_Comm

 98:   Input Parameter:
 99: . comm - MPI communicator

101:   Output Parameter:
102: . newls - the new TaoLineSearch context

104:   Available methods include:
105: + more-thuente
106: . gpcg
107: - unit - Do not perform any line search


110:    Options Database Keys:
111: .   -tao_ls_type - select which method TAO should use

113:    Level: beginner

115: .seealso: TaoLineSearchSetType(), TaoLineSearchApply(), TaoLineSearchDestroy()
116: @*/

118: PetscErrorCode TaoLineSearchCreate(MPI_Comm comm, TaoLineSearch *newls)
119: {
121:   TaoLineSearch  ls;

125:   *newls = NULL;

127:  #ifndef PETSC_USE_DYNAMIC_LIBRARIES
128:   TaoLineSearchInitializePackage();
129:  #endif

131:   PetscHeaderCreate(ls,TAOLINESEARCH_CLASSID,"TaoLineSearch","Linesearch","Tao",comm,TaoLineSearchDestroy,TaoLineSearchView);
132:   ls->bounded = 0;
133:   ls->max_funcs=30;
134:   ls->ftol = 0.0001;
135:   ls->gtol = 0.9;
136: #if defined(PETSC_USE_REAL_SINGLE)
137:   ls->rtol = 1.0e-5;
138: #else
139:   ls->rtol = 1.0e-10;
140: #endif
141:   ls->stepmin=1.0e-20;
142:   ls->stepmax=1.0e+20;
143:   ls->step=1.0;
144:   ls->nfeval=0;
145:   ls->ngeval=0;
146:   ls->nfgeval=0;

148:   ls->ops->computeobjective=0;
149:   ls->ops->computegradient=0;
150:   ls->ops->computeobjectiveandgradient=0;
151:   ls->ops->computeobjectiveandgts=0;
152:   ls->ops->setup=0;
153:   ls->ops->apply=0;
154:   ls->ops->view=0;
155:   ls->ops->setfromoptions=0;
156:   ls->ops->reset=0;
157:   ls->ops->destroy=0;
158:   ls->setupcalled=PETSC_FALSE;
159:   ls->usetaoroutines=PETSC_FALSE;
160:   *newls = ls;
161:   return(0);
162: }

166: /*@
167:   TaoLineSearchSetUp - Sets up the internal data structures for the later use
168:   of a Tao solver

170:   Collective on ls

172:   Input Parameters:
173: . ls - the TaoLineSearch context

175:   Notes:
176:   The user will not need to explicitly call TaoLineSearchSetUp(), as it will
177:   automatically be called in TaoLineSearchSolve().  However, if the user
178:   desires to call it explicitly, it should come after TaoLineSearchCreate()
179:   but before TaoLineSearchApply().

181:   Level: developer

183: .seealso: TaoLineSearchCreate(), TaoLineSearchApply()
184: @*/

186: PetscErrorCode TaoLineSearchSetUp(TaoLineSearch ls)
187: {
189:   const char     *default_type=TAOLINESEARCHMT;
190:   PetscBool      flg;

194:   if (ls->setupcalled) return(0);
195:   if (!((PetscObject)ls)->type_name) {
196:     TaoLineSearchSetType(ls,default_type);
197:   }
198:   if (ls->ops->setup) {
199:     (*ls->ops->setup)(ls);
200:   }
201:   if (ls->usetaoroutines) {
202:     TaoIsObjectiveDefined(ls->tao,&flg);
203:     ls->hasobjective = flg;
204:     TaoIsGradientDefined(ls->tao,&flg);
205:     ls->hasgradient = flg;
206:     TaoIsObjectiveAndGradientDefined(ls->tao,&flg);
207:     ls->hasobjectiveandgradient = flg;
208:   } else {
209:     if (ls->ops->computeobjective) {
210:       ls->hasobjective = PETSC_TRUE;
211:     } else {
212:       ls->hasobjective = PETSC_FALSE;
213:     }
214:     if (ls->ops->computegradient) {
215:       ls->hasgradient = PETSC_TRUE;
216:     } else {
217:       ls->hasgradient = PETSC_FALSE;
218:     }
219:     if (ls->ops->computeobjectiveandgradient) {
220:       ls->hasobjectiveandgradient = PETSC_TRUE;
221:     } else {
222:       ls->hasobjectiveandgradient = PETSC_FALSE;
223:     }
224:   }
225:   ls->setupcalled = PETSC_TRUE;
226:   return(0);
227: }

231: /*@
232:   TaoLineSearchReset - Some line searches may carry state information
233:   from one TaoLineSearchApply() to the next.  This function resets this
234:   state information.

236:   Collective on TaoLineSearch

238:   Input Parameter:
239: . ls - the TaoLineSearch context

241:   Level: developer

243: .seealso: TaoLineSearchCreate(), TaoLineSearchApply()
244: @*/
245: PetscErrorCode TaoLineSearchReset(TaoLineSearch ls)
246: {

251:   if (ls->ops->reset) {
252:     (*ls->ops->reset)(ls);
253:   }
254:   return(0);
255: }

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

263:   Collective on TaoLineSearch

265:   Input Parameter
266: . ls - the TaoLineSearch context

268:   Level: beginner

270: .seealse: TaoLineSearchCreate(), TaoLineSearchSolve()
271: @*/
272: PetscErrorCode TaoLineSearchDestroy(TaoLineSearch *ls)
273: {

277:   if (!*ls) return(0);
279:   if (--((PetscObject)*ls)->refct > 0) {*ls=0; return(0);}
280:   VecDestroy(&(*ls)->stepdirection);
281:   VecDestroy(&(*ls)->start_x);
282:   if ((*ls)->ops->destroy) {
283:     (*(*ls)->ops->destroy)(*ls);
284:   }
285:   PetscHeaderDestroy(ls);
286:   return(0);
287: }

291: /*@
292:   TaoLineSearchApply - Performs a line-search in a given step direction.  Criteria for acceptable step length depends on the line-search algorithm chosen

294:   Collective on TaoLineSearch

296:   Input Parameters:
297: + ls - the Tao context
298: . x - The current solution (on output x contains the new solution determined by the line search)
299: . f - objective function value at current solution (on output contains the objective function value at new solution)
300: . g - gradient evaluated at x (on output contains the gradient at new solution)
301: - s - search direction

303:   Output Parameters:
304: + x - new solution
305: . f - objective function value at x
306: . g - gradient vector at x
307: . steplength - scalar multiplier of s used ( x = x0 + steplength * x )
308: - reason - reason why the line-search stopped

310:   reason will be set to one of:

312: + TAOLINESEARCH_FAILED_ASCENT - initial line search step * g is not descent direction
313: . TAOLINESEARCH_FAILED_INFORNAN - function evaluation gives Inf or Nan value
314: . TAOLINESEARCH_FAILED_BADPARAMETER - negative value set as parameter
315: . TAOLINESEARCH_HALTED_MAXFCN - maximum number of function evaluation reached
316: . TAOLINESEARCH_HALTED_UPPERBOUND - step is at upper bound
317: . TAOLINESEARCH_HALTED_LOWERBOUND - step is at lower bound
318: . TAOLINESEARCH_HALTED_RTOL - range of uncertainty is smaller than given tolerance
319: . TAOLINESEARCH_HALTED_USER - user can set this reason to stop line search
320: . TAOLINESEARCH_HALTED_OTHER - any other reason
321: - TAOLINESEARCH_SUCCESS - successful line search

323:   Note:
324:   The algorithm developer must set up the TaoLineSearch with calls to
325:   TaoLineSearchSetObjectiveRoutine() and TaoLineSearchSetGradientRoutine(), TaoLineSearchSetObjectiveAndGradientRoutine(), or TaoLineSearchUseTaoRoutines()

327:   Note:
328:   You may or may not need to follow this with a call to
329:   TaoAddLineSearchCounts(), depending on whether you want these
330:   evaluations to count toward the total function/gradient evaluations.

332:   Level: beginner

334:   .seealso: TaoLineSearchCreate(), TaoLineSearchSetType(), TaoLineSearchSetInitialStepLength(), TaoAddLineSearchCounts()
335:  @*/

337: PetscErrorCode TaoLineSearchApply(TaoLineSearch ls, Vec x, PetscReal *f, Vec g, Vec s, PetscReal *steplength, TaoLineSearchConvergedReason *reason)
338: {
340:   PetscInt       low1,low2,low3,high1,high2,high3;

343:   *reason = TAOLINESEARCH_CONTINUE_ITERATING;
353:   VecGetOwnershipRange(x, &low1, &high1);
354:   VecGetOwnershipRange(g, &low2, &high2);
355:   VecGetOwnershipRange(s, &low3, &high3);
356:   if ( low1!= low2 || low1!= low3 || high1!= high2 || high1!= high3) SETERRQ(PETSC_COMM_SELF,1,"InCompatible vector local lengths");

358:   PetscObjectReference((PetscObject)s);
359:   VecDestroy(&ls->stepdirection);
360:   ls->stepdirection = s;

362:   TaoLineSearchSetUp(ls);
363:   if (!ls->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search Object does not have 'apply' routine");
364:   ls->nfeval=0;
365:   ls->ngeval=0;
366:   ls->nfgeval=0;
367:   /* Check parameter values */
368:   if (ls->ftol < 0.0) {
369:     PetscInfo1(ls,"Bad Line Search Parameter: ftol (%g) < 0\n",(double)ls->ftol);
370:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
371:   }
372:   if (ls->rtol < 0.0) {
373:     PetscInfo1(ls,"Bad Line Search Parameter: rtol (%g) < 0\n",(double)ls->rtol);
374:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
375:   }
376:   if (ls->gtol < 0.0) {
377:     PetscInfo1(ls,"Bad Line Search Parameter: gtol (%g) < 0\n",(double)ls->gtol);
378:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
379:   }
380:   if (ls->stepmin < 0.0) {
381:     PetscInfo1(ls,"Bad Line Search Parameter: stepmin (%g) < 0\n",(double)ls->stepmin);
382:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
383:   }
384:   if (ls->stepmax < ls->stepmin) {
385:     PetscInfo2(ls,"Bad Line Search Parameter: stepmin (%g) > stepmax (%g)\n",(double)ls->stepmin,(double)ls->stepmax);
386:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
387:   }
388:   if (ls->max_funcs < 0) {
389:     PetscInfo1(ls,"Bad Line Search Parameter: max_funcs (%D) < 0\n",ls->max_funcs);
390:     *reason=TAOLINESEARCH_FAILED_BADPARAMETER;
391:   }
392:   if (PetscIsInfOrNanReal(*f)) {
393:     PetscInfo1(ls,"Initial Line Search Function Value is Inf or Nan (%g)\n",(double)*f);
394:     *reason=TAOLINESEARCH_FAILED_INFORNAN;
395:   }

397:   PetscObjectReference((PetscObject)x);
398:   VecDestroy(&ls->start_x);
399:   ls->start_x = x;

401:   PetscLogEventBegin(TaoLineSearch_ApplyEvent,ls,0,0,0);
402:   (*ls->ops->apply)(ls,x,f,g,s);
403:   PetscLogEventEnd(TaoLineSearch_ApplyEvent, ls, 0,0,0);
404:   *reason=ls->reason;
405:   ls->new_f = *f;

407:   if (steplength) {
408:     *steplength=ls->step;
409:   }

411:   TaoLineSearchViewFromOptions(ls,NULL,"-tao_ls_view");
412:   return(0);
413: }

417: /*@C
418:    TaoLineSearchSetType - Sets the algorithm used in a line search

420:    Collective on TaoLineSearch

422:    Input Parameters:
423: +  ls - the TaoLineSearch context
424: -  type - a known method

426:   Available methods include:
427: + more-thuente
428: . gpcg
429: - unit - Do not perform any line search


432:   Options Database Keys:
433: .   -tao_ls_type - select which method TAO should use

435:   Level: beginner


438: .seealso: TaoLineSearchCreate(), TaoLineSearchGetType(), TaoLineSearchApply()

440: @*/

442: PetscErrorCode TaoLineSearchSetType(TaoLineSearch ls, const TaoLineSearchType type)
443: {
445:   PetscErrorCode (*r)(TaoLineSearch);
446:   PetscBool      flg;

451:   PetscObjectTypeCompare((PetscObject)ls, type, &flg);
452:   if (flg) return(0);

454:   PetscFunctionListFind(TaoLineSearchList,type, (void (**)(void)) &r);
455:   if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested TaoLineSearch type %s",type);
456:   if (ls->ops->destroy) {
457:     (*(ls)->ops->destroy)(ls);
458:   }
459:   ls->max_funcs=30;
460:   ls->ftol = 0.0001;
461:   ls->gtol = 0.9;
462: #if defined(PETSC_USE_REAL_SINGLE)
463:   ls->rtol = 1.0e-5;
464: #else
465:   ls->rtol = 1.0e-10;
466: #endif
467:   ls->stepmin=1.0e-20;
468:   ls->stepmax=1.0e+20;

470:   ls->nfeval=0;
471:   ls->ngeval=0;
472:   ls->nfgeval=0;
473:   ls->ops->setup=0;
474:   ls->ops->apply=0;
475:   ls->ops->view=0;
476:   ls->ops->setfromoptions=0;
477:   ls->ops->destroy=0;
478:   ls->setupcalled = PETSC_FALSE;
479:   (*r)(ls);
480:   PetscObjectChangeTypeName((PetscObject)ls, type);
481:   return(0);
482: }

486: /*@
487:   TaoLineSearchSetFromOptions - Sets various TaoLineSearch parameters from user
488:   options.

490:   Collective on TaoLineSearch

492:   Input Paremeter:
493: . ls - the TaoLineSearch context

495:   Options Database Keys:
496: + -tao_ls_type <type> - The algorithm that TAO uses (more-thuente, gpcg, unit)
497: . -tao_ls_ftol <tol> - tolerance for sufficient decrease
498: . -tao_ls_gtol <tol> - tolerance for curvature condition
499: . -tao_ls_rtol <tol> - relative tolerance for acceptable step
500: . -tao_ls_stepmin <step> - minimum steplength allowed
501: . -tao_ls_stepmax <step> - maximum steplength allowed
502: . -tao_ls_max_funcs <n> - maximum number of function evaluations allowed
503: - -tao_ls_view - display line-search results to standard output

505:   Level: beginner
506: @*/
507: PetscErrorCode TaoLineSearchSetFromOptions(TaoLineSearch ls)
508: {
510:   const char     *default_type=TAOLINESEARCHMT;
511:   char           type[256];
512:   PetscBool      flg;

516:   PetscObjectOptionsBegin((PetscObject)ls);
517:   if (!TaoLineSearchInitialized) {
518:     TaoLineSearchInitializePackage();
519:   }
520:   if (((PetscObject)ls)->type_name) {
521:     default_type = ((PetscObject)ls)->type_name;
522:   }
523:   /* Check for type from options */
524:   PetscOptionsFList("-tao_ls_type","Tao Line Search type","TaoLineSearchSetType",TaoLineSearchList,default_type,type,256,&flg);
525:   if (flg) {
526:     TaoLineSearchSetType(ls,type);
527:   } else if (!((PetscObject)ls)->type_name) {
528:     TaoLineSearchSetType(ls,default_type);
529:   }

531:   PetscOptionsInt("-tao_ls_max_funcs","max function evals in line search","",ls->max_funcs,&ls->max_funcs,NULL);
532:   PetscOptionsReal("-tao_ls_ftol","tol for sufficient decrease","",ls->ftol,&ls->ftol,NULL);
533:   PetscOptionsReal("-tao_ls_gtol","tol for curvature condition","",ls->gtol,&ls->gtol,NULL);
534:   PetscOptionsReal("-tao_ls_rtol","relative tol for acceptable step","",ls->rtol,&ls->rtol,NULL);
535:   PetscOptionsReal("-tao_ls_stepmin","lower bound for step","",ls->stepmin,&ls->stepmin,NULL);
536:   PetscOptionsReal("-tao_ls_stepmax","upper bound for step","",ls->stepmax,&ls->stepmax,NULL);
537:   if (ls->ops->setfromoptions) {
538:     (*ls->ops->setfromoptions)(PetscOptionsObject,ls);
539:   }
540:   PetscOptionsEnd();
541:   return(0);
542: }

546: /*@C
547:   TaoLineSearchGetType - Gets the current line search algorithm

549:   Not Collective

551:   Input Parameter:
552: . ls - the TaoLineSearch context

554:   Output Paramter:
555: . type - the line search algorithm in effect

557:   Level: developer

559: @*/
560: PetscErrorCode TaoLineSearchGetType(TaoLineSearch ls, const TaoLineSearchType *type)
561: {
565:   *type = ((PetscObject)ls)->type_name;
566:   return(0);
567: }

571: /*@
572:   TaoLineSearchGetNumberFunctionEvaluations - Gets the number of function and gradient evaluation
573:   routines used by the line search in last application (not cumulative).

575:   Not Collective

577:   Input Parameter:
578: . ls - the TaoLineSearch context

580:   Output Parameters:
581: + nfeval   - number of function evaluations
582: . ngeval   - number of gradient evaluations
583: - nfgeval  - number of function/gradient evaluations

585:   Level: intermediate

587:   Note:
588:   If the line search is using the Tao objective and gradient
589:   routines directly (see TaoLineSearchUseTaoRoutines()), then TAO
590:   is already counting the number of evaluations.

592: @*/
593: PetscErrorCode TaoLineSearchGetNumberFunctionEvaluations(TaoLineSearch ls, PetscInt *nfeval, PetscInt *ngeval, PetscInt *nfgeval)
594: {
597:   *nfeval = ls->nfeval;
598:   *ngeval = ls->ngeval;
599:   *nfgeval = ls->nfgeval;
600:   return(0);
601: }

605: /*@
606:   TaoLineSearchIsUsingTaoRoutines - Checks whether the line search is using
607:   Tao evaluation routines.

609:   Not Collective

611:   Input Parameter:
612: . ls - the TaoLineSearch context

614:   Output Parameter:
615: . flg - PETSC_TRUE if the line search is using Tao evaluation routines,
616:         otherwise PETSC_FALSE

618:   Level: developer
619: @*/
620: PetscErrorCode TaoLineSearchIsUsingTaoRoutines(TaoLineSearch ls, PetscBool *flg)
621: {
624:   *flg = ls->usetaoroutines;
625:   return(0);
626: }

630: /*@C
631:   TaoLineSearchSetObjectiveRoutine - Sets the function evaluation routine for the line search

633:   Logically Collective on TaoLineSearch

635:   Input Parameter:
636: + ls - the TaoLineSearch context
637: . func - the objective function evaluation routine
638: - ctx - the (optional) user-defined context for private data

640:   Calling sequence of func:
641: $      func (TaoLinesearch ls, Vec x, PetscReal *f, void *ctx);

643: + x - input vector
644: . f - function value
645: - ctx (optional) user-defined context

647:   Level: beginner

649:   Note:
650:   Use this routine only if you want the line search objective
651:   evaluation routine to be different from the Tao's objective
652:   evaluation routine. If you use this routine you must also set
653:   the line search gradient and/or function/gradient routine.

655:   Note:
656:   Some algorithms (lcl, gpcg) set their own objective routine for the
657:   line search, application programmers should be wary of overriding the
658:   default objective routine.

660: .seealso: TaoLineSearchCreate(), TaoLineSearchSetGradientRoutine(), TaoLineSearchSetObjectiveAndGradientRoutine(), TaoLineSearchUseTaoRoutines()
661: @*/
662: PetscErrorCode TaoLineSearchSetObjectiveRoutine(TaoLineSearch ls, PetscErrorCode(*func)(TaoLineSearch ls, Vec x, PetscReal*, void*), void *ctx)
663: {

667:   ls->ops->computeobjective=func;
668:   if (ctx) ls->userctx_func=ctx;
669:   ls->usetaoroutines=PETSC_FALSE;
670:   return(0);
671: }

675: /*@C
676:   TaoLineSearchSetGradientRoutine - Sets the gradient evaluation routine for the line search

678:   Logically Collective on TaoLineSearch

680:   Input Parameter:
681: + ls - the TaoLineSearch context
682: . func - the gradient evaluation routine
683: - ctx - the (optional) user-defined context for private data

685:   Calling sequence of func:
686: $      func (TaoLinesearch ls, Vec x, Vec g, void *ctx);

688: + x - input vector
689: . g - gradient vector
690: - ctx (optional) user-defined context

692:   Level: beginner

694:   Note:
695:   Use this routine only if you want the line search gradient
696:   evaluation routine to be different from the Tao's gradient
697:   evaluation routine. If you use this routine you must also set
698:   the line search function and/or function/gradient routine.

700:   Note:
701:   Some algorithms (lcl, gpcg) set their own gradient routine for the
702:   line search, application programmers should be wary of overriding the
703:   default gradient routine.

705: .seealso: TaoLineSearchCreate(), TaoLineSearchSetObjectiveRoutine(), TaoLineSearchSetObjectiveAndGradientRoutine(), TaoLineSearchUseTaoRoutines()
706: @*/
707: PetscErrorCode TaoLineSearchSetGradientRoutine(TaoLineSearch ls, PetscErrorCode(*func)(TaoLineSearch ls, Vec x, Vec g, void*), void *ctx)
708: {
711:   ls->ops->computegradient=func;
712:   if (ctx) ls->userctx_grad=ctx;
713:   ls->usetaoroutines=PETSC_FALSE;
714:   return(0);
715: }

719: /*@C
720:   TaoLineSearchSetObjectiveAndGradientRoutine - Sets the objective/gradient evaluation routine for the line search

722:   Logically Collective on TaoLineSearch

724:   Input Parameter:
725: + ls - the TaoLineSearch context
726: . func - the objective and gradient evaluation routine
727: - ctx - the (optional) user-defined context for private data

729:   Calling sequence of func:
730: $      func (TaoLinesearch ls, Vec x, PetscReal *f, Vec g, void *ctx);

732: + x - input vector
733: . f - function value
734: . g - gradient vector
735: - ctx (optional) user-defined context

737:   Level: beginner

739:   Note:
740:   Use this routine only if you want the line search objective and gradient
741:   evaluation routines to be different from the Tao's objective
742:   and gradient evaluation routines.

744:   Note:
745:   Some algorithms (lcl, gpcg) set their own objective routine for the
746:   line search, application programmers should be wary of overriding the
747:   default objective routine.

749: .seealso: TaoLineSearchCreate(), TaoLineSearchSetObjectiveRoutine(), TaoLineSearchSetGradientRoutine(), TaoLineSearchUseTaoRoutines()
750: @*/
751: PetscErrorCode TaoLineSearchSetObjectiveAndGradientRoutine(TaoLineSearch ls, PetscErrorCode(*func)(TaoLineSearch ls, Vec x, PetscReal *, Vec g, void*), void *ctx)
752: {
755:   ls->ops->computeobjectiveandgradient=func;
756:   if (ctx) ls->userctx_funcgrad=ctx;
757:   ls->usetaoroutines = PETSC_FALSE;
758:   return(0);
759: }

763: /*@C
764:   TaoLineSearchSetObjectiveAndGTSRoutine - Sets the objective and
765:   (gradient'*stepdirection) evaluation routine for the line search.
766:   Sometimes it is more efficient to compute the inner product of the gradient
767:   and the step direction than it is to compute the gradient, and this is all
768:   the line search typically needs of the gradient.

770:   Logically Collective on TaoLineSearch

772:   Input Parameter:
773: + ls - the TaoLineSearch context
774: . func - the objective and gradient evaluation routine
775: - ctx - the (optional) user-defined context for private data

777:   Calling sequence of func:
778: $      func (TaoLinesearch ls, Vec x, PetscReal *f, PetscReal *gts, void *ctx);

780: + x - input vector
781: . s - step direction
782: . f - function value
783: . gts - inner product of gradient and step direction vectors
784: - ctx (optional) user-defined context

786:   Note: The gradient will still need to be computed at the end of the line
787:   search, so you will still need to set a line search gradient evaluation
788:   routine

790:   Note: Bounded line searches (those used in bounded optimization algorithms)
791:   don't use g's directly, but rather (g'x - g'x0)/steplength.  You can get the
792:   x0 and steplength with TaoLineSearchGetStartingVector() and TaoLineSearchGetStepLength()

794:   Level: advanced

796:   Note:
797:   Some algorithms (lcl, gpcg) set their own objective routine for the
798:   line search, application programmers should be wary of overriding the
799:   default objective routine.

801: .seealso: TaoLineSearchCreate(), TaoLineSearchSetObjective(), TaoLineSearchSetGradient(), TaoLineSearchUseTaoRoutines()
802: @*/
803: PetscErrorCode TaoLineSearchSetObjectiveAndGTSRoutine(TaoLineSearch ls, PetscErrorCode(*func)(TaoLineSearch ls, Vec x, Vec s, PetscReal *, PetscReal *, void*), void *ctx)
804: {
807:   ls->ops->computeobjectiveandgts=func;
808:   if (ctx) ls->userctx_funcgts=ctx;
809:   ls->usegts = PETSC_TRUE;
810:   ls->usetaoroutines=PETSC_FALSE;
811:   return(0);
812: }

816: /*@C
817:   TaoLineSearchUseTaoRoutines - Informs the TaoLineSearch to use the
818:   objective and gradient evaluation routines from the given Tao object.

820:   Logically Collective on TaoLineSearch

822:   Input Parameter:
823: + ls - the TaoLineSearch context
824: - ts - the Tao context with defined objective/gradient evaluation routines

826:   Level: developer

828: .seealso: TaoLineSearchCreate()
829: @*/
830: PetscErrorCode TaoLineSearchUseTaoRoutines(TaoLineSearch ls, Tao ts)
831: {
835:   ls->tao = ts;
836:   ls->usetaoroutines=PETSC_TRUE;
837:   return(0);
838: }

842: /*@
843:   TaoLineSearchComputeObjective - Computes the objective function value at a given point

845:   Collective on TaoLineSearch

847:   Input Parameters:
848: + ls - the TaoLineSearch context
849: - x - input vector

851:   Output Parameter:
852: . f - Objective value at X

854:   Notes: TaoLineSearchComputeObjective() is typically used within line searches
855:   so most users would not generally call this routine themselves.

857:   Level: developer

859: .seealso: TaoLineSearchComputeGradient(), TaoLineSearchComputeObjectiveAndGradient(), TaoLineSearchSetObjectiveRoutine()
860: @*/
861: PetscErrorCode TaoLineSearchComputeObjective(TaoLineSearch ls, Vec x, PetscReal *f)
862: {
864:   Vec            gdummy;
865:   PetscReal      gts;

872:   if (ls->usetaoroutines) {
873:     TaoComputeObjective(ls->tao,x,f);
874:   } else {
875:     PetscLogEventBegin(TaoLineSearch_EvalEvent,ls,0,0,0);
876:     if (!ls->ops->computeobjective && !ls->ops->computeobjectiveandgradient && !ls->ops->computeobjectiveandgts) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search does not have objective function set");
877:     PetscStackPush("TaoLineSearch user objective routine");
878:     if (ls->ops->computeobjective) {
879:       (*ls->ops->computeobjective)(ls,x,f,ls->userctx_func);
880:     } else if (ls->ops->computeobjectiveandgradient) {
881:       VecDuplicate(x,&gdummy);
882:       (*ls->ops->computeobjectiveandgradient)(ls,x,f,gdummy,ls->userctx_funcgrad);
883:       VecDestroy(&gdummy);
884:     } else {
885:       (*ls->ops->computeobjectiveandgts)(ls,x,ls->stepdirection,f,&gts,ls->userctx_funcgts);
886:     }
887:     PetscStackPop;
888:     PetscLogEventEnd(TaoLineSearch_EvalEvent,ls,0,0,0);
889:   }
890:   ls->nfeval++;
891:   return(0);
892: }

896: /*@
897:   TaoLineSearchComputeObjectiveAndGradient - Computes the objective function value at a given point

899:   Collective on Tao

901:   Input Parameters:
902: + ls - the TaoLineSearch context
903: - x - input vector

905:   Output Parameter:
906: + f - Objective value at X
907: - g - Gradient vector at X

909:   Notes: TaoLineSearchComputeObjectiveAndGradient() is typically used within line searches
910:   so most users would not generally call this routine themselves.

912:   Level: developer

914: .seealso: TaoLineSearchComputeGradient(), TaoLineSearchComputeObjectiveAndGradient(), TaoLineSearchSetObjectiveRoutine()
915: @*/
916: PetscErrorCode TaoLineSearchComputeObjectiveAndGradient(TaoLineSearch ls, Vec x, PetscReal *f, Vec g)
917: {

927:   if (ls->usetaoroutines) {
928:       TaoComputeObjectiveAndGradient(ls->tao,x,f,g);
929:   } else {
930:     PetscLogEventBegin(TaoLineSearch_EvalEvent,ls,0,0,0);
931:     if (!ls->ops->computeobjective && !ls->ops->computeobjectiveandgradient) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search does not have objective function set");
932:     if (!ls->ops->computegradient && !ls->ops->computeobjectiveandgradient) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search does not have gradient function set");

934:     PetscStackPush("TaoLineSearch user objective/gradient routine");
935:     if (ls->ops->computeobjectiveandgradient) {
936:       (*ls->ops->computeobjectiveandgradient)(ls,x,f,g,ls->userctx_funcgrad);
937:     } else {
938:       (*ls->ops->computeobjective)(ls,x,f,ls->userctx_func);
939:       (*ls->ops->computegradient)(ls,x,g,ls->userctx_grad);
940:     }
941:     PetscStackPop;
942:     PetscLogEventEnd(TaoLineSearch_EvalEvent,ls,0,0,0);
943:     PetscInfo1(ls,"TaoLineSearch Function evaluation: %14.12e\n",(double)(*f));
944:   }
945:   ls->nfgeval++;
946:   return(0);
947: }

951: /*@
952:   TaoLineSearchComputeGradient - Computes the gradient of the objective function

954:   Collective on TaoLineSearch

956:   Input Parameters:
957: + ls - the TaoLineSearch context
958: - x - input vector

960:   Output Parameter:
961: . g - gradient vector

963:   Notes: TaoComputeGradient() is typically used within line searches
964:   so most users would not generally call this routine themselves.

966:   Level: developer

968: .seealso: TaoLineSearchComputeObjective(), TaoLineSearchComputeObjectiveAndGradient(), TaoLineSearchSetGradient()
969: @*/
970: PetscErrorCode TaoLineSearchComputeGradient(TaoLineSearch ls, Vec x, Vec g)
971: {
973:   PetscReal      fdummy;

981:   if (ls->usetaoroutines) {
982:     TaoComputeGradient(ls->tao,x,g);
983:   } else {
984:     PetscLogEventBegin(TaoLineSearch_EvalEvent,ls,0,0,0);
985:     if (!ls->ops->computegradient && !ls->ops->computeobjectiveandgradient) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search does not have gradient functions set");
986:     PetscStackPush("TaoLineSearch user gradient routine");
987:     if (ls->ops->computegradient) {
988:       (*ls->ops->computegradient)(ls,x,g,ls->userctx_grad);
989:     } else {
990:       (*ls->ops->computeobjectiveandgradient)(ls,x,&fdummy,g,ls->userctx_funcgrad);
991:     }
992:     PetscStackPop;
993:     PetscLogEventEnd(TaoLineSearch_EvalEvent,ls,0,0,0);
994:   }
995:   ls->ngeval++;
996:   return(0);
997: }

1001: /*@
1002:   TaoLineSearchComputeObjectiveAndGTS - Computes the objective function value and inner product of gradient and step direction at a given point

1004:   Collective on Tao

1006:   Input Parameters:
1007: + ls - the TaoLineSearch context
1008: - x - input vector

1010:   Output Parameter:
1011: + f - Objective value at X
1012: - gts - inner product of gradient and step direction at X

1014:   Notes: TaoLineSearchComputeObjectiveAndGTS() is typically used within line searches
1015:   so most users would not generally call this routine themselves.

1017:   Level: developer

1019: .seealso: TaoLineSearchComputeGradient(), TaoLineSearchComputeObjectiveAndGradient(), TaoLineSearchSetObjectiveRoutine()
1020: @*/
1021: PetscErrorCode TaoLineSearchComputeObjectiveAndGTS(TaoLineSearch ls, Vec x, PetscReal *f, PetscReal *gts)
1022: {
1030:   PetscLogEventBegin(TaoLineSearch_EvalEvent,ls,0,0,0);
1031:   if (!ls->ops->computeobjectiveandgts) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Line Search does not have objective and gts function set");
1032:   PetscStackPush("TaoLineSearch user objective/gts routine");
1033:   (*ls->ops->computeobjectiveandgts)(ls,x,ls->stepdirection,f,gts,ls->userctx_funcgts);
1034:   PetscStackPop;
1035:   PetscLogEventEnd(TaoLineSearch_EvalEvent,ls,0,0,0);
1036:   PetscInfo1(ls,"TaoLineSearch Function evaluation: %14.12e\n",(double)(*f));
1037:   ls->nfeval++;
1038:   return(0);
1039: }

1043: /*@
1044:   TaoLineSearchGetSolution - Returns the solution to the line search

1046:   Collective on TaoLineSearch

1048:   Input Parameter:
1049: . ls - the TaoLineSearch context

1051:   Output Parameter:
1052: + x - the new solution
1053: . f - the objective function value at x
1054: . g - the gradient at x
1055: . steplength - the multiple of the step direction taken by the line search
1056: - reason - the reason why the line search terminated

1058:   reason will be set to one of:

1060: + TAOLINESEARCH_FAILED_INFORNAN - function evaluation gives Inf or Nan value
1061: . TAOLINESEARCH_FAILED_BADPARAMETER - negative value set as parameter
1062: . TAOLINESEARCH_FAILED_ASCENT - initial line search step * g is not descent direction
1063: . TAOLINESEARCH_HALTED_MAXFCN - maximum number of function evaluation reached
1064: . TAOLINESEARCH_HALTED_UPPERBOUND - step is at upper bound
1065: . TAOLINESEARCH_HALTED_LOWERBOUND - step is at lower bound
1066: . TAOLINESEARCH_HALTED_RTOL - range of uncertainty is smaller than given tolerance

1068: . TAOLINESEARCH_HALTED_USER - user can set this reason to stop line search
1069: . TAOLINESEARCH_HALTED_OTHER - any other reason

1071: + TAOLINESEARCH_SUCCESS - successful line search

1073:   Level: developer

1075: @*/
1076: PetscErrorCode TaoLineSearchGetSolution(TaoLineSearch ls, Vec x, PetscReal *f, Vec g, PetscReal *steplength, TaoLineSearchConvergedReason *reason)
1077: {

1086:   if (ls->new_x) {
1087:     VecCopy(ls->new_x,x);
1088:   }
1089:   *f = ls->new_f;
1090:   if (ls->new_g) {
1091:     VecCopy(ls->new_g,g);
1092:   }
1093:   if (steplength) {
1094:     *steplength=ls->step;
1095:   }
1096:   *reason = ls->reason;
1097:   return(0);
1098: }

1102: /*@
1103:   TaoLineSearchGetStartingVector - Gets a the initial point of the line
1104:   search.

1106:   Not Collective

1108:   Input Parameter:
1109: . ls - the TaoLineSearch context

1111:   Output Parameter:
1112: . x - The initial point of the line search

1114:   Level: intermediate
1115: @*/
1116: PetscErrorCode TaoLineSearchGetStartingVector(TaoLineSearch ls, Vec *x)
1117: {
1120:   if (x) {
1121:     *x = ls->start_x;
1122:   }
1123:   return(0);
1124: }

1128: /*@
1129:   TaoLineSearchGetStepDirection - Gets the step direction of the line
1130:   search.

1132:   Not Collective

1134:   Input Parameter:
1135: . ls - the TaoLineSearch context

1137:   Output Parameter:
1138: . s - the step direction of the line search

1140:   Level: advanced
1141: @*/
1142: PetscErrorCode TaoLineSearchGetStepDirection(TaoLineSearch ls, Vec *s)
1143: {
1146:   if (s) {
1147:     *s = ls->stepdirection;
1148:   }
1149:   return(0);

1151: }

1155: /*@
1156:   TaoLineSearchGetFullStepObjective - Returns the objective function value at the full step.  Useful for some minimization algorithms.

1158:   Not Collective

1160:   Input Parameter:
1161: . ls - the TaoLineSearch context

1163:   Output Parameter:
1164: . f - the objective value at the full step length

1166:   Level: developer
1167: @*/

1169: PetscErrorCode TaoLineSearchGetFullStepObjective(TaoLineSearch ls, PetscReal *f_fullstep)
1170: {
1173:   *f_fullstep = ls->f_fullstep;
1174:   return(0);
1175: }

1179: /*@
1180:   TaoLineSearchSetVariableBounds - Sets the upper and lower bounds.

1182:   Logically Collective on Tao

1184:   Input Parameters:
1185: + ls - the TaoLineSearch context
1186: . xl  - vector of lower bounds
1187: - xu  - vector of upper bounds

1189:   Note: If the variable bounds are not set with this routine, then
1190:   PETSC_NINFINITY and PETSC_INFINITY are assumed

1192:   Level: beginner

1194: .seealso: TaoSetVariableBounds(), TaoLineSearchCreate()
1195: @*/
1196: PetscErrorCode TaoLineSearchSetVariableBounds(TaoLineSearch ls,Vec xl, Vec xu)
1197: {
1202:   ls->lower = xl;
1203:   ls->upper = xu;
1204:   ls->bounded = 1;
1205:   return(0);
1206: }

1210: /*@
1211:   TaoLineSearchSetInitialStepLength - Sets the initial step length of a line
1212:   search.  If this value is not set then 1.0 is assumed.

1214:   Logically Collective on TaoLineSearch

1216:   Input Parameters:
1217: + ls - the TaoLineSearch context
1218: - s - the initial step size

1220:   Level: intermediate

1222: .seealso: TaoLineSearchGetStepLength(), TaoLineSearchApply()
1223: @*/
1224: PetscErrorCode TaoLineSearchSetInitialStepLength(TaoLineSearch ls,PetscReal s)
1225: {
1228:   ls->initstep = s;
1229:   return(0);
1230: }

1234: /*@
1235:   TaoLineSearchGetStepLength - Get the current step length

1237:   Not Collective

1239:   Input Parameters:
1240: . ls - the TaoLineSearch context

1242:   Output Parameters
1243: . s - the current step length

1245:   Level: beginner

1247: .seealso: TaoLineSearchSetInitialStepLength(), TaoLineSearchApply()
1248: @*/
1249: PetscErrorCode TaoLineSearchGetStepLength(TaoLineSearch ls,PetscReal *s)
1250: {
1253:   *s = ls->step;
1254:   return(0);
1255: }

1259: /*MC
1260:    TaoLineSearchRegister - Adds a line-search algorithm to the registry

1262:    Not collective

1264:    Input Parameters:
1265: +  sname - name of a new user-defined solver
1266: -  func - routine to Create method context

1268:    Notes:
1269:    TaoLineSearchRegister() may be called multiple times to add several user-defined solvers.

1271:    Sample usage:
1272: .vb
1273:    TaoLineSearchRegister("my_linesearch",MyLinesearchCreate);
1274: .ve

1276:    Then, your solver can be chosen with the procedural interface via
1277: $     TaoLineSearchSetType(ls,"my_linesearch")
1278:    or at runtime via the option
1279: $     -tao_ls_type my_linesearch

1281:    Level: developer

1283: .seealso: TaoLineSearchRegisterDestroy()
1284: M*/
1285: PetscErrorCode TaoLineSearchRegister(const char sname[], PetscErrorCode (*func)(TaoLineSearch))
1286: {
1289:   PetscFunctionListAdd(&TaoLineSearchList, sname, (void (*)(void))func);
1290:   return(0);
1291: }

1295: /*@C
1296:    TaoLineSearchRegisterDestroy - Frees the list of line-search algorithms that were
1297:    registered by TaoLineSearchRegister().

1299:    Not Collective

1301:    Level: developer

1303: .seealso: TaoLineSearchRegister()
1304: @*/
1305: PetscErrorCode TaoLineSearchRegisterDestroy(void)
1306: {
1309:   PetscFunctionListDestroy(&TaoLineSearchList);
1310:   TaoLineSearchInitialized = PETSC_FALSE;
1311:   return(0);
1312: }

1316: /*@C
1317:    TaoLineSearchAppendOptionsPrefix - Appends to the prefix used for searching
1318:    for all TaoLineSearch options in the database.


1321:    Collective on TaoLineSearch

1323:    Input Parameters:
1324: +  ls - the TaoLineSearch solver context
1325: -  prefix - the prefix string to prepend to all line search requests

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


1332:    Level: advanced

1334: .seealso: TaoLineSearchSetOptionsPrefix(), TaoLineSearchGetOptionsPrefix()
1335: @*/
1336: PetscErrorCode TaoLineSearchAppendOptionsPrefix(TaoLineSearch ls, const char p[])
1337: {
1338:   return PetscObjectAppendOptionsPrefix((PetscObject)ls,p);
1339: }

1343: /*@C
1344:   TaoLineSearchGetOptionsPrefix - Gets the prefix used for searching for all
1345:   TaoLineSearch options in the database

1347:   Not Collective

1349:   Input Parameters:
1350: . ls - the TaoLineSearch context

1352:   Output Parameters:
1353: . prefix - pointer to the prefix string used is returned

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

1358:   Level: advanced

1360: .seealso: TaoLineSearchSetOptionsPrefix(), TaoLineSearchAppendOptionsPrefix()
1361: @*/
1362: PetscErrorCode TaoLineSearchGetOptionsPrefix(TaoLineSearch ls, const char *p[])
1363: {
1364:   return PetscObjectGetOptionsPrefix((PetscObject)ls,p);
1365: }

1369: /*@C
1370:    TaoLineSearchSetOptionsPrefix - Sets the prefix used for searching for all
1371:    TaoLineSearch options in the database.


1374:    Logically Collective on TaoLineSearch

1376:    Input Parameters:
1377: +  ls - the TaoLineSearch context
1378: -  prefix - the prefix string to prepend to all TAO option requests

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

1384:    For example, to distinguish between the runtime options for two
1385:    different line searches, one could call
1386: .vb
1387:       TaoLineSearchSetOptionsPrefix(ls1,"sys1_")
1388:       TaoLineSearchSetOptionsPrefix(ls2,"sys2_")
1389: .ve

1391:    This would enable use of different options for each system, such as
1392: .vb
1393:       -sys1_tao_ls_type mt
1394:       -sys2_tao_ls_type armijo
1395: .ve

1397:    Level: advanced

1399: .seealso: TaoLineSearchAppendOptionsPrefix(), TaoLineSearchGetOptionsPrefix()
1400: @*/

1402: PetscErrorCode TaoLineSearchSetOptionsPrefix(TaoLineSearch ls, const char p[])
1403: {
1404:   return PetscObjectSetOptionsPrefix((PetscObject)ls,p);
1405: }