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