Actual source code: taolinesearch.c

  1: #include <petsctaolinesearch.h>
  2: #include <petsc/private/taolinesearchimpl.h>

  4: PetscFunctionList TaoLineSearchList = NULL;

  6: PetscClassId TAOLINESEARCH_CLASSID = 0;

  8: PetscLogEvent TAOLINESEARCH_Apply;
  9: PetscLogEvent TAOLINESEARCH_Eval;

 11: /*@C
 12:    TaoLineSearchViewFromOptions - View a `TaoLineSearch` object based on values in the options database

 14:    Collective

 16:    Input Parameters:
 17: +  A - the `Tao` context
 18: .  obj - Optional object
 19: -  name - command line option

 21:    Level: intermediate

 23:    Note:
 24:    See `PetscObjectViewFromOptions()` for available viewer options

 26: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchView()`, `PetscObjectViewFromOptions()`, `TaoLineSearchCreate()`
 27: @*/
 28: PetscErrorCode TaoLineSearchViewFromOptions(TaoLineSearch A, PetscObject obj, const char name[])
 29: {
 30:   PetscFunctionBegin;
 32:   PetscCall(PetscObjectViewFromOptions((PetscObject)A, obj, name));
 33:   PetscFunctionReturn(PETSC_SUCCESS);
 34: }

 36: /*@C
 37:   TaoLineSearchView - Prints information about the `TaoLineSearch`

 39:   Collective

 41:   InputParameters:
 42: + ls - the `TaoLineSearch` context
 43: - viewer - visualization context

 45:   Options Database Key:
 46: . -tao_ls_view - Calls `TaoLineSearchView()` at the end of each line search

 48:   Level: beginner

 50:   Notes:
 51:   The available visualization contexts include
 52: +     `PETSC_VIEWER_STDOUT_SELF` - standard output (default)
 53: -     `PETSC_VIEWER_STDOUT_WORLD` - synchronized standard
 54:          output where only the first processor opens
 55:          the file.  All other processors send their
 56:          data to the first processor to print.

 58: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `PetscViewerASCIIOpen()`, `TaoLineSearchViewFromOptions()`
 59: @*/
 60: PetscErrorCode TaoLineSearchView(TaoLineSearch ls, PetscViewer viewer)
 61: {
 62:   PetscBool         isascii, isstring;
 63:   TaoLineSearchType type;

 65:   PetscFunctionBegin;
 67:   if (!viewer) PetscCall(PetscViewerASCIIGetStdout(((PetscObject)ls)->comm, &viewer));
 69:   PetscCheckSameComm(ls, 1, viewer, 2);

 71:   PetscCall(PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &isascii));
 72:   PetscCall(PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERSTRING, &isstring));
 73:   if (isascii) {
 74:     PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)ls, viewer));
 75:     PetscCall(PetscViewerASCIIPushTab(viewer));
 76:     PetscTryTypeMethod(ls, view, viewer);
 77:     PetscCall(PetscViewerASCIIPopTab(viewer));
 78:     PetscCall(PetscViewerASCIIPushTab(viewer));
 79:     PetscCall(PetscViewerASCIIPrintf(viewer, "maximum function evaluations=%" PetscInt_FMT "\n", ls->max_funcs));
 80:     PetscCall(PetscViewerASCIIPrintf(viewer, "tolerances: ftol=%g, rtol=%g, gtol=%g\n", (double)ls->ftol, (double)ls->rtol, (double)ls->gtol));
 81:     PetscCall(PetscViewerASCIIPrintf(viewer, "total number of function evaluations=%" PetscInt_FMT "\n", ls->nfeval));
 82:     PetscCall(PetscViewerASCIIPrintf(viewer, "total number of gradient evaluations=%" PetscInt_FMT "\n", ls->ngeval));
 83:     PetscCall(PetscViewerASCIIPrintf(viewer, "total number of function/gradient evaluations=%" PetscInt_FMT "\n", ls->nfgeval));

 85:     if (ls->bounded) PetscCall(PetscViewerASCIIPrintf(viewer, "using variable bounds\n"));
 86:     PetscCall(PetscViewerASCIIPrintf(viewer, "Termination reason: %d\n", (int)ls->reason));
 87:     PetscCall(PetscViewerASCIIPopTab(viewer));
 88:   } else if (isstring) {
 89:     PetscCall(TaoLineSearchGetType(ls, &type));
 90:     PetscCall(PetscViewerStringSPrintf(viewer, " %-3.3s", type));
 91:   }
 92:   PetscFunctionReturn(PETSC_SUCCESS);
 93: }

 95: /*@C
 96:   TaoLineSearchCreate - Creates a `TaoLineSearch` object.  Algorithms in `Tao` that use
 97:   line-searches will automatically create one so this all is rarely needed

 99:   Collective

101:   Input Parameter:
102: . comm - MPI communicator

104:   Output Parameter:
105: . newls - the new `TaoLineSearch` context

107:    Options Database Key:
108: .   -tao_ls_type - select which method `Tao` should use

110:    Level: developer

112: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchType`, `TaoLineSearchSetType()`, `TaoLineSearchApply()`, `TaoLineSearchDestroy()`
113: @*/
114: PetscErrorCode TaoLineSearchCreate(MPI_Comm comm, TaoLineSearch *newls)
115: {
116:   TaoLineSearch ls;

118:   PetscFunctionBegin;
120:   PetscCall(TaoLineSearchInitializePackage());

122:   PetscCall(PetscHeaderCreate(ls, TAOLINESEARCH_CLASSID, "TaoLineSearch", "Linesearch", "Tao", comm, TaoLineSearchDestroy, TaoLineSearchView));
123:   ls->max_funcs = 30;
124:   ls->ftol      = 0.0001;
125:   ls->gtol      = 0.9;
126: #if defined(PETSC_USE_REAL_SINGLE)
127:   ls->rtol = 1.0e-5;
128: #else
129:   ls->rtol = 1.0e-10;
130: #endif
131:   ls->stepmin  = 1.0e-20;
132:   ls->stepmax  = 1.0e+20;
133:   ls->step     = 1.0;
134:   ls->initstep = 1.0;
135:   *newls       = ls;
136:   PetscFunctionReturn(PETSC_SUCCESS);
137: }

139: /*@
140:   TaoLineSearchSetUp - Sets up the internal data structures for the later use
141:   of a `TaoLineSearch`

143:   Collective

145:   Input Parameter:
146: . ls - the `TaoLineSearch` context

148:   Level: developer

150:   Note:
151:   The user will not need to explicitly call `TaoLineSearchSetUp()`, as it will
152:   automatically be called in `TaoLineSearchSolve()`.  However, if the user
153:   desires to call it explicitly, it should come after `TaoLineSearchCreate()`
154:   but before `TaoLineSearchApply()`.

156: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchApply()`
157: @*/
158: PetscErrorCode TaoLineSearchSetUp(TaoLineSearch ls)
159: {
160:   const char *default_type = TAOLINESEARCHMT;
161:   PetscBool   flg;

163:   PetscFunctionBegin;
165:   if (ls->setupcalled) PetscFunctionReturn(PETSC_SUCCESS);
166:   if (!((PetscObject)ls)->type_name) PetscCall(TaoLineSearchSetType(ls, default_type));
167:   PetscTryTypeMethod(ls, setup);
168:   if (ls->usetaoroutines) {
169:     PetscCall(TaoIsObjectiveDefined(ls->tao, &flg));
170:     ls->hasobjective = flg;
171:     PetscCall(TaoIsGradientDefined(ls->tao, &flg));
172:     ls->hasgradient = flg;
173:     PetscCall(TaoIsObjectiveAndGradientDefined(ls->tao, &flg));
174:     ls->hasobjectiveandgradient = flg;
175:   } else {
176:     if (ls->ops->computeobjective) {
177:       ls->hasobjective = PETSC_TRUE;
178:     } else {
179:       ls->hasobjective = PETSC_FALSE;
180:     }
181:     if (ls->ops->computegradient) {
182:       ls->hasgradient = PETSC_TRUE;
183:     } else {
184:       ls->hasgradient = PETSC_FALSE;
185:     }
186:     if (ls->ops->computeobjectiveandgradient) {
187:       ls->hasobjectiveandgradient = PETSC_TRUE;
188:     } else {
189:       ls->hasobjectiveandgradient = PETSC_FALSE;
190:     }
191:   }
192:   ls->setupcalled = PETSC_TRUE;
193:   PetscFunctionReturn(PETSC_SUCCESS);
194: }

196: /*@
197:   TaoLineSearchReset - Some line searches may carry state information
198:   from one `TaoLineSearchApply()` to the next.  This function resets this
199:   state information.

201:   Collective

203:   Input Parameter:
204: . ls - the `TaoLineSearch` context

206:   Level: developer

208: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchApply()`
209: @*/
210: PetscErrorCode TaoLineSearchReset(TaoLineSearch ls)
211: {
212:   PetscFunctionBegin;
214:   PetscTryTypeMethod(ls, reset);
215:   PetscFunctionReturn(PETSC_SUCCESS);
216: }

218: /*@
219:   TaoLineSearchDestroy - Destroys the `TaoLineSearch` context that was created with
220:   `TaoLineSearchCreate()`

222:   Collective

224:   Input Parameter:
225: . ls - the `TaoLineSearch` context

227:   Level: developer

229: .seealse: `TaoLineSearchCreate()`, `TaoLineSearchSolve()`
230: @*/
231: PetscErrorCode TaoLineSearchDestroy(TaoLineSearch *ls)
232: {
233:   PetscFunctionBegin;
234:   if (!*ls) PetscFunctionReturn(PETSC_SUCCESS);
236:   if (--((PetscObject)*ls)->refct > 0) {
237:     *ls = NULL;
238:     PetscFunctionReturn(PETSC_SUCCESS);
239:   }
240:   PetscCall(VecDestroy(&(*ls)->stepdirection));
241:   PetscCall(VecDestroy(&(*ls)->start_x));
242:   PetscCall(VecDestroy(&(*ls)->upper));
243:   PetscCall(VecDestroy(&(*ls)->lower));
244:   if ((*ls)->ops->destroy) PetscCall((*(*ls)->ops->destroy)(*ls));
245:   if ((*ls)->usemonitor) PetscCall(PetscViewerDestroy(&(*ls)->viewer));
246:   PetscCall(PetscHeaderDestroy(ls));
247:   PetscFunctionReturn(PETSC_SUCCESS);
248: }

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

254:   Collective

256:   Input Parameters:
257: + ls - the `TaoLineSearch` context
258: - s - search direction

260:   Output Parameters:
261: + x - On input the current solution, on output `x` contains the new solution determined by the line search
262: . f - On input the objective function value at current solution, on output contains the objective function value at new solution
263: . g - On input the gradient evaluated at `x`, on output contains the gradient at new solution
264: . steplength - scalar multiplier of s used ( x = x0 + steplength * x)
265: - reason - `TaoLineSearchConvergedReason` reason why the line-search stopped

267:   Level: advanced

269:   Notes:
270:   The algorithm developer must set up the `TaoLineSearch` with calls to
271:   `TaoLineSearchSetObjectiveRoutine()` and `TaoLineSearchSetGradientRoutine()`,
272:   `TaoLineSearchSetObjectiveAndGradientRoutine()`, or `TaoLineSearchUseTaoRoutines()`.
273:   The latter is done automatically by default and thus requires no user input.

275:   You may or may not need to follow this with a call to
276:   `TaoAddLineSearchCounts()`, depending on whether you want these
277:   evaluations to count toward the total function/gradient evaluations.

279: .seealso: [](ch_tao), `Tao`, `TaoLineSearchConvergedReason`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchSetType()`,
280:           `TaoLineSearchSetInitialStepLength()`, `TaoAddLineSearchCounts()`
281: @*/
282: PetscErrorCode TaoLineSearchApply(TaoLineSearch ls, Vec x, PetscReal *f, Vec g, Vec s, PetscReal *steplength, TaoLineSearchConvergedReason *reason)
283: {
284:   PetscInt low1, low2, low3, high1, high2, high3;

286:   PetscFunctionBegin;
293:   PetscCheckSameComm(ls, 1, x, 2);
294:   PetscCheckSameTypeAndComm(x, 2, g, 4);
295:   PetscCheckSameTypeAndComm(x, 2, s, 5);
296:   PetscCall(VecGetOwnershipRange(x, &low1, &high1));
297:   PetscCall(VecGetOwnershipRange(g, &low2, &high2));
298:   PetscCall(VecGetOwnershipRange(s, &low3, &high3));
299:   PetscCheck(low1 == low2 && low1 == low3 && high1 == high2 && high1 == high3, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "Incompatible vector local lengths");

301:   *reason = TAOLINESEARCH_CONTINUE_ITERATING;
302:   PetscCall(PetscObjectReference((PetscObject)s));
303:   PetscCall(VecDestroy(&ls->stepdirection));
304:   ls->stepdirection = s;

306:   PetscCall(TaoLineSearchSetUp(ls));
307:   ls->nfeval  = 0;
308:   ls->ngeval  = 0;
309:   ls->nfgeval = 0;
310:   /* Check parameter values */
311:   if (ls->ftol < 0.0) {
312:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: ftol (%g) < 0\n", (double)ls->ftol));
313:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
314:   }
315:   if (ls->rtol < 0.0) {
316:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: rtol (%g) < 0\n", (double)ls->rtol));
317:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
318:   }
319:   if (ls->gtol < 0.0) {
320:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: gtol (%g) < 0\n", (double)ls->gtol));
321:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
322:   }
323:   if (ls->stepmin < 0.0) {
324:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: stepmin (%g) < 0\n", (double)ls->stepmin));
325:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
326:   }
327:   if (ls->stepmax < ls->stepmin) {
328:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: stepmin (%g) > stepmax (%g)\n", (double)ls->stepmin, (double)ls->stepmax));
329:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
330:   }
331:   if (ls->max_funcs < 0) {
332:     PetscCall(PetscInfo(ls, "Bad Line Search Parameter: max_funcs (%" PetscInt_FMT ") < 0\n", ls->max_funcs));
333:     *reason = TAOLINESEARCH_FAILED_BADPARAMETER;
334:   }
335:   if (PetscIsInfOrNanReal(*f)) {
336:     PetscCall(PetscInfo(ls, "Initial Line Search Function Value is Inf or Nan (%g)\n", (double)*f));
337:     *reason = TAOLINESEARCH_FAILED_INFORNAN;
338:   }

340:   PetscCall(PetscObjectReference((PetscObject)x));
341:   PetscCall(VecDestroy(&ls->start_x));
342:   ls->start_x = x;

344:   PetscCall(PetscLogEventBegin(TAOLINESEARCH_Apply, ls, 0, 0, 0));
345:   PetscUseTypeMethod(ls, apply, x, f, g, s);
346:   PetscCall(PetscLogEventEnd(TAOLINESEARCH_Apply, ls, 0, 0, 0));
347:   *reason   = ls->reason;
348:   ls->new_f = *f;

350:   if (steplength) *steplength = ls->step;

352:   PetscCall(TaoLineSearchViewFromOptions(ls, NULL, "-tao_ls_view"));
353:   PetscFunctionReturn(PETSC_SUCCESS);
354: }

356: /*@C
357:    TaoLineSearchSetType - Sets the algorithm used in a line search

359:    Collective

361:    Input Parameters:
362: +  ls - the `TaoLineSearch` context
363: -  type - the `TaoLineSearchType` selection

365:   Options Database Key:
366: .  -tao_ls_type <type> - select which method Tao should use at runtime

368:   Level: beginner

370: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchType`, `TaoLineSearchCreate()`, `TaoLineSearchGetType()`,
371:           `TaoLineSearchApply()`
372: @*/
373: PetscErrorCode TaoLineSearchSetType(TaoLineSearch ls, TaoLineSearchType type)
374: {
375:   PetscErrorCode (*r)(TaoLineSearch);
376:   PetscBool flg;

378:   PetscFunctionBegin;
381:   PetscCall(PetscObjectTypeCompare((PetscObject)ls, type, &flg));
382:   if (flg) PetscFunctionReturn(PETSC_SUCCESS);

384:   PetscCall(PetscFunctionListFind(TaoLineSearchList, type, (void (**)(void)) & r));
385:   PetscCheck(r, PetscObjectComm((PetscObject)ls), PETSC_ERR_ARG_UNKNOWN_TYPE, "Unable to find requested TaoLineSearch type %s", type);
386:   PetscTryTypeMethod(ls, destroy);
387:   ls->max_funcs = 30;
388:   ls->ftol      = 0.0001;
389:   ls->gtol      = 0.9;
390: #if defined(PETSC_USE_REAL_SINGLE)
391:   ls->rtol = 1.0e-5;
392: #else
393:   ls->rtol = 1.0e-10;
394: #endif
395:   ls->stepmin = 1.0e-20;
396:   ls->stepmax = 1.0e+20;

398:   ls->nfeval              = 0;
399:   ls->ngeval              = 0;
400:   ls->nfgeval             = 0;
401:   ls->ops->setup          = NULL;
402:   ls->ops->apply          = NULL;
403:   ls->ops->view           = NULL;
404:   ls->ops->setfromoptions = NULL;
405:   ls->ops->destroy        = NULL;
406:   ls->setupcalled         = PETSC_FALSE;
407:   PetscCall((*r)(ls));
408:   PetscCall(PetscObjectChangeTypeName((PetscObject)ls, type));
409:   PetscFunctionReturn(PETSC_SUCCESS);
410: }

412: /*@C
413:   TaoLineSearchMonitor - Monitor the line search steps. This routine will otuput the
414:   iteration number, step length, and function value before calling the implementation
415:   specific monitor.

417:    Input Parameters:
418: +  ls - the `TaoLineSearch` context
419: .  its - the current iterate number (>=0)
420: .  f - the current objective function value
421: -  step - the step length

423:    Options Database Key:
424: .  -tao_ls_monitor - Use the default monitor, which prints statistics to standard output

426:    Level: developer

428: .seealso: `TaoLineSearch`
429: @*/
430: PetscErrorCode TaoLineSearchMonitor(TaoLineSearch ls, PetscInt its, PetscReal f, PetscReal step)
431: {
432:   PetscInt tabs;

434:   PetscFunctionBegin;
436:   if (ls->usemonitor) {
437:     PetscCall(PetscViewerASCIIGetTab(ls->viewer, &tabs));
438:     PetscCall(PetscViewerASCIISetTab(ls->viewer, ((PetscObject)ls)->tablevel));
439:     PetscCall(PetscViewerASCIIPrintf(ls->viewer, "%3" PetscInt_FMT " LS", its));
440:     PetscCall(PetscViewerASCIIPrintf(ls->viewer, "  Function value: %g,", (double)f));
441:     PetscCall(PetscViewerASCIIPrintf(ls->viewer, "  Step length: %g\n", (double)step));
442:     if (ls->ops->monitor && its > 0) {
443:       PetscCall(PetscViewerASCIISetTab(ls->viewer, ((PetscObject)ls)->tablevel + 3));
444:       PetscUseTypeMethod(ls, monitor);
445:     }
446:     PetscCall(PetscViewerASCIISetTab(ls->viewer, tabs));
447:   }
448:   PetscFunctionReturn(PETSC_SUCCESS);
449: }

451: /*@
452:   TaoLineSearchSetFromOptions - Sets various `TaoLineSearch` parameters from user
453:   options.

455:   Collective

457:   Input Parameter:
458: . ls - the `TaoLineSearch` context

460:   Options Database Keys:
461: + -tao_ls_type <type> - The algorithm that `TaoLineSearch` uses (more-thuente, gpcg, unit)
462: . -tao_ls_ftol <tol> - tolerance for sufficient decrease
463: . -tao_ls_gtol <tol> - tolerance for curvature condition
464: . -tao_ls_rtol <tol> - relative tolerance for acceptable step
465: . -tao_ls_stepinit <step> - initial steplength allowed
466: . -tao_ls_stepmin <step> - minimum steplength allowed
467: . -tao_ls_stepmax <step> - maximum steplength allowed
468: . -tao_ls_max_funcs <n> - maximum number of function evaluations allowed
469: - -tao_ls_view - display line-search results to standard output

471:   Level: beginner

473: .seealso: `TaoLineSearch`
474: @*/
475: PetscErrorCode TaoLineSearchSetFromOptions(TaoLineSearch ls)
476: {
477:   const char *default_type = TAOLINESEARCHMT;
478:   char        type[256], monfilename[PETSC_MAX_PATH_LEN];
479:   PetscViewer monviewer;
480:   PetscBool   flg;

482:   PetscFunctionBegin;
484:   PetscObjectOptionsBegin((PetscObject)ls);
485:   if (((PetscObject)ls)->type_name) default_type = ((PetscObject)ls)->type_name;
486:   /* Check for type from options */
487:   PetscCall(PetscOptionsFList("-tao_ls_type", "Tao Line Search type", "TaoLineSearchSetType", TaoLineSearchList, default_type, type, 256, &flg));
488:   if (flg) {
489:     PetscCall(TaoLineSearchSetType(ls, type));
490:   } else if (!((PetscObject)ls)->type_name) {
491:     PetscCall(TaoLineSearchSetType(ls, default_type));
492:   }

494:   PetscCall(PetscOptionsInt("-tao_ls_max_funcs", "max function evals in line search", "", ls->max_funcs, &ls->max_funcs, NULL));
495:   PetscCall(PetscOptionsReal("-tao_ls_ftol", "tol for sufficient decrease", "", ls->ftol, &ls->ftol, NULL));
496:   PetscCall(PetscOptionsReal("-tao_ls_gtol", "tol for curvature condition", "", ls->gtol, &ls->gtol, NULL));
497:   PetscCall(PetscOptionsReal("-tao_ls_rtol", "relative tol for acceptable step", "", ls->rtol, &ls->rtol, NULL));
498:   PetscCall(PetscOptionsReal("-tao_ls_stepmin", "lower bound for step", "", ls->stepmin, &ls->stepmin, NULL));
499:   PetscCall(PetscOptionsReal("-tao_ls_stepmax", "upper bound for step", "", ls->stepmax, &ls->stepmax, NULL));
500:   PetscCall(PetscOptionsReal("-tao_ls_stepinit", "initial step", "", ls->initstep, &ls->initstep, NULL));
501:   PetscCall(PetscOptionsString("-tao_ls_monitor", "enable the basic monitor", "TaoLineSearchSetMonitor", "stdout", monfilename, sizeof(monfilename), &flg));
502:   if (flg) {
503:     PetscCall(PetscViewerASCIIOpen(PetscObjectComm((PetscObject)ls), monfilename, &monviewer));
504:     ls->viewer     = monviewer;
505:     ls->usemonitor = PETSC_TRUE;
506:   }
507:   PetscTryTypeMethod(ls, setfromoptions, PetscOptionsObject);
508:   PetscOptionsEnd();
509:   PetscFunctionReturn(PETSC_SUCCESS);
510: }

512: /*@C
513:   TaoLineSearchGetType - Gets the current line search algorithm

515:   Not Collective

517:   Input Parameter:
518: . ls - the `TaoLineSearch` context

520:   Output Parameter:
521: . type - the line search algorithm in effect

523:   Level: developer

525: .seealso: `TaoLineSearch`
526: @*/
527: PetscErrorCode TaoLineSearchGetType(TaoLineSearch ls, TaoLineSearchType *type)
528: {
529:   PetscFunctionBegin;
532:   *type = ((PetscObject)ls)->type_name;
533:   PetscFunctionReturn(PETSC_SUCCESS);
534: }

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

540:   Not Collective

542:   Input Parameter:
543: . ls - the `TaoLineSearch` context

545:   Output Parameters:
546: + nfeval   - number of function evaluations
547: . ngeval   - number of gradient evaluations
548: - nfgeval  - number of function/gradient evaluations

550:   Level: intermediate

552:   Note:
553:   If the line search is using the `Tao` objective and gradient
554:   routines directly (see `TaoLineSearchUseTaoRoutines()`), then the `Tao`
555:   is already counting the number of evaluations.

557: .seealso: `TaoLineSearch`
558: @*/
559: PetscErrorCode TaoLineSearchGetNumberFunctionEvaluations(TaoLineSearch ls, PetscInt *nfeval, PetscInt *ngeval, PetscInt *nfgeval)
560: {
561:   PetscFunctionBegin;
563:   *nfeval  = ls->nfeval;
564:   *ngeval  = ls->ngeval;
565:   *nfgeval = ls->nfgeval;
566:   PetscFunctionReturn(PETSC_SUCCESS);
567: }

569: /*@
570:   TaoLineSearchIsUsingTaoRoutines - Checks whether the line search is using
571:   the standard `Tao` evaluation routines.

573:   Not Collective

575:   Input Parameter:
576: . ls - the `TaoLineSearch` context

578:   Output Parameter:
579: . flg - `PETSC_TRUE` if the line search is using `Tao` evaluation routines,
580:         otherwise `PETSC_FALSE`

582:   Level: developer

584: .seealso: `TaoLineSearch`
585: @*/
586: PetscErrorCode TaoLineSearchIsUsingTaoRoutines(TaoLineSearch ls, PetscBool *flg)
587: {
588:   PetscFunctionBegin;
590:   *flg = ls->usetaoroutines;
591:   PetscFunctionReturn(PETSC_SUCCESS);
592: }

594: /*@C
595:   TaoLineSearchSetObjectiveRoutine - Sets the function evaluation routine for the line search

597:   Logically Collective

599:   Input Parameters:
600: + ls - the `TaoLineSearch` context
601: . func - the objective function evaluation routine
602: - ctx - the (optional) user-defined context for private data

604:   Calling sequence of `func`:
605: $ PetscErrorCode func(TaoLinesearch ls, Vec x, PetscReal *f, void *ctx);
606: + ls - the line search context
607: . x - input vector
608: . f - function value
609: - ctx (optional) user-defined context

611:   Level: advanced

613:   Notes:
614:   Use this routine only if you want the line search objective
615:   evaluation routine to be different from the `Tao`'s objective
616:   evaluation routine. If you use this routine you must also set
617:   the line search gradient and/or function/gradient routine.

619:   Some algorithms (lcl, gpcg) set their own objective routine for the
620:   line search, application programmers should be wary of overriding the
621:   default objective routine.

623: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchSetGradientRoutine()`, `TaoLineSearchSetObjectiveAndGradientRoutine()`, `TaoLineSearchUseTaoRoutines()`
624: @*/
625: PetscErrorCode TaoLineSearchSetObjectiveRoutine(TaoLineSearch ls, PetscErrorCode (*func)(TaoLineSearch ls, Vec x, PetscReal *, void *), void *ctx)
626: {
627:   PetscFunctionBegin;

630:   ls->ops->computeobjective = func;
631:   if (ctx) ls->userctx_func = ctx;
632:   ls->usetaoroutines = PETSC_FALSE;
633:   PetscFunctionReturn(PETSC_SUCCESS);
634: }

636: /*@C
637:   TaoLineSearchSetGradientRoutine - Sets the gradient evaluation routine for the line search

639:   Logically Collective

641:   Input Parameters:
642: + ls - the `TaoLineSearch` context
643: . func - the gradient evaluation routine
644: - ctx - the (optional) user-defined context for private data

646:   Calling sequence of `func`:
647: $ PetscErrorCode func(TaoLinesearch ls, Vec x, Vec g, void *ctx);
648: + ls - the linesearch object
649: . x - input vector
650: . g - gradient vector
651: - ctx (optional) user-defined context

653:   Level: beginner

655:   Note:
656:   Use this routine only if you want the line search gradient
657:   evaluation routine to be different from the `Tao`'s gradient
658:   evaluation routine. If you use this routine you must also set
659:   the line search function and/or function/gradient routine.

661:   Some algorithms (lcl, gpcg) set their own gradient routine for the
662:   line search, application programmers should be wary of overriding the
663:   default gradient routine.

665: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchSetObjectiveRoutine()`, `TaoLineSearchSetObjectiveAndGradientRoutine()`, `TaoLineSearchUseTaoRoutines()`
666: @*/
667: PetscErrorCode TaoLineSearchSetGradientRoutine(TaoLineSearch ls, PetscErrorCode (*func)(TaoLineSearch ls, Vec x, Vec g, void *), void *ctx)
668: {
669:   PetscFunctionBegin;
671:   ls->ops->computegradient = func;
672:   if (ctx) ls->userctx_grad = ctx;
673:   ls->usetaoroutines = PETSC_FALSE;
674:   PetscFunctionReturn(PETSC_SUCCESS);
675: }

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

680:   Logically Collective

682:   Input Parameters:
683: + ls - the `TaoLineSearch` context
684: . func - the objective and gradient evaluation routine
685: - ctx - the (optional) user-defined context for private data

687:   Calling sequence of `func`:
688: $ PetscErrorCode func(TaoLinesearch ls, Vec x, PetscReal *f, Vec g, void *ctx);
689: + ls - the linesearch object
690: . x - input vector
691: . f - function value
692: . g - gradient vector
693: - ctx (optional) user-defined context

695:   Level: beginner

697:   Note:
698:   Use this routine only if you want the line search objective and gradient
699:   evaluation routines to be different from the `Tao`'s objective
700:   and gradient evaluation routines.

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

706: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchSetObjectiveRoutine()`, `TaoLineSearchSetGradientRoutine()`, `TaoLineSearchUseTaoRoutines()`
707: @*/
708: PetscErrorCode TaoLineSearchSetObjectiveAndGradientRoutine(TaoLineSearch ls, PetscErrorCode (*func)(TaoLineSearch ls, Vec x, PetscReal *, Vec g, void *), void *ctx)
709: {
710:   PetscFunctionBegin;
712:   ls->ops->computeobjectiveandgradient = func;
713:   if (ctx) ls->userctx_funcgrad = ctx;
714:   ls->usetaoroutines = PETSC_FALSE;
715:   PetscFunctionReturn(PETSC_SUCCESS);
716: }

718: /*@C
719:   TaoLineSearchSetObjectiveAndGTSRoutine - Sets the objective and
720:   (gradient'*stepdirection) evaluation routine for the line search.
721:   Sometimes it is more efficient to compute the inner product of the gradient
722:   and the step direction than it is to compute the gradient, and this is all
723:   the line search typically needs of the gradient.

725:   Logically Collective

727:   Input Parameters:
728: + ls - the `TaoLineSearch` context
729: . func - the objective and gradient evaluation routine
730: - ctx - the (optional) user-defined context for private data

732:   Calling sequence of `func`:
733: $ PetscErrorCode func(TaoLinesearch ls, Vec x, PetscReal *f, PetscReal *gts, void *ctx);
734: + ls - the linesearch context
735: . x - input vector
736: . s - step direction
737: . f - function value
738: . gts - inner product of gradient and step direction vectors
739: - ctx (optional) user-defined context

741:   Level: advanced

743:   Notes:
744:   The gradient will still need to be computed at the end of the line
745:   search, so you will still need to set a line search gradient evaluation
746:   routine

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

752:   Some algorithms (lcl, gpcg) set their own objective routine for the
753:   line search, application programmers should be wary of overriding the
754:   default objective routine.

756: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`, `TaoLineSearchSetObjective()`, `TaoLineSearchSetGradient()`, `TaoLineSearchUseTaoRoutines()`
757: @*/
758: PetscErrorCode TaoLineSearchSetObjectiveAndGTSRoutine(TaoLineSearch ls, PetscErrorCode (*func)(TaoLineSearch ls, Vec x, Vec s, PetscReal *, PetscReal *, void *), void *ctx)
759: {
760:   PetscFunctionBegin;
762:   ls->ops->computeobjectiveandgts = func;
763:   if (ctx) ls->userctx_funcgts = ctx;
764:   ls->usegts         = PETSC_TRUE;
765:   ls->usetaoroutines = PETSC_FALSE;
766:   PetscFunctionReturn(PETSC_SUCCESS);
767: }

769: /*@C
770:   TaoLineSearchUseTaoRoutines - Informs the `TaoLineSearch` to use the
771:   objective and gradient evaluation routines from the given `Tao` object. The default.

773:   Logically Collective

775:   Input Parameters:
776: + ls - the `TaoLineSearch` context
777: - ts - the `Tao` context with defined objective/gradient evaluation routines

779:   Level: developer

781: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchCreate()`
782: @*/
783: PetscErrorCode TaoLineSearchUseTaoRoutines(TaoLineSearch ls, Tao ts)
784: {
785:   PetscFunctionBegin;
788:   ls->tao            = ts;
789:   ls->usetaoroutines = PETSC_TRUE;
790:   PetscFunctionReturn(PETSC_SUCCESS);
791: }

793: /*@
794:   TaoLineSearchComputeObjective - Computes the objective function value at a given point

796:   Collective

798:   Input Parameters:
799: + ls - the `TaoLineSearch` context
800: - x - input vector

802:   Output Parameter:
803: . f - Objective value at `x`

805:   Level: developer

807:   Note:
808:   `TaoLineSearchComputeObjective()` is typically used within line searches
809:   so most users would not generally call this routine themselves.

811: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchComputeGradient()`, `TaoLineSearchComputeObjectiveAndGradient()`, `TaoLineSearchSetObjectiveRoutine()`
812: @*/
813: PetscErrorCode TaoLineSearchComputeObjective(TaoLineSearch ls, Vec x, PetscReal *f)
814: {
815:   Vec       gdummy;
816:   PetscReal gts;

818:   PetscFunctionBegin;
822:   PetscCheckSameComm(ls, 1, x, 2);
823:   if (ls->usetaoroutines) {
824:     PetscCall(TaoComputeObjective(ls->tao, x, f));
825:   } else {
826:     PetscCheck(ls->ops->computeobjective || ls->ops->computeobjectiveandgradient || ls->ops->computeobjectiveandgts, PetscObjectComm((PetscObject)ls), PETSC_ERR_ARG_WRONGSTATE, "Line Search does not have objective function set");
827:     PetscCall(PetscLogEventBegin(TAOLINESEARCH_Eval, ls, 0, 0, 0));
828:     if (ls->ops->computeobjective) PetscCallBack("TaoLineSearch callback objective", (*ls->ops->computeobjective)(ls, x, f, ls->userctx_func));
829:     else if (ls->ops->computeobjectiveandgradient) {
830:       PetscCall(VecDuplicate(x, &gdummy));
831:       PetscCallBack("TaoLineSearch callback objective", (*ls->ops->computeobjectiveandgradient)(ls, x, f, gdummy, ls->userctx_funcgrad));
832:       PetscCall(VecDestroy(&gdummy));
833:     } else PetscCallBack("TaoLineSearch callback objective", (*ls->ops->computeobjectiveandgts)(ls, x, ls->stepdirection, f, &gts, ls->userctx_funcgts));
834:     PetscCall(PetscLogEventEnd(TAOLINESEARCH_Eval, ls, 0, 0, 0));
835:   }
836:   ls->nfeval++;
837:   PetscFunctionReturn(PETSC_SUCCESS);
838: }

840: /*@
841:   TaoLineSearchComputeObjectiveAndGradient - Computes the objective function value at a given point

843:   Collective

845:   Input Parameters:
846: + ls - the `TaoLineSearch` context
847: - x - input vector

849:   Output Parameters:
850: + f - Objective value at `x`
851: - g - Gradient vector at `x`

853:   Level: developer

855:   Note:
856:   `TaoLineSearchComputeObjectiveAndGradient()` is typically used within line searches
857:   so most users would not generally call this routine themselves.

859: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchComputeGradient()`, `TaoLineSearchComputeObjectiveAndGradient()`, `TaoLineSearchSetObjectiveRoutine()`
860: @*/
861: PetscErrorCode TaoLineSearchComputeObjectiveAndGradient(TaoLineSearch ls, Vec x, PetscReal *f, Vec g)
862: {
863:   PetscFunctionBegin;
868:   PetscCheckSameComm(ls, 1, x, 2);
869:   PetscCheckSameComm(ls, 1, g, 4);
870:   if (ls->usetaoroutines) {
871:     PetscCall(TaoComputeObjectiveAndGradient(ls->tao, x, f, g));
872:   } else {
873:     PetscCall(PetscLogEventBegin(TAOLINESEARCH_Eval, ls, 0, 0, 0));
874:     if (ls->ops->computeobjectiveandgradient) PetscCallBack("TaoLineSearch callback objective/gradient", (*ls->ops->computeobjectiveandgradient)(ls, x, f, g, ls->userctx_funcgrad));
875:     else {
876:       PetscCallBack("TaoLineSearch callback objective", (*ls->ops->computeobjective)(ls, x, f, ls->userctx_func));
877:       PetscCallBack("TaoLineSearch callback gradient", (*ls->ops->computegradient)(ls, x, g, ls->userctx_grad));
878:     }
879:     PetscCall(PetscLogEventEnd(TAOLINESEARCH_Eval, ls, 0, 0, 0));
880:     PetscCall(PetscInfo(ls, "TaoLineSearch Function evaluation: %14.12e\n", (double)(*f)));
881:   }
882:   ls->nfgeval++;
883:   PetscFunctionReturn(PETSC_SUCCESS);
884: }

886: /*@
887:   TaoLineSearchComputeGradient - Computes the gradient of the objective function

889:   Collective

891:   Input Parameters:
892: + ls - the `TaoLineSearch` context
893: - x - input vector

895:   Output Parameter:
896: . g - gradient vector

898:   Level: developer

900:   Note:
901:   `TaoComputeGradient()` is typically used within line searches
902:   so most users would not generally call this routine themselves.

904: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchComputeObjective()`, `TaoLineSearchComputeObjectiveAndGradient()`, `TaoLineSearchSetGradient()`
905: @*/
906: PetscErrorCode TaoLineSearchComputeGradient(TaoLineSearch ls, Vec x, Vec g)
907: {
908:   PetscReal fdummy;

910:   PetscFunctionBegin;
914:   PetscCheckSameComm(ls, 1, x, 2);
915:   PetscCheckSameComm(ls, 1, g, 3);
916:   if (ls->usetaoroutines) {
917:     PetscCall(TaoComputeGradient(ls->tao, x, g));
918:   } else {
919:     PetscCall(PetscLogEventBegin(TAOLINESEARCH_Eval, ls, 0, 0, 0));
920:     if (ls->ops->computegradient) PetscCallBack("TaoLineSearch callback gradient", (*ls->ops->computegradient)(ls, x, g, ls->userctx_grad));
921:     else PetscCallBack("TaoLineSearch callback gradient", (*ls->ops->computeobjectiveandgradient)(ls, x, &fdummy, g, ls->userctx_funcgrad));
922:     PetscCall(PetscLogEventEnd(TAOLINESEARCH_Eval, ls, 0, 0, 0));
923:   }
924:   ls->ngeval++;
925:   PetscFunctionReturn(PETSC_SUCCESS);
926: }

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

932:   Collective

934:   Input Parameters:
935: + ls - the `TaoLineSearch` context
936: - x - input vector

938:   Output Parameters:
939: + f - Objective value at `x`
940: - gts - inner product of gradient and step direction at `x`

942:   Level: developer

944:   Note:
945:   `TaoLineSearchComputeObjectiveAndGTS()` is typically used within line searches
946:   so most users would not generally call this routine themselves.

948: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchComputeGradient()`, `TaoLineSearchComputeObjectiveAndGradient()`, `TaoLineSearchSetObjectiveRoutine()`
949: @*/
950: PetscErrorCode TaoLineSearchComputeObjectiveAndGTS(TaoLineSearch ls, Vec x, PetscReal *f, PetscReal *gts)
951: {
952:   PetscFunctionBegin;
957:   PetscCheckSameComm(ls, 1, x, 2);
958:   PetscCall(PetscLogEventBegin(TAOLINESEARCH_Eval, ls, 0, 0, 0));
959:   PetscCallBack("TaoLineSearch callback objective/gts", (*ls->ops->computeobjectiveandgts)(ls, x, ls->stepdirection, f, gts, ls->userctx_funcgts));
960:   PetscCall(PetscLogEventEnd(TAOLINESEARCH_Eval, ls, 0, 0, 0));
961:   PetscCall(PetscInfo(ls, "TaoLineSearch Function evaluation: %14.12e\n", (double)(*f)));
962:   ls->nfeval++;
963:   PetscFunctionReturn(PETSC_SUCCESS);
964: }

966: /*@
967:   TaoLineSearchGetSolution - Returns the solution to the line search

969:   Collective

971:   Input Parameter:
972: . ls - the `TaoLineSearch` context

974:   Output Parameters:
975: + x - the new solution
976: . f - the objective function value at `x`
977: . g - the gradient at `x`
978: . steplength - the multiple of the step direction taken by the line search
979: - reason - the reason why the line search terminated

981:   Level: developer

983: .seealso: `TaoLineSearchGetStartingVector()`, `TaoLineSearchGetStepDirection()`
984: @*/
985: PetscErrorCode TaoLineSearchGetSolution(TaoLineSearch ls, Vec x, PetscReal *f, Vec g, PetscReal *steplength, TaoLineSearchConvergedReason *reason)
986: {
987:   PetscFunctionBegin;
993:   if (ls->new_x) PetscCall(VecCopy(ls->new_x, x));
994:   *f = ls->new_f;
995:   if (ls->new_g) PetscCall(VecCopy(ls->new_g, g));
996:   if (steplength) *steplength = ls->step;
997:   *reason = ls->reason;
998:   PetscFunctionReturn(PETSC_SUCCESS);
999: }

1001: /*@
1002:   TaoLineSearchGetStartingVector - Gets a the initial point of the line
1003:   search.

1005:   Not Collective

1007:   Input Parameter:
1008: . ls - the `TaoLineSearch` context

1010:   Output Parameter:
1011: . x - The initial point of the line search

1013:   Level: advanced

1015: .seealso: `TaoLineSearchGetSolution()`, `TaoLineSearchGetStepDirection()`
1016: @*/
1017: PetscErrorCode TaoLineSearchGetStartingVector(TaoLineSearch ls, Vec *x)
1018: {
1019:   PetscFunctionBegin;
1021:   if (x) *x = ls->start_x;
1022:   PetscFunctionReturn(PETSC_SUCCESS);
1023: }

1025: /*@
1026:   TaoLineSearchGetStepDirection - Gets the step direction of the line
1027:   search.

1029:   Not Collective

1031:   Input Parameter:
1032: . ls - the `TaoLineSearch` context

1034:   Output Parameter:
1035: . s - the step direction of the line search

1037:   Level: advanced

1039: .seealso: `TaoLineSearchGetSolution()`, `TaoLineSearchGetStartingVector()`
1040: @*/
1041: PetscErrorCode TaoLineSearchGetStepDirection(TaoLineSearch ls, Vec *s)
1042: {
1043:   PetscFunctionBegin;
1045:   if (s) *s = ls->stepdirection;
1046:   PetscFunctionReturn(PETSC_SUCCESS);
1047: }

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

1052:   Not Collective

1054:   Input Parameter:
1055: . ls - the `TaoLineSearch` context

1057:   Output Parameter:
1058: . f - the objective value at the full step length

1060:   Level: developer

1062: .seealso: `TaoLineSearchGetSolution()`, `TaoLineSearchGetStartingVector()`, `TaoLineSearchGetStepDirection()`
1063: @*/

1065: PetscErrorCode TaoLineSearchGetFullStepObjective(TaoLineSearch ls, PetscReal *f_fullstep)
1066: {
1067:   PetscFunctionBegin;
1069:   *f_fullstep = ls->f_fullstep;
1070:   PetscFunctionReturn(PETSC_SUCCESS);
1071: }

1073: /*@
1074:   TaoLineSearchSetVariableBounds - Sets the upper and lower bounds for a bounded line search

1076:   Logically Collective

1078:   Input Parameters:
1079: + ls - the `TaoLineSearch` context
1080: . xl  - vector of lower bounds
1081: - xu  - vector of upper bounds

1083:   Level: beginner

1085:   Note:
1086:   If the variable bounds are not set with this routine, then
1087:   `PETSC_NINFINITY` and `PETSC_INFINITY` are assumed

1089: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoSetVariableBounds()`, `TaoLineSearchCreate()`
1090: @*/
1091: PetscErrorCode TaoLineSearchSetVariableBounds(TaoLineSearch ls, Vec xl, Vec xu)
1092: {
1093:   PetscFunctionBegin;
1097:   PetscCall(PetscObjectReference((PetscObject)xl));
1098:   PetscCall(PetscObjectReference((PetscObject)xu));
1099:   PetscCall(VecDestroy(&ls->lower));
1100:   PetscCall(VecDestroy(&ls->upper));
1101:   ls->lower   = xl;
1102:   ls->upper   = xu;
1103:   ls->bounded = (PetscBool)(xl || xu);
1104:   PetscFunctionReturn(PETSC_SUCCESS);
1105: }

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

1111:   Logically Collective

1113:   Input Parameters:
1114: + ls - the `TaoLineSearch` context
1115: - s - the initial step size

1117:   Level: intermediate

1119: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchGetStepLength()`, `TaoLineSearchApply()`
1120: @*/
1121: PetscErrorCode TaoLineSearchSetInitialStepLength(TaoLineSearch ls, PetscReal s)
1122: {
1123:   PetscFunctionBegin;
1126:   ls->initstep = s;
1127:   PetscFunctionReturn(PETSC_SUCCESS);
1128: }

1130: /*@
1131:   TaoLineSearchGetStepLength - Get the current step length

1133:   Not Collective

1135:   Input Parameter:
1136: . ls - the `TaoLineSearch` context

1138:   Output Parameter:
1139: . s - the current step length

1141:   Level: intermediate

1143: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchSetInitialStepLength()`, `TaoLineSearchApply()`
1144: @*/
1145: PetscErrorCode TaoLineSearchGetStepLength(TaoLineSearch ls, PetscReal *s)
1146: {
1147:   PetscFunctionBegin;
1149:   *s = ls->step;
1150:   PetscFunctionReturn(PETSC_SUCCESS);
1151: }

1153: /*@C
1154:    TaoLineSearchRegister - Adds a line-search algorithm to the registry

1156:    Not Collective

1158:    Input Parameters:
1159: +  sname - name of a new user-defined solver
1160: -  func - routine to Create method context

1162:    Sample usage:
1163: .vb
1164:    TaoLineSearchRegister("my_linesearch", MyLinesearchCreate);
1165: .ve

1167:    Then, your solver can be chosen with the procedural interface via
1168: $     TaoLineSearchSetType(ls, "my_linesearch")
1169:    or at runtime via the option
1170: $     -tao_ls_type my_linesearch

1172:    Level: developer

1174:    Note:
1175:    `TaoLineSearchRegister()` may be called multiple times to add several user-defined solvers.

1177: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`
1178: @*/
1179: PetscErrorCode TaoLineSearchRegister(const char sname[], PetscErrorCode (*func)(TaoLineSearch))
1180: {
1181:   PetscFunctionBegin;
1182:   PetscCall(TaoLineSearchInitializePackage());
1183:   PetscCall(PetscFunctionListAdd(&TaoLineSearchList, sname, (void (*)(void))func));
1184:   PetscFunctionReturn(PETSC_SUCCESS);
1185: }

1187: /*@C
1188:    TaoLineSearchAppendOptionsPrefix - Appends to the prefix used for searching
1189:    for all `TaoLineSearch` options in the database.

1191:    Collective

1193:    Input Parameters:
1194: +  ls - the `TaoLineSearch` solver context
1195: -  prefix - the prefix string to prepend to all line search requests

1197:    Level: advanced

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

1203:    This is inherited from the `Tao` object so rarely needs to be set

1205: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchSetOptionsPrefix()`, `TaoLineSearchGetOptionsPrefix()`
1206: @*/
1207: PetscErrorCode TaoLineSearchAppendOptionsPrefix(TaoLineSearch ls, const char p[])
1208: {
1209:   return PetscObjectAppendOptionsPrefix((PetscObject)ls, p);
1210: }

1212: /*@C
1213:   TaoLineSearchGetOptionsPrefix - Gets the prefix used for searching for all
1214:   `TaoLineSearch` options in the database

1216:   Not Collective

1218:   Input Parameter:
1219: . ls - the `TaoLineSearch` context

1221:   Output Parameter:
1222: . prefix - pointer to the prefix string used is returned

1224:   Level: advanced

1226:   Fortran Note:
1227:   The user should pass in a string 'prefix' of
1228:   sufficient length to hold the prefix.

1230: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchSetOptionsPrefix()`, `TaoLineSearchAppendOptionsPrefix()`
1231: @*/
1232: PetscErrorCode TaoLineSearchGetOptionsPrefix(TaoLineSearch ls, const char *p[])
1233: {
1234:   return PetscObjectGetOptionsPrefix((PetscObject)ls, p);
1235: }

1237: /*@C
1238:    TaoLineSearchSetOptionsPrefix - Sets the prefix used for searching for all
1239:    `TaoLineSearch` options in the database.

1241:    Logically Collective

1243:    Input Parameters:
1244: +  ls - the `TaoLineSearch` context
1245: -  prefix - the prefix string to prepend to all `ls` option requests

1247:    Level: advanced

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

1253:    This is inherited from the `Tao` object so rarely needs to be set

1255:    For example, to distinguish between the runtime options for two
1256:    different line searches, one could call
1257: .vb
1258:       TaoLineSearchSetOptionsPrefix(ls1,"sys1_")
1259:       TaoLineSearchSetOptionsPrefix(ls2,"sys2_")
1260: .ve

1262:    This would enable use of different options for each system, such as
1263: .vb
1264:       -sys1_tao_ls_type mt
1265:       -sys2_tao_ls_type armijo
1266: .ve

1268: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchAppendOptionsPrefix()`, `TaoLineSearchGetOptionsPrefix()`
1269: @*/
1270: PetscErrorCode TaoLineSearchSetOptionsPrefix(TaoLineSearch ls, const char p[])
1271: {
1272:   return PetscObjectSetOptionsPrefix((PetscObject)ls, p);
1273: }