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: }