Actual source code: tao.c
1: /*$Id$*/
3: #include "src/tao_impl.h" /*I "tao_solver.h" I*/
8: /*@C
9: TaoMonitor - Monitor the solver and the current solution. This
10: routine will calls the records the iteration number and residual statistics,
11: monitors specified by the user, and calls the termaination routine.
13: Input Parameters:
14: + tao - the TAO_SOLVER context
15: . f - the current objective function value
16: . iterate - the current iterate number (>=0)
17: . fnorm - the gradient norm, square root of the duality gap, or other measure
18: indicating distince from optimality. This measure will be recorded and
19: used for some termination tests.
20: . cnorm - the infeasibility of the current solution with regard to the constraints.
21: - step - multiple of the step direction added to the previous iterate.
23: Output Parameters:
24: . reason - The termination reason, which can equal TAO_CONTINUE_ITERATING
26: Options Database Key:
27: . -tao_monitor - The default monitor, which prints statistics to standard output is used.
29: .seealso TaoGetTerminationReason(),TaoGetSolutionStatus()
31: Level: developer
33: .keywords: Monitor, convergence
34: @*/
35: int TaoMonitor(TAO_SOLVER tao, TaoInt iterate, double f, double fnorm, double cnorm, double step, TaoTerminateReason *reason)
36: {
37: int info;
38: TaoInt i;
39: TaoTruth cstop;
40: TaoFunctionBegin;
41: if (iterate>=tao->iter){
42: TaoLogConvHistory(tao,fnorm,tao->iter);
43: tao->norm=fnorm; tao->cnorm=cnorm; tao->fc=f;
44: tao->iter=TaoMax(tao->iter,iterate);
45: tao->step=step;
46: }
47: if (iterate==0){
48: tao->norm0=fnorm; tao->cnorm0=cnorm;
49: }
50: info=TaoCheckConvergence(tao,&tao->reason);CHKERRQ(info);
51: if (iterate>0){
52: info=tao->taoappl->Monitor2(tao->vec_sol,tao->vec_grad,tao->vec_sol_update,&cstop);CHKERRQ(info);
53: if (cstop==TAO_TRUE) tao->reason=TAO_CONVERGED_USER;
54: }
55: for ( i=0; i<tao->numbermonitors; i++ ) {
56: info = (*tao->monitor[i])(tao,tao->monitorcontext[i]);CHKERRQ(info);
57: }
58: info=tao->taoappl->Monitor();CHKERRQ(info);
59: *reason = tao->reason;
61: TaoFunctionReturn(0);
62: }
67: /*@C
68: TaoGetSolutionStatus - Get the current iterate, objective value, residual,
69: infeasibility, and termination
71: Input Parameters:
72: . tao - the TAO_SOLVER context
74: Output Parameters:
75: + iterate - the current iterate number (>=0)
76: . f - the current function value
77: . gnorm - the square of the gradient norm, duality gap, or other measure
78: indicating distance from optimality.
79: . cnorm - the infeasibility of the current solution with regard to the constraints.
80: . xdiff - the step length or trust region radius of the most recent iterate.
81: - reason - The termination reason, which can equal TAO_CONTINUE_ITERATING
83: Level: intermediate
85: Note:
86: TAO returns the values set by the solvers in the routine TaoMonitor().
88: Note:
89: If any of the output arguments are set to TAO_NULL, no value will be
90: returned.
93: .seealso: TaoMonitor(), TaoGetTerminationReason()
95: .keywords: convergence, monitor
96: @*/
97: int TaoGetSolutionStatus(TAO_SOLVER tao, TaoInt* iterate, double* f, double* gnorm, double *cnorm, double *xdiff, TaoTerminateReason *reason)
98: {
100: TaoFunctionBegin;
101: if (iterate) *iterate=tao->iter;
102: if (f) *f=tao->fc;
103: if (gnorm) *gnorm=tao->norm;
104: if (cnorm) *cnorm=tao->cnorm;
105: if (reason) *reason=tao->reason;
106: if (xdiff) *xdiff=tao->step;
108: TaoFunctionReturn(0);
109: }
114: /*@C
116: TaoCheckConvergence - Checks the convergence of the solver
118: Collective on TAO_SOLVER
120: Input Parameters:
121: . tao - the TAO_SOLVER context
123: Output Parameters:
124: . reason - one of
126: $ TAO_CONVERGED_ATOL (2), (res <= atol)
127: $ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol)
128: $ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol)
129: $ TAO_CONVERGED_MINF (5), (f <= fmin)
130: $ TAO_CONVERGED_USER (6), (user defined)
132: $ TAO_DIVERGED_MAXITS (-2), (its>maxits)
133: $ TAO_DIVERGED_NAN (-4), (Numerical problems)
134: $ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts)
135: $ TAO_DIVERGED_LS_FAILURE (-6), (line search failure)
136: $ TAO_DIVERGED_TR_REDUCTION (-7),
137: $ TAO_DIVERGED_USER (-8), (user defined)
139: $ TAO_CONTINUE_ITERATING (0)
141: where
142: + res - residual of optimality conditions
143: . res0 - initial residual of optimality conditions
144: . xdiff - current trust region size
145: . f - function value
146: . atol - absolute tolerance
147: . rtol - relative tolerance
148: . its - current iterate number
149: . maxits - maximum number of iterates
150: . nfunc - number of function evaluations
151: - maxnfuncts - maximum number of function evaluations
154: Level: advanced
156: .seealso: TaoGetTerminationReason()
158: .keywords: Convergence
160: @*/
161: int TaoCheckConvergence(TAO_SOLVER tao, TaoTerminateReason *reason)
162: {
163: int info;
165: TaoFunctionBegin;
166: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
167: if (tao->converged){
168: info = (*tao->converged)(tao,tao->cnvP);CHKERRQ(info);
169: }
170: if (reason) *reason=tao->reason;
172: TaoFunctionReturn(0);
173: }
177: /*@
178: TaoView - Prints the TAO_SOLVER data structure.
180: Collective on TAO_SOLVER
182: Input Parameters:
183: . tao - the TAO_SOLVER context
185: Options Database Key:
186: . -tao_view - Calls TaoView() at end of TaoSolve()
188: Level: beginner
190: .seealso: TaoGetTerminationReason(), TaoGetSolutionStatus(), TaoViewLinearSolver()
192: .keywords: View
194: @*/
195: int TaoView(TAO_SOLVER tao)
196: {
197: int info;
198: TaoMethod type;
200: TaoFunctionBegin;
201: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
203: info = TaoPrintStatement(tao,"TAO_SOLVER:\n");CHKERRQ(info);
204: info = TaoGetMethod(tao,&type);CHKERRQ(info);
205: if (type) {
206: info = TaoPrintString(tao," method: %s\n",type);CHKERRQ(info);
207: } else {
208: info = TaoPrintStatement(tao," method: not set yet\n");CHKERRQ(info);
209: }
210: if (tao->view) {
211: info = (*tao->view)(tao,tao->data);CHKERRQ(info);
212: }
213:
214: info=TaoPrintDouble(tao," convergence tolerances: fatol=%g,",tao->fatol);CHKERRQ(info);
215: info=TaoPrintDouble(tao," frtol=%g\n",tao->frtol);CHKERRQ(info);
217: info=TaoPrintDouble(tao," convergence tolerances: gatol=%g,",tao->gatol);CHKERRQ(info);
218: info=TaoPrintDouble(tao," trtol=%g,",tao->trtol);CHKERRQ(info);
219: info=TaoPrintDouble(tao," gttol=%g\n",tao->gttol);CHKERRQ(info);
221: info = TaoPrintDouble(tao," Residual in Function/Gradient:=%e\n",tao->norm);CHKERRQ(info);
223: if (tao->cnorm>0 || tao->catol>0 || tao->crtol>0){
224: info=TaoPrintStatement(tao," convergence tolerances:");CHKERRQ(info);
225: info=TaoPrintDouble(tao," catol=%g,",tao->catol);CHKERRQ(info);
226: info=TaoPrintDouble(tao," crtol=%g\n",tao->crtol);CHKERRQ(info);
227: info = TaoPrintDouble(tao," Residual in Constraints:=%e\n",tao->cnorm);CHKERRQ(info);
228: }
230: if (tao->trtol>0){
231: info=TaoPrintDouble(tao," convergence tolerances: trtol=%g\n",tao->trtol);CHKERRQ(info);
232: info=TaoPrintDouble(tao," Final step size/trust region radius:=%g\n",tao->step);CHKERRQ(info);
233: }
235: if (tao->fmin>-1.e25){
236: info=TaoPrintDouble(tao," convergence tolerances: function minimum=%g\n",tao->fmin);CHKERRQ(info);
237: }
238: info = TaoPrintDouble(tao," Objective value=%e\n",tao->fc);CHKERRQ(info);
240: info = TaoPrintInt(tao," total number of iterations=%d, ",tao->iter);CHKERRQ(info);
241: info = TaoPrintInt(tao," (max: %d)\n",tao->max_its);CHKERRQ(info);
243: if (tao->nfuncs>0){
244: info = TaoPrintInt(tao," total number of function evaluations=%d,",tao->nfuncs);CHKERRQ(info);
245: info = TaoPrintInt(tao," max: %d\n",tao->max_funcs);CHKERRQ(info);
246: }
247: if (tao->ngrads>0){
248: info = TaoPrintInt(tao," total number of gradient evaluations=%d,",tao->ngrads);CHKERRQ(info);
249: info = TaoPrintInt(tao," max: %d\n",tao->max_funcs);CHKERRQ(info);
250: }
251: if (tao->nfgrads>0){
252: info = TaoPrintInt(tao," total number of function/gradient evaluations=%d,",tao->nfgrads);CHKERRQ(info);
253: info = TaoPrintInt(tao," (max: %d)\n",tao->max_funcs);CHKERRQ(info);
254: }
255: if (tao->nhesss>0){
256: info = TaoPrintInt(tao," total number of Hessian evaluations=%d\n",tao->nhesss);CHKERRQ(info);
257: }
258: if (tao->linear_its>0){
259: info = TaoPrintInt(tao," total Krylov method iterations=%d\n",tao->linear_its);CHKERRQ(info);
260: }
261: if (tao->nvfunc>0){
262: info = TaoPrintInt(tao," total number of constraint function evaluations=%d\n",tao->nvfunc);CHKERRQ(info);
263: }
264: if (tao->njac>0){
265: info = TaoPrintInt(tao," total number of Jacobian evaluations=%d\n",tao->njac);CHKERRQ(info);
266: }
268: if (tao->reason>0){
269: info = TaoPrintStatement(tao," Solution found\n");CHKERRQ(info);
270: } else {
271: info = TaoPrintInt(tao," Solver terminated: %d\n",tao->reason);CHKERRQ(info);
272: }
274: TaoFunctionReturn(0);
275: }
279: /* ----------- Routines to set solver parameters ---------- */
283: /*@
284: TaoSetGradientTolerances - Sets the stopping criteria in terms of the norm
285: of the Lagrangian function. The algorithm will terminate when the norm
286: of the gradient is less that the absolute tolerance, or when the norm
287: of the gradient has been reduced by a factor of the reduction tolerance,
288: or when the norm of the gradient divided by the absolute value of the
289: objective function is less than the relative tolerance.
291: Collective on TAO_SOLVER
293: Input Parameters:
294: + tao - the TAO_SOLVER solver context
295: . gatol - stop if norm of gradient is less than
296: . grtol - stop if relative norm of gradient is less than
297: - gttol - stop if norm of gradient is reduced by a factor of
299: Options Database Keys:
300: + -tao_gatol <gatol> - sets gatol
301: . -tao_grtol <grtol> - sets grtol
302: - -tao_gttol <gttol> - sets gttol
304: Level: intermediate
306: .keywords: Gradient, options, convergence
308: .seealso: TaoSetTolerances(), TaoGetGradientTolerances()
309: @*/
310: int TaoSetGradientTolerances(TAO_SOLVER tao,double gatol, double grtol, double gttol)
311: {
312: int info;
313: double zero=0.0;
314: TaoFunctionBegin;
315: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
317: if (gatol==TAO_DEFAULT){}
318: else if (gatol<0){
319: info=PetscInfo(tao,"Absolute Gradient tolerance < 0 and ignored"); CHKERRQ(info);
320: CHKERRQ(info); }
321: else{
322: tao->gatol = TaoMax(zero,gatol);
323: }
325: if (grtol==TAO_DEFAULT){}
326: else if (grtol<0){
327: info=PetscInfo(tao,"Relative Gradient tolerance < 0 and ignored");
328: CHKERRQ(info); }
329: else{
330: tao->grtol = TaoMax(zero,grtol);
331: }
333: if (gttol==TAO_DEFAULT){}
334: else if (gttol<0){
335: info=PetscInfo(tao,"Gradient reduction tolerance < 0 and ignored");
336: CHKERRQ(info); }
337: else{
338: tao->gttol = TaoMax(zero,gttol);
339: }
342: TaoFunctionReturn(0);
343: }
345: /* ----------- Routines to set solver parameters ---------- */
349: /*@
350: TaoGetGradientTolerances - Returns the gradient termination tolerances.
352: Collective on TAO_SOLVER
354: Input Parameters:
355: . tao - the TAO_SOLVER tao context
357: Output Parameters:
358: + gatol - the absolute gradient tolerance
359: . grtol - the relative gradient tolerance
360: - gttol - the gradient reduction tolerance
362: Level: intermediate
364: .keywords: options, convergence, View
366: .seealso: TaoSetGradientTolerances()
367: @*/
368: int TaoGetGradientTolerances(TAO_SOLVER tao,double *gatol, double *grtol, double *gttol)
369: {
370: TaoFunctionBegin;
371: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
372: if (gatol) *gatol = tao->gatol;
373: if (grtol) *grtol = tao->grtol;
374: if (gttol) *gttol = tao->gttol;
375: TaoFunctionReturn(0);
376: }
380: /*@
381: TaoSetFunctionLowerBound - Sets a bound on the solution objective value.
382: When an approximate solution with an objective value below this number
383: has been found, the solver will terminate.
385: Collective on TAO_SOLVER
387: Input Parameters:
388: + tao - the TAO_SOLVER solver context
389: - fmin - the tolerance
391: Options Database Keys:
392: . -tao_fmin <fmin> - sets the minimum function value
394: Level: intermediate
396: .keywords: options, View, Bounds,
398: .seealso: TaoSetTolerances()
399: @*/
400: int TaoSetFunctionLowerBound(TAO_SOLVER tao,double fmin)
401: {
402: double dflt=-1.0e+30;
403: TaoFunctionBegin;
404: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
405: if (fmin != TAO_DEFAULT) tao->fmin = fmin;
406: else tao->fmin=dflt;
407: TaoFunctionReturn(0);
408: }
413: /*@
414: TaoSetMaximumIterates - Sets a maximum number of iterates.
416: Collective on TAO_SOLVER
418: Input Parameters:
419: + tao - the TAO_SOLVER solver context
420: - maxits - the maximum number of iterates (>=0)
422: Options Database Keys:
423: . -tao_max_its <its> - sets the maximum number of iterations
425: Level: intermediate
427: .keywords: options, Iterate, convergence
429: .seealso: TaoSetTolerances(), TaoSetMaximumFunctionEvaluations()
430: @*/
431: int TaoSetMaximumIterates(TAO_SOLVER tao,TaoInt maxits)
432: {
433: TaoInt zero=0;
434: TaoFunctionBegin;
435: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
436: if (maxits != TAO_DEFAULT) tao->max_its = TaoMax(zero,maxits);
437: TaoFunctionReturn(0);
438: }
443: /*@
444: TaoSetMaximumFunctionEvaluations - Sets a maximum number of
445: function evaluations.
447: Collective on TAO_SOLVER
449: Input Parameters:
450: + tao - the TAO_SOLVER solver context
451: - nfcn - the maximum number of function evaluations (>=0)
453: Options Database Keys:
454: . -tao_max_funcs <nfcn> - sets the maximum number of function evaluations
456: Level: intermediate
458: .keywords: options, Iterate, convergence
460: .seealso: TaoSetTolerances(), TaoSetMaximumIterates()
461: @*/
462: int TaoSetMaximumFunctionEvaluations(TAO_SOLVER tao,TaoInt nfcn)
463: {
464: int zero=0;
465: TaoFunctionBegin;
466: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
467: if (nfcn != TAO_DEFAULT) tao->max_funcs = TaoMax(zero,nfcn);
468: TaoFunctionReturn(0);
469: }
474: /*@
475: TaoSetTolerances - Sets convergence parameters. TAO tries to satisfy an
476: absolute stopping criteria or a relative stopping criteria.
477:
478: Collective on TAO_SOLVER
480: Input Parameters:
481: + tao - the TAO_SOLVER solver context
482: . fatol - absolute convergence tolerance
483: . frtol - relative convergence tolerance
484: . catol - allowable error in constraints
485: - crtol - allowable relative error in constraints
487: Options Database Keys:
488: + -tao_fatol <fatol> - Sets fatol
489: . -tao_frtol <frtol> - Sets frtol
490: . -tao_catol <catol> - Sets catol
491: - -tao_crtol <crtol> - Sets crtol
493: Absolute Stopping Criteria:
494: $ f <= f + fatol
495: $ B1 - catol <= B(X) <= B2 + catol
497: Relative stopping criteria:
498: $ f <= f + frtol*|f|
499: $ B1 - catol <= B(X) <= B2 + catol
501: Level: beginner
503: .keywords: options, convergence
505: .seealso: TaoSetMaximumIterates(),TaoSetTrustRegionTolerance(), TaoSetGradientTolerances
506: TaoSetMaximumFunctionEvaluations()
507: @*/
508: int TaoSetTolerances(TAO_SOLVER tao,double fatol,double frtol,double catol,double crtol)
509: {
510: int info;
511: double zero=0.0;
512: TaoFunctionBegin;
513: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
515: if (fatol==TAO_DEFAULT){}
516: else if (fatol<0){
517: info=PetscInfo(tao,"Absolute convergence tolerance < 0 and ignored");
518: CHKERRQ(info); }
519: else{
520: tao->fatol = TaoMax(zero,fatol);
521: }
523: if (frtol==TAO_DEFAULT){}
524: else if (frtol<0){
525: info=PetscInfo(tao,"Relative convergence tolerance < 0 and ignored");
526: CHKERRQ(info); }
527: else{
528: tao->frtol = TaoMax(zero,frtol);
529: }
531: if (catol==TAO_DEFAULT){}
532: else if (catol<0){
533: info=PetscInfo(tao,"Absolute constraint tolerance < 0 and ignored");
534: CHKERRQ(info); }
535: else{
536: tao->catol = TaoMax(zero,catol);
537: }
539: if (crtol==TAO_DEFAULT){}
540: else if (crtol<0){
541: info=PetscInfo(tao,"Relative constraint tolerance < 0 and ignored");
542: CHKERRQ(info); }
543: else{
544: tao->crtol = TaoMax(zero,crtol);
545: }
547: TaoFunctionReturn(0);
548: }
554: /*@
555: TaoGetTolerances - Gets convergence parameters.
556:
558: Collective on TAO_SOLVER
560: Input Parameters:
561: . tao - the TAO_SOLVER solver context
563: Input Parameters:
564: + fatol - absolute convergence tolerance
565: . frtol - relative convergence tolerance
566: . catol - trust region convergence tolerance
567: - crtol - convergence of the function evaluates less than this tolerance
569: Level: advanced
571: .keywords: options, convergence
573: .seealso: TaoSetTolerances
574: @*/
575: int TaoGetTolerances(TAO_SOLVER tao,double *fatol,double *frtol,double *catol,double *crtol)
576: {
577: TaoFunctionBegin;
578: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
579: if (fatol) *fatol = tao->fatol;
580: if (frtol) *frtol = tao->frtol;
581: if (catol) *catol = tao->catol;
582: if (crtol) *crtol = tao->crtol;
583: TaoFunctionReturn(0);
584: }
587: /* ------------ Routines to set performance monitoring options ----------- */
591: /*@C
592: TaoSetMonitor - Sets an ADDITIONAL function that is to be used at every
593: iteration of the unconstrained minimization solver to display the iteration's
594: progress.
596: Collective on TAO_SOLVER
598: Input Parameters:
599: + tao - the TAO_SOLVER solver context
600: . mymonitor - monitoring routine
601: - mctx - [optional] user-defined context for private data for the
602: monitor routine (may be TAO_NULL)
604: Calling sequence of mymonitor:
605: $ int mymonitor(TAO_SOLVER tao,void *mctx)
607: + tao - the TAO_SOLVER solver context
608: - mctx - [optional] monitoring context
611: Options Database Keys:
612: + -tao_monitor - sets TaoDefaultMonitor()
613: . -tao_smonitor - sets short monitor
614: - -tao_cancelmonitors - cancels all monitors that have been hardwired into a code by calls to TaoSetMonitor(), but does not cancel those set via the options database.
616: Notes:
617: Several different monitoring routines may be set by calling
618: TaoSetMonitor() multiple times; all will be called in the
619: order in which they were set.
621: Level: intermediate
623: .keywords: options, monitor, View
625: .seealso: TaoDefaultMonitor(), TaoClearMonitor(), TaoSetDestroyRoutine()
626: @*/
627: int TaoSetMonitor(TAO_SOLVER tao,int (*mymonitor)(TAO_SOLVER,void*),void *mctx)
628: {
629: TaoFunctionBegin;
630: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
631: if (tao->numbermonitors >= MAX_TAO_MONITORS) {
632: SETERRQ(1,"Too many monitors set");
633: }
635: tao->monitor[tao->numbermonitors] = mymonitor;
636: tao->monitorcontext[tao->numbermonitors++] = (void*)mctx;
637: TaoFunctionReturn(0);
638: }
642: /*@
643: TaoClearMonitor - Clears all the monitor functions for a TAO_SOLVER object.
645: Collective on TAO_SOLVER
647: Input Parameters:
648: . tao - the TAO_SOLVER solver context
650: Options Database:
651: . -tao_cancelmonitors - cancels all monitors that have been hardwired
652: into a code by calls to TaoSetMonitor(), but does not cancel those
653: set via the options database
655: Notes:
656: There is no way to clear one specific monitor from a TAO_SOLVER object.
658: Level: advanced
660: .keywords: options, monitor, View
662: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
663: @*/
664: int TaoClearMonitor(TAO_SOLVER tao)
665: {
666: TaoFunctionBegin;
667: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
668: tao->numbermonitors = 0;
669: TaoFunctionReturn(0);
670: }
674: /*@C
675: TaoSetConvergenceTest - Sets the function that is to be used
676: to test for convergence of the iterative minimization solution. The
677: new convergence testing routine will replace TAO's default
678: convergence test.
680: Collective on TAO_SOLVER
682: Input Parameters:
683: + tao - the TAO_SOLVER solver context
684: . conv - routine to test for convergence
685: - cctx - [optional] context for private data for the convergence routine
686: (may be TAO_NULL)
688: Calling sequence of conv:
689: $ int conv (TAO_SOLVER tao, void *cctx)
691: + tao - the TAO_SOLVER solver context
692: - cctx - [optional] convergence context
694: Note: The new convergence testing routine should call TaoSetTerminationReason().
696: Level: intermediate
698: .keywords: options, convergence
700: .seealso: TaoSetTerminationReason(), TaoGetSolutionStatus(), TaoGetTolerances(), TaoGetGradientTolerances()
702: @*/
703: int TaoSetConvergenceTest(TAO_SOLVER tao,int (*conv)(TAO_SOLVER,void*),void *cctx)
704: {
705: TaoFunctionBegin;
706: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
707: (tao)->converged = conv;
708: (tao)->cnvP = cctx;
709: TaoFunctionReturn(0);
710: }
715: /*@C
716: TaoGetTerminationReason - Gets the reason the TAO_SOLVER iteration was stopped.
718: Not Collective
720: Input Parameter:
721: . tao - the TAO_SOLVER solver context
723: Output Parameter:
724: . reason - one of
726: $ TAO_CONVERGED_ATOL (2), (res <= atol)
727: $ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol)
728: $ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol)
729: $ TAO_CONVERGED_MINF (5), (f <= fmin)
730: $ TAO_CONVERGED_USER (6), (user defined)
732: $ TAO_DIVERGED_MAXITS (-2), (its>maxits)
733: $ TAO_DIVERGED_NAN (-4), (Numerical problems)
734: $ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts)
735: $ TAO_DIVERGED_LS_FAILURE (-6), (line search failure)
736: $ TAO_DIVERGED_TR_REDUCTION (-7),
737: $ TAO_DIVERGED_USER (-8), (user defined)
739: $ TAO_CONTINUE_ITERATING (0)
741: where
742: + res - residual of optimality conditions
743: . res0 - initial residual of optimality conditions
744: . xdiff - current trust region size
745: . f - function value
746: . atol - absolute tolerance
747: . rtol - relative tolerance
748: . its - current iterate number
749: . maxits - maximum number of iterates
750: . nfunc - number of function evaluations
751: - maxnfuncts - maximum number of function evaluations
753: Level: intermediate
755: .keywords: convergence, View
757: .seealso: TaoSetConvergenceTest(), TaoSetTolerances()
758: @*/
759: int TaoGetTerminationReason(TAO_SOLVER tao,TaoTerminateReason *reason)
760: {
761: TaoFunctionBegin;
762: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
763: *reason = tao->reason;
764: TaoFunctionReturn(0);
765: }
769: /*@
770: TaoSetConvergenceHistory - Sets the array used to hold the convergence history.
772: Collective on TAO_SOLVER
774: Input Parameters:
775: + tao - the TAO_SOLVER solver context
776: . a - array to hold history
777: . its - integer array holds the number of linear iterations (or
778: negative if not converged) for each solve.
779: . na - size of a and its
780: - reset - TAO_TRUE indicates each new minimization resets the history counter to zero,
781: else it continues storing new values for new minimizations after the old ones
783: Notes:
784: If set, this array will contain the gradient norms computed at each step.
786: This routine is useful, e.g., when running a code for purposes
787: of accurate performance monitoring, when no I/O should be done
788: during the section of code that is being timed.
790: Level: intermediate
792: .keywords: options, view, monitor, convergence, history
794: .seealso: TaoGetConvergenceHistory()
796: @*/
797: int TaoSetConvergenceHistory(TAO_SOLVER tao, double *a, TaoInt *its,TaoInt na,TaoTruth reset)
798: {
799: TaoFunctionBegin;
800: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
801: if (na) TaoValidScalarPointer(a,2);
802: tao->conv_hist = a;
803: tao->conv_hist_its = its;
804: tao->conv_hist_max = na;
805: tao->conv_hist_reset = reset;
806: TaoFunctionReturn(0);
807: }
811: /*@C
812: TaoGetConvergenceHistory - Gets the array used to hold the convergence history.
814: Collective on TAO_SOLVER
816: Input Parameter:
817: . tao - the TAO_SOLVER solver context
819: Output Parameters:
820: + a - array to hold history
821: . its - integer array holds the number of linear iterations (or
822: negative if not converged) for each solve.
823: - na - size of a and its
825: Notes:
826: The calling sequence for this routine in Fortran is
827: $ call TaoGetConvergenceHistory(TAO_SOLVER tao, integer na, integer info)
829: This routine is useful, e.g., when running a code for purposes
830: of accurate performance monitoring, when no I/O should be done
831: during the section of code that is being timed.
833: Level: advanced
835: .keywords: convergence, history, monitor, View
837: .seealso: TaoSetConvergencHistory()
839: @*/
840: int TaoGetConvergenceHistory(TAO_SOLVER tao, double **a, TaoInt **its,TaoInt *na)
841: {
842: TaoFunctionBegin;
843: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
844: if (a) *a = tao->conv_hist;
845: if (its) *its = tao->conv_hist_its;
846: if (na) *na = tao->conv_hist_len;
847: TaoFunctionReturn(0);
848: }
853: /*@
854: TaoSolve - Solves an unconstrained minimization problem. Call TaoSolve()
855: after calling TaoCreate() and optional routines of the form TaoSetXXX().
857: Collective on TAO_SOLVER
859: Input Parameters:
860: . tao - the TAO_SOLVER solver context
862: Notes:
863: By default the TAO solvers use an initial starting guess of zero. To
864: provide an alternative initial guess, the user must call TaoAppSetInitialSolutionVec()
865: before calling TaoSolve().
867: Level: advanced
869: .keywords: Solve
871: .seealso: TaoCreate(), TaoDestroy()
872: @*/
873: int TaoSolve(TAO_SOLVER tao)
874: {
875: int info;
876: TaoVec *xx;
878: TaoFunctionBegin;
879: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
880: info = TaoGetSolution(tao,&xx);CHKERRQ(info);
881: info = tao->taoappl->InitializeVariables(xx);CHKERRQ(info);
882: info = TaoSetUp(tao);CHKERRQ(info);
883: info = TaoSetDefaultStatistics(tao); CHKERRQ(info);
884: if (tao->solve){ info = (*(tao)->solve)(tao,tao->data);CHKERRQ(info); }
885: if (tao->viewtao) { info = TaoView(tao);CHKERRQ(info); }
886: if (tao->viewksptao) { info = TaoViewLinearSolver(tao);CHKERRQ(info); }
887: TaoFunctionReturn(0);
888: }
893: /*@C
894: TaoGetMethod - Gets the TAO_SOLVER method type and name (as a string).
896: Not Collective
898: Input Parameter:
899: . tao - the TAO_SOLVER solver context
901: Output Parameter:
902: . type - TAO_SOLVER method (a charactor string)
904: Level: intermediate
906: .keywords: method
907: @*/
908: int TaoGetMethod(TAO_SOLVER tao, TaoMethod *type)
909: {
910: TaoFunctionBegin;
911: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
912: *type = ((PetscObject)tao)->type_name;
913: TaoFunctionReturn(0);
914: }
919: /*@C
920: TaoSetStepDirectionVector - Sets the vector where the solution update is
921: stored.
923: Not Collective, but Vec is parallel if TAO_SOLVER is parallel
925: Input Parameter:
926: + tao - the TAO_SOLVER solver context
927: - dx - the step direction vector
929: Level: developer
931: .keywords: solution, step direction
933: .seealso: TaoGetSolution(), TaoGetStepDirectionVector()
934: @*/
935: int TaoSetStepDirectionVector(TAO_SOLVER tao,TaoVec* dx)
936: {
937: TaoFunctionBegin;
938: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
939: tao->vec_sol_update=dx;
940: TaoFunctionReturn(0);
941: }
946: /*@C
947: TaoGetStepDirectionVector - Returns the vector where the solution update is
948: stored.
950: Not Collective, but Vec is parallel if TAO_SOLVER is parallel
952: Input Parameter:
953: . tao - the TAO_SOLVER solver context
955: Output Parameter:
956: . xx - the solution update
958: Level: developer
960: .keywords: solution
962: .seealso: TaoGetSolution()
963: @*/
964: int TaoGetStepDirectionVector(TAO_SOLVER tao,TaoVec** xx)
965: {
966: TaoFunctionBegin;
967: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
968: *xx = tao->vec_sol_update;
969: TaoFunctionReturn(0);
970: }
976: /*@
977: TaoSetTrustRegionTolerance - Sets a minimum step size or trust region radius. The
978: solver will terminate when the step size or radius of the trust region is smaller
979: than this tolerance.
980:
981: Collective on TAO_SOLVER
982:
983: Input Parameters:
984: + tao - the TAO_SOLVER solver context
985: - steptol - tolerance
986:
987: Options Database Key:
988: . -tao_steptol <trtol> - Sets steptol
989:
990: Level: intermediate
991:
992: .keywords: options, convergence, trust region
993:
994: .seealso: TaoSetTolerances()
995: @*/
996: int TaoSetTrustRegionTolerance(TAO_SOLVER tao,double steptol)
997: {
998: double zero=0.0, dflt=0.0;
1000: TaoFunctionBegin;
1001: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1002: if (steptol != TAO_DEFAULT) tao->xtol = TaoMax(zero,steptol);
1003: else tao->xtol=dflt;
1004: tao->trtol=steptol;
1005: TaoFunctionReturn(0);
1006: }
1010: /*@
1011: TaoGetTrustRegionRadius - Gets the current trust region radius
1013: Collective on TAO_SOLVER
1015: Input Parameter:
1016: . tao - a TAO optimization solver
1018: Output Parameter:
1019: . radius - the trust region radius
1021: Level: advanced
1023: .keywords: options, view, trust region
1025: .seealso: TaoSetTrustRegionRadius(), TaoSetTrustRegionTolerance()
1026: @*/
1027: int TaoGetTrustRegionRadius(TAO_SOLVER tao,double *radius)
1028: {
1029: TaoFunctionBegin;
1030: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1031: *radius=tao->step;
1032: TaoFunctionReturn(0);
1033: }
1036: /*@C
1037: TaoGetInitialTrustRegionRadius - Gets the initial trust region radius
1039: Collective on TAO_SOLVER
1041: Input Parameter:
1042: . tao - a TAO optimization solver
1044: Output Parameter:
1045: . radius - the initial trust region radius
1047: Level: intermediate
1049: .keywords: options, trust region
1051: .seealso: TaoGetTrustRegionRadius(), TaoSetTrustRegionRadius()
1052: @*/
1053: int TaoGetInitialTrustRegionRadius(TAO_SOLVER tao,double *radius)
1054: {
1055: TaoFunctionBegin;
1056: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1057: *radius=tao->trust0;
1058: TaoFunctionReturn(0);
1059: }
1063: /*@
1064: TaoSetTrustRegionRadius - Sets the initial trust region radius.
1066: Collective on TAO_SOLVER
1068: Input Parameter:
1069: + tao - a TAO optimization solver
1070: - radius - the trust region radius
1072: Level: intermediate
1074: Options Database Key:
1075: . -tao_trust0
1077: .keywords: trust region
1079: .seealso: TaoGetTrustRegionRadius(), TaoSetTrustRegionTolerance()
1080: @*/
1081: int TaoSetTrustRegionRadius(TAO_SOLVER tao,double radius)
1082: {
1083: TaoFunctionBegin;
1084: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1085: tao->trust0=radius;
1086: tao->step=radius;
1087: TaoFunctionReturn(0);
1088: }
1093: /*@
1094: TaoSetVariableBounds - Sets lower and upper bounds on the variables.
1096: Collective on TAO_SOLVER
1098: Input Parameters:
1099: + tao - the TAO_SOLVER solver context
1100: . xxll - vector of lower bounds upon the solution vector
1101: - xxuu - vector of upper bounds upon the solution vector
1103: Level: developer
1105: .keywords: bounds
1107: .seealso: TaoGetVariableBounds(), TaoAppSetVariableBounds()
1108: @*/
1109: int TaoSetVariableBounds(TAO_SOLVER tao,TaoVec *xxll,TaoVec *xxuu)
1110: {
1111: int info;
1112: double dd;
1113: TaoVec *xx;
1114: TaoTruth flag;
1116: TaoFunctionBegin;
1117: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1118: info=TaoGetSolution(tao,&xx);CHKERRQ(info);
1119: if (xxll){
1120: info=xx->Compatible(xxll,&flag); CHKERRQ(info);
1121: if (flag == TAO_FALSE){
1122: SETERRQ(1,"Vector of lower bounds not Compatible with Variable Vector");
1123: }
1124: if (tao->XL==0){
1125: dd=-TAO_INFINITY;
1126: info = xxll->SetToConstant(dd); CHKERRQ(info);
1127: }
1128: }
1129: if (xxuu){
1130: info=xx->Compatible(xxuu,&flag); CHKERRQ(info);
1131: if (flag == TAO_FALSE){
1132: SETERRQ(1,"Vector of upper bounds not Compatible with Variable vector");
1133: }
1134: if (tao->XU==0){
1135: dd= TAO_INFINITY;
1136: info = xxuu->SetToConstant(dd); CHKERRQ(info);
1137: }
1138: }
1139: tao->XL=xxll;
1140: tao->XU=xxuu;
1141: TaoFunctionReturn(0);
1142: }
1146: /*@
1147: TaoGetDualVariables - Gets the dual variables corresponding to
1148: the bounds of the variables.
1150: Collective on TAO_SOLVER
1152: Input Parameter:
1153: + tao - the TAO_SOLVER solver context
1154: . DXL - vector to place the dual variables of the lower bounds
1155: - DXU - vector to place the dual variables of the upper bounds
1157: Output Parameter:
1158: + DXL - dual variables of the lower bounds
1159: - DXU - dual variables of the upper bounds
1161: Level: advanced
1163: .keywords: dual, bounds
1165: .seealso: TaoGetVariableBounds()
1166: @*/
1167: int TaoGetDualVariables(TAO_SOLVER tao, TaoVec *DXL, TaoVec *DXU)
1168: {
1169: int info;
1170: TaoTruth flag;
1171: TaoVec *XL, *XU;
1173: TaoFunctionBegin;
1174: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1175: info=TaoGetVariableBounds(tao,&XL,&XU);CHKERRQ(info);
1177: info=DXU->Compatible(XU,&flag); CHKERRQ(info);
1178: if (flag == TAO_FALSE){
1179: SETERRQ(1,"Dual bound vectors not Compatible");
1180: }
1182: info=DXL->Compatible(XL,&flag); CHKERRQ(info);
1183: if (flag == TAO_FALSE){
1184: SETERRQ(1,"Dual bound vectors not Compatible");
1185: }
1187: if (tao->CopyDuals){
1188: info = (*tao->CopyDuals)(tao,DXL,DXU,tao->data);CHKERRQ(info);
1189: } else {
1190: info=DXL->SetToZero();CHKERRQ(info);
1191: info=DXU->SetToZero();CHKERRQ(info);
1192: }
1194: TaoFunctionReturn(0);
1195: }
1200: /* ---------------------------------------------------------- */
1201: /* @C
1202: TaoSetInitialVector - Sets the initial vector used by the TAO
1203: solver.
1205: Collective on TAO_SOLVER
1207: Input Parameters:
1208: + tao - the TAO solver
1209: - xx0 - vector used for initial point (set xx0==TAO_NULL for default)
1211: Notes:
1212: By default the TAO solvers use an initial starting guess of zero.
1213: To provide an alternative initial guess, the user must call
1214: TaoSetInitialVector() before calling TaoSolve().
1216: This vector will replace the variable vector set in the TaoCreate() routine.
1218: The user is responsible for destroying this vector.
1220: If this vector is TAO_NULL, TAO will use the set the previous variable
1221: vector to a default starting point.
1223: Level: developer
1225: .seealso: TaoSolve(), TaoGetSolution()
1226: @ */
1227: int TaoSetInitialVector(TAO_SOLVER tao,TaoVec *xx0)
1228: {
1229: int info;
1230: TaoTruth flag;
1231: TaoVec* X;
1233: TaoFunctionBegin;
1234: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1235: if (xx0==TAO_NULL){
1236: // tao->userstart=TAO_FALSE;
1237: } else {
1238: info=TaoGetSolution(tao,&X);CHKERRQ(info);
1239: info=X->Compatible(xx0,&flag);CHKERRQ(info);
1240: if (flag == TAO_FALSE){
1241: SETERRQ(1,"New TAO variable vector must have identical structure as the previous variable vector.");
1242: }
1243: tao->vec_sol=xx0;
1244: /* info=X->CopyFrom(xx0);CHKERRQ(info); */
1245: // tao->userstart=TAO_TRUE;
1246: }
1247: TaoFunctionReturn(0);
1248: }
1253: /*@C
1254: TaoGetVariableBounds - Sets the vector pointers to the vectors
1255: containing the upper and lower bounds on the variables.
1257: Collective on TAO_SOLVER
1259: Input Parameter:
1260: . tao - the TAO_SOLVER solver context
1262: Output Parameters:
1263: + xxll - Pointer to lower bounds on all the variables
1264: - xxuu - Pointer to upper bounds on all the variables
1266: Level: advanced
1268: .keywords: bounds, View
1270: @*/
1271: int TaoGetVariableBounds(TAO_SOLVER tao,TaoVec **xxll,TaoVec **xxuu)
1272: {
1273: TaoFunctionBegin;
1274: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1275: if (xxll){
1276: *xxll=tao->XL;
1277: }
1278: if (xxuu){
1279: *xxuu=tao->XU;
1280: }
1281: TaoFunctionReturn(0);
1282: }
1284: /* ---------------------------------------------------------- */
1287: /*@C
1288: TaoSetTerminationReason - Sets the termination reason
1290: Collective on TAO_SOLVER
1292: Input Parameters:
1293: + tao - the TAO_SOLVER context
1294: - reason - one of
1296: $ TAO_CONVERGED_ATOL (2), (res <= atol)
1297: $ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol)
1298: $ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol)
1299: $ TAO_CONVERGED_MINF (5), (f <= fmin)
1300: $ TAO_CONVERGED_USER (6), (user defined)
1302: $ TAO_DIVERGED_MAXITS (-2), (its>maxits)
1303: $ TAO_DIVERGED_NAN (-4), (Numerical problems)
1304: $ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts)
1305: $ TAO_DIVERGED_LS_FAILURE (-6), (line search failure)
1306: $ TAO_DIVERGED_TR_REDUCTION (-7),
1307: $ TAO_DIVERGED_USER (-8), (user defined)
1309: $ TAO_CONTINUE_ITERATING (0)
1311: where
1312: + res - residual of optimality conditions
1313: . res0 - initial residual of optimality conditions
1314: . xdiff - current trust region size
1315: . f - function value
1316: . atol - absolute tolerance
1317: . rtol - relative tolerance
1318: . its - current iterate number
1319: . maxits - maximum number of iterates
1320: . nfunc - number of function evaluations
1321: - maxnfuncts - maximum number of function evaluations
1324: Output Parameter:
1326: Level: intermediate
1328: .seealso TaoGetTerminationReason(), TaoAppSetMonitor(), TaoSetMonitor()
1330: .keywords: convergence
1332: @*/
1333: int TaoSetTerminationReason(TAO_SOLVER tao,TaoTerminateReason reason)
1334: {
1335: TaoFunctionBegin;
1336: TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
1338: tao->reason=reason;
1340: TaoFunctionReturn(0);
1341: }
1344: /* ------------ Routines to called when destroying this application ----------- */
1347: /*@C
1348: TaoSetDestroyRoutine - Sets an ADDITIONAL function that will be called when
1349: this object is destroyed.
1351: Collective on TAO_SOLVER
1353: Input Parameters:
1354: + taoapp - the TAO_SOLVER solver context
1355: . destroy - function pointer
1356: - mctx - [optional] user-defined context for private data for the
1357: destroy routine (may be TAO_NULL)
1359: Calling sequence of destroy:
1360: $ int mydestroy(void *mctx)
1362: . mctx - [optional] destroy context
1365: Level: intermediate
1367: .keywords: destroy
1369: .seealso: TaoSetMonitor(), TaoDestroy()
1370: @*/
1371: int TaoSetDestroyRoutine(TAO_SOLVER tao,int (*destroy)(void*),void *mctx)
1372: {
1373: TaoFunctionBegin;
1374: if (destroy){
1375: if (tao->numberdestroyers >= MAX_TAO_DESTROY) {
1376: SETERRQ(1,"TAO ERRROR: Too many TAO destroy routines set");
1377: }
1378:
1379: tao->userdestroy[tao->numberdestroyers] = destroy;
1380: tao->userctxdestroy[tao->numberdestroyers++] = mctx;
1381: }
1382: TaoFunctionReturn(0);
1383: }
1389: /*@C
1390: TaoSetOptionsPrefix - Sets the prefix used for searching for all
1391: TAO options in the database.
1394: Collective on TAO_SOLVER
1396: Input Parameters:
1397: + tao - the TAO_SOLVER solver context
1398: - prefix - the prefix string to prepend to all TAO option requests
1400: Notes:
1401: A hyphen (-) must NOT be given at the beginning of the prefix name.
1402: The first character of all runtime options is AUTOMATICALLY the hyphen.
1404: For example, to distinguish between the runtime options for two
1405: different TAO solvers, one could call
1406: .vb
1407: TaoSetOptionsPrefix(ksp1,"sys1_")
1408: TaoSetOptionsPrefix(ksp2,"sys2_")
1409: .ve
1411: This would enable use of different options for each system, such as
1412: .vb
1413: -sys1_tao_method blmvm -sys1_tao_gtol 1.e-3
1414: -sys2_tao_method lmvm -sys2_tao_gtol 1.e-4
1415: .ve
1418: Level: advanced
1420: .keywords: options
1422: .seealso: TaoAppendOptionsPrefix(), TaoGetOptionsPrefix()
1423: @*/
1424: int TaoSetOptionsPrefix(TAO_SOLVER tao, const char prefix[])
1425: {
1426: int info;
1427: TaoFunctionBegin;
1429: info = PetscObjectSetOptionsPrefix((PetscObject)tao,prefix); CHKERRQ(info);
1430: TaoFunctionReturn(0);
1431: }
1436: /*@C
1437: TaoAppendOptionsPrefix - Appends to the prefix used for searching for all
1438: TAO options in the database.
1441: Collective on TAO_SOLVER
1443: Input Parameters:
1444: + tao - the TAO_SOLVER solver context
1445: - prefix - the prefix string to prepend to all TAO option requests
1447: Notes:
1448: A hyphen (-) must NOT be given at the beginning of the prefix name.
1449: The first character of all runtime options is AUTOMATICALLY the hyphen.
1452: Level: advanced
1454: .keywords: options
1456: .seealso: TaoSetOptionsPrefix(), TaoGetOptionsPrefix()
1457: @*/
1458: int TaoAppendOptionsPrefix(TAO_SOLVER tao, const char prefix[])
1459: {
1460: int info;
1461: TaoFunctionBegin;
1463: info = PetscObjectAppendOptionsPrefix((PetscObject)tao,prefix); CHKERRQ(info);
1464: TaoFunctionReturn(0);
1465: }
1469: /*@C
1470: TaoGetOptionsPrefix - Gets the prefix used for searching for all
1471: TAO options in the database
1473: Not Collective
1475: Input Parameters:
1476: . tao - the TAO_SOLVER context
1477:
1478: Output Parameters:
1479: . prefix - pointer to the prefix string used is returned
1481: Notes: On the fortran side, the user should pass in a string 'prefix' of
1482: sufficient length to hold the prefix.
1484: Level: advanced
1486: .keywords: options
1488: .seealso: TaoSetOptionsPrefix(), TaoAppendOptionsPrefix()
1489: @*/
1490: int TaoGetOptionsPrefix(TAO_SOLVER tao, const char *prefix[])
1491: {
1492: int info;
1493: TaoFunctionBegin;
1495: info = PetscObjectGetOptionsPrefix((PetscObject)tao,prefix); CHKERRQ(info);
1496: TaoFunctionReturn(0);
1497: }