Actual source code: taosolver_fg.c
1: #include <petsc/private/taoimpl.h>
3: /*@
4: TaoSetSolution - Sets the vector holding the initial guess for the solve
6: Logically Collective
8: Input Parameters:
9: + tao - the `Tao` context
10: - x0 - the initial guess
12: Level: beginner
14: .seealso: [](ch_tao), `Tao`, `TaoCreate()`, `TaoSolve()`, `TaoGetSolution()`
15: @*/
16: PetscErrorCode TaoSetSolution(Tao tao, Vec x0)
17: {
18: PetscFunctionBegin;
21: PetscCall(PetscObjectReference((PetscObject)x0));
22: PetscCall(VecDestroy(&tao->solution));
23: tao->solution = x0;
24: if (x0) PetscCall(TaoTermSetSolutionTemplate(tao->callbacks, x0));
25: PetscFunctionReturn(PETSC_SUCCESS);
26: }
28: PETSC_INTERN PetscErrorCode TaoTestGradient_Internal(Tao tao, Vec x, Vec g1, PetscViewer viewer, PetscViewer mviewer)
29: {
30: Vec g2, g3;
31: PetscReal hcnorm, fdnorm, hcmax, fdmax, diffmax, diffnorm;
32: PetscScalar dot;
34: PetscFunctionBegin;
35: PetscCall(VecDuplicate(x, &g2));
36: PetscCall(VecDuplicate(x, &g3));
38: /* Compute finite difference gradient, assume the gradient is already computed by TaoComputeGradient() and put into g1 */
39: PetscCall(TaoDefaultComputeGradient(tao, x, g2, NULL));
41: PetscCall(VecNorm(g2, NORM_2, &fdnorm));
42: PetscCall(VecNorm(g1, NORM_2, &hcnorm));
43: PetscCall(VecNorm(g2, NORM_INFINITY, &fdmax));
44: PetscCall(VecNorm(g1, NORM_INFINITY, &hcmax));
45: PetscCall(VecDot(g1, g2, &dot));
46: PetscCall(VecCopy(g1, g3));
47: PetscCall(VecAXPY(g3, -1.0, g2));
48: PetscCall(VecNorm(g3, NORM_2, &diffnorm));
49: PetscCall(VecNorm(g3, NORM_INFINITY, &diffmax));
50: PetscCall(PetscViewerASCIIPrintf(viewer, " ||Gfd|| %g, ||G|| = %g, angle cosine = (Gfd'G)/||Gfd||||G|| = %g\n", (double)fdnorm, (double)hcnorm, (double)(PetscRealPart(dot) / (fdnorm * hcnorm))));
51: PetscCall(PetscViewerASCIIPrintf(viewer, " 2-norm ||G - Gfd||/||G|| = %g, ||G - Gfd|| = %g\n", (double)(diffnorm / PetscMax(hcnorm, fdnorm)), (double)diffnorm));
52: PetscCall(PetscViewerASCIIPrintf(viewer, " max-norm ||G - Gfd||/||G|| = %g, ||G - Gfd|| = %g\n", (double)(diffmax / PetscMax(hcmax, fdmax)), (double)diffmax));
54: if (mviewer) {
55: PetscCall(PetscViewerASCIIPrintf(viewer, " Hand-coded gradient ----------\n"));
56: PetscCall(VecView(g1, mviewer));
57: PetscCall(PetscViewerASCIIPrintf(viewer, " Finite difference gradient ----------\n"));
58: PetscCall(VecView(g2, mviewer));
59: PetscCall(PetscViewerASCIIPrintf(viewer, " Hand-coded minus finite-difference gradient ----------\n"));
60: PetscCall(VecView(g3, mviewer));
61: }
62: PetscCall(VecDestroy(&g2));
63: PetscCall(VecDestroy(&g3));
64: PetscFunctionReturn(PETSC_SUCCESS);
65: }
67: /*@
68: TaoTestGradient - Compare the user-supplied gradient with a finite-difference approximation, when requested via
69: the options database, and print the difference.
71: Collective
73: Input Parameters:
74: + tao - the `Tao` context
75: . x - the point at which to evaluate the gradient
76: - g1 - the user-supplied gradient at `x`
78: Options Database Keys:
79: + -tao_test_gradient - enable the comparison
80: - -tao_test_gradient_view - display the user-supplied gradient, the finite-difference gradient, and their difference
82: Level: intermediate
84: Note:
85: If `-tao_test_gradient` is not set, this routine returns immediately without performing any work.
87: .seealso: [](ch_tao), `Tao`, `TaoTestHessian()`, `TaoComputeGradient()`
88: @*/
89: PetscErrorCode TaoTestGradient(Tao tao, Vec x, Vec g1)
90: {
91: PetscBool complete_print = PETSC_FALSE, test = PETSC_FALSE;
92: MPI_Comm comm;
93: PetscViewer viewer, mviewer;
94: PetscViewerFormat format;
95: PetscInt tabs;
96: static PetscBool directionsprinted = PETSC_FALSE;
98: PetscFunctionBegin;
99: PetscObjectOptionsBegin((PetscObject)tao);
100: PetscCall(PetscOptionsName("-tao_test_gradient", "Compare hand-coded and finite difference Gradients", "None", &test));
101: PetscCall(PetscOptionsViewer("-tao_test_gradient_view", "View difference between hand-coded and finite difference Gradients element entries", "None", &mviewer, &format, &complete_print));
102: PetscOptionsEnd();
103: if (!test) {
104: if (complete_print) PetscCall(PetscViewerDestroy(&mviewer));
105: PetscFunctionReturn(PETSC_SUCCESS);
106: }
108: PetscCall(PetscObjectGetComm((PetscObject)tao, &comm));
109: PetscCall(PetscViewerASCIIGetStdout(comm, &viewer));
110: PetscCall(PetscViewerASCIIGetTab(viewer, &tabs));
111: PetscCall(PetscViewerASCIISetTab(viewer, ((PetscObject)tao)->tablevel));
112: PetscCall(PetscViewerASCIIPrintf(viewer, " ---------- Testing Gradient -------------\n"));
113: if (!complete_print && !directionsprinted) {
114: PetscCall(PetscViewerASCIIPrintf(viewer, " Run with -tao_test_gradient_view and optionally -tao_test_gradient <threshold> to show difference\n"));
115: PetscCall(PetscViewerASCIIPrintf(viewer, " of hand-coded and finite difference gradient entries greater than <threshold>.\n"));
116: }
117: if (!directionsprinted) {
118: PetscCall(PetscViewerASCIIPrintf(viewer, " Testing hand-coded Gradient, if (for double precision runs) ||G - Gfd||/||G|| is\n"));
119: PetscCall(PetscViewerASCIIPrintf(viewer, " O(1.e-8), the hand-coded Gradient is probably correct.\n"));
120: directionsprinted = PETSC_TRUE;
121: }
122: if (complete_print) PetscCall(PetscViewerPushFormat(mviewer, format));
123: PetscCall(TaoTestGradient_Internal(tao, x, g1, viewer, complete_print ? mviewer : NULL));
124: if (complete_print) {
125: PetscCall(PetscViewerPopFormat(mviewer));
126: PetscCall(PetscViewerDestroy(&mviewer));
127: }
128: PetscCall(PetscViewerASCIISetTab(viewer, tabs));
129: PetscFunctionReturn(PETSC_SUCCESS);
130: }
132: /*@
133: TaoComputeGradient - Computes the gradient of the objective function
135: Collective
137: Input Parameters:
138: + tao - the `Tao` context
139: - X - input vector
141: Output Parameter:
142: . G - gradient vector
144: Options Database Keys:
145: + -tao_test_gradient - compare the user provided gradient with one compute via finite differences to check for errors
146: - -tao_test_gradient_view - display the user provided gradient, the finite difference gradient and the difference between them to help users detect the location of errors in the user provided gradient
148: Level: developer
150: Note:
151: `TaoComputeGradient()` is typically used within the implementation of the optimization method,
152: so most users would not generally call this routine themselves.
154: .seealso: [](ch_tao), `TaoComputeObjective()`, `TaoComputeObjectiveAndGradient()`, `TaoSetGradient()`
155: @*/
156: PetscErrorCode TaoComputeGradient(Tao tao, Vec X, Vec G)
157: {
158: PetscFunctionBegin;
162: PetscCheckSameComm(tao, 1, X, 2);
163: PetscCheckSameComm(tao, 1, G, 3);
164: PetscCall(TaoTermMappingComputeGradient(&tao->objective_term, X, tao->objective_parameters, INSERT_VALUES, G));
165: PetscCall(TaoTestGradient(tao, X, G));
166: PetscFunctionReturn(PETSC_SUCCESS);
167: }
169: /*@
170: TaoComputeObjective - Computes the objective function value at a given point
172: Collective
174: Input Parameters:
175: + tao - the `Tao` context
176: - X - input vector
178: Output Parameter:
179: . f - Objective value at X
181: Level: developer
183: Note:
184: `TaoComputeObjective()` is typically used within the implementation of the optimization algorithm
185: so most users would not generally call this routine themselves.
187: .seealso: [](ch_tao), `Tao`, `TaoComputeGradient()`, `TaoComputeObjectiveAndGradient()`, `TaoSetObjective()`
188: @*/
189: PetscErrorCode TaoComputeObjective(Tao tao, Vec X, PetscReal *f)
190: {
191: PetscFunctionBegin;
194: PetscAssertPointer(f, 3);
195: PetscCheckSameComm(tao, 1, X, 2);
196: PetscCall(TaoTermMappingComputeObjective(&tao->objective_term, X, tao->objective_parameters, INSERT_VALUES, f));
197: PetscFunctionReturn(PETSC_SUCCESS);
198: }
200: /*@
201: TaoComputeObjectiveAndGradient - Computes the objective function value at a given point
203: Collective
205: Input Parameters:
206: + tao - the `Tao` context
207: - X - input vector
209: Output Parameters:
210: + f - Objective value at `X`
211: - G - Gradient vector at `X`
213: Level: developer
215: Note:
216: `TaoComputeObjectiveAndGradient()` is typically used within the implementation of the optimization algorithm,
217: so most users would not generally call this routine themselves.
219: .seealso: [](ch_tao), `TaoComputeGradient()`, `TaoSetObjective()`
220: @*/
221: PetscErrorCode TaoComputeObjectiveAndGradient(Tao tao, Vec X, PetscReal *f, Vec G)
222: {
223: PetscFunctionBegin;
226: PetscAssertPointer(f, 3);
228: PetscCheckSameComm(tao, 1, X, 2);
229: PetscCheckSameComm(tao, 1, G, 4);
230: PetscCall(TaoTermMappingComputeObjectiveAndGradient(&tao->objective_term, X, tao->objective_parameters, INSERT_VALUES, f, G));
231: PetscCall(TaoTestGradient(tao, X, G));
232: PetscFunctionReturn(PETSC_SUCCESS);
233: }
235: /*@
236: TaoSetObjective - Sets the function evaluation routine for minimization
238: Logically Collective
240: Input Parameters:
241: + tao - the `Tao` context
242: . func - the objective function
243: - ctx - [optional] user-defined context for private data for the function evaluation
244: routine (may be `NULL`)
246: Calling sequence of `func`:
247: + tao - the optimizer
248: . x - input vector
249: . f - function value
250: - ctx - [optional] user-defined function context
252: Level: beginner
254: .seealso: [](ch_tao), `TaoSetGradient()`, `TaoSetHessian()`, `TaoSetObjectiveAndGradient()`, `TaoGetObjective()`
255: @*/
256: PetscErrorCode TaoSetObjective(Tao tao, PetscErrorCode (*func)(Tao tao, Vec x, PetscReal *f, PetscCtx ctx), PetscCtx ctx)
257: {
258: PetscFunctionBegin;
260: PetscCall(TaoTermCallbacksSetObjective(tao->callbacks, func, ctx));
261: PetscFunctionReturn(PETSC_SUCCESS);
262: }
264: /*@
265: TaoGetObjective - Gets the function evaluation routine for the function to be minimized
267: Not Collective
269: Input Parameter:
270: . tao - the `Tao` context
272: Output Parameters:
273: + func - the objective function
274: - ctx - the user-defined context for private data for the function evaluation
276: Calling sequence of `func`:
277: + tao - the optimizer
278: . x - input vector
279: . f - function value
280: - ctx - [optional] user-defined function context
282: Level: beginner
284: Notes:
285: In addition to specifying an objective function using callbacks such as
286: `TaoSetObjective()` and `TaoSetGradient()`, users can specify
287: objective functions with `TaoAddTerm()`.
289: `TaoGetObjective()` will always return the callback specified with
290: `TaoSetObjective()`, even if the objective function has been changed by
291: calling `TaoAddTerm()`.
293: .seealso: [](ch_tao), `Tao`, `TaoSetGradient()`, `TaoSetHessian()`, `TaoSetObjective()`
294: @*/
295: PetscErrorCode TaoGetObjective(Tao tao, PetscErrorCode (**func)(Tao tao, Vec x, PetscReal *f, PetscCtx ctx), PetscCtxRt ctx)
296: {
297: PetscFunctionBegin;
299: if (func || ctx) PetscCall(TaoTermCallbacksGetObjective(tao->callbacks, func, ctx));
300: PetscFunctionReturn(PETSC_SUCCESS);
301: }
303: /*@
304: TaoSetResidualRoutine - Sets the residual evaluation routine for least-square applications
306: Logically Collective
308: Input Parameters:
309: + tao - the `Tao` context
310: . res - the residual vector
311: . func - the residual evaluation routine
312: - ctx - [optional] user-defined context for private data for the function evaluation
313: routine (may be `NULL`)
315: Calling sequence of `func`:
316: + tao - the optimizer
317: . x - input vector
318: . res - function value vector
319: - ctx - [optional] user-defined function context
321: Level: beginner
323: .seealso: [](ch_tao), `Tao`, `TaoSetObjective()`, `TaoSetJacobianRoutine()`
324: @*/
325: PetscErrorCode TaoSetResidualRoutine(Tao tao, Vec res, PetscErrorCode (*func)(Tao tao, Vec x, Vec res, PetscCtx ctx), PetscCtx ctx)
326: {
327: PetscFunctionBegin;
330: PetscCall(PetscObjectReference((PetscObject)res));
331: PetscCall(VecDestroy(&tao->ls_res));
332: tao->ls_res = res;
333: tao->user_lsresP = ctx;
334: tao->ops->computeresidual = func;
335: PetscFunctionReturn(PETSC_SUCCESS);
336: }
338: /*@
339: TaoSetResidualWeights - Give weights for the residual values. A vector can be used if only diagonal terms are used, otherwise a matrix can be give.
341: Collective
343: Input Parameters:
344: + tao - the `Tao` context
345: . sigma_v - vector of weights (diagonal terms only)
346: . n - the number of weights (if using off-diagonal)
347: . rows - index list of rows for `sigma_v`
348: . cols - index list of columns for `sigma_v`
349: - vals - array of weights
351: Level: intermediate
353: Notes:
354: If this function is not provided, or if `sigma_v` and `vals` are both `NULL`, then the
355: identity matrix will be used for weights.
357: Either `sigma_v` or `vals` should be `NULL`
359: .seealso: [](ch_tao), `Tao`, `TaoSetResidualRoutine()`
360: @*/
361: PetscErrorCode TaoSetResidualWeights(Tao tao, Vec sigma_v, PetscInt n, PetscInt *rows, PetscInt *cols, PetscReal *vals)
362: {
363: PetscFunctionBegin;
366: PetscCall(PetscObjectReference((PetscObject)sigma_v));
367: PetscCall(VecDestroy(&tao->res_weights_v));
368: tao->res_weights_v = sigma_v;
369: if (vals) {
370: PetscCall(PetscFree(tao->res_weights_rows));
371: PetscCall(PetscFree(tao->res_weights_cols));
372: PetscCall(PetscFree(tao->res_weights_w));
373: PetscCall(PetscMalloc1(n, &tao->res_weights_rows));
374: PetscCall(PetscMalloc1(n, &tao->res_weights_cols));
375: PetscCall(PetscMalloc1(n, &tao->res_weights_w));
376: tao->res_weights_n = n;
377: for (PetscInt i = 0; i < n; i++) {
378: tao->res_weights_rows[i] = rows[i];
379: tao->res_weights_cols[i] = cols[i];
380: tao->res_weights_w[i] = vals[i];
381: }
382: } else {
383: tao->res_weights_n = 0;
384: tao->res_weights_rows = NULL;
385: tao->res_weights_cols = NULL;
386: }
387: PetscFunctionReturn(PETSC_SUCCESS);
388: }
390: /*@
391: TaoComputeResidual - Computes a least-squares residual vector at a given point
393: Collective
395: Input Parameters:
396: + tao - the `Tao` context
397: - X - input vector
399: Output Parameter:
400: . F - Objective vector at `X`
402: Level: advanced
404: Notes:
405: `TaoComputeResidual()` is typically used within the implementation of the optimization algorithm,
406: so most users would not generally call this routine themselves.
408: .seealso: [](ch_tao), `Tao`, `TaoSetResidualRoutine()`
409: @*/
410: PetscErrorCode TaoComputeResidual(Tao tao, Vec X, Vec F)
411: {
412: PetscFunctionBegin;
416: PetscCheckSameComm(tao, 1, X, 2);
417: PetscCheckSameComm(tao, 1, F, 3);
418: PetscCheck(tao->ops->computeresidual, PetscObjectComm((PetscObject)tao), PETSC_ERR_ARG_WRONGSTATE, "TaoSetResidualRoutine() has not been called");
419: PetscCall(PetscLogEventBegin(TAO_ResidualEval, tao, X, NULL, NULL));
420: PetscCallBack("Tao callback least-squares residual", (*tao->ops->computeresidual)(tao, X, F, tao->user_lsresP));
421: PetscCall(PetscLogEventEnd(TAO_ResidualEval, tao, X, NULL, NULL));
422: tao->nres++;
423: PetscCall(PetscInfo(tao, "TAO least-squares residual evaluation.\n"));
424: PetscFunctionReturn(PETSC_SUCCESS);
425: }
427: /*@
428: TaoSetGradient - Sets the gradient evaluation routine for the function to be optimized
430: Logically Collective
432: Input Parameters:
433: + tao - the `Tao` context
434: . g - [optional] the vector to internally hold the gradient computation
435: . func - the gradient function
436: - ctx - [optional] user-defined context for private data for the gradient evaluation
437: routine (may be `NULL`)
439: Calling sequence of `func`:
440: + tao - the optimization solver
441: . x - input vector
442: . g - gradient value (output)
443: - ctx - [optional] user-defined function context
445: Level: beginner
447: .seealso: [](ch_tao), `Tao`, `TaoSolve()`, `TaoSetObjective()`, `TaoSetHessian()`, `TaoSetObjectiveAndGradient()`, `TaoGetGradient()`
448: @*/
449: PetscErrorCode TaoSetGradient(Tao tao, Vec g, PetscErrorCode (*func)(Tao tao, Vec x, Vec g, PetscCtx ctx), PetscCtx ctx)
450: {
451: PetscFunctionBegin;
453: if (g) {
455: PetscCheckSameComm(tao, 1, g, 2);
456: PetscCall(PetscObjectReference((PetscObject)g));
457: PetscCall(VecDestroy(&tao->gradient));
458: tao->gradient = g;
459: }
460: PetscCall(TaoTermCallbacksSetGradient(tao->callbacks, func, ctx));
461: PetscFunctionReturn(PETSC_SUCCESS);
462: }
464: /*@
465: TaoGetGradient - Gets the gradient evaluation routine for the function being optimized
467: Not Collective
469: Input Parameter:
470: . tao - the `Tao` context
472: Output Parameters:
473: + g - the vector to internally hold the gradient computation
474: . func - the gradient function
475: - ctx - user-defined context for private data for the gradient evaluation routine
477: Calling sequence of `func`:
478: + tao - the optimizer
479: . x - input vector
480: . g - gradient value (output)
481: - ctx - [optional] user-defined function context
483: Level: beginner
485: Notes:
486: In addition to specifying an objective function using callbacks such as
487: `TaoSetObjective()` and `TaoSetGradient()`, users can specify
488: objective functions with `TaoAddTerm()`.
490: `TaoGetGradient()` will always return the callback specified with
491: `TaoSetGradient()`, even if the objective function has been changed by
492: calling `TaoAddTerm()`.
494: .seealso: [](ch_tao), `Tao`, `TaoSetObjective()`, `TaoSetHessian()`, `TaoSetObjectiveAndGradient()`, `TaoSetGradient()`
495: @*/
496: PetscErrorCode TaoGetGradient(Tao tao, Vec *g, PetscErrorCode (**func)(Tao tao, Vec x, Vec g, PetscCtx ctx), PetscCtxRt ctx)
497: {
498: PetscFunctionBegin;
500: if (g) *g = tao->gradient;
501: if (func || ctx) PetscCall(TaoTermCallbacksGetGradient(tao->callbacks, func, ctx));
502: PetscFunctionReturn(PETSC_SUCCESS);
503: }
505: /*@
506: TaoSetObjectiveAndGradient - Sets a combined objective function and gradient evaluation routine for the function to be optimized
508: Logically Collective
510: Input Parameters:
511: + tao - the `Tao` context
512: . g - [optional] the vector to internally hold the gradient computation
513: . func - the gradient function
514: - ctx - [optional] user-defined context for private data for the gradient evaluation
515: routine (may be `NULL`)
517: Calling sequence of `func`:
518: + tao - the optimization object
519: . x - input vector
520: . f - objective value (output)
521: . g - gradient value (output)
522: - ctx - [optional] user-defined function context
524: Level: beginner
526: Note:
527: For some optimization methods using a combined function can be more efficient.
529: .seealso: [](ch_tao), `Tao`, `TaoSolve()`, `TaoSetObjective()`, `TaoSetHessian()`, `TaoSetGradient()`, `TaoGetObjectiveAndGradient()`
530: @*/
531: PetscErrorCode TaoSetObjectiveAndGradient(Tao tao, Vec g, PetscErrorCode (*func)(Tao tao, Vec x, PetscReal *f, Vec g, PetscCtx ctx), PetscCtx ctx)
532: {
533: PetscFunctionBegin;
535: if (g) {
537: PetscCheckSameComm(tao, 1, g, 2);
538: PetscCall(PetscObjectReference((PetscObject)g));
539: PetscCall(VecDestroy(&tao->gradient));
540: tao->gradient = g;
541: }
542: PetscCall(TaoTermCallbacksSetObjectiveAndGradient(tao->callbacks, func, ctx));
543: PetscFunctionReturn(PETSC_SUCCESS);
544: }
546: /*@
547: TaoGetObjectiveAndGradient - Gets the combined objective function and gradient evaluation routine for the function to be optimized
549: Not Collective
551: Input Parameter:
552: . tao - the `Tao` context
554: Output Parameters:
555: + g - the vector to internally hold the gradient computation
556: . func - the gradient function
557: - ctx - user-defined context for private data for the gradient evaluation routine
559: Calling sequence of `func`:
560: + tao - the optimizer
561: . x - input vector
562: . f - objective value (output)
563: . g - gradient value (output)
564: - ctx - [optional] user-defined function context
566: Level: beginner
568: Note:
569: In addition to specifying an objective function using callbacks such as
570: `TaoSetObjectiveAndGradient()`, users can specify
571: objective functions with `TaoAddTerm()`.
573: `TaoGetObjectiveAndGradient()` will always return the callback specified with
574: `TaoSetObjectiveAndGradient()`, even if the objective function has been changed by
575: calling `TaoAddTerm()`.
577: .seealso: [](ch_tao), `Tao`, `TaoSolve()`, `TaoSetObjective()`, `TaoSetGradient()`, `TaoSetHessian()`, `TaoSetObjectiveAndGradient()`
578: @*/
579: PetscErrorCode TaoGetObjectiveAndGradient(Tao tao, Vec *g, PetscErrorCode (**func)(Tao tao, Vec x, PetscReal *f, Vec g, PetscCtx ctx), PetscCtxRt ctx)
580: {
581: PetscFunctionBegin;
583: if (g) *g = tao->gradient;
584: if (func || ctx) PetscCall(TaoTermCallbacksGetObjectiveAndGradient(tao->callbacks, func, ctx));
585: PetscFunctionReturn(PETSC_SUCCESS);
586: }
588: /*@
589: TaoIsObjectiveDefined - Checks to see if the user has
590: declared an objective-only routine. Useful for determining when
591: it is appropriate to call `TaoComputeObjective()` or
592: `TaoComputeObjectiveAndGradient()`
594: Not Collective
596: Input Parameter:
597: . tao - the `Tao` context
599: Output Parameter:
600: . flg - `PETSC_TRUE` if the `Tao` has this routine `PETSC_FALSE` otherwise
602: Level: developer
604: Note:
605: If the objective of `Tao` has been altered via `TaoAddTerm()`, it will
606: return whether the summation of all terms has this routine.
608: .seealso: [](ch_tao), `Tao`, `TaoSetObjective()`, `TaoIsGradientDefined()`, `TaoIsObjectiveAndGradientDefined()`
609: @*/
610: PetscErrorCode TaoIsObjectiveDefined(Tao tao, PetscBool *flg)
611: {
612: PetscFunctionBegin;
614: PetscCall(TaoTermIsObjectiveDefined(tao->objective_term.term, flg));
615: PetscFunctionReturn(PETSC_SUCCESS);
616: }
618: /*@
619: TaoIsGradientDefined - Checks to see if the user has
620: declared a gradient-only routine. Useful for determining when
621: it is appropriate to call `TaoComputeGradient()` or
622: `TaoComputeObjectiveAndGradient()`
624: Not Collective
626: Input Parameter:
627: . tao - the `Tao` context
629: Output Parameter:
630: . flg - `PETSC_TRUE` if the objective `TaoTerm` has this routine, `PETSC_FALSE` otherwise
632: Level: developer
634: Note:
635: If the objective of `Tao` has been altered via `TaoAddTerm()`, it will
636: return whether the summation of all terms has this routine.
638: .seealso: [](ch_tao), `TaoSetGradient()`, `TaoIsObjectiveDefined()`, `TaoIsObjectiveAndGradientDefined()`
639: @*/
640: PetscErrorCode TaoIsGradientDefined(Tao tao, PetscBool *flg)
641: {
642: PetscFunctionBegin;
644: PetscCall(TaoTermIsGradientDefined(tao->objective_term.term, flg));
645: PetscFunctionReturn(PETSC_SUCCESS);
646: }
648: /*@
649: TaoIsObjectiveAndGradientDefined - Checks to see if the user has
650: declared a joint objective/gradient routine. Useful for determining when
651: it is appropriate to call `TaoComputeObjectiveAndGradient()`
653: Not Collective
655: Input Parameter:
656: . tao - the `Tao` context
658: Output Parameter:
659: . flg - `PETSC_TRUE` if the objective `TaoTerm` has this routine `PETSC_FALSE` otherwise
661: Level: developer
663: Note:
664: If the objective of `Tao` has been altered via `TaoAddTerm()`, it will
665: return whether the summation of all terms has this routine.
667: .seealso: [](ch_tao), `TaoSetObjectiveAndGradient()`, `TaoIsObjectiveDefined()`, `TaoIsGradientDefined()`
668: @*/
669: PetscErrorCode TaoIsObjectiveAndGradientDefined(Tao tao, PetscBool *flg)
670: {
671: PetscFunctionBegin;
673: PetscCall(TaoTermIsObjectiveAndGradientDefined(tao->objective_term.term, flg));
674: PetscFunctionReturn(PETSC_SUCCESS);
675: }