Date: 2015-10-02T22:29:55+00:00

Actual source code: taosolver.c
petsc-3.6.2 2015-10-02
Report Typos and Errors

      1: #define TAO_DLL

      3: #include <petsc/private/taoimpl.h> /*I "petsctao.h" I*/

      5: PetscBool TaoRegisterAllCalled = PETSC_FALSE;
      6: PetscFunctionList TaoList = NULL;

      8: PetscClassId TAO_CLASSID;
      9: PetscLogEvent Tao_Solve, Tao_ObjectiveEval, Tao_GradientEval, Tao_ObjGradientEval, Tao_HessianEval, Tao_ConstraintsEval, Tao_JacobianEval;

     11: const char *TaoSubSetTypes[] = {  "subvec","mask","matrixfree","TaoSubSetType","TAO_SUBSET_",0};

     15: /*@
     16:   TaoCreate - Creates a TAO solver

     18:   Collective on MPI_Comm

     20:   Input Parameter:
     21: . comm - MPI communicator

     23:   Output Parameter:
     24: . newtao - the new Tao context

     26:   Available methods include:
     27: +    nls - Newton's method with line search for unconstrained minimization
     28: .    ntr - Newton's method with trust region for unconstrained minimization
     29: .    ntl - Newton's method with trust region, line search for unconstrained minimization
     30: .    lmvm - Limited memory variable metric method for unconstrained minimization
     31: .    cg - Nonlinear conjugate gradient method for unconstrained minimization
     32: .    nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
     33: .    tron - Newton Trust Region method for bound constrained minimization
     34: .    gpcg - Newton Trust Region method for quadratic bound constrained minimization
     35: .    blmvm - Limited memory variable metric method for bound constrained minimization
     36: .    lcl - Linearly constrained Lagrangian method for pde-constrained minimization
     37: -    pounders - Model-based algorithm for nonlinear least squares

     39:    Options Database Keys:
     40: .   -tao_type - select which method TAO should use

     42:    Level: beginner

     44: .seealso: TaoSolve(), TaoDestroy()
     45: @*/
     46: PetscErrorCode TaoCreate(MPI_Comm comm, Tao *newtao)
     47: {
     49:   Tao            tao;

     53:   *newtao = NULL;

     55:   TaoInitializePackage();
     56:   TaoLineSearchInitializePackage();

     58:   PetscHeaderCreate(tao,TAO_CLASSID,"Tao","Optimization solver","Tao",comm,TaoDestroy,TaoView);
     59:   tao->ops->computeobjective=0;
     60:   tao->ops->computeobjectiveandgradient=0;
     61:   tao->ops->computegradient=0;
     62:   tao->ops->computehessian=0;
     63:   tao->ops->computeseparableobjective=0;
     64:   tao->ops->computeconstraints=0;
     65:   tao->ops->computejacobian=0;
     66:   tao->ops->computejacobianequality=0;
     67:   tao->ops->computejacobianinequality=0;
     68:   tao->ops->computeequalityconstraints=0;
     69:   tao->ops->computeinequalityconstraints=0;
     70:   tao->ops->convergencetest=TaoDefaultConvergenceTest;
     71:   tao->ops->convergencedestroy=0;
     72:   tao->ops->computedual=0;
     73:   tao->ops->setup=0;
     74:   tao->ops->solve=0;
     75:   tao->ops->view=0;
     76:   tao->ops->setfromoptions=0;
     77:   tao->ops->destroy=0;

     79:   tao->solution=NULL;
     80:   tao->gradient=NULL;
     81:   tao->sep_objective = NULL;
     82:   tao->constraints=NULL;
     83:   tao->constraints_equality=NULL;
     84:   tao->constraints_inequality=NULL;
     85:   tao->stepdirection=NULL;
     86:   tao->niter=0;
     87:   tao->ntotalits=0;
     88:   tao->XL = NULL;
     89:   tao->XU = NULL;
     90:   tao->IL = NULL;
     91:   tao->IU = NULL;
     92:   tao->DI = NULL;
     93:   tao->DE = NULL;
     94:   tao->hessian = NULL;
     95:   tao->hessian_pre = NULL;
     96:   tao->jacobian = NULL;
     97:   tao->jacobian_pre = NULL;
     98:   tao->jacobian_state = NULL;
     99:   tao->jacobian_state_pre = NULL;
    100:   tao->jacobian_state_inv = NULL;
    101:   tao->jacobian_design = NULL;
    102:   tao->jacobian_design_pre = NULL;
    103:   tao->jacobian_equality = NULL;
    104:   tao->jacobian_equality_pre = NULL;
    105:   tao->jacobian_inequality = NULL;
    106:   tao->jacobian_inequality_pre = NULL;
    107:   tao->state_is = NULL;
    108:   tao->design_is = NULL;

    110:   tao->max_it     = 10000;
    111:   tao->max_funcs   = 10000;
    112: #if defined(PETSC_USE_REAL_SINGLE)
    113:   tao->fatol       = 1e-5;
    114:   tao->frtol       = 1e-5;
    115:   tao->gatol       = 1e-5;
    116:   tao->grtol       = 1e-5;
    117: #else
    118:   tao->fatol       = 1e-8;
    119:   tao->frtol       = 1e-8;
    120:   tao->gatol       = 1e-8;
    121:   tao->grtol       = 1e-8;
    122: #endif
    123:   tao->crtol       = 0.0;
    124:   tao->catol       = 0.0;
    125:   tao->steptol     = 0.0;
    126:   tao->gttol       = 0.0;
    127:   tao->trust0      = PETSC_INFINITY;
    128:   tao->fmin        = PETSC_NINFINITY;
    129:   tao->hist_malloc = PETSC_FALSE;
    130:   tao->hist_reset = PETSC_TRUE;
    131:   tao->hist_max = 0;
    132:   tao->hist_len = 0;
    133:   tao->hist_obj = NULL;
    134:   tao->hist_resid = NULL;
    135:   tao->hist_cnorm = NULL;
    136:   tao->hist_lits = NULL;

    138:   tao->numbermonitors=0;
    139:   tao->viewsolution=PETSC_FALSE;
    140:   tao->viewhessian=PETSC_FALSE;
    141:   tao->viewgradient=PETSC_FALSE;
    142:   tao->viewjacobian=PETSC_FALSE;
    143:   tao->viewconstraints = PETSC_FALSE;

    145:   /* These flags prevents algorithms from overriding user options */
    146:   tao->max_it_changed   =PETSC_FALSE;
    147:   tao->max_funcs_changed=PETSC_FALSE;
    148:   tao->fatol_changed    =PETSC_FALSE;
    149:   tao->frtol_changed    =PETSC_FALSE;
    150:   tao->gatol_changed    =PETSC_FALSE;
    151:   tao->grtol_changed    =PETSC_FALSE;
    152:   tao->gttol_changed    =PETSC_FALSE;
    153:   tao->steptol_changed  =PETSC_FALSE;
    154:   tao->trust0_changed   =PETSC_FALSE;
    155:   tao->fmin_changed     =PETSC_FALSE;
    156:   tao->catol_changed    =PETSC_FALSE;
    157:   tao->crtol_changed    =PETSC_FALSE;
    158:   TaoResetStatistics(tao);
    159:   *newtao = tao;
    160:   return(0);
    161: }

    165: /*@
    166:   TaoSolve - Solves an optimization problem min F(x) s.t. l <= x <= u

    168:   Collective on Tao

    170:   Input Parameters:
    171: . tao - the Tao context

    173:   Notes:
    174:   The user must set up the Tao with calls to TaoSetInitialVector(),
    175:   TaoSetObjectiveRoutine(),
    176:   TaoSetGradientRoutine(), and (if using 2nd order method) TaoSetHessianRoutine().

    178:   Level: beginner

    180: .seealso: TaoCreate(), TaoSetObjectiveRoutine(), TaoSetGradientRoutine(), TaoSetHessianRoutine()
    181:  @*/
    182: PetscErrorCode TaoSolve(Tao tao)
    183: {
    184:   PetscErrorCode   ierr;
    185:   static PetscBool set = PETSC_FALSE;

    189:   PetscCitationsRegister("@TechReport{tao-user-ref,\n"
    190:                                 "title   = {Toolkit for Advanced Optimization (TAO) Users Manual},\n"
    191:                                 "author  = {Todd Munson and Jason Sarich and Stefan Wild and Steve Benson and Lois Curfman McInnes},\n"
    192:                                 "Institution = {Argonne National Laboratory},\n"
    193:                                 "Year   = 2014,\n"
    194:                                 "Number = {ANL/MCS-TM-322 - Revision 3.5},\n"
    195:                                 "url    = {http://www.mcs.anl.gov/tao}\n}\n",&set);

    197:   TaoSetUp(tao);
    198:   TaoResetStatistics(tao);
    199:   if (tao->linesearch) {
    200:     TaoLineSearchReset(tao->linesearch);
    201:   }

    203:   PetscLogEventBegin(Tao_Solve,tao,0,0,0);
    204:   if (tao->ops->solve){ (*tao->ops->solve)(tao); }
    205:   PetscLogEventEnd(Tao_Solve,tao,0,0,0);

    207:   tao->ntotalits += tao->niter;
    208:   TaoViewFromOptions(tao,NULL,"-tao_view");

    210:   if (tao->printreason) {
    211:     if (tao->reason > 0) {
    212:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve converged due to %s iterations %D\n",TaoConvergedReasons[tao->reason],tao->niter);
    213:     } else {
    214:       PetscPrintf(((PetscObject)tao)->comm,"TAO solve did not converge due to %s iteration %D\n",TaoConvergedReasons[tao->reason],tao->niter);
    215:     }
    216:   }
    217:   return(0);
    218: }

    222: /*@
    223:   TaoSetUp - Sets up the internal data structures for the later use
    224:   of a Tao solver

    226:   Collective on tao

    228:   Input Parameters:
    229: . tao - the TAO context

    231:   Notes:
    232:   The user will not need to explicitly call TaoSetUp(), as it will
    233:   automatically be called in TaoSolve().  However, if the user
    234:   desires to call it explicitly, it should come after TaoCreate()
    235:   and any TaoSetSomething() routines, but before TaoSolve().

    237:   Level: advanced

    239: .seealso: TaoCreate(), TaoSolve()
    240: @*/
    241: PetscErrorCode TaoSetUp(Tao tao)
    242: {

    247:   if (tao->setupcalled) return(0);

    249:   if (!tao->solution) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetInitialVector");
    250:   if (tao->ops->setup) {
    251:     (*tao->ops->setup)(tao);
    252:   }
    253:   tao->setupcalled = PETSC_TRUE;
    254:   return(0);
    255: }

    259: /*@
    260:   TaoDestroy - Destroys the TAO context that was created with
    261:   TaoCreate()

    263:   Collective on Tao

    265:   Input Parameter:
    266: . tao - the Tao context

    268:   Level: beginner

    270: .seealso: TaoCreate(), TaoSolve()
    271: @*/
    272: PetscErrorCode TaoDestroy(Tao *tao)
    273: {

    277:   if (!*tao) return(0);
    279:   if (--((PetscObject)*tao)->refct > 0) {*tao=0;return(0);}

    281:   if ((*tao)->ops->destroy) {
    282:     (*((*tao))->ops->destroy)(*tao);
    283:   }
    284:   KSPDestroy(&(*tao)->ksp);
    285:   TaoLineSearchDestroy(&(*tao)->linesearch);

    287:   if ((*tao)->ops->convergencedestroy) {
    288:     (*(*tao)->ops->convergencedestroy)((*tao)->cnvP);
    289:     if ((*tao)->jacobian_state_inv) {
    290:       MatDestroy(&(*tao)->jacobian_state_inv);
    291:     }
    292:   }
    293:   VecDestroy(&(*tao)->solution);
    294:   VecDestroy(&(*tao)->gradient);

    296:   VecDestroy(&(*tao)->XL);
    297:   VecDestroy(&(*tao)->XU);
    298:   VecDestroy(&(*tao)->IL);
    299:   VecDestroy(&(*tao)->IU);
    300:   VecDestroy(&(*tao)->DE);
    301:   VecDestroy(&(*tao)->DI);
    302:   VecDestroy(&(*tao)->constraints_equality);
    303:   VecDestroy(&(*tao)->constraints_inequality);
    304:   VecDestroy(&(*tao)->stepdirection);
    305:   MatDestroy(&(*tao)->hessian_pre);
    306:   MatDestroy(&(*tao)->hessian);
    307:   MatDestroy(&(*tao)->jacobian_pre);
    308:   MatDestroy(&(*tao)->jacobian);
    309:   MatDestroy(&(*tao)->jacobian_state_pre);
    310:   MatDestroy(&(*tao)->jacobian_state);
    311:   MatDestroy(&(*tao)->jacobian_state_inv);
    312:   MatDestroy(&(*tao)->jacobian_design);
    313:   MatDestroy(&(*tao)->jacobian_equality);
    314:   MatDestroy(&(*tao)->jacobian_equality_pre);
    315:   MatDestroy(&(*tao)->jacobian_inequality);
    316:   MatDestroy(&(*tao)->jacobian_inequality_pre);
    317:   ISDestroy(&(*tao)->state_is);
    318:   ISDestroy(&(*tao)->design_is);
    319:   TaoCancelMonitors(*tao);
    320:   if ((*tao)->hist_malloc) {
    321:     PetscFree((*tao)->hist_obj);
    322:     PetscFree((*tao)->hist_resid);
    323:     PetscFree((*tao)->hist_cnorm);
    324:     PetscFree((*tao)->hist_lits);
    325:   }
    326:   PetscHeaderDestroy(tao);
    327:   return(0);
    328: }

    332: /*@
    333:   TaoSetFromOptions - Sets various Tao parameters from user
    334:   options.

    336:   Collective on Tao

    338:   Input Paremeter:
    339: . tao - the Tao solver context

    341:   options Database Keys:
    342: + -tao_type <type> - The algorithm that TAO uses (lmvm, nls, etc.)
    343: . -tao_fatol <fatol> - absolute error tolerance in function value
    344: . -tao_frtol <frtol> - relative error tolerance in function value
    345: . -tao_gatol <gatol> - absolute error tolerance for ||gradient||
    346: . -tao_grtol <grtol> - relative error tolerance for ||gradient||
    347: . -tao_gttol <gttol> - reduction of ||gradient|| relative to initial gradient
    348: . -tao_max_it <max> - sets maximum number of iterations
    349: . -tao_max_funcs <max> - sets maximum number of function evaluations
    350: . -tao_fmin <fmin> - stop if function value reaches fmin
    351: . -tao_steptol <tol> - stop if trust region radius less than <tol>
    352: . -tao_trust0 <t> - initial trust region radius
    353: . -tao_monitor - prints function value and residual at each iteration
    354: . -tao_smonitor - same as tao_monitor, but truncates very small values
    355: . -tao_cmonitor - prints function value, residual, and constraint norm at each iteration
    356: . -tao_view_solution - prints solution vector at each iteration
    357: . -tao_view_separableobjective - prints separable objective vector at each iteration
    358: . -tao_view_step - prints step direction vector at each iteration
    359: . -tao_view_gradient - prints gradient vector at each iteration
    360: . -tao_draw_solution - graphically view solution vector at each iteration
    361: . -tao_draw_step - graphically view step vector at each iteration
    362: . -tao_draw_gradient - graphically view gradient at each iteration
    363: . -tao_fd_gradient - use gradient computed with finite differences
    364: . -tao_cancelmonitors - cancels all monitors (except those set with command line)
    365: . -tao_view - prints information about the Tao after solving
    366: - -tao_converged_reason - prints the reason TAO stopped iterating

    368:   Notes:
    369:   To see all options, run your program with the -help option or consult the
    370:   user's manual. Should be called after TaoCreate() but before TaoSolve()

    372:   Level: beginner
    373: @*/
    374: PetscErrorCode TaoSetFromOptions(Tao tao)
    375: {
    377:   const TaoType  default_type = TAOLMVM;
    378:   const char     *prefix;
    379:   char           type[256], monfilename[PETSC_MAX_PATH_LEN];
    380:   PetscViewer    monviewer;
    381:   PetscBool      flg;
    382:   MPI_Comm       comm;

    386:   PetscObjectGetComm((PetscObject)tao,&comm);
    387:   TaoGetOptionsPrefix(tao,&prefix);
    388:   /* So no warnings are given about unused options */
    389:   PetscOptionsHasName(prefix,"-tao_ls_type",&flg);

    391:   PetscObjectOptionsBegin((PetscObject)tao);
    392:   {
    393:     TaoRegisterAll();
    394:     if (((PetscObject)tao)->type_name) {
    395:       default_type = ((PetscObject)tao)->type_name;
    396:     }
    397:     /* Check for type from options */
    398:     PetscOptionsFList("-tao_type","Tao Solver type","TaoSetType",TaoList,default_type,type,256,&flg);
    399:     if (flg) {
    400:       TaoSetType(tao,type);
    401:     } else if (!((PetscObject)tao)->type_name) {
    402:       TaoSetType(tao,default_type);
    403:     }

    405:     PetscOptionsReal("-tao_fatol","Stop if solution within","TaoSetTolerances",tao->fatol,&tao->fatol,&flg);
    406:     if (flg) tao->fatol_changed=PETSC_TRUE;
    407:     PetscOptionsReal("-tao_frtol","Stop if relative solution within","TaoSetTolerances",tao->frtol,&tao->frtol,&flg);
    408:     if (flg) tao->frtol_changed=PETSC_TRUE;
    409:     PetscOptionsReal("-tao_catol","Stop if constraints violations within","TaoSetConstraintTolerances",tao->catol,&tao->catol,&flg);
    410:     if (flg) tao->catol_changed=PETSC_TRUE;
    411:     PetscOptionsReal("-tao_crtol","Stop if relative contraint violations within","TaoSetConstraintTolerances",tao->crtol,&tao->crtol,&flg);
    412:     if (flg) tao->crtol_changed=PETSC_TRUE;
    413:     PetscOptionsReal("-tao_gatol","Stop if norm of gradient less than","TaoSetTolerances",tao->gatol,&tao->gatol,&flg);
    414:     if (flg) tao->gatol_changed=PETSC_TRUE;
    415:     PetscOptionsReal("-tao_grtol","Stop if norm of gradient divided by the function value is less than","TaoSetTolerances",tao->grtol,&tao->grtol,&flg);
    416:     if (flg) tao->grtol_changed=PETSC_TRUE;
    417:     PetscOptionsReal("-tao_gttol","Stop if the norm of the gradient is less than the norm of the initial gradient times tol","TaoSetTolerances",tao->gttol,&tao->gttol,&flg);
    418:     if (flg) tao->gttol_changed=PETSC_TRUE;
    419:     PetscOptionsInt("-tao_max_it","Stop if iteration number exceeds","TaoSetMaximumIterations",tao->max_it,&tao->max_it,&flg);
    420:     if (flg) tao->max_it_changed=PETSC_TRUE;
    421:     PetscOptionsInt("-tao_max_funcs","Stop if number of function evaluations exceeds","TaoSetMaximumFunctionEvaluations",tao->max_funcs,&tao->max_funcs,&flg);
    422:     if (flg) tao->max_funcs_changed=PETSC_TRUE;
    423:     PetscOptionsReal("-tao_fmin","Stop if function less than","TaoSetFunctionLowerBound",tao->fmin,&tao->fmin,&flg);
    424:     if (flg) tao->fmin_changed=PETSC_TRUE;
    425:     PetscOptionsReal("-tao_steptol","Stop if step size or trust region radius less than","",tao->steptol,&tao->steptol,&flg);
    426:     if (flg) tao->steptol_changed=PETSC_TRUE;
    427:     PetscOptionsReal("-tao_trust0","Initial trust region radius","TaoSetTrustRegionRadius",tao->trust0,&tao->trust0,&flg);
    428:     if (flg) tao->trust0_changed=PETSC_TRUE;
    429:     PetscOptionsString("-tao_view_solution","view solution vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    430:     if (flg) {
    431:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    432:       TaoSetMonitor(tao,TaoSolutionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    433:     }

    435:     PetscOptionsBool("-tao_converged_reason","Print reason for TAO converged","TaoSolve",tao->printreason,&tao->printreason,NULL);
    436:     PetscOptionsString("-tao_view_gradient","view gradient vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    437:     if (flg) {
    438:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    439:       TaoSetMonitor(tao,TaoGradientMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    440:     }

    442:     PetscOptionsString("-tao_view_stepdirection","view step direction vector after each iteration","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    443:     if (flg) {
    444:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    445:       TaoSetMonitor(tao,TaoStepDirectionMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    446:     }

    448:     PetscOptionsString("-tao_view_separableobjective","view separable objective vector after each evaluation","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    449:     if (flg) {
    450:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    451:       TaoSetMonitor(tao,TaoSeparableObjectiveMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    452:     }

    454:     PetscOptionsString("-tao_monitor","Use the default convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    455:     if (flg) {
    456:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    457:       TaoSetMonitor(tao,TaoDefaultMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    458:     }

    460:     PetscOptionsString("-tao_smonitor","Use the short convergence monitor","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    461:     if (flg) {
    462:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    463:       TaoSetMonitor(tao,TaoDefaultSMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    464:     }

    466:     PetscOptionsString("-tao_cmonitor","Use the default convergence monitor with constraint norm","TaoSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    467:     if (flg) {
    468:       PetscViewerASCIIOpen(comm,monfilename,&monviewer);
    469:       TaoSetMonitor(tao,TaoDefaultCMonitor,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    470:     }

    473:     flg = PETSC_FALSE;
    474:     PetscOptionsBool("-tao_cancelmonitors","cancel all monitors and call any registered destroy routines","TaoCancelMonitors",flg,&flg,NULL);
    475:     if (flg) {TaoCancelMonitors(tao);}

    477:     flg = PETSC_FALSE;
    478:     PetscOptionsBool("-tao_draw_solution","Plot solution vector at each iteration","TaoSetMonitor",flg,&flg,NULL);
    479:     if (flg) {
    480:       TaoSetMonitor(tao,TaoDrawSolutionMonitor,NULL,NULL);
    481:     }

    483:     flg = PETSC_FALSE;
    484:     PetscOptionsBool("-tao_draw_step","plots step direction at each iteration","TaoSetMonitor",flg,&flg,NULL);
    485:     if (flg) {
    486:       TaoSetMonitor(tao,TaoDrawStepMonitor,NULL,NULL);
    487:     }

    489:     flg = PETSC_FALSE;
    490:     PetscOptionsBool("-tao_draw_gradient","plots gradient at each iteration","TaoSetMonitor",flg,&flg,NULL);
    491:     if (flg) {
    492:       TaoSetMonitor(tao,TaoDrawGradientMonitor,NULL,NULL);
    493:     }
    494:     flg = PETSC_FALSE;
    495:     PetscOptionsBool("-tao_fd_gradient","compute gradient using finite differences","TaoDefaultComputeGradient",flg,&flg,NULL);
    496:     if (flg) {
    497:       TaoSetGradientRoutine(tao,TaoDefaultComputeGradient,NULL);
    498:     }
    499:     PetscOptionsEnum("-tao_subset_type","subset type", "", TaoSubSetTypes,(PetscEnum)tao->subset_type, (PetscEnum*)&tao->subset_type, 0);

    501:     if (tao->ops->setfromoptions) {
    502:       (*tao->ops->setfromoptions)(PetscOptionsObject,tao);
    503:     }
    504:   }
    505:   PetscOptionsEnd();
    506:   return(0);
    507: }

    511: /*@C
    512:   TaoView - Prints information about the Tao

    514:   Collective on Tao

    516:   InputParameters:
    517: + tao - the Tao context
    518: - viewer - visualization context

    520:   Options Database Key:
    521: . -tao_view - Calls TaoView() at the end of TaoSolve()

    523:   Notes:
    524:   The available visualization contexts include
    525: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
    526: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
    527:          output where only the first processor opens
    528:          the file.  All other processors send their
    529:          data to the first processor to print.

    531:   Level: beginner

    533: .seealso: PetscViewerASCIIOpen()
    534: @*/
    535: PetscErrorCode TaoView(Tao tao, PetscViewer viewer)
    536: {
    537:   PetscErrorCode      ierr;
    538:   PetscBool           isascii,isstring;
    539:   const TaoType type;

    543:   if (!viewer) {
    544:     PetscViewerASCIIGetStdout(((PetscObject)tao)->comm,&viewer);
    545:   }

    549:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
    550:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSTRING,&isstring);
    551:   if (isascii) {
    552:     PetscObjectPrintClassNamePrefixType((PetscObject)tao,viewer);
    553:     PetscViewerASCIIPushTab(viewer);

    555:     if (tao->ops->view) {
    556:       PetscViewerASCIIPushTab(viewer);
    557:       (*tao->ops->view)(tao,viewer);
    558:       PetscViewerASCIIPopTab(viewer);
    559:     }
    560:     if (tao->linesearch) {
    561:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->linesearch),viewer);
    562:     }
    563:     if (tao->ksp) {
    564:       PetscObjectPrintClassNamePrefixType((PetscObject)(tao->ksp),viewer);
    565:       PetscViewerASCIIPrintf(viewer,"total KSP iterations: %D\n",tao->ksp_tot_its);
    566:     }
    567:     if (tao->XL || tao->XU) {
    568:       PetscViewerASCIIPrintf(viewer,"Active Set subset type: %s\n",TaoSubSetTypes[tao->subset_type]);
    569:     }

    571:     ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: fatol=%g,",(double)tao->fatol);
    572:     ierr=PetscViewerASCIIPrintf(viewer," frtol=%g\n",(double)tao->frtol);

    574:     ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: gatol=%g,",(double)tao->gatol);
    575:     ierr=PetscViewerASCIIPrintf(viewer," steptol=%g,",(double)tao->steptol);
    576:     ierr=PetscViewerASCIIPrintf(viewer," gttol=%g\n",(double)tao->gttol);

    578:     PetscViewerASCIIPrintf(viewer,"Residual in Function/Gradient:=%g\n",(double)tao->residual);

    580:     if (tao->cnorm>0 || tao->catol>0 || tao->crtol>0){
    581:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances:");
    582:       ierr=PetscViewerASCIIPrintf(viewer," catol=%g,",(double)tao->catol);
    583:       ierr=PetscViewerASCIIPrintf(viewer," crtol=%g\n",(double)tao->crtol);
    584:       PetscViewerASCIIPrintf(viewer,"Residual in Constraints:=%g\n",(double)tao->cnorm);
    585:     }

    587:     if (tao->trust < tao->steptol){
    588:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: steptol=%g\n",(double)tao->steptol);
    589:       ierr=PetscViewerASCIIPrintf(viewer,"Final trust region radius:=%g\n",(double)tao->trust);
    590:     }

    592:     if (tao->fmin>-1.e25){
    593:       ierr=PetscViewerASCIIPrintf(viewer,"convergence tolerances: function minimum=%g\n",(double)tao->fmin);
    594:     }
    595:     PetscViewerASCIIPrintf(viewer,"Objective value=%g\n",(double)tao->fc);

    597:     PetscViewerASCIIPrintf(viewer,"total number of iterations=%D,          ",tao->niter);
    598:     PetscViewerASCIIPrintf(viewer,"              (max: %D)\n",tao->max_it);

    600:     if (tao->nfuncs>0){
    601:       PetscViewerASCIIPrintf(viewer,"total number of function evaluations=%D,",tao->nfuncs);
    602:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
    603:     }
    604:     if (tao->ngrads>0){
    605:       PetscViewerASCIIPrintf(viewer,"total number of gradient evaluations=%D,",tao->ngrads);
    606:       PetscViewerASCIIPrintf(viewer,"                max: %D\n",tao->max_funcs);
    607:     }
    608:     if (tao->nfuncgrads>0){
    609:       PetscViewerASCIIPrintf(viewer,"total number of function/gradient evaluations=%D,",tao->nfuncgrads);
    610:       PetscViewerASCIIPrintf(viewer,"    (max: %D)\n",tao->max_funcs);
    611:     }
    612:     if (tao->nhess>0){
    613:       PetscViewerASCIIPrintf(viewer,"total number of Hessian evaluations=%D\n",tao->nhess);
    614:     }
    615:     /*  if (tao->linear_its>0){
    616:      PetscViewerASCIIPrintf(viewer,"  total Krylov method iterations=%D\n",tao->linear_its);
    617:      }*/
    618:     if (tao->nconstraints>0){
    619:       PetscViewerASCIIPrintf(viewer,"total number of constraint function evaluations=%D\n",tao->nconstraints);
    620:     }
    621:     if (tao->njac>0){
    622:       PetscViewerASCIIPrintf(viewer,"total number of Jacobian evaluations=%D\n",tao->njac);
    623:     }

    625:     if (tao->reason>0){
    626:       PetscViewerASCIIPrintf(viewer,    "Solution converged: ");
    627:       switch (tao->reason) {
    628:       case TAO_CONVERGED_FATOL:
    629:         PetscViewerASCIIPrintf(viewer,"estimated f(x)-f(X*) <= fatol\n");
    630:         break;
    631:       case TAO_CONVERGED_FRTOL:
    632:         PetscViewerASCIIPrintf(viewer,"estimated |f(x)-f(X*)|/|f(X*)| <= frtol\n");
    633:         break;
    634:       case TAO_CONVERGED_GATOL:
    635:         PetscViewerASCIIPrintf(viewer," ||g(X)|| <= gatol\n");
    636:         break;
    637:       case TAO_CONVERGED_GRTOL:
    638:         PetscViewerASCIIPrintf(viewer," ||g(X)||/|f(X)| <= grtol\n");
    639:         break;
    640:       case TAO_CONVERGED_GTTOL:
    641:         PetscViewerASCIIPrintf(viewer," ||g(X)||/||g(X0)|| <= gttol\n");
    642:         break;
    643:       case TAO_CONVERGED_STEPTOL:
    644:         PetscViewerASCIIPrintf(viewer," Steptol -- step size small\n");
    645:         break;
    646:       case TAO_CONVERGED_MINF:
    647:         PetscViewerASCIIPrintf(viewer," Minf --  f < fmin\n");
    648:         break;
    649:       case TAO_CONVERGED_USER:
    650:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
    651:         break;
    652:       default:
    653:         PetscViewerASCIIPrintf(viewer,"\n");
    654:         break;
    655:       }

    657:     } else {
    658:       PetscViewerASCIIPrintf(viewer,"Solver terminated: %D",tao->reason);
    659:       switch (tao->reason) {
    660:       case TAO_DIVERGED_MAXITS:
    661:         PetscViewerASCIIPrintf(viewer," Maximum Iterations\n");
    662:         break;
    663:       case TAO_DIVERGED_NAN:
    664:         PetscViewerASCIIPrintf(viewer," NAN or Inf encountered\n");
    665:         break;
    666:       case TAO_DIVERGED_MAXFCN:
    667:         PetscViewerASCIIPrintf(viewer," Maximum Function Evaluations\n");
    668:         break;
    669:       case TAO_DIVERGED_LS_FAILURE:
    670:         PetscViewerASCIIPrintf(viewer," Line Search Failure\n");
    671:         break;
    672:       case TAO_DIVERGED_TR_REDUCTION:
    673:         PetscViewerASCIIPrintf(viewer," Trust Region too small\n");
    674:         break;
    675:       case TAO_DIVERGED_USER:
    676:         PetscViewerASCIIPrintf(viewer," User Terminated\n");
    677:         break;
    678:       default:
    679:         PetscViewerASCIIPrintf(viewer,"\n");
    680:         break;
    681:       }
    682:     }
    683:     PetscViewerASCIIPopTab(viewer);
    684:   } else if (isstring) {
    685:     TaoGetType(tao,&type);
    686:     PetscViewerStringSPrintf(viewer," %-3.3s",type);
    687:   }
    688:   return(0);
    689: }

    693: /*@
    694:   TaoSetTolerances - Sets parameters used in TAO convergence tests

    696:   Logically collective on Tao

    698:   Input Parameters:
    699: + tao - the Tao context
    700: . fatol - absolute convergence tolerance
    701: . frtol - relative convergence tolerance
    702: . gatol - stop if norm of gradient is less than this
    703: . grtol - stop if relative norm of gradient is less than this
    704: - gttol - stop if norm of gradient is reduced by this factor

    706:   Options Database Keys:
    707: + -tao_fatol <fatol> - Sets fatol
    708: . -tao_frtol <frtol> - Sets frtol
    709: . -tao_gatol <gatol> - Sets gatol
    710: . -tao_grtol <grtol> - Sets grtol
    711: - -tao_gttol <gttol> - Sets gttol

    713:   Stopping Criteria:
    714: $ f(X) - f(X*) (estimated)            <= fatol
    715: $ |f(X) - f(X*)| (estimated) / |f(X)| <= frtol
    716: $ ||g(X)||                            <= gatol
    717: $ ||g(X)|| / |f(X)|                   <= grtol
    718: $ ||g(X)|| / ||g(X0)||                <= gttol

    720:   Notes:
    721:   Use PETSC_DEFAULT to leave one or more tolerances unchanged.

    723:   Level: beginner

    725: .seealso: TaoGetTolerances()

    727: @*/
    728: PetscErrorCode TaoSetTolerances(Tao tao, PetscReal fatol, PetscReal frtol, PetscReal gatol, PetscReal grtol, PetscReal gttol)
    729: {

    735:   if (fatol != PETSC_DEFAULT) {
    736:     if (fatol<0) {
    737:       PetscInfo(tao,"Tried to set negative fatol -- ignored.\n");
    738:     } else {
    739:       tao->fatol = PetscMax(0,fatol);
    740:       tao->fatol_changed=PETSC_TRUE;
    741:     }
    742:   }
    743:   if (frtol != PETSC_DEFAULT) {
    744:     if (frtol<0) {
    745:       PetscInfo(tao,"Tried to set negative frtol -- ignored.\n");
    746:     } else {
    747:       tao->frtol = PetscMax(0,frtol);
    748:       tao->frtol_changed=PETSC_TRUE;
    749:     }
    750:   }

    752:   if (gatol != PETSC_DEFAULT) {
    753:     if (gatol<0) {
    754:       PetscInfo(tao,"Tried to set negative gatol -- ignored.\n");
    755:     } else {
    756:       tao->gatol = PetscMax(0,gatol);
    757:       tao->gatol_changed=PETSC_TRUE;
    758:     }
    759:   }

    761:   if (grtol != PETSC_DEFAULT) {
    762:     if (grtol<0) {
    763:       PetscInfo(tao,"Tried to set negative grtol -- ignored.\n");
    764:     } else {
    765:       tao->grtol = PetscMax(0,grtol);
    766:       tao->grtol_changed=PETSC_TRUE;
    767:     }
    768:   }

    770:   if (gttol != PETSC_DEFAULT) {
    771:     if (gttol<0) {
    772:       PetscInfo(tao,"Tried to set negative gttol -- ignored.\n");
    773:     } else {
    774:       tao->gttol = PetscMax(0,gttol);
    775:       tao->gttol_changed=PETSC_TRUE;
    776:     }
    777:   }
    778:   return(0);
    779: }

    783: /*@
    784:   TaoSetConstraintTolerances - Sets constraint tolerance parameters used in TAO  convergence tests

    786:   Logically collective on Tao

    788:   Input Parameters:
    789: + tao - the Tao context
    790: . catol - absolute constraint tolerance, constraint norm must be less than catol for used for fatol, gatol convergence criteria
    791: - crtol - relative contraint tolerance, constraint norm must be less than crtol for used for fatol, gatol, gttol convergence criteria

    793:   Options Database Keys:
    794: + -tao_catol <catol> - Sets catol
    795: - -tao_crtol <crtol> - Sets crtol

    797:   Notes:
    798:   Use PETSC_DEFAULT to leave any tolerance unchanged.

    800:   Level: intermediate

    802: .seealso: TaoGetTolerances(), TaoGetConstraintTolerances(), TaoSetTolerances()

    804: @*/
    805: PetscErrorCode TaoSetConstraintTolerances(Tao tao, PetscReal catol, PetscReal crtol)
    806: {

    812:   if (catol != PETSC_DEFAULT) {
    813:     if (catol<0) {
    814:       PetscInfo(tao,"Tried to set negative catol -- ignored.\n");
    815:     } else {
    816:       tao->catol = PetscMax(0,catol);
    817:       tao->catol_changed=PETSC_TRUE;
    818:     }
    819:   }

    821:   if (crtol != PETSC_DEFAULT) {
    822:     if (crtol<0) {
    823:       PetscInfo(tao,"Tried to set negative crtol -- ignored.\n");
    824:     } else {
    825:       tao->crtol = PetscMax(0,crtol);
    826:       tao->crtol_changed=PETSC_TRUE;
    827:     }
    828:   }
    829:   return(0);
    830: }

    834: /*@
    835:   TaoGetConstraintTolerances - Gets constraint tolerance parameters used in TAO  convergence tests

    837:   Not ollective

    839:   Input Parameter:
    840: . tao - the Tao context

    842:   Output Parameter:
    843: + catol - absolute constraint tolerance, constraint norm must be less than catol for used for fatol, gatol convergence criteria
    844: - crtol - relative contraint tolerance, constraint norm must be less than crtol for used for fatol, gatol, gttol convergence criteria

    846:   Level: intermediate

    848: .seealso: TaoGetTolerances(), TaoSetTolerances(), TaoSetConstraintTolerances()

    850: @*/
    851: PetscErrorCode TaoGetConstraintTolerances(Tao tao, PetscReal *catol, PetscReal *crtol)
    852: {
    855:   if (catol) *catol = tao->catol;
    856:   if (crtol) *crtol = tao->crtol;
    857:   return(0);
    858: }

    862: /*@
    863:    TaoSetFunctionLowerBound - Sets a bound on the solution objective value.
    864:    When an approximate solution with an objective value below this number
    865:    has been found, the solver will terminate.

    867:    Logically Collective on Tao

    869:    Input Parameters:
    870: +  tao - the Tao solver context
    871: -  fmin - the tolerance

    873:    Options Database Keys:
    874: .    -tao_fmin <fmin> - sets the minimum function value

    876:    Level: intermediate

    878: .seealso: TaoSetTolerances()
    879: @*/
    880: PetscErrorCode TaoSetFunctionLowerBound(Tao tao,PetscReal fmin)
    881: {
    884:   tao->fmin = fmin;
    885:   tao->fmin_changed=PETSC_TRUE;
    886:   return(0);
    887: }

    891: /*@
    892:    TaoGetFunctionLowerBound - Sets a bound on the solution objective value.
    893:    When an approximate solution with an objective value below this number
    894:    has been found, the solver will terminate.

    896:    Not collective on Tao

    898:    Input Parameters:
    899: .  tao - the Tao solver context

    901:    OutputParameters:
    902: .  fmin - the minimum function value

    904:    Level: intermediate

    906: .seealso: TaoSetFunctionLowerBound()
    907: @*/
    908: PetscErrorCode TaoGetFunctionLowerBound(Tao tao,PetscReal *fmin)
    909: {
    912:   *fmin = tao->fmin;
    913:   return(0);
    914: }

    918: /*@
    919:    TaoSetMaximumFunctionEvaluations - Sets a maximum number of
    920:    function evaluations.

    922:    Logically Collective on Tao

    924:    Input Parameters:
    925: +  tao - the Tao solver context
    926: -  nfcn - the maximum number of function evaluations (>=0)

    928:    Options Database Keys:
    929: .    -tao_max_funcs <nfcn> - sets the maximum number of function evaluations

    931:    Level: intermediate

    933: .seealso: TaoSetTolerances(), TaoSetMaximumIterations()
    934: @*/

    936: PetscErrorCode TaoSetMaximumFunctionEvaluations(Tao tao,PetscInt nfcn)
    937: {
    940:   tao->max_funcs = PetscMax(0,nfcn);
    941:   tao->max_funcs_changed=PETSC_TRUE;
    942:   return(0);
    943: }

    947: /*@
    948:    TaoGetMaximumFunctionEvaluations - Sets a maximum number of
    949:    function evaluations.

    951:    Not Collective

    953:    Input Parameters:
    954: .  tao - the Tao solver context

    956:    Output Parameters:
    957: .  nfcn - the maximum number of function evaluations

    959:    Level: intermediate

    961: .seealso: TaoSetMaximumFunctionEvaluations(), TaoGetMaximumIterations()
    962: @*/

    964: PetscErrorCode TaoGetMaximumFunctionEvaluations(Tao tao,PetscInt *nfcn)
    965: {
    968:   *nfcn = tao->max_funcs;
    969:   return(0);
    970: }

    974: /*@
    975:    TaoGetCurrentFunctionEvaluations - Get current number of
    976:    function evaluations.

    978:    Not Collective

    980:    Input Parameters:
    981: .  tao - the Tao solver context

    983:    Output Parameters:
    984: .  nfuncs - the current number of function evaluations

    986:    Level: intermediate

    988: .seealso: TaoSetMaximumFunctionEvaluations(), TaoGetMaximumFunctionEvaluations(), TaoGetMaximumIterations()
    989: @*/

    991: PetscErrorCode TaoGetCurrentFunctionEvaluations(Tao tao,PetscInt *nfuncs)
    992: {
    995:   *nfuncs=PetscMax(tao->nfuncs,tao->nfuncgrads);
    996:   return(0);
    997: }

    1001: /*@
    1002:    TaoSetMaximumIterations - Sets a maximum number of iterates.

    1004:    Logically Collective on Tao

    1006:    Input Parameters:
    1007: +  tao - the Tao solver context
    1008: -  maxits - the maximum number of iterates (>=0)

    1010:    Options Database Keys:
    1011: .    -tao_max_it <its> - sets the maximum number of iterations

    1013:    Level: intermediate

    1015: .seealso: TaoSetTolerances(), TaoSetMaximumFunctionEvaluations()
    1016: @*/
    1017: PetscErrorCode TaoSetMaximumIterations(Tao tao,PetscInt maxits)
    1018: {
    1021:   tao->max_it = PetscMax(0,maxits);
    1022:   tao->max_it_changed=PETSC_TRUE;
    1023:   return(0);
    1024: }

    1028: /*@
    1029:    TaoGetMaximumIterations - Sets a maximum number of iterates.

    1031:    Not Collective

    1033:    Input Parameters:
    1034: .  tao - the Tao solver context

    1036:    Output Parameters:
    1037: .  maxits - the maximum number of iterates

    1039:    Level: intermediate

    1041: .seealso: TaoSetMaximumIterations(), TaoGetMaximumFunctionEvaluations()
    1042: @*/
    1043: PetscErrorCode TaoGetMaximumIterations(Tao tao,PetscInt *maxits)
    1044: {
    1047:   *maxits = tao->max_it;
    1048:   return(0);
    1049: }

    1053: /*@
    1054:    TaoSetInitialTrustRegionRadius - Sets the initial trust region radius.

    1056:    Logically collective on Tao

    1058:    Input Parameter:
    1059: +  tao - a TAO optimization solver
    1060: -  radius - the trust region radius

    1062:    Level: intermediate

    1064:    Options Database Key:
    1065: .  -tao_trust0 <t0> - sets initial trust region radius

    1067: .seealso: TaoGetTrustRegionRadius(), TaoSetTrustRegionTolerance()
    1068: @*/
    1069: PetscErrorCode TaoSetInitialTrustRegionRadius(Tao tao, PetscReal radius)
    1070: {
    1073:   tao->trust0 = PetscMax(0.0,radius);
    1074:   tao->trust0_changed=PETSC_TRUE;
    1075:   return(0);
    1076: }

    1080: /*@
    1081:    TaoGetInitialTrustRegionRadius - Sets the initial trust region radius.

    1083:    Not Collective

    1085:    Input Parameter:
    1086: .  tao - a TAO optimization solver

    1088:    Output Parameter:
    1089: .  radius - the trust region radius

    1091:    Level: intermediate

    1093: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetCurrentTrustRegionRadius()
    1094: @*/
    1095: PetscErrorCode TaoGetInitialTrustRegionRadius(Tao tao, PetscReal *radius)
    1096: {
    1099:   *radius = tao->trust0;
    1100:   return(0);
    1101: }

    1105: /*@
    1106:    TaoGetCurrentTrustRegionRadius - Gets the current trust region radius.

    1108:    Not Collective

    1110:    Input Parameter:
    1111: .  tao - a TAO optimization solver

    1113:    Output Parameter:
    1114: .  radius - the trust region radius

    1116:    Level: intermediate

    1118: .seealso: TaoSetInitialTrustRegionRadius(), TaoGetInitialTrustRegionRadius()
    1119: @*/
    1120: PetscErrorCode TaoGetCurrentTrustRegionRadius(Tao tao, PetscReal *radius)
    1121: {
    1124:   *radius = tao->trust;
    1125:   return(0);
    1126: }

    1130: /*@
    1131:   TaoGetTolerances - gets the current values of tolerances

    1133:   Not Collective

    1135:   Input Parameters:
    1136: . tao - the Tao context

    1138:   Output Parameters:
    1139: + fatol - absolute convergence tolerance
    1140: . frtol - relative convergence tolerance
    1141: . gatol - stop if norm of gradient is less than this
    1142: . grtol - stop if relative norm of gradient is less than this
    1143: - gttol - stop if norm of gradient is reduced by a this factor

    1145:   Note: NULL can be used as an argument if not all tolerances values are needed

    1147: .seealso TaoSetTolerances()

    1149:   Level: intermediate
    1150: @*/
    1151: PetscErrorCode TaoGetTolerances(Tao tao, PetscReal *fatol, PetscReal *frtol, PetscReal *gatol, PetscReal *grtol, PetscReal *gttol)
    1152: {
    1155:   if (fatol) *fatol=tao->fatol;
    1156:   if (frtol) *frtol=tao->frtol;
    1157:   if (gatol) *gatol=tao->gatol;
    1158:   if (grtol) *grtol=tao->grtol;
    1159:   if (gttol) *gttol=tao->gttol;
    1160:   return(0);
    1161: }

    1165: /*@
    1166:   TaoGetKSP - Gets the linear solver used by the optimization solver.
    1167:   Application writers should use TaoGetKSP if they need direct access
    1168:   to the PETSc KSP object.

    1170:   Not Collective

    1172:    Input Parameters:
    1173: .  tao - the TAO solver

    1175:    Output Parameters:
    1176: .  ksp - the KSP linear solver used in the optimization solver

    1178:    Level: intermediate

    1180: @*/
    1181: PetscErrorCode TaoGetKSP(Tao tao, KSP *ksp)
    1182: {
    1184:   *ksp = tao->ksp;
    1185:   return(0);
    1186: }

    1190: /*@
    1191:    TaoGetLinearSolveIterations - Gets the total number of linear iterations
    1192:    used by the TAO solver

    1194:    Not Collective

    1196:    Input Parameter:
    1197: .  tao - TAO context

    1199:    Output Parameter:
    1200: .  lits - number of linear iterations

    1202:    Notes:
    1203:    This counter is reset to zero for each successive call to TaoSolve()

    1205:    Level: intermediate

    1207: .keywords: TAO

    1209: .seealso:  TaoGetKSP()
    1210: @*/
    1211: PetscErrorCode  TaoGetLinearSolveIterations(Tao tao,PetscInt *lits)
    1212: {
    1216:   *lits = tao->ksp_tot_its;
    1217:   return(0);
    1218: }

    1222: /*@
    1223:   TaoGetLineSearch - Gets the line search used by the optimization solver.
    1224:   Application writers should use TaoGetLineSearch if they need direct access
    1225:   to the TaoLineSearch object.

    1227:   Not Collective

    1229:    Input Parameters:
    1230: .  tao - the TAO solver

    1232:    Output Parameters:
    1233: .  ls - the line search used in the optimization solver

    1235:    Level: intermediate

    1237: @*/
    1238: PetscErrorCode TaoGetLineSearch(Tao tao, TaoLineSearch *ls)
    1239: {
    1241:   *ls = tao->linesearch;
    1242:   return(0);
    1243: }

    1247: /*@
    1248:   TaoAddLineSearchCounts - Adds the number of function evaluations spent
    1249:   in the line search to the running total.

    1251:    Input Parameters:
    1252: +  tao - the TAO solver
    1253: -  ls - the line search used in the optimization solver

    1255:    Level: developer

    1257: .seealso: TaoLineSearchApply()
    1258: @*/
    1259: PetscErrorCode TaoAddLineSearchCounts(Tao tao)
    1260: {
    1262:   PetscBool      flg;
    1263:   PetscInt       nfeval,ngeval,nfgeval;

    1267:   if (tao->linesearch) {
    1268:     TaoLineSearchIsUsingTaoRoutines(tao->linesearch,&flg);
    1269:     if (!flg) {
    1270:       TaoLineSearchGetNumberFunctionEvaluations(tao->linesearch,&nfeval,&ngeval,&nfgeval);
    1271:       tao->nfuncs+=nfeval;
    1272:       tao->ngrads+=ngeval;
    1273:       tao->nfuncgrads+=nfgeval;
    1274:     }
    1275:   }
    1276:   return(0);
    1277: }

    1281: /*@
    1282:   TaoGetSolutionVector - Returns the vector with the current TAO solution

    1284:   Not Collective

    1286:   Input Parameter:
    1287: . tao - the Tao context

    1289:   Output Parameter:
    1290: . X - the current solution

    1292:   Level: intermediate

    1294:   Note:  The returned vector will be the same object that was passed into TaoSetInitialVector()
    1295: @*/
    1296: PetscErrorCode TaoGetSolutionVector(Tao tao, Vec *X)
    1297: {
    1300:   *X = tao->solution;
    1301:   return(0);
    1302: }

    1306: /*@
    1307:   TaoGetGradientVector - Returns the vector with the current TAO gradient

    1309:   Not Collective

    1311:   Input Parameter:
    1312: . tao - the Tao context

    1314:   Output Parameter:
    1315: . G - the current solution

    1317:   Level: intermediate
    1318: @*/
    1319: PetscErrorCode TaoGetGradientVector(Tao tao, Vec *G)
    1320: {
    1323:   *G = tao->gradient;
    1324:   return(0);
    1325: }

    1329: /*@
    1330:    TaoResetStatistics - Initialize the statistics used by TAO for all of the solvers.
    1331:    These statistics include the iteration number, residual norms, and convergence status.
    1332:    This routine gets called before solving each optimization problem.

    1334:    Collective on Tao

    1336:    Input Parameters:
    1337: .  solver - the Tao context

    1339:    Level: developer

    1341: .seealso: TaoCreate(), TaoSolve()
    1342: @*/
    1343: PetscErrorCode TaoResetStatistics(Tao tao)
    1344: {
    1347:   tao->niter        = 0;
    1348:   tao->nfuncs       = 0;
    1349:   tao->nfuncgrads   = 0;
    1350:   tao->ngrads       = 0;
    1351:   tao->nhess        = 0;
    1352:   tao->njac         = 0;
    1353:   tao->nconstraints = 0;
    1354:   tao->ksp_its      = 0;
    1355:   tao->ksp_tot_its      = 0;
    1356:   tao->reason       = TAO_CONTINUE_ITERATING;
    1357:   tao->residual     = 0.0;
    1358:   tao->cnorm        = 0.0;
    1359:   tao->step         = 0.0;
    1360:   tao->lsflag       = PETSC_FALSE;
    1361:   if (tao->hist_reset) tao->hist_len=0;
    1362:   return(0);
    1363: }

    1367: /*@C
    1368:   TaoSetConvergenceTest - Sets the function that is to be used to test
    1369:   for convergence o fthe iterative minimization solution.  The new convergence
    1370:   testing routine will replace TAO's default convergence test.

    1372:   Logically Collective on Tao

    1374:   Input Parameters:
    1375: + tao - the Tao object
    1376: . conv - the routine to test for convergence
    1377: - ctx - [optional] context for private data for the convergence routine
    1378:         (may be NULL)

    1380:   Calling sequence of conv:
    1381: $   PetscErrorCode conv(Tao tao, void *ctx)

    1383: + tao - the Tao object
    1384: - ctx - [optional] convergence context

    1386:   Note: The new convergence testing routine should call TaoSetConvergedReason().

    1388:   Level: advanced

    1390: .seealso: TaoSetConvergedReason(), TaoGetSolutionStatus(), TaoGetTolerances(), TaoSetMonitor

    1392: @*/
    1393: PetscErrorCode TaoSetConvergenceTest(Tao tao, PetscErrorCode (*conv)(Tao,void*), void *ctx)
    1394: {
    1397:   (tao)->ops->convergencetest = conv;
    1398:   (tao)->cnvP = ctx;
    1399:   return(0);
    1400: }

    1404: /*@C
    1405:    TaoSetMonitor - Sets an ADDITIONAL function that is to be used at every
    1406:    iteration of the solver to display the iteration's
    1407:    progress.

    1409:    Logically Collective on Tao

    1411:    Input Parameters:
    1412: +  tao - the Tao solver context
    1413: .  mymonitor - monitoring routine
    1414: -  mctx - [optional] user-defined context for private data for the
    1415:           monitor routine (may be NULL)

    1417:    Calling sequence of mymonitor:
    1418: $     int mymonitor(Tao tao,void *mctx)

    1420: +    tao - the Tao solver context
    1421: -    mctx - [optional] monitoring context

    1424:    Options Database Keys:
    1425: +    -tao_monitor        - sets TaoDefaultMonitor()
    1426: .    -tao_smonitor       - sets short monitor
    1427: .    -tao_cmonitor       - same as smonitor plus constraint norm
    1428: .    -tao_view_solution   - view solution at each iteration
    1429: .    -tao_view_gradient   - view gradient at each iteration
    1430: .    -tao_view_separableobjective - view separable objective function at each iteration
    1431: -    -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.

    1434:    Notes:
    1435:    Several different monitoring routines may be set by calling
    1436:    TaoSetMonitor() multiple times; all will be called in the
    1437:    order in which they were set.

    1439:    Fortran Notes: Only one monitor function may be set

    1441:    Level: intermediate

    1443: .seealso: TaoDefaultMonitor(), TaoCancelMonitors(),  TaoSetDestroyRoutine()
    1444: @*/
    1445: PetscErrorCode TaoSetMonitor(Tao tao, PetscErrorCode (*func)(Tao, void*), void *ctx,PetscErrorCode (*dest)(void**))
    1446: {
    1448:   PetscInt       i;

    1452:   if (tao->numbermonitors >= MAXTAOMONITORS) SETERRQ1(PETSC_COMM_SELF,1,"Cannot attach another monitor -- max=",MAXTAOMONITORS);

    1454:   for (i=0; i<tao->numbermonitors;i++) {
    1455:     if (func == tao->monitor[i] && dest == tao->monitordestroy[i] && ctx == tao->monitorcontext[i]) {
    1456:       if (dest) {
    1457:         (*dest)(&ctx);
    1458:       }
    1459:       return(0);
    1460:     }
    1461:   }
    1462:   tao->monitor[tao->numbermonitors] = func;
    1463:   tao->monitorcontext[tao->numbermonitors] = ctx;
    1464:   tao->monitordestroy[tao->numbermonitors] = dest;
    1465:   ++tao->numbermonitors;
    1466:   return(0);
    1467: }

    1471: /*@
    1472:    TaoCancelMonitors - Clears all the monitor functions for a Tao object.

    1474:    Logically Collective on Tao

    1476:    Input Parameters:
    1477: .  tao - the Tao solver context

    1479:    Options Database:
    1480: .  -tao_cancelmonitors - cancels all monitors that have been hardwired
    1481:     into a code by calls to TaoSetMonitor(), but does not cancel those
    1482:     set via the options database

    1484:    Notes:
    1485:    There is no way to clear one specific monitor from a Tao object.

    1487:    Level: advanced

    1489: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
    1490: @*/
    1491: PetscErrorCode TaoCancelMonitors(Tao tao)
    1492: {
    1493:   PetscInt       i;

    1498:   for (i=0;i<tao->numbermonitors;i++) {
    1499:     if (tao->monitordestroy[i]) {
    1500:       (*tao->monitordestroy[i])(&tao->monitorcontext[i]);
    1501:     }
    1502:   }
    1503:   tao->numbermonitors=0;
    1504:   return(0);
    1505: }

    1509: /*@
    1510:    TaoDefaultMonitor - Default routine for monitoring progress of the
    1511:    Tao solvers (default).  This monitor prints the function value and gradient
    1512:    norm at each iteration.  It can be turned on from the command line using the
    1513:    -tao_monitor option

    1515:    Collective on Tao

    1517:    Input Parameters:
    1518: +  tao - the Tao context
    1519: -  ctx - PetscViewer context or NULL

    1521:    Options Database Keys:
    1522: .  -tao_monitor

    1524:    Level: advanced

    1526: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
    1527: @*/
    1528: PetscErrorCode TaoDefaultMonitor(Tao tao, void *ctx)
    1529: {
    1531:   PetscInt       its;
    1532:   PetscReal      fct,gnorm;
    1533:   PetscViewer    viewer;

    1536:   if (ctx) {
    1537:     viewer = (PetscViewer)ctx;
    1538:   } else {
    1539:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1540:   }
    1541:   its=tao->niter;
    1542:   fct=tao->fc;
    1543:   gnorm=tao->residual;
    1544:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
    1545:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
    1546:   if (gnorm >= PETSC_INFINITY) {
    1547:     ierr=PetscViewerASCIIPrintf(viewer,"  Residual: Inf \n");
    1548:   } else {
    1549:     ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g \n",(double)gnorm);
    1550:   }
    1551:   return(0);
    1552: }

    1556: /*@
    1557:    TaoDefaultSMonitor - Default routine for monitoring progress of the
    1558:    solver. Same as TaoDefaultMonitor() except
    1559:    it prints fewer digits of the residual as the residual gets smaller.
    1560:    This is because the later digits are meaningless and are often
    1561:    different on different machines; by using this routine different
    1562:    machines will usually generate the same output. It can be turned on
    1563:    by using the -tao_smonitor option

    1565:    Collective on Tao

    1567:    Input Parameters:
    1568: +  tao - the Tao context
    1569: -  ctx - PetscViewer context or NULL

    1571:    Options Database Keys:
    1572: .  -tao_smonitor

    1574:    Level: advanced

    1576: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
    1577: @*/
    1578: PetscErrorCode TaoDefaultSMonitor(Tao tao, void *ctx)
    1579: {
    1581:   PetscInt       its;
    1582:   PetscReal      fct,gnorm;
    1583:   PetscViewer    viewer;

    1586:   if (ctx) {
    1587:     viewer = (PetscViewer)ctx;
    1588:   } else {
    1589:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1590:   }
    1591:   its=tao->niter;
    1592:   fct=tao->fc;
    1593:   gnorm=tao->residual;
    1594:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %3D,",its);
    1595:   ierr=PetscViewerASCIIPrintf(viewer," Function value %g,",(double)fct);
    1596:   if (gnorm >= PETSC_INFINITY/2) {
    1597:     ierr=PetscViewerASCIIPrintf(viewer," Residual: Inf \n");
    1598:   } else if (gnorm > 1.e-6) {
    1599:     ierr=PetscViewerASCIIPrintf(viewer," Residual: %g \n",(double)gnorm);
    1600:   } else if (gnorm > 1.e-11) {
    1601:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-6 \n");
    1602:   } else {
    1603:     ierr=PetscViewerASCIIPrintf(viewer," Residual: < 1.0e-11 \n");
    1604:   }
    1605:   return(0);
    1606: }

    1610: /*@
    1611:    TaoDefaultCMonitor - same as TaoDefaultMonitor() except
    1612:    it prints the norm of the constraints function. It can be turned on
    1613:    from the command line using the -tao_cmonitor option

    1615:    Collective on Tao

    1617:    Input Parameters:
    1618: +  tao - the Tao context
    1619: -  ctx - PetscViewer context or NULL

    1621:    Options Database Keys:
    1622: .  -tao_cmonitor

    1624:    Level: advanced

    1626: .seealso: TaoDefaultMonitor(), TaoSetMonitor()
    1627: @*/
    1628: PetscErrorCode TaoDefaultCMonitor(Tao tao, void *ctx)
    1629: {
    1631:   PetscInt       its;
    1632:   PetscReal      fct,gnorm;
    1633:   PetscViewer    viewer;

    1636:   if (ctx) {
    1637:     viewer = (PetscViewer)ctx;
    1638:   } else {
    1639:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1640:   }
    1641:   its=tao->niter;
    1642:   fct=tao->fc;
    1643:   gnorm=tao->residual;
    1644:   ierr=PetscViewerASCIIPrintf(viewer,"iter = %D,",its);
    1645:   ierr=PetscViewerASCIIPrintf(viewer," Function value: %g,",(double)fct);
    1646:   ierr=PetscViewerASCIIPrintf(viewer,"  Residual: %g ",(double)gnorm);
    1647:   PetscViewerASCIIPrintf(viewer,"  Constraint: %g \n",(double)tao->cnorm);
    1648:   return(0);
    1649: }

    1653: /*@C
    1654:    TaoSolutionMonitor - Views the solution at each iteration
    1655:    It can be turned on from the command line using the
    1656:    -tao_view_solution option

    1658:    Collective on Tao

    1660:    Input Parameters:
    1661: +  tao - the Tao context
    1662: -  ctx - PetscViewer context or NULL

    1664:    Options Database Keys:
    1665: .  -tao_view_solution

    1667:    Level: advanced

    1669: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
    1670: @*/
    1671: PetscErrorCode TaoSolutionMonitor(Tao tao, void *ctx)
    1672: {
    1674:   PetscViewer viewer;

    1677:   if (ctx) {
    1678:     viewer = (PetscViewer)ctx;
    1679:   } else {
    1680:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1681:   }
    1682:   VecView(tao->solution, viewer);
    1683:   return(0);
    1684: }

    1688: /*@C
    1689:    TaoGradientMonitor - Views the gradient at each iteration
    1690:    It can be turned on from the command line using the
    1691:    -tao_view_gradient option

    1693:    Collective on Tao

    1695:    Input Parameters:
    1696: +  tao - the Tao context
    1697: -  ctx - PetscViewer context or NULL

    1699:    Options Database Keys:
    1700: .  -tao_view_gradient

    1702:    Level: advanced

    1704: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
    1705: @*/
    1706: PetscErrorCode TaoGradientMonitor(Tao tao, void *ctx)
    1707: {
    1709:   PetscViewer viewer;

    1712:   if (ctx) {
    1713:     viewer = (PetscViewer)ctx;
    1714:   } else {
    1715:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1716:   }
    1717:   VecView(tao->gradient, viewer);
    1718:   return(0);
    1719: }

    1723: /*@C
    1724:    TaoStepDirectionMonitor - Views the gradient at each iteration
    1725:    It can be turned on from the command line using the
    1726:    -tao_view_gradient option

    1728:    Collective on Tao

    1730:    Input Parameters:
    1731: +  tao - the Tao context
    1732: -  ctx - PetscViewer context or NULL

    1734:    Options Database Keys:
    1735: .  -tao_view_gradient

    1737:    Level: advanced

    1739: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
    1740: @*/
    1741: PetscErrorCode TaoStepDirectionMonitor(Tao tao, void *ctx)
    1742: {
    1744:   PetscViewer viewer;
    1746:   if (ctx) {
    1747:     viewer = (PetscViewer)ctx;
    1748:   } else {
    1749:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1750:   }
    1751:   VecView(tao->stepdirection, viewer);
    1752:   return(0);
    1753: }

    1757: /*@C
    1758:    TaoDrawSolutionMonitor - Plots the solution at each iteration
    1759:    It can be turned on from the command line using the
    1760:    -tao_draw_solution option

    1762:    Collective on Tao

    1764:    Input Parameters:
    1765: +  tao - the Tao context
    1766: -  ctx - PetscViewer context or NULL

    1768:    Options Database Keys:
    1769: .  -tao_draw_solution

    1771:    Level: advanced

    1773: .seealso: TaoSolutionMonitor(), TaoSetMonitor(), TaoDrawGradientMonitor
    1774: @*/
    1775: PetscErrorCode TaoDrawSolutionMonitor(Tao tao, void *ctx)
    1776: {
    1778:   PetscViewer    viewer = (PetscViewer) ctx;
    1779:   MPI_Comm       comm;

    1782:   if (!viewer) {
    1783:     PetscObjectGetComm((PetscObject)tao,&comm);
    1784:     viewer = PETSC_VIEWER_DRAW_(comm);
    1785:   }
    1786:   VecView(tao->solution, viewer);
    1787:   return(0);
    1788: }

    1792: /*@C
    1793:    TaoDrawGradientMonitor - Plots the gradient at each iteration
    1794:    It can be turned on from the command line using the
    1795:    -tao_draw_gradient option

    1797:    Collective on Tao

    1799:    Input Parameters:
    1800: +  tao - the Tao context
    1801: -  ctx - PetscViewer context or NULL

    1803:    Options Database Keys:
    1804: .  -tao_draw_gradient

    1806:    Level: advanced

    1808: .seealso: TaoGradientMonitor(), TaoSetMonitor(), TaoDrawSolutionMonitor
    1809: @*/
    1810: PetscErrorCode TaoDrawGradientMonitor(Tao tao, void *ctx)
    1811: {
    1813:   PetscViewer    viewer = (PetscViewer)ctx;
    1814:   MPI_Comm       comm;

    1817:   if (!viewer) {
    1818:     PetscObjectGetComm((PetscObject)tao,&comm);
    1819:     viewer = PETSC_VIEWER_DRAW_(comm);
    1820:   }
    1821:   VecView(tao->gradient, viewer);
    1822:   return(0);
    1823: }

    1827: /*@C
    1828:    TaoDrawStepMonitor - Plots the step direction at each iteration
    1829:    It can be turned on from the command line using the
    1830:    -tao_draw_step option

    1832:    Collective on Tao

    1834:    Input Parameters:
    1835: +  tao - the Tao context
    1836: -  ctx - PetscViewer context or NULL

    1838:    Options Database Keys:
    1839: .  -tao_draw_step

    1841:    Level: advanced

    1843: .seealso: TaoSetMonitor(), TaoDrawSolutionMonitor
    1844: @*/
    1845: PetscErrorCode TaoDrawStepMonitor(Tao tao, void *ctx)
    1846: {
    1848:   PetscViewer    viewer = (PetscViewer)(ctx);
    1849:   MPI_Comm       comm;

    1852:   if (!viewer) {
    1853:     PetscObjectGetComm((PetscObject)tao,&comm);
    1854:     viewer = PETSC_VIEWER_DRAW_(comm);
    1855:   }
    1856:   VecView(tao->stepdirection, viewer);
    1857:   return(0);
    1858: }

    1862: /*@C
    1863:    TaoSeparableObjectiveMonitor - Views the separable objective function at each iteration
    1864:    It can be turned on from the command line using the
    1865:    -tao_view_separableobjective option

    1867:    Collective on Tao

    1869:    Input Parameters:
    1870: +  tao - the Tao context
    1871: -  ctx - PetscViewer context or NULL

    1873:    Options Database Keys:
    1874: .  -tao_view_separableobjective

    1876:    Level: advanced

    1878: .seealso: TaoDefaultSMonitor(), TaoSetMonitor()
    1879: @*/
    1880: PetscErrorCode TaoSeparableObjectiveMonitor(Tao tao, void *ctx)
    1881: {
    1883:   PetscViewer    viewer;

    1886:   if (ctx) {
    1887:     viewer = (PetscViewer)ctx;
    1888:   } else {
    1889:     viewer = PETSC_VIEWER_STDOUT_(((PetscObject)tao)->comm);
    1890:   }
    1891:   VecView(tao->sep_objective,viewer);
    1892:   return(0);
    1893: }

    1897: /*@
    1898:    TaoDefaultConvergenceTest - Determines whether the solver should continue iterating
    1899:    or terminate.

    1901:    Collective on Tao

    1903:    Input Parameters:
    1904: +  tao - the Tao context
    1905: -  dummy - unused dummy context

    1907:    Output Parameter:
    1908: .  reason - for terminating

    1910:    Notes:
    1911:    This routine checks the residual in the optimality conditions, the
    1912:    relative residual in the optimity conditions, the number of function
    1913:    evaluations, and the function value to test convergence.  Some
    1914:    solvers may use different convergence routines.

    1916:    Level: developer

    1918: .seealso: TaoSetTolerances(),TaoGetConvergedReason(),TaoSetConvergedReason()
    1919: @*/

    1921: PetscErrorCode TaoDefaultConvergenceTest(Tao tao,void *dummy)
    1922: {
    1923:   PetscInt           niter=tao->niter, nfuncs=PetscMax(tao->nfuncs,tao->nfuncgrads);
    1924:   PetscInt           max_funcs=tao->max_funcs;
    1925:   PetscReal          gnorm=tao->residual, gnorm0=tao->gnorm0;
    1926:   PetscReal          f=tao->fc, steptol=tao->steptol,trradius=tao->step;
    1927:   PetscReal          gatol=tao->gatol,grtol=tao->grtol,gttol=tao->gttol;
    1928:   PetscReal          fatol=tao->fatol,frtol=tao->frtol,catol=tao->catol,crtol=tao->crtol;
    1929:   PetscReal          fmin=tao->fmin, cnorm=tao->cnorm, cnorm0=tao->cnorm0;
    1930:   PetscReal          gnorm2;
    1931:   TaoConvergedReason reason=tao->reason;
    1932:   PetscErrorCode     ierr;

    1936:   if (reason != TAO_CONTINUE_ITERATING) {
    1937:     return(0);
    1938:   }
    1939:   gnorm2=gnorm*gnorm;

    1941:   if (PetscIsInfOrNanReal(f)) {
    1942:     PetscInfo(tao,"Failed to converged, function value is Inf or NaN\n");
    1943:     reason = TAO_DIVERGED_NAN;
    1944:   } else if (f <= fmin && cnorm <=catol) {
    1945:     PetscInfo2(tao,"Converged due to function value %g < minimum function value %g\n", (double)f,(double)fmin);
    1946:     reason = TAO_CONVERGED_MINF;
    1947:   } else if (gnorm2 <= fatol && cnorm <=catol) {
    1948:     PetscInfo2(tao,"Converged due to estimated f(X) - f(X*) = %g < %g\n",(double)gnorm2,(double)fatol);
    1949:     reason = TAO_CONVERGED_FATOL;
    1950:   } else if (f != 0 && gnorm2 / PetscAbsReal(f)<= frtol && cnorm/PetscMax(cnorm0,1.0) <= crtol) {
    1951:     PetscInfo2(tao,"Converged due to estimated |f(X)-f(X*)|/f(X) = %g < %g\n",(double)(gnorm2/PetscAbsReal(f)),(double)frtol);
    1952:     reason = TAO_CONVERGED_FRTOL;
    1953:   } else if (gnorm<= gatol && cnorm <=catol) {
    1954:     PetscInfo2(tao,"Converged due to residual norm ||g(X)||=%g < %g\n",(double)gnorm,(double)gatol);
    1955:     reason = TAO_CONVERGED_GATOL;
    1956:   } else if ( f!=0 && PetscAbsReal(gnorm/f) <= grtol && cnorm <= crtol) {
    1957:     PetscInfo2(tao,"Converged due to residual ||g(X)||/|f(X)| =%g < %g\n",(double)(gnorm/f),(double)grtol);
    1958:     reason = TAO_CONVERGED_GRTOL;
    1959:   } else if (gnorm0 != 0 && gnorm/gnorm0 <= gttol && cnorm <= crtol) {
    1960:     PetscInfo2(tao,"Converged due to relative residual norm ||g(X)||/||g(X0)|| = %g < %g\n",(double)(gnorm/gnorm0),(double)gttol);
    1961:     reason = TAO_CONVERGED_GTTOL;
    1962:   } else if (nfuncs > max_funcs){
    1963:     PetscInfo2(tao,"Exceeded maximum number of function evaluations: %D > %D\n", nfuncs,max_funcs);
    1964:     reason = TAO_DIVERGED_MAXFCN;
    1965:   } else if ( tao->lsflag != 0 ){
    1966:     PetscInfo(tao,"Tao Line Search failure.\n");
    1967:     reason = TAO_DIVERGED_LS_FAILURE;
    1968:   } else if (trradius < steptol && niter > 0){
    1969:     PetscInfo2(tao,"Trust region/step size too small: %g < %g\n", (double)trradius,(double)steptol);
    1970:     reason = TAO_CONVERGED_STEPTOL;
    1971:   } else if (niter > tao->max_it) {
    1972:     PetscInfo2(tao,"Exceeded maximum number of iterations: %D > %D\n",niter,tao->max_it);
    1973:     reason = TAO_DIVERGED_MAXITS;
    1974:   } else {
    1975:     reason = TAO_CONTINUE_ITERATING;
    1976:   }
    1977:   tao->reason = reason;
    1978:   return(0);
    1979: }

    1983: /*@C
    1984:    TaoSetOptionsPrefix - Sets the prefix used for searching for all
    1985:    TAO options in the database.

    1988:    Logically Collective on Tao

    1990:    Input Parameters:
    1991: +  tao - the Tao context
    1992: -  prefix - the prefix string to prepend to all TAO option requests

    1994:    Notes:
    1995:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1996:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    1998:    For example, to distinguish between the runtime options for two
    1999:    different TAO solvers, one could call
    2000: .vb
    2001:       TaoSetOptionsPrefix(tao1,"sys1_")
    2002:       TaoSetOptionsPrefix(tao2,"sys2_")
    2003: .ve

    2005:    This would enable use of different options for each system, such as
    2006: .vb
    2007:       -sys1_tao_method blmvm -sys1_tao_gtol 1.e-3
    2008:       -sys2_tao_method lmvm  -sys2_tao_gtol 1.e-4
    2009: .ve

    2012:    Level: advanced

    2014: .seealso: TaoAppendOptionsPrefix(), TaoGetOptionsPrefix()
    2015: @*/

    2017: PetscErrorCode TaoSetOptionsPrefix(Tao tao, const char p[])
    2018: {

    2022:   PetscObjectSetOptionsPrefix((PetscObject)tao,p);
    2023:   if (tao->linesearch) {
    2024:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
    2025:   }
    2026:   if (tao->ksp) {
    2027:     KSPSetOptionsPrefix(tao->ksp,p);
    2028:   }
    2029:   return(0);
    2030: }

    2034: /*@C
    2035:    TaoAppendOptionsPrefix - Appends to the prefix used for searching for all
    2036:    TAO options in the database.

    2039:    Logically Collective on Tao

    2041:    Input Parameters:
    2042: +  tao - the Tao solver context
    2043: -  prefix - the prefix string to prepend to all TAO option requests

    2045:    Notes:
    2046:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    2047:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    2050:    Level: advanced

    2052: .seealso: TaoSetOptionsPrefix(), TaoGetOptionsPrefix()
    2053: @*/
    2054: PetscErrorCode TaoAppendOptionsPrefix(Tao tao, const char p[])
    2055: {

    2059:   PetscObjectAppendOptionsPrefix((PetscObject)tao,p);
    2060:   if (tao->linesearch) {
    2061:     TaoLineSearchSetOptionsPrefix(tao->linesearch,p);
    2062:   }
    2063:   if (tao->ksp) {
    2064:     KSPSetOptionsPrefix(tao->ksp,p);
    2065:   }
    2066:   return(0);
    2067: }

    2071: /*@C
    2072:   TaoGetOptionsPrefix - Gets the prefix used for searching for all
    2073:   TAO options in the database

    2075:   Not Collective

    2077:   Input Parameters:
    2078: . tao - the Tao context

    2080:   Output Parameters:
    2081: . prefix - pointer to the prefix string used is returned

    2083:   Notes: On the fortran side, the user should pass in a string 'prefix' of
    2084:   sufficient length to hold the prefix.

    2086:   Level: advanced

    2088: .seealso: TaoSetOptionsPrefix(), TaoAppendOptionsPrefix()
    2089: @*/
    2090: PetscErrorCode TaoGetOptionsPrefix(Tao tao, const char *p[])
    2091: {
    2092:    return PetscObjectGetOptionsPrefix((PetscObject)tao,p);
    2093: }

    2097: /*@C
    2098:    TaoSetType - Sets the method for the unconstrained minimization solver.

    2100:    Collective on Tao

    2102:    Input Parameters:
    2103: +  solver - the Tao solver context
    2104: -  type - a known method

    2106:    Options Database Key:
    2107: .  -tao_type <type> - Sets the method; use -help for a list
    2108:    of available methods (for instance, "-tao_type lmvm" or "-tao_type tron")

    2110:    Available methods include:
    2111: +    nls - Newton's method with line search for unconstrained minimization
    2112: .    ntr - Newton's method with trust region for unconstrained minimization
    2113: .    ntl - Newton's method with trust region, line search for unconstrained minimization
    2114: .    lmvm - Limited memory variable metric method for unconstrained minimization
    2115: .    cg - Nonlinear conjugate gradient method for unconstrained minimization
    2116: .    nm - Nelder-Mead algorithm for derivate-free unconstrained minimization
    2117: .    tron - Newton Trust Region method for bound constrained minimization
    2118: .    gpcg - Newton Trust Region method for quadratic bound constrained minimization
    2119: .    blmvm - Limited memory variable metric method for bound constrained minimization
    2120: -    pounders - Model-based algorithm pounder extended for nonlinear least squares

    2122:   Level: intermediate

    2124: .seealso: TaoCreate(), TaoGetType(), TaoType

    2126: @*/
    2127: PetscErrorCode TaoSetType(Tao tao, const TaoType type)
    2128: {
    2130:   PetscErrorCode (*create_xxx)(Tao);
    2131:   PetscBool      issame;

    2136:   PetscObjectTypeCompare((PetscObject)tao,type,&issame);
    2137:   if (issame) return(0);

    2139:   PetscFunctionListFind(TaoList, type, (void(**)(void))&create_xxx);
    2140:   if (!create_xxx) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested Tao type %s",type);

    2142:   /* Destroy the existing solver information */
    2143:   if (tao->ops->destroy) {
    2144:     (*tao->ops->destroy)(tao);
    2145:   }
    2146:   KSPDestroy(&tao->ksp);
    2147:   TaoLineSearchDestroy(&tao->linesearch);
    2148:   VecDestroy(&tao->gradient);
    2149:   VecDestroy(&tao->stepdirection);

    2151:   tao->ops->setup = 0;
    2152:   tao->ops->solve = 0;
    2153:   tao->ops->view  = 0;
    2154:   tao->ops->setfromoptions = 0;
    2155:   tao->ops->destroy = 0;

    2157:   tao->setupcalled = PETSC_FALSE;

    2159:   (*create_xxx)(tao);
    2160:   PetscObjectChangeTypeName((PetscObject)tao,type);
    2161:   return(0);
    2162: }

    2166: /*MC
    2167:    TaoRegister - Adds a method to the TAO package for unconstrained minimization.

    2169:    Synopsis:
    2170:    TaoRegister(char *name_solver,char *path,char *name_Create,int (*routine_Create)(Tao))

    2172:    Not collective

    2174:    Input Parameters:
    2175: +  sname - name of a new user-defined solver
    2176: -  func - routine to Create method context

    2178:    Notes:
    2179:    TaoRegister() may be called multiple times to add several user-defined solvers.

    2181:    Sample usage:
    2182: .vb
    2183:    TaoRegister("my_solver",MySolverCreate);
    2184: .ve

    2186:    Then, your solver can be chosen with the procedural interface via
    2187: $     TaoSetType(tao,"my_solver")
    2188:    or at runtime via the option
    2189: $     -tao_type my_solver

    2191:    Level: advanced

    2193: .seealso: TaoRegisterAll(), TaoRegisterDestroy()
    2194: M*/
    2195: PetscErrorCode TaoRegister(const char sname[], PetscErrorCode (*func)(Tao))
    2196: {

    2200:   PetscFunctionListAdd(&TaoList,sname, (void (*)(void))func);
    2201:   return(0);
    2202: }

    2206: /*@C
    2207:    TaoRegisterDestroy - Frees the list of minimization solvers that were
    2208:    registered by TaoRegisterDynamic().

    2210:    Not Collective

    2212:    Level: advanced

    2214: .seealso: TaoRegisterAll(), TaoRegister()
    2215: @*/
    2216: PetscErrorCode TaoRegisterDestroy(void)
    2217: {
    2220:   PetscFunctionListDestroy(&TaoList);
    2221:   TaoRegisterAllCalled = PETSC_FALSE;
    2222:   return(0);
    2223: }

    2227: /*@
    2228:    TaoGetIterationNumber - Gets the number of Tao iterations completed
    2229:    at this time.

    2231:    Not Collective

    2233:    Input Parameter:
    2234: .  tao - Tao context

    2236:    Output Parameter:
    2237: .  iter - iteration number

    2239:    Notes:
    2240:    For example, during the computation of iteration 2 this would return 1.

    2243:    Level: intermediate

    2245: .keywords: Tao, nonlinear, get, iteration, number,

    2247: .seealso:   TaoGetLinearSolveIterations()
    2248: @*/
    2249: PetscErrorCode  TaoGetIterationNumber(Tao tao,PetscInt *iter)
    2250: {
    2254:   *iter = tao->niter;
    2255:   return(0);
    2256: }

    2260: /*@
    2261:    TaoSetIterationNumber - Sets the current iteration number.

    2263:    Not Collective

    2265:    Input Parameter:
    2266: .  tao - Tao context
    2267: .  iter - iteration number

    2269:    Level: developer

    2271: .keywords: Tao, nonlinear, set, iteration, number,

    2273: .seealso:   TaoGetLinearSolveIterations()
    2274: @*/
    2275: PetscErrorCode  TaoSetIterationNumber(Tao tao,PetscInt iter)
    2276: {

    2281:   PetscObjectSAWsTakeAccess((PetscObject)tao);
    2282:   tao->niter = iter;
    2283:   PetscObjectSAWsGrantAccess((PetscObject)tao);
    2284:   return(0);
    2285: }

    2289: /*@
    2290:    TaoGetTotalIterationNumber - Gets the total number of Tao iterations
    2291:    completed. This number keeps accumulating if multiple solves
    2292:    are called with the Tao object.

    2294:    Not Collective

    2296:    Input Parameter:
    2297: .  tao - Tao context

    2299:    Output Parameter:
    2300: .  iter - iteration number

    2302:    Notes:
    2303:    The total iteration count is updated after each solve, if there is a current
    2304:    TaoSolve() in progress then those iterations are not yet counted.

    2306:    Level: intermediate

    2308: .keywords: Tao, nonlinear, get, iteration, number,

    2310: .seealso:   TaoGetLinearSolveIterations()
    2311: @*/
    2312: PetscErrorCode  TaoGetTotalIterationNumber(Tao tao,PetscInt *iter)
    2313: {
    2317:   *iter = tao->ntotalits;
    2318:   return(0);
    2319: }

    2323: /*@
    2324:    TaoSetTotalIterationNumber - Sets the current total iteration number.

    2326:    Not Collective

    2328:    Input Parameter:
    2329: .  tao - Tao context
    2330: .  iter - iteration number

    2332:    Level: developer

    2334: .keywords: Tao, nonlinear, set, iteration, number,

    2336: .seealso:   TaoGetLinearSolveIterations()
    2337: @*/
    2338: PetscErrorCode  TaoSetTotalIterationNumber(Tao tao,PetscInt iter)
    2339: {

    2344:   PetscObjectSAWsTakeAccess((PetscObject)tao);
    2345:   tao->ntotalits = iter;
    2346:   PetscObjectSAWsGrantAccess((PetscObject)tao);
    2347:   return(0);
    2348: }

    2352: /*@
    2353:   TaoSetConvergedReason - Sets the termination flag on a Tao object

    2355:   Logically Collective on Tao

    2357:   Input Parameters:
    2358: + tao - the Tao context
    2359: - reason - one of
    2360: $     TAO_CONVERGED_ATOL (2),
    2361: $     TAO_CONVERGED_RTOL (3),
    2362: $     TAO_CONVERGED_STEPTOL (4),
    2363: $     TAO_CONVERGED_MINF (5),
    2364: $     TAO_CONVERGED_USER (6),
    2365: $     TAO_DIVERGED_MAXITS (-2),
    2366: $     TAO_DIVERGED_NAN (-4),
    2367: $     TAO_DIVERGED_MAXFCN (-5),
    2368: $     TAO_DIVERGED_LS_FAILURE (-6),
    2369: $     TAO_DIVERGED_TR_REDUCTION (-7),
    2370: $     TAO_DIVERGED_USER (-8),
    2371: $     TAO_CONTINUE_ITERATING (0)

    2373:    Level: intermediate

    2375: @*/
    2376: PetscErrorCode TaoSetConvergedReason(Tao tao, TaoConvergedReason reason)
    2377: {
    2380:   tao->reason = reason;
    2381:   return(0);
    2382: }

    2386: /*@
    2387:    TaoGetConvergedReason - Gets the reason the Tao iteration was stopped.

    2389:    Not Collective

    2391:    Input Parameter:
    2392: .  tao - the Tao solver context

    2394:    Output Parameter:
    2395: .  reason - one of
    2396: $  TAO_CONVERGED_FATOL (1)           f(X)-f(X*) <= fatol
    2397: $  TAO_CONVERGED_FRTOL (2)           |f(X) - f(X*)|/|f(X)| < frtol
    2398: $  TAO_CONVERGED_GATOL (3)           ||g(X)|| < gatol
    2399: $  TAO_CONVERGED_GRTOL (4)           ||g(X)|| / f(X)  < grtol
    2400: $  TAO_CONVERGED_GTTOL (5)           ||g(X)|| / ||g(X0)|| < gttol
    2401: $  TAO_CONVERGED_STEPTOL (6)         step size small
    2402: $  TAO_CONVERGED_MINF (7)            F < F_min
    2403: $  TAO_CONVERGED_USER (8)            User defined
    2404: $  TAO_DIVERGED_MAXITS (-2)          its > maxits
    2405: $  TAO_DIVERGED_NAN (-4)             Numerical problems
    2406: $  TAO_DIVERGED_MAXFCN (-5)          fevals > max_funcsals
    2407: $  TAO_DIVERGED_LS_FAILURE (-6)      line search failure
    2408: $  TAO_DIVERGED_TR_REDUCTION (-7)    trust region failure
    2409: $  TAO_DIVERGED_USER(-8)             (user defined)
    2410:  $  TAO_CONTINUE_ITERATING (0)

    2412:    where
    2413: +  X - current solution
    2414: .  X0 - initial guess
    2415: .  f(X) - current function value
    2416: .  f(X*) - true solution (estimated)
    2417: .  g(X) - current gradient
    2418: .  its - current iterate number
    2419: .  maxits - maximum number of iterates
    2420: .  fevals - number of function evaluations
    2421: -  max_funcsals - maximum number of function evaluations

    2423:    Level: intermediate

    2425: .seealso: TaoSetConvergenceTest(), TaoSetTolerances()

    2427: @*/
    2428: PetscErrorCode TaoGetConvergedReason(Tao tao, TaoConvergedReason *reason)
    2429: {
    2433:   *reason = tao->reason;
    2434:   return(0);
    2435: }

    2439: /*@
    2440:   TaoGetSolutionStatus - Get the current iterate, objective value,
    2441:   residual, infeasibility, and termination

    2443:   Not Collective

    2445:    Input Parameters:
    2446: .  tao - the Tao context

    2448:    Output Parameters:
    2449: +  iterate - the current iterate number (>=0)
    2450: .  f - the current function value
    2451: .  gnorm - the square of the gradient norm, duality gap, or other measure indicating distance from optimality.
    2452: .  cnorm - the infeasibility of the current solution with regard to the constraints.
    2453: .  xdiff - the step length or trust region radius of the most recent iterate.
    2454: -  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

    2456:    Level: intermediate

    2458:    Note:
    2459:    TAO returns the values set by the solvers in the routine TaoMonitor().

    2461:    Note:
    2462:    If any of the output arguments are set to NULL, no corresponding value will be returned.

    2464: .seealso: TaoMonitor(), TaoGetConvergedReason()
    2465: @*/
    2466: PetscErrorCode TaoGetSolutionStatus(Tao tao, PetscInt *its, PetscReal *f, PetscReal *gnorm, PetscReal *cnorm, PetscReal *xdiff, TaoConvergedReason *reason)
    2467: {
    2469:   if (its) *its=tao->niter;
    2470:   if (f) *f=tao->fc;
    2471:   if (gnorm) *gnorm=tao->residual;
    2472:   if (cnorm) *cnorm=tao->cnorm;
    2473:   if (reason) *reason=tao->reason;
    2474:   if (xdiff) *xdiff=tao->step;
    2475:   return(0);
    2476: }

    2480: /*@C
    2481:    TaoGetType - Gets the current Tao algorithm.

    2483:    Not Collective

    2485:    Input Parameter:
    2486: .  tao - the Tao solver context

    2488:    Output Parameter:
    2489: .  type - Tao method

    2491:    Level: intermediate

    2493: @*/
    2494: PetscErrorCode TaoGetType(Tao tao, const TaoType *type)
    2495: {
    2499:   *type=((PetscObject)tao)->type_name;
    2500:   return(0);
    2501: }

    2505: /*@C
    2506:   TaoMonitor - Monitor the solver and the current solution.  This
    2507:   routine will record the iteration number and residual statistics,
    2508:   call any monitors specified by the user, and calls the convergence-check routine.

    2510:    Input Parameters:
    2511: +  tao - the Tao context
    2512: .  its - the current iterate number (>=0)
    2513: .  f - the current objective function value
    2514: .  res - the gradient norm, square root of the duality gap, or other measure indicating distince from optimality.  This measure will be recorded and
    2515:           used for some termination tests.
    2516: .  cnorm - the infeasibility of the current solution with regard to the constraints.
    2517: -  steplength - multiple of the step direction added to the previous iterate.

    2519:    Output Parameters:
    2520: .  reason - The termination reason, which can equal TAO_CONTINUE_ITERATING

    2522:    Options Database Key:
    2523: .  -tao_monitor - Use the default monitor, which prints statistics to standard output

    2525: .seealso TaoGetConvergedReason(), TaoDefaultMonitor(), TaoSetMonitor()

    2527:    Level: developer

    2529: @*/
    2530: PetscErrorCode TaoMonitor(Tao tao, PetscInt its, PetscReal f, PetscReal res, PetscReal cnorm, PetscReal steplength, TaoConvergedReason *reason)
    2531: {
    2533:   PetscInt       i;

    2537:   tao->fc = f;
    2538:   tao->residual = res;
    2539:   tao->cnorm = cnorm;
    2540:   tao->step = steplength;
    2541:   if (its == 0) {
    2542:     tao->cnorm0 = cnorm; tao->gnorm0 = res;
    2543:   }
    2544:   TaoLogConvergenceHistory(tao,f,res,cnorm,tao->ksp_its);
    2545:   if (PetscIsInfOrNanReal(f) || PetscIsInfOrNanReal(res)) SETERRQ(PETSC_COMM_SELF,1, "User provided compute function generated Inf or NaN");
    2546:   if (tao->ops->convergencetest) {
    2547:     (*tao->ops->convergencetest)(tao,tao->cnvP);
    2548:   }
    2549:   for (i=0;i<tao->numbermonitors;i++) {
    2550:     (*tao->monitor[i])(tao,tao->monitorcontext[i]);
    2551:   }
    2552:   *reason = tao->reason;
    2553:   return(0);
    2554: }

    2558: /*@
    2559:    TaoSetConvergenceHistory - Sets the array used to hold the convergence history.

    2561:    Logically Collective on Tao

    2563:    Input Parameters:
    2564: +  tao - the Tao solver context
    2565: .  obj   - array to hold objective value history
    2566: .  resid - array to hold residual history
    2567: .  cnorm - array to hold constraint violation history
    2568: .  lits - integer array holds the number of linear iterations for each Tao iteration
    2569: .  na  - size of obj, resid, and cnorm
    2570: -  reset - PetscTrue indicates each new minimization resets the history counter to zero,
    2571:            else it continues storing new values for new minimizations after the old ones

    2573:    Notes:
    2574:    If set, TAO will fill the given arrays with the indicated
    2575:    information at each iteration.  If 'obj','resid','cnorm','lits' are
    2576:    *all* NULL then space (using size na, or 1000 if na is PETSC_DECIDE or
    2577:    PETSC_DEFAULT) is allocated for the history.
    2578:    If not all are NULL, then only the non-NULL information categories
    2579:    will be stored, the others will be ignored.

    2581:    Any convergence information after iteration number 'na' will not be stored.

    2583:    This routine is useful, e.g., when running a code for purposes
    2584:    of accurate performance monitoring, when no I/O should be done
    2585:    during the section of code that is being timed.

    2587:    Level: intermediate

    2589: .seealso: TaoGetConvergenceHistory()

    2591: @*/
    2592: PetscErrorCode TaoSetConvergenceHistory(Tao tao, PetscReal *obj, PetscReal *resid, PetscReal *cnorm, PetscInt *lits, PetscInt na,PetscBool reset)
    2593: {

    2603:   if (na == PETSC_DECIDE || na == PETSC_DEFAULT) na = 1000;
    2604:   if (!obj && !resid && !cnorm && !lits) {
    2605:     PetscCalloc1(na,&obj);
    2606:     PetscCalloc1(na,&resid);
    2607:     PetscCalloc1(na,&cnorm);
    2608:     PetscCalloc1(na,&lits);
    2609:     tao->hist_malloc=PETSC_TRUE;
    2610:   }

    2612:   tao->hist_obj = obj;
    2613:   tao->hist_resid = resid;
    2614:   tao->hist_cnorm = cnorm;
    2615:   tao->hist_lits = lits;
    2616:   tao->hist_max   = na;
    2617:   tao->hist_reset = reset;
    2618:   tao->hist_len = 0;
    2619:   return(0);
    2620: }

    2624: /*@C
    2625:    TaoGetConvergenceHistory - Gets the arrays used to hold the convergence history.

    2627:    Collective on Tao

    2629:    Input Parameter:
    2630: .  tao - the Tao context

    2632:    Output Parameters:
    2633: +  obj   - array used to hold objective value history
    2634: .  resid - array used to hold residual history
    2635: .  cnorm - array used to hold constraint violation history
    2636: .  lits  - integer array used to hold linear solver iteration count
    2637: -  nhist  - size of obj, resid, cnorm, and lits (will be less than or equal to na given in TaoSetHistory)

    2639:    Notes:
    2640:     This routine must be preceded by calls to TaoSetConvergenceHistory()
    2641:     and TaoSolve(), otherwise it returns useless information.

    2643:     The calling sequence for this routine in Fortran is
    2644: $   call TaoGetConvergenceHistory(Tao tao, PetscInt nhist, PetscErrorCode ierr)

    2646:    This routine is useful, e.g., when running a code for purposes
    2647:    of accurate performance monitoring, when no I/O should be done
    2648:    during the section of code that is being timed.

    2650:    Level: advanced

    2652: .seealso: TaoSetConvergenceHistory()

    2654: @*/
    2655: PetscErrorCode TaoGetConvergenceHistory(Tao tao, PetscReal **obj, PetscReal **resid, PetscReal **cnorm, PetscInt **lits, PetscInt *nhist)
    2656: {
    2659:   if (obj)   *obj   = tao->hist_obj;
    2660:   if (cnorm) *cnorm = tao->hist_cnorm;
    2661:   if (resid) *resid = tao->hist_resid;
    2662:   if (nhist) *nhist   = tao->hist_len;
    2663:   return(0);
    2664: }

    2668: /*@
    2669:    TaoSetApplicationContext - Sets the optional user-defined context for
    2670:    a solver.

    2672:    Logically Collective on Tao

    2674:    Input Parameters:
    2675: +  tao  - the Tao context
    2676: -  usrP - optional user context

    2678:    Level: intermediate

    2680: .seealso: TaoGetApplicationContext(), TaoSetApplicationContext()
    2681: @*/
    2682: PetscErrorCode  TaoSetApplicationContext(Tao tao,void *usrP)
    2683: {
    2686:   tao->user = usrP;
    2687:   return(0);
    2688: }

    2692: /*@
    2693:    TaoGetApplicationContext - Gets the user-defined context for a
    2694:    TAO solvers.

    2696:    Not Collective

    2698:    Input Parameter:
    2699: .  tao  - Tao context

    2701:    Output Parameter:
    2702: .  usrP - user context

    2704:    Level: intermediate

    2706: .seealso: TaoSetApplicationContext()
    2707: @*/
    2708: PetscErrorCode  TaoGetApplicationContext(Tao tao,void *usrP)
    2709: {
    2712:   *(void**)usrP = tao->user;
    2713:   return(0);
    2714: }