Actual source code: line.c

      1: /*$Id: line.c 1.31 04/03/09 16:11:16-06:00 sarich@Chico.mcs.anl.gov $*/

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

      7: /*@C
      8:    TaoSetLineSearch - Set the line search routine for algorithms that
      9:    require one.

     11:    Collective on TAO_SOLVER

     13:    Input Parameter:
     14: +  tao - the TAO_SOLVER solver context
     15: .  setup -  setup routine (or TAO_NULL)
     16: .  options - set line search options (or TAO_NULL)
     17: .  line - the line search routine
     18: .  viewit - routine that views the linesearch (or TAO_NULL)
     19: .  destroy - destroys the user defined routine when the solver is destroyed (or TAO_NULL)
     20: -  ctx - linesearch structure (or TAO_NULL)

     22:    Calling sequence of line:
     23: $     line(TAO_SOLVER tao, TaoVec* X, TaoVec* G, TaoVec* DX, TaoVec* Work, double *f,double *step, int *flag, void *ctx)

     25:    Input Parameter for line search:
     26: +  tao - the TAO_SOLVER solver context
     27: .  xx - current solution
     28: .  gg - current gradient
     29: .  dxdx - step direction
     30: .  Work - work vector
     31: .  f - function value
     32: .  step - initial stepsize
     33: -  ctx - user-defined line search context

     35:    Output Parameter for line search:
     36: +  X - new solution
     37: .  G - new gradient
     38: .  f - new function value
     39: .  step - multiple of DX added to the previous solution
     40: -  flag - indicator of success or failure (flag=0 is a success, flag=7 means DX is not a descent direction)

     42:    Notes:
     43:    The input parameter gdx should be negative and is used to test the Armijo
     44:    condition.
     45:
     46:    To ensure descent in a projected line search, the input parameter gdx
     47:    should be the inner product of the gradient and the first linear manifold
     48:    being searched.

     50:    Level: advanced

     52: .keywords: TAO_SOLVER, destroy

     54: .seealso: TaoLineSearchApply()
     55: @*/
     56: int TaoSetLineSearch(TAO_SOLVER tao,
     57:                      int (*setup)(TAO_SOLVER,void*),
     58:                      int (*options)(TAO_SOLVER,void*),
     59:                      int (*line)(TAO_SOLVER,TaoVec*,TaoVec*,TaoVec*,TaoVec*,
     60:                                  double*,double*,int*,void*),
     61:                      int (*viewit)(TAO_SOLVER,void*),
     62:                      int (*destroy)(TAO_SOLVER,void*),
     63:                      void *ctx)
     64: {
     65:   int info;

     67:   TaoFunctionBegin;
     68:   TaoValidHeaderSpecific(tao,TAO_COOKIE,1);

     70:   info=TaoLineSearchDestroy(tao);CHKERRQ(info);

     72:   tao->LineSearchSetUp                = setup;
     73:   tao->LineSearchSetFromOptions = options;
     74:   tao->LineSearchApply          = line;
     75:   tao->LineSearchView           = viewit;
     76:   tao->LineSearchDestroy        = destroy;
     77:   tao->linectx                  = ctx;
     78:   tao->lsflag                  = 0;

     80:   TaoFunctionReturn(0);
     81: }

     86: /*@C
     87:    TaoLineSearchView - View information about the line search

     89:    Collective on TAO_SOLVER

     91:    Input Parameter:
     92: .  tao - the TAO_SOLVER solver context

     94:    Level: developer

     96: .keywords: line search, view

     98: .seealso: TaoView()
     99: @*/
    100: int TaoLineSearchView(TAO_SOLVER tao)
    101: {
    102:   int info;
    103:
    104:   if (tao->LineSearchView){
    105:     info = (*tao->LineSearchView)(tao,tao->linectx);CHKERRQ(info);
    106:   }
    107:   TaoFunctionReturn(0);
    108: }

    114: /*@C
    115:    TaoLineSearchSetUp - Setup the line search for an optimization solver

    117:    Collective on TAO_SOLVER

    119:    Input Parameter:
    120: .  tao - the TAO_SOLVER solver context

    122:    Level: developer

    124: .keywords: line search, setup

    126: .seealso: TaoSetUp()
    127: @*/
    128: int TaoLineSearchSetUp(TAO_SOLVER tao)
    129: {
    130:   int info;

    132:   if (tao->LineSearchSetUp) {
    133:     info = (*tao->LineSearchSetUp)(tao,tao->linectx);CHKERRQ(info);
    134:   }
    135:   TaoFunctionReturn(0);
    136: }

    142: /*@C
    143:    TaoLineSearchDestroy - Destroy the line search in an TAO solver

    145:    Collective on TAO_SOLVER

    147:    Input Parameter:
    148: .  tao - the TAO_SOLVER solver context

    150:    Level: developer

    152: .keywords: line search, destroy

    154: .seealso: TaoDestroy()
    155: @*/
    156: int TaoLineSearchDestroy(TAO_SOLVER tao)
    157: {
    158:   int info;

    160:   if (tao->LineSearchDestroy && tao->linectx){
    161:     info = (*tao->LineSearchDestroy)(tao,tao->linectx);CHKERRQ(info);
    162:   }
    163:   tao->linectx=0;
    164:   TaoFunctionReturn(0);
    165: }

    170: /*@C
    171:    TaoLineSearchApply - Applies a line search.

    173:    Collective on TAO_SOLVER

    175:    Input Parameter:
    176: +  tao - the TAO_SOLVER solver context
    177: .  xx - current solution
    178: .  gg - current gradient
    179: .  dxdx - step direction
    180: .  ww - work vector
    181: .  f - function value
    182: -  step - initial stepsize

    184:    Output Parameter:
    185: +  xx - new solution
    186: .  gg - new gradient
    187: .  f - new function value
    188: .  step - multiple of DX added to the previous solution
    189: -  flag - indicator of success or failure (flag=0 is a success, flag=7 means DX is not a descent direction)

    191:    Notes:
    192:    The input parameter gdx should be negative and is used to test the Armijo
    193:    condition.
    194:
    195:    To ensure descent in a projected line search, the input parameter gdx
    196:    should be the inner product of the gradient and the first linear manifold
    197:    being searched.

    199:    Level: developer

    201: .keywords: line search, help

    203: .seealso: TaoSetLineSearch()
    204: @*/
    205: int TaoLineSearchApply(TAO_SOLVER tao, TaoVec *xx, TaoVec *gg, TaoVec *dxdx, TaoVec *ww,
    206:                        double *f, double *step, int*flag)
    207: {
    208:   int info;

    210:   TaoFunctionBegin;
    211:   TaoValidHeaderSpecific(tao,TAO_COOKIE,1);
    212:   if (tao->LineSearchApply){
    213:     info = (*tao->LineSearchApply)(tao,xx,gg,dxdx,ww,f,step,flag,tao->linectx);
    214:     CHKERRQ(info);
    215:     tao->lsflag=*flag;
    216:   } else {
    217:     SETERRQ(1,"No line search has been set.");
    218:   }
    219:   TaoFunctionReturn(0);
    220: }

    224: /*@C
    225:    TaoLineSearchSetFromOptions - Set options for the line search in an optimization solver

    227:    Collective on TAO_SOLVER

    229:    Input Parameter:
    230: .  tao - the TAO_SOLVER solver context

    232:    Level: developer

    234: .keywords: line search, options

    236: .seealso: TaoSetFromOptions()
    237: @*/
    238: int TaoLineSearchSetFromOptions(TAO_SOLVER tao)
    239: {
    240:   int info;

    242:   if (tao->LineSearchSetFromOptions){
    243:     info = (*tao->LineSearchSetFromOptions)(tao,tao->linectx); CHKERRQ(info);
    244:   }
    245:   TaoFunctionReturn(0);
    246: }