Actual source code: newsolver.c

  1: #include "src/tao_impl.h"      /*I "tao_solver.h"  I*/

  5: /*@
  6:   TaoSetMethodFromOptions - Sets the TAO_SOLVER solver type from the options database, 
  7:   or sets a default if no method has been specified.

  9:    Collective on TAO_SOLVER

 11:    Input Parameter:
 12: .  solver - the TAO_SOLVER solver context

 14:    Options Database Keys:
 15: .  -tao_method <type> - tao_nls, tao_ntr, tao_lmvm, tao_cg, tao_tron, etc.

 17:    Level: intermediate

 19: .keywords: method, options, database

 21: .seealso: TaoSetOptions()
 22: @*/
 23: int TaoSetMethodFromOptions(TAO_SOLVER solver)
 24: {
 25:   char       type[256];
 26:   int        info;
 27:   TaoTruth flg;

 29:   TaoFunctionBegin;
 30:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);
 31:   if (solver->setupcalled) SETERRQ(1,"Must call prior to TaoSetUp()");

 33:   info = TaoOptionString("-tao_method","TaoMethod","TaoSetMethod","",type,256, &flg);CHKERRQ(info);
 34:   if (flg) {
 35:     info = TaoSetMethod(solver,(TaoMethod) type);CHKERRQ(info);
 36:   }
 37:   if (!solver->type_name) {
 38:     info = TaoSetMethod(solver,"tao_lmvm");CHKERRQ(info);
 39:   }
 40:   TaoFunctionReturn(0);
 41: }


 46: /*@
 47:    TaoSetFromOptions - Sets many TAO_SOLVER parameters from the command line arguments.  
 48:    This command does not set the solver type.

 50:    Collective on TAO_SOLVER

 52:    Input Parameter:
 53: .  solver - the TAO_SOLVER solver context

 55:    Options Database Keys:
 56: +  -tao_stol - convergence tolerance in terms of the norm
 57:                 of the change in the solution between steps
 58: .  -tao_fatol <fatol> - absolute tolerance of residual norm
 59: .  -tao_frtol <frtol> - relative decrease in tolerance norm from initial
 60: .  -tao_max_its <max_its> - maximum number of iterations
 61: .  -tao_max_funcs <max_funcs> - maximum number of function evaluations
 62: .  -tao_trtol <trtol> - trust region tolerance
 63: .  -tao_trust0 <radius> - initial trust region radius
 64: .  -tao_no_convergence_test - skip convergence test in minimization solver;
 65:                                hence iterations will continue until max_it
 66:                                or some other criterion is reached. Saves expense
 67:                                of convergence test
 68: .  -tao_monitor - prints residual norm at each iteration 
 69: .  -tao_vecmonitor - plots solution at each iteration
 70: .  -tao_vecmonitor_update - plots update to solution at each iteration 
 71: .  -tao_xmonitor - plots residual norm at each iteration 
 72: .  -tao_fd - use finite differences to compute Hessian; very slow, only for testing
 73: -  -tao_mf_ksp_monitor - if using matrix-free multiply then print h at each KSP iteration

 75:    Notes:
 76:    To see all options, run your program with the -help option or consult
 77:    the users manual.

 79:    Level: developer

 81: .keywords: options, converence, monitor, view, database

 83: .seealso: TaoSetMethodFromOptions()
 84: @*/
 85: int TaoSetFromOptions(TAO_SOLVER solver)
 86: {
 87:   TaoTruth flg;
 88:   int      info;
 89:   char      type[256];

 91:   TaoFunctionBegin;
 92:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);

 94:   info = TaoMethodsList("-tao_method","Select TAO method","TaoSetMethod",0,type,256,0);CHKERRQ(info);

 96:   if (solver->setfromoptions) {
 97:     info = (*solver->setfromoptions)(solver,solver->data); CHKERRQ(info);
 98:   }


101:   info = TaoOptionName("-tao_view","view TAO_SOLVER info after each minimization has completed","TaoView",&flg);CHKERRQ(info);
102:   if (flg) solver->viewtao = TAO_TRUE;
103:   info = TaoOptionName("-tao_kspview","view the Linear Solver used by the solver after minimization has completed","TaoViewLinearSolver",&flg);CHKERRQ(info);
104:   if (flg) solver->viewksptao = TAO_TRUE;
105: 
106:   info = TaoOptionDouble("-tao_fatol","Stop if solution within","TaoSetTolerances",solver->fatol,&solver->fatol,&flg);CHKERRQ(info);
107:   info = TaoOptionDouble("-tao_frtol","Stop if relative solution within","TaoSetTolerances",solver->frtol,&solver->frtol,&flg);CHKERRQ(info);
108:   info = TaoOptionDouble("-tao_catol","Stop if constraints violations within","TaoSetTolerances",solver->catol,&solver->catol,&flg);CHKERRQ(info);
109:   info = TaoOptionDouble("-tao_crtol","Stop if relative contraint violations within","TaoSetTolerances",solver->crtol,&solver->crtol,&flg);CHKERRQ(info);
110:   info = TaoOptionDouble("-tao_gatol","Stop if norm of gradient less than","TaoSetGradientTolerances",solver->gatol,&solver->gatol,&flg);CHKERRQ(info);
111:   info = TaoOptionDouble("-tao_grtol","Stop if norm of gradient divided by the function value is less than","TaoSetGradientTolerances",solver->grtol,&solver->grtol,&flg);CHKERRQ(info);
112:   info = TaoOptionDouble("-tao_gttol","Stop if the norm of the gradient is less than the norm of the initial gradient times","TaoSetGradientTolerances",solver->gttol,&solver->gttol,&flg);CHKERRQ(info);
113:   info = TaoOptionInt("-tao_max_its","Stop if iteration number exceeds",
114:                        "TaoSetMaximumIterates",solver->max_its,&solver->max_its,
115:                        &flg);CHKERRQ(info);
116:   info = TaoOptionInt("-tao_max_funcs","Stop if number of function evaluations exceeds","TaoSetMaximumFunctionEvaluations",solver->max_funcs,&solver->max_funcs,&flg);
117:   info = TaoOptionDouble("-tao_fmin","Stop if function less than","TaoSetFunctionLowerBound",solver->fmin,&solver->fmin,&flg);
118:   info = TaoOptionDouble("-tao_steptol","Stop if step size or trust region radius less than","TaoSetTrustRegionRadius",solver->trtol,&solver->trtol,&flg);CHKERRQ(info);
119:   info = TaoOptionDouble("-tao_trust0","Initial trust region radius","TaoSetTrustRegionRadius",solver->trust0,&solver->trust0,&flg);CHKERRQ(info);
120:   info = TaoOptionInt("-tao_lmmax","Maximum number of vector pairs to use in limited memory variable metric matrix","TaoSetLMVMSetSize",solver->lm,&solver->lm,&flg);

122:   /*
123:   info = (*PetscHelpPrintf)(solver->comm," TAO_SOLVER Monitoring Options: Choose any of the following\n");CHKERRQ(info);
124:   */

126:   info = TaoOptionName("-tao_unitstep","Always use unit step length","TaoCreateUnitLineSearch",&flg);
127:   if (flg){info=TaoCreateUnitLineSearch(solver);CHKERRQ(info);}
128:   info = TaoOptionName("-tao_lmvmh","User supplies approximate hessian for LMVM solvers","TaoLMVMSetH0",&flg);
129:   if (flg){info=TaoBLMVMSetH0(solver,TAO_TRUE);CHKERRQ(info);info=TaoLMVMSetH0(solver,TAO_TRUE);CHKERRQ(info);}
130: 
131:   info = TaoOptionName("-tao_view_hessian","view Hessian after each evaluation","None",&flg);CHKERRQ(info);
132:   if (flg) solver->viewhessian = TAO_TRUE;
133:   info = TaoOptionName("-tao_view_gradient","view gradient after each evaluation","None",&flg);CHKERRQ(info);
134:   if (flg) solver->viewgradient = TAO_TRUE;
135:   info = TaoOptionName("-tao_view_jacobian","view jacobian after each evaluation","None",&flg);CHKERRQ(info);
136:   if (flg) solver->viewjacobian = TAO_TRUE;
137:   info = TaoOptionName("-tao_view_constraints","view constraint function after each evaluation","None",&flg);CHKERRQ(info);
138:   if (flg) solver->viewvfunc = TAO_TRUE;

140:   info = TaoOptionName("-tao_cancelmonitors","cancel all monitors hardwired in code","TaoClearMonitor",&flg);CHKERRQ(info);
141:   if (flg) {info = TaoClearMonitor(solver);CHKERRQ(info);}
142:   info = TaoOptionName("-tao_monitor","Use the default convergence monitor","TaoSetMonitor",&flg);CHKERRQ(info);
143:   if (flg && solver->defaultmonitor) {
144:     info = TaoSetMonitor(solver,solver->defaultmonitor,TAO_NULL);CHKERRQ(info);
145:   }
146:   info = TaoOptionName("-tao_smonitor","Use short monitor","None",&flg);CHKERRQ(info);
147:   if (flg) {info = TaoSetMonitor(solver,TaoDefaultSMonitor,TAO_NULL);CHKERRQ(info);}
148:   info = TaoOptionName("-tao_vecmonitor","Plot solution vector at each iteration","TaoVecViewMonitor",&flg);CHKERRQ(info);
149:   if (flg) {info = TaoSetMonitor(solver,TaoVecViewMonitor,TAO_NULL);CHKERRQ(info);}
150:   info = TaoOptionName("-tao_vecmonitor_update","plots step direction at each iteration","TaoVecViewMonitorUpdate",&flg);CHKERRQ(info);
151:   if (flg) {info = TaoSetMonitor(solver,TaoVecViewMonitorUpdate,TAO_NULL);CHKERRQ(info);}


154:   //  info = PetscOptionsEnd();CHKERRQ(info);

156:   //  info = TaoSetLinearSolverOptions(solver);CHKERRQ(info);

158:   TaoFunctionReturn(0);
159: }


162: /* -----------------------------------------------------------*/
165: /*
166:    TaoCreateFull - Creates a TAO_SOLVER context.

168:    Collective on MPI_Comm

170:    Input Parameters:
171: +  method - A TAO method.  
172: .  prefix - a prefix to prepend to all option names (usually TAO_NULL)
173: -  comm - MPI communicator

175:    Output Parameter:
176: .  newsolver - the new TAO_SOLVER context

178:    Options Database Keys:
179: .   -tao_method - select which method TAO should use

181:    Level: developer

183: .keywords: Create, solver, method, context

185: .seealso: TaoCreate(), TaoSolve(), TaoSetMethod(), TaoDestroy()
186: */
187: int TaoCreateFull(TaoMethod method, const char* prefix, MPI_Comm comm, TAO_SOLVER *newsolver)
188: {
189:   TAO_SOLVER solver;
190:   int info;

192:   TaoFunctionBegin;

194:   *newsolver = 0;

196:   info = TaoInitialize(0,0,0,0);CHKERRQ(info);CHKERRQ(info);

198:   info = TaoObjectCreate(newsolver,comm);CHKERRQ(info);
199:   solver=*newsolver;

201:   //  info = TaoSetOptionsPrefix(solver,prefix);CHKERRQ(info);

203:   solver->vec_sol=0;
204:   solver->hessian=0;
205:   solver->vfunc=0;
206:   solver->jacobian=0;
207:   solver->RXL=0;
208:   solver->RXU=0;
209:   solver->CA=0;

211:   info = TaoResetSolver(solver); CHKERRQ(info);  /* Set some pointers to NULL */
212:   info = TaoSetDefaultParameters(solver);CHKERRQ(info);
213:   info = TaoSetDefaultStatistics(solver);CHKERRQ(info);
214:   info = TaoSetDefaultMonitors(solver);CHKERRQ(info);

216:   *newsolver = solver;
217:   if (method) {
218:     info=TaoSetMethod(solver,method);CHKERRQ(info);
219:   }

221:   TaoFunctionReturn(0);
222: }


225: /* -----------------------------------------------------------*/
228: /*@C
229:    TaoCreate - Creates a TAO_SOLVER context.

231:    Collective on MPI_Comm

233:    Input Parameters:
234: +  comm - MPI communicator
235: -  method - A TAO method.  

237:    Output Parameter:
238: .  newsolver - the new TAO_SOLVER context

240:    Options Database Keys:
241: .   -tao_method - select which method TAO should use

243:    Available methods include:
244: +    tao_nls - Newton's method with line search for unconstrained minimization
245: .    tao_ntr - Newton's method with trust region for unconstrained minimization
246: .    tao_lmvm - Limited memory variable metric method for unconstrained minimization
247: .    tao_cg_fr - Fletcher-Reeves Nonlinear conjugate gradient method for unconstrained minimization
248: .    tao_cg_pr - Polak-Ribiere Nonlinear conjugate gradient method for unconstrained minimization
249: .    tao_cg_prp - Polak-Ribiere-Plus Nonlinear conjugate gradient method for unconstrained minimization
250: .    tao_tron - Newton Trust Region method for bound constrained minimization
251: .    tao_gpcg - Newton Trust Region method for quadratic bound constrained minimization
252: .    tao_blmvm - Limited memory variable metric method for bound constrained minimization
253: .    tao_kt - Formulate a bound constrained problem as a complementarity problem
254: .    tao_bqpip - Interior point method for quadratic bound constrained minimization
255: .    tao_ssils - Infeasible semismooth method with a linesearch for complementarity problems
256: -    tao_ssfls - Feasible semismooth method with a linesearch for complementarity problems

258:    Level: beginner

260:    Note: 
261:    If the second argument specifies a TaoMethod, quotation marks should 
262:    surround the method.

264:    Note:
265:    The TaoMethod can be TAO_NULL (C/C++) or 
266:    TAO_NULL_CHARACTER (Fortran), in which case the
267:    method will be specified by the runtime option -tao_method

269:    If a particular optimization method is specified at runtime by
270:    the option '-tao_method', this choice will be used instead of
271:    any default that may have been specified as the input parameter
272:    "method" to this routine.

274: .keywords: Create, solver, method, context

276: .seealso: TaoSolve(), TaoSetMethod(), TaoSetApplication(), TaoDestroy()
277: @*/
278: int TaoCreate(MPI_Comm comm, TaoMethod method, TAO_SOLVER *newsolver)
279: {
280:   int info;

282:   TaoFunctionBegin;

284:   *newsolver = 0;

286:   info = TaoCreateFull(method,0,comm,newsolver);CHKERRQ(info);
287:   info = TaoSetMethodFromOptions(*newsolver);CHKERRQ(info);

289:   TaoFunctionReturn(0);
290: }



294: /* ----- Routines to initialize and destroy a minimization solver ---- */

298: /*@
299:    TaoSetDefaultParameters - Set the parameters used by all TAO solvers to a default value.  These
300:    parameter include convergence tolerances.  This routine is called before setting the
301:    method used by TAO

303:    Collective on TAO_SOLVER

305:    Input Parameters:
306: .  solver - the TAO_SOLVER solver context

308:    Level: developer

310: .keywords: options, defaults

312: .seealso: TaoCreate(), TaoSetDefaultStatistics(), TaoSetDefaultMonitors()
313: @*/
314: int TaoSetDefaultParameters(TAO_SOLVER solver){

316:   TaoFunctionBegin;
317:   solver->max_its            = 0;
318:   solver->max_funcs             = 100000000;
319:   solver->fatol              = 0.0;
320:   solver->frtol              = 0.0;
321:   solver->catol              = 0.0;
322:   solver->crtol              = 0.0;
323:   solver->gatol              = 0.0;
324:   solver->grtol              = 0.0;
325:   solver->xtol                     = 0.0;
326:   solver->trtol              = 0.0;
327:   solver->fmin               = -1.e30;
328:   solver->lm                 = 0;
329:   TaoFunctionReturn(0);
330: }

334: /*@
335:    TaoSetDefaultStatistics - Initialize the statistics used by TAO for all of the solvers.
336:    These statistics include the iteration number, residual norms, and convergence status.
337:    This routine gets called before solving each optimization problem.

339:    Collective on TAO_SOLVER

341:    Input Parameters:
342: .  solver - the TAO_SOLVER solver context

344:    Level: developer

346: .keywords: options, defaults

348: .seealso: TaoCreate(), TaoSetDefaultParameters(), TaoSetDefaultMonitors(), TaoSolve()
349: @*/
350: int TaoSetDefaultStatistics(TAO_SOLVER solver){

352:   TaoFunctionBegin;
353:   solver->iter               = 0;
354:   solver->fc                 = 0;
355:   solver->norm                     = 0.0;
356:   solver->norm0                     = 0.0;
357:   solver->cnorm                     = 0.0;
358:   solver->cnorm0             = 0.0;
359:   solver->nfuncs             = 0;
360:   solver->ngrads             = 0;
361:   solver->nhesss             = 0;
362:   solver->nvfunc             = 0;
363:   solver->njac               = 0;
364:   solver->linear_its         = 0;
365:   solver->lsflag             = 0;
366:   solver->reason             = TAO_CONTINUE_ITERATING;
367:   solver->step               = 1.0e+30;
368:   if (solver->conv_hist_reset == TAO_TRUE) solver->conv_hist_len = 0;
369:   TaoFunctionReturn(0);

371: }
374: /*@
375:    TaoSetDefaultMonitors - Set the default monitors and viewing options available in TAO.
376:    This routine is generally called only in TaoCreate().

378:    Collective on TAO_SOLVER

380:    Input Parameters:
381: .  solver - the TAO_SOLVER solver context

383:    Level: developer

385: .keywords: options, defaults

387: .seealso: TaoCreate(), TaoSetDefaultStatistics(), TaoSetDefaultParameters(), TaoSetMonitor(), TaoView()
388: @*/
389: int TaoSetDefaultMonitors(TAO_SOLVER solver){

391:   TaoFunctionBegin;
392:   solver->numbermonitors     = 0;
393:   solver->viewhessian        = TAO_FALSE;
394:   solver->viewgradient       = TAO_FALSE;
395:   solver->viewjacobian       = TAO_FALSE;
396:   solver->viewvfunc          = TAO_FALSE;
397:   solver->viewtao            = TAO_FALSE;
398:   solver->viewksptao        = TAO_FALSE;

400:   solver->converged          = TaoConverged_Default;
401:   solver->defaultmonitor     = TaoDefaultMonitor;

403:   solver->conv_hist_len      = 0;
404:   solver->conv_hist_max      = 0;
405:   solver->conv_hist          = TAO_NULL;
406:   solver->conv_hist_its      = TAO_NULL;
407:   solver->conv_hist_reset    = TAO_TRUE;

409:   solver->numberdestroyers   =0;

411:   TaoFunctionReturn(0);

413: }

415: /* ----- Routines to initialize and destroy a minimization solver ---- */

419: /*@
420:    TaoSetUp - Sets up the internal data structures for the later use
421:    of a minimization solver.

423:    Collective on TAO_SOLVER

425:    Input Parameters:
426: .  solver - the TAO_SOLVER solver context

428:    Notes:
429:    For basic use of the TAO_SOLVER solvers the user need not explicitly call
430:    TaoSetUp(), since these actions will automatically occur during
431:    the call to TaoSolve().  However, if one wishes to control this
432:    phase separately, TaoSetUp() should be called after TaoCreate()
433:    and optional routines of the form TaoSetXXX(), but before TaoSolve().  

435:    Level: developer

437: .keywords: Solve, setup

439: .seealso: TaoCreate(), TaoSolve(), TaoSetDown(), TaoDestroy()
440: @*/
441: int TaoSetUp(TAO_SOLVER solver)
442: {
443:   int      info;
444:   TaoTruth flag;
445:   TaoVec   *xx,*dx;
446:   TaoFunctionBegin;
447:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);

449:   //  info = TaoSetOptions(solver);CHKERRQ(info);
450:   if (!solver->set_method_called) {
451:     SETERRQ(1,"Must explicitly call TaoSetMethod() or TaoSetMethodFromOptions() before TaoSolve()");
452:   }

454:   /* Determine if the solver has already been set up with structures of the right dimension */
455:   if ( solver->setupcalled==TAO_TRUE) {
456:     info = TaoGetSolution(solver,&xx);CHKERRQ(info);
457:     if (!xx){SETERRQ(1,"Must explicitly call TaoSetApplication() and Set Variable Vector");}
458:     info = TaoGetStepDirectionVector(solver,&dx);CHKERRQ(info);
459:     if (dx){
460:       info = xx->Compatible(dx,&flag); CHKERRQ(info);
461:     } else {
462:       flag=TAO_FALSE;
463:     }
464:     if (flag==TAO_TRUE){
465:       info = TaoGetGradient(solver,&dx);CHKERRQ(info);
466:       if (dx){
467:         info = xx->Compatible(dx,&flag); CHKERRQ(info);
468:       }
469:     }
470:     if (flag==TAO_FALSE){  /* Setup done, but data structures of wrong size */
471:       info = TaoSetDown(solver); CHKERRQ(info);
472:     }
473:   }

475:   if ( solver->setupcalled==TAO_FALSE) {
476:     if (solver->setup) {
477:       info = (*solver->setup)(solver,solver->data);CHKERRQ(info);
478:     }
479:   }
480:   solver->setupcalled=TAO_TRUE;
481:   info = TaoLineSearchSetUp(solver);CHKERRQ(info);
482:   TaoFunctionReturn(0);
483: }

487: /*@
488:    TaoDestroy - Destroys the TAO solver that was created with TaoCreate().

490:    Collective on TAO_SOLVER

492:    Input Parameter:
493: .  solver - the TAO_SOLVER solver context

495:    Level: beginner

497: .keywords: Destroy

499: .seealso: TaoCreate(), TaoSolve()
500: @*/
501: int TaoDestroy(TAO_SOLVER solver)
502: {
503:   int i,info;

505:   TaoFunctionBegin;
506:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);
507:   if (--solver->refct > 0) TaoFunctionReturn(0);

509:   for (i=0; i< solver->numberdestroyers; i++){
510:     info = (*solver->userdestroy[i])(solver->userctxdestroy[i]); CHKERRQ(info);
511:   }

513:   info = TaoResetSolver(solver);CHKERRQ(info);

515:   info = TaoObjectDestroy(solver); CHKERRQ(info);
516: 
517:   TaoFunctionReturn(0);
518: }

522: /*@
523:    TaoSetDown - Take down the data structures created in TaoSetUp().
524:    These structures typically include the work vectors, and linear solver.

526:    Collective on TAO_SOLVER

528:    Input Parameter:
529: .  solver - the TAO_SOLVER solver context

531:    Level: advanced

533: .keywords: Destroy

535: .seealso: TaoSetUp(), TaoDestroy()
536: @*/
537: int TaoSetDown(TAO_SOLVER solver)
538: {
539:   int info;

541:   TaoFunctionBegin;
542:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);

544:   if (solver->setupcalled){
545:     if (solver->setdown) {info = (*(solver)->setdown)(solver,solver->data);CHKERRQ(info);}
546:   }
547:   info = TaoSetLagrangianGradientVector(solver,0);CHKERRQ(info);
548:   info = TaoSetStepDirectionVector(solver,0);CHKERRQ(info);
549:   info = TaoSetVariableBounds(solver,0,0);CHKERRQ(info);
550:   solver->ksp = TAO_NULL;
551:   solver->setupcalled=TAO_FALSE;

553:   TaoFunctionReturn(0);
554: }

558: /*@
559:    TaoResetSolver - Take down the data structures created in TaoCreate__XXX().
560:    This routine destroys the line search, and the solver context.  It
561:    also set many of the solver routines for solving, options, duals, viewing,
562:    setup, and destroy to TAO_NULL.

564:    Collective on TAO_SOLVER

566:    Input Parameter:
567: .  solver - the TAO_SOLVER solver context

569:    Level: advanced

571: .keywords: Destroy

573: .seealso: TaoCreate(), TaoSetMethod(), TaoSetDown(), TaoDestroy()
574: @*/
575: int TaoResetSolver(TAO_SOLVER solver)
576: {
577:   int info;

579:   TaoFunctionBegin;
580:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);

582:   info = TaoSetDown(solver); CHKERRQ(info);
583:   if (solver->data){
584:     info = TaoFree(solver->data);CHKERRQ(info);
585:   }
586:   solver->data = 0;
587:   solver->CopyDuals=0;
588:   solver->solve=0;
589:   solver->data=0;
590:   solver->view=0;
591:   solver->setup=0;
592:   solver->setdown=0;
593:   solver->setfromoptions=0;

595:   info = TaoLineSearchDestroy(solver);CHKERRQ(info);
596:   info = TaoMeritFunctionDestroy(solver);CHKERRQ(info);

598:   /* Set Default Parameters */
599:   info = TaoSetDefaultParameters(solver); CHKERRQ(info);
600:   info = TaoSetDefaultMeritFunction(solver); CHKERRQ(info);

602:   solver->set_method_called  = TAO_FALSE;

604:   TaoFunctionReturn(0);
605: }



609: /* --------- Internal routines for TAO_SOLVER Package --------- */

613: /*@C
614:    TaoSetMethod - Sets the method for the unconstrained minimization solver.  

616:    Collective on TAO_SOLVER

618:    Input Parameters:
619: +  solver - the TAO_SOLVER solver context
620: -  type - a known method

622:    Options Database Key:
623: .  -tao_method <type> - Sets the method; use -help for a list
624:    of available methods (for instance, "-tao_method tao_lmvm" or 
625:    "-tao_method tao_tron")

627:    Available methods include:
628: +    tao_nls - Newton's method with line search for unconstrained minimization
629: .    tao_ntr - Newton's method with trust region for unconstrained minimization
630: .    tao_lmvm - Limited memory variable metric method for unconstrained minimization
631: .    tao_cg_fr - Fletcher-Reeves Nonlinear conjugate gradient method for unconstrained minimization
632: .    tao_cg_pr - Polak-Ribiere Nonlinear conjugate gradient method for unconstrained minimization
633: .    tao_cg_prp - Polak-Ribiere-Plus Nonlinear conjugate gradient method for unconstrained minimization
634: .    tao_tron - Newton Trust Region method for bound constrained minimization
635: .    tao_gpcg - Newton Trust Region method for quadratic bound constrained minimization
636: .    tao_blmvm - Limited memory variable metric method for bound constrained minimization
637: .    tao_kt - Formulate a bound constrained problem as a complementarity problem
638: .    tao_bqpip - Interior point method for quadratic bound constrained minimization
639: .    tao_ssils - Infeasible semismooth method with a linesearch for complementarity problems
640: -    tao_ssfls - Feasible semismooth method with a linesearch for complementarity problems

642:   Level: intermediate

644: .keywords: method, Create, solve

646: .seealso: TaoCreate(), TaoGetMethod()

648: @*/
649: int TaoSetMethod(TAO_SOLVER solver,TaoMethod type)
650: {
651:   int info;
652:   int (*r)(TAO_SOLVER);
653:   TaoTruth issame;

655:   TaoFunctionBegin;
656:   TaoValidHeaderSpecific(solver,TAO_COOKIE,1);

658:   info = TaoCompareMethod(solver,type,&issame);CHKERRQ(info);
659:   if (issame) TaoFunctionReturn(0);
660:   info = TaoResetSolver(solver); CHKERRQ(info);
661:   info = TaoFindSolver(solver,type,&r);CHKERRQ(info);

663:   if (!r) SETERRQ1(1,"Unable to find requested TAO_SOLVER type %s",type);
664:   info = (*r)(solver);CHKERRQ(info);

666:   solver->set_method_called = TAO_TRUE;

668:   TaoFunctionReturn(0);
669: }


672: /* --------------------------------------------------------------------- */
675: /*@C
676:   TaoSetTaoDualVariablesRoutine - Set a routine that can be called
677:   to compute the dual variables on the lower and upper bounds of the
678:   variables.

680:    Collective on TAO_SOLVER

682:    Input Parameters:
683: +  tao - the TAO_SOLVER context
684: -  dual - Dual variables routine

686:    Note: The calling sequence of the dual routine passes
687:    the TAO_SOLVER object in the first argument, an (optional)
688:    pointer to a TaoVec to put the duals of the lower bounds,
689:    an (optional) pointer to a TaoVec to put the duals of 
690:    the upper bounds, and the solver context passed to TAO
691:    in TaoSetSolver().

693:    Level: developer

695: .keywords: TAO_SOLVER, duals

697: .seealso: TaoSetTaoSolveRoutine()
698: @*/
699: int TaoSetTaoDualVariablesRoutine(TAO_SOLVER tao, 
700:                                   int (*duals)(TAO_SOLVER,TaoVec*,TaoVec*,void*))
701: {
702:   TaoFunctionBegin;
703:   tao->CopyDuals  = duals;
704:   TaoFunctionReturn(0);
705: }

709: /*@C
710:    TaoSetTaoSolveRoutine - Sets the routine that will solve an optimization application

712:    Collective on TAO_SOLVER

714:    Input Parameters:
715: +  solver - the TAO_SOLVER context
716: .  solve - routine that applies the algorithm
717: -  data - solver data structure (optional)

719:    Level: developer

721:    Note:
722:    This routine is generally used within a "TaoCreate_XXX" routine.
723:    TAO will call this routine as part of the TaoSolve() routine.

725:    Note:
726:    The first and third arguments of this routine will be used as
727:    the arguments of the solver routine provided here.

729: .keywords: TAO_SOLVER, solve

731: .seealso: TaoCreate(), TaoSolve(), TaoGetSolverContext()
732: @*/
733: int TaoSetTaoSolveRoutine(TAO_SOLVER tao, 
734:                           int (*solve)(TAO_SOLVER,void*), void*ctx)
735: {
736:   TaoFunctionBegin;
737:   tao->solve                  = solve;
738:   tao->data                  = ctx;
739:   TaoFunctionReturn(0);
740: }

744: /*@C
745:    TaoSetTaoSetUpDownRoutines - Sets the routines that setup and destroy solver data structures

747:    Collective on TAO_SOLVER

749:    Input Parameters:
750: +  tao - the TAO_SOLVER context
751: .  setup - routine that creates the work vectors in a solver.
752: -  setdown - the routine that will destroy the work vectors of a solver

754:    Note:
755:    This routine is generally called within a "TaoCreate_XXX" routine.
756:    The routines set here will be called in the TaoSetApplication() and
757:    TaoDestroy() routines, respectively.  Vectors and other data structures
758:    needed by the solver can be created and destroyed within the TaoSolve_XXX()
759:    routine, or before and after this routine.  The advantage to doing it
760:    before and after is that the solver can be called multiple times
761:    without reallocated these structures -- improving efficiency.

763:    Note:
764:    When the 'setup' routine is called, the solution vector, and other
765:    data will be available to clone.
766:    
767:    Note:
768:    When TAO calls these routines, the second arguement will be the
769:    context specified in TaoSetTaoSolveRoutine().

771:    Level: developer

773: .keywords: TAO_SOLVER, setup, destroy

775: .seealso: TaoCreate(), TaoSetUp(), TaoSetDown(), TaoDestroy(), TaoSetTaoSolveRoutine()
776: @*/
777: int TaoSetTaoSetUpDownRoutines(TAO_SOLVER tao, 
778:                                  int (*setup)(TAO_SOLVER,void*),
779:                                  int (*setdown)(TAO_SOLVER,void*))
780: {
781:   TaoFunctionBegin;
782:   tao->setup                  = setup;
783:   tao->setdown                  = setdown;
784:   TaoFunctionReturn(0);
785: }

789: /*@C
790:    TaoSetTaoViewRoutine - Sets the routine that will display information
791:    about the optimization solver

793:    Collective on TAO_SOLVER

795:    Input Parameters:
796: +  tao - the TAO_SOLVER context
797: -  view - routine that views the solver

799:    Note:
800:    This routine is generally used within a "TaoCreate_XXX" routine.
801:    TAO will call this routine as part of the TaoView() routine.

803:    Note:
804:    When TAO calls these routines, the second arguement will be the
805:    context specified in TaoSetTaoSolveRoutine().

807:    Level: developer

809: .keywords: TAO_SOLVER, view

811: .seealso: TaoCreate(), TaoView(), TaoSetTaoSolveRoutine()
812: @*/
813: int TaoSetTaoViewRoutine(TAO_SOLVER tao, 
814:                          int (*view)(TAO_SOLVER,void*))
815: {
816:   TaoFunctionBegin;
817:   tao->view               = view;
818:   TaoFunctionReturn(0);
819: }

823: /*@C
824:    TaoSetTaoSolveRoutine - Sets the routine that will set the options for
825:    the optimization solver.

827:    Collective on TAO_SOLVER

829:    Input Parameters:
830: +  solver - the TAO_SOLVER context
831: -  options - routine that views the solver

833:    Note:
834:    This routine is generally used within a "TaoCreate_XXX" routine.
835:    TAO will call this routine as part of the TaoSetOptions() routine.

837:    Note:
838:    When TAO calls these routines, the second argument will be the
839:    context specified in TaoSetTaoSolveRoutine().

841:    Level: developer

843: .keywords: TAO_SOLVER, solve

845: .seealso: TaoCreate(), TaoSetOptions(), TaoSetTaoSolveRoutine().
846: @*/
847: int TaoSetTaoOptionsRoutine(TAO_SOLVER tao, 
848:                             int (*options)(TAO_SOLVER,void*))
849: {
850:   TaoFunctionBegin;
851:   tao->setfromoptions     = options;
852:   TaoFunctionReturn(0);
853: }


858: /*@C
859:    TaoGetApplication - Gets the user defined context for 
860:    the minimization solvers.  

862:    Collective on TAO_SOLVER

864:    Input Parameters:
865: +  tao - the TAO_SOLVER solver context
866: -  taoapp - user application context

868:    Level: advanced

870: .keywords: application, context

872: @*/
873: int TaoGetApplication(TAO_SOLVER tao, TaoApplication **taoapp){
874:   TaoFunctionBegin;
875:   *taoapp=tao->taoappl;
876:   TaoFunctionReturn(0);
877: }



883: /*@C
884:    TaoGetSolverContext - Gets the solver context for 
885:    the minimization solvers.  

887:    Collective on TAO_SOLVER

889:    Input Parameter:
890: +  tao - the TAO_SOLVER solver context
891: -  type - the name of the method

893:    Output Parameter:
894: .  solverctx - solver context IF the type matches.

896:    Level: developer

898: .keywords: application, context

900: .seealso: TaoSetTaoSolveRoutine()

902: @*/
903: int TaoGetSolverContext(TAO_SOLVER tao, TaoMethod type, void **solverctx){
904:   int info;
905:   TaoTruth issame;
906:   TaoFunctionBegin;
907:   if (solverctx){
908:     info = TaoCompareMethod(tao,type,&issame);CHKERRQ(info);
909:     if (issame) *solverctx=tao->data;
910:     else        *solverctx=0;
911:   }
912:   TaoFunctionReturn(0);
913: }