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