~ubuntu-branches/ubuntu/hoary/scilab/hoary

<SP>: external, i.e Scilab function list or string (<VERB>costf</VERB> is the cost function: see below its calling sequence (Scilab or Fortran)). See also external for details about external functions.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>x0</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: real vector (initial value of variable to be minimized).</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>f</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: value of optimal cost (<VERB>f=costf(xopt)</VERB>)</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>xopt</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: best value of <VERB>x</VERB> found.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>contr</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: <VERB>'b',binf,bsup</VERB> with <VERB>binf</VERB> and <VERB>bsup</VERB> real vectors with same dimension as <VERB>x0</VERB>. <VERB>binf</VERB> and <VERB>bsup</VERB> are lower and upper bounds on <VERB>x</VERB>.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>"algo" </PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: <VERB>'qn'</VERB> or <VERB>'gc'</VERB> or <VERB>'nd'</VERB> . This string stands for quasi-Newton (default), conjugate gradient or non-differentiable respectively. Note that <VERB>'nd'</VERB> does not accept bounds on <VERB>x</VERB> ).</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>df0</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: real scalar. Guessed decreasing of <VERB>f</VERB> at first iteration. (<VERB>df0=1</VERB> is the default value).</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>mem : </PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>integer, number of variables used to approximate the Hessian, (<VERB>algo='gc' or 'nd'</VERB>). Default value is around 6.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>stop</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: sequence of optional parameters controlling the convergence of the algorithm. <VERB> stop= 'ar',nap, [iter [,epsg [,epsf [,epsx]]]]</VERB></SP>

<PARAM_INDENT>

<PARAM_ITEM>

<PARAM_NAME>"ar" </PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: reserved keyword for stopping rule selection defined as follows:</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>nap</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: maximum number of calls to <VERB>costf</VERB> allowed.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>iter</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: maximum number of iterations allowed.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>epsg</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: threshold on gradient norm.</SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

<PARAM_NAME>epsf</PARAM_NAME>

<PARAM_DESCRIPTION>

<SP>: threshold controlling decreasing of <VERB>f</VERB></SP>

</PARAM_DESCRIPTION>

</PARAM_ITEM>

<PARAM_ITEM>

100

<PARAM_NAME>epsx</PARAM_NAME>

101

<PARAM_DESCRIPTION>

102

<SP>: threshold controlling variation of <VERB>x</VERB>. This vector (possibly matrix) of same size as <VERB>x0</VERB> can be used to scale <VERB>x</VERB>.</SP>

103

</PARAM_DESCRIPTION>

104

</PARAM_ITEM>

105

</PARAM_INDENT>

106

</PARAM_DESCRIPTION>

107

</PARAM_ITEM>

108

<PARAM_ITEM>

109

<PARAM_NAME>"in" </PARAM_NAME>

110

<PARAM_DESCRIPTION>

111

<SP>: reserved keyword for initialization of parameters used when <VERB>costf</VERB> in given as a Fortran routine (see below).</SP>

112

</PARAM_DESCRIPTION>

113

</PARAM_ITEM>

114

<PARAM_ITEM>

115

<PARAM_NAME>"imp=iflag" </PARAM_NAME>

116

<PARAM_DESCRIPTION>

117

<SP>: named argument used to set the trace mode. <VERB>iflag=0</VERB> nothing (execpt errors) is reported, <VERB>iflag=1</VERB> initial and final reports, <VERB>iflag=2</VERB> adds a report per iteration, <VERB>iflag>2</VERB> add reports on linear search. Warning, most of these reports are written on the Scilab standard output.</SP>

118

</PARAM_DESCRIPTION>

119

</PARAM_ITEM>

120

<PARAM_ITEM>

121

<PARAM_NAME>gradopt</PARAM_NAME>

122

<PARAM_DESCRIPTION>

123

<SP>: gradient of <VERB>costf</VERB> at <VERB>xopt</VERB></SP>

124

</PARAM_DESCRIPTION>

125

</PARAM_ITEM>

126

<PARAM_ITEM>

127

<PARAM_NAME>work</PARAM_NAME>

128

<PARAM_DESCRIPTION>

129

<SP>: working array for hot restart for quasi-Newton method. This array is automatically initialized by <VERB>optim</VERB> when <VERB>optim</VERB> is invoked. It can be used as input parameter to speed-up the calculations.</SP>

130

</PARAM_DESCRIPTION>

131

</PARAM_ITEM>

132

</PARAM_INDENT>

133

</PARAM>

134

135

136

Non-linear optimization routine for programs without constraints or with bound constraints:

137

138

<![CDATA[

139

min costf(x) w.r.t x.

140

]]>

141

</VERBATIM>

142

<VERB>costf</VERB> is an "external" i.e function, or list or Fortran routine (see "external").

143

This external must return <VERB>f</VERB> (<VERB>costf(x)</VERB>) and <VERB>g</VERB> (gradient of <VERB>costf</VERB>)

144

given <VERB>x</VERB>.

145

146

If <VERB>costf</VERB> is a function, the calling sequence for <VERB>costf</VERB> must be:

147

148

<![CDATA[

149

[f,g,ind]=costf(x,ind).

150

]]>

151

</VERBATIM>

152

153

Here, <VERB>costf</VERB> is a function which returns <VERB>f</VERB>, value (real number) of

154

cost function at <VERB>x</VERB>, and <VERB>g</VERB>, gradient vector of cost function at <VERB>x</VERB>.

155

The variable <VERB>ind</VERB> is used by <VERB>optim</VERB> and is described below.

156

157

If <VERB>ind=2</VERB> (resp. <VERB>3, 4</VERB>), <VERB>costf</VERB> must provide <VERB>f</VERB> (resp. <VERB>g, f</VERB> and <VERB>g</VERB>).

158

159

If <VERB>ind=1</VERB> nothing is computed (used for display purposes only).

160

161

On output, <VERB>ind<0</VERB> means that <VERB>f</VERB> cannot be evaluated at <VERB>x</VERB> and

162

<VERB>ind=0</VERB> interrupts the optimization.

163

164

If <VERB>costf</VERB> is a character string, it refers to the name of a Fortran routine

165

which must be linked to Scilab (see examples in the routines <VERB>foptim.f</VERB>

166

and e.g. <VERB>genros.f</VERB> in the directory SCIDIR/default)

167

168

Dynamic link of Fortran routine is also possible (help <VERB>link</VERB>).

169

170

Here, the generic calling sequence for the Fortran subroutine is:

171

<VERB>function costf(ind,n,x,f,g,ti,tr,td)</VERB>

172

<VERB>ind</VERB> has the same meaning as above if set to <VERB>0,1,2</VERB> but the

173

values <VERB>ind=10</VERB> and <VERB>ind=11</VERB> are now valid.

174

These values are used for initializations (see below).

175

<VERB>n</VERB> is the dimension of <VERB>x</VERB>, <VERB>x</VERB> is an <VERB>n</VERB> vector,

176

<VERB>ti,tr,td</VERB> are working arrays.

177

178

The Fortran function <VERB>costf</VERB> must return <VERB>f</VERB> and the vector <VERB>g</VERB>,

179

given <VERB>x, ind, n, ti, tr, td</VERB>.

180

181

If <VERB>costf</VERB> is given as a Fortran routine, it is possible to initialize

182

parameters or to send Scilab variables to this routine.

183

184

This facility is managed by the parameter <VERB>'in</VERB>.

185

186

If the string <VERB>'in'</VERB> is present, initialization is done by Fortran:

187

<VERB>optim</VERB> makes two calls to the Fortran function <VERB>costf</VERB>, once with

188

<VERB>ind=10</VERB> and once with <VERB>ind=11</VERB>. In this case, for <VERB>ind=10</VERB>,

189

<VERB>costf</VERB> must set the dimensions <VERB>nti, ntr, ntd</VERB> of <VERB>ti, tr, td</VERB>

190

in the <VERB>common/nird/nti, ntr, ntd</VERB> and, for <VERB>ind=11</VERB>, <VERB>costf</VERB>

191

must initialize the vectors <VERB>ti , tr, td</VERB> (integer vector, real vector,

192

double precision vector respectively).

193

194

In the calling sequence of <VERB>optim</VERB>, the string <VERB>'in'</VERB> can be

195

replaced by <VERB>'ti', valti ,'td' , valtd</VERB>. Then, the Fortran function

196

<VERB>costf(ind, x, f, g, ti, tr, td)</VERB> is evaluated with <VERB>ti=valti</VERB>

197

and <VERB>td=valtd</VERB> whatever the value of <VERB>ind</VERB>.

198

Thus, the Scilab variables <VERB>valti</VERB> and <VERB>valtd</VERB> (integer vector and

199

real vector) are sent to the Fortran function <VERB>costf</VERB>.

200

201

It is also possible to save the content of of the working arrays

202

<VERB>ti</VERB> and <VERB>td</VERB>. This is possible by adding the strings 'si' and/or 'sd'

203

at the ned of the calling sequence of <VERB>optim</VERB>.

204

Then, the output variables must be: <VERB>[f,[x,[g],[to]]],[ti],[td]]</VERB>.

205

</DESCRIPTION>

206

207

<![CDATA[

208

xref=[1;2;3];x0=[1;-1;1]

209

deff('[f,g,ind]=cost(x,ind)','f=0.5*norm(x-xref)^2,g=x-xref');

210

[f,xopt]=optim(cost,x0) //Simplest call

211

[f,xopt,gopt]=optim(cost,x0,'gc') // By conjugate gradient

212

[f,xopt,gopt]=optim(cost,x0,'nd') //Seen as non differentiable

213

[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0) // Bounds on x

214

[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc') // Bounds on x

215

[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc','ar',3)

216

// Here, 3 calls to cost are allowed.

217

// Now calling the Fortran subroutine "genros" in SCIDIR/default/Ex-optim.f

218

// See also the link function for dynamically linking an objective function

219

[f,xopt,gopt]=optim('genros',[1;2;3]) //Rosenbrock's function

220

]]>

221

</EXAMPLE>

222

<SEE_ALSO>

223

<SEE_ALSO_ITEM>

224

<LINK>external</LINK>

225

</SEE_ALSO_ITEM>

226

<SEE_ALSO_ITEM>

227

<LINK>quapro</LINK>

228

</SEE_ALSO_ITEM>

229

<SEE_ALSO_ITEM>

230

<LINK>linpro</LINK>

231

</SEE_ALSO_ITEM>

232

<SEE_ALSO_ITEM>

233

<LINK>datafit</LINK>

234

</SEE_ALSO_ITEM>

235

<SEE_ALSO_ITEM>

236

<LINK>leastsq</LINK>

237

</SEE_ALSO_ITEM>

238

<SEE_ALSO_ITEM>

239

<LINK>numdiff</LINK>

240

</SEE_ALSO_ITEM>

241

<SEE_ALSO_ITEM>

242

<LINK>derivative</LINK>

243

</SEE_ALSO_ITEM>

244

<SEE_ALSO_ITEM>

245

<LINK>NDcost</LINK>

246

</SEE_ALSO_ITEM>

247

</SEE_ALSO>

248

</MAN>

Older »