← Back to branch summary

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

« back to all changes in this revision

Viewing changes to man/nonlinear/optim.man

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Werner
  • Date: 2005-01-09 22:58:21 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050109225821-473xr8vhgugxxx5j
Tags: 3.0-12
http://bugs.debian.org/255869
changed configure.in to build scilab's own malloc.o, closes: #255869

Show diffs side-by-side

added added

removed removed

Lines of Context:
man/nonlinear/optim.man
1
 
.TH optim G "April 1993" "Scilab Group" "Scilab Function"
2
 
.so ../sci.an
3
 
.SH NAME
4
 
optim - non-linear optimization routine
5
 
.SH CALLING SEQUENCE
6
 
.nf
7
 
[f,xopt]=optim(costf,x0)
8
 
[f,[xopt,[gradopt,[work]]]]=optim(costf,[contr],x0,['algo'],[df0,[mem]],
9
 
     [work],[stop],['in'],[imp=iflag])
10
 
.fi
11
 
.SH PARAMETERS
12
 
.TP 10
13
 
costf
14
 
: external, i.e Scilab function or string (\fVcostf\fR is the cost function: see below its
15
 
calling sequence (Scilab or Fortran)).
16
 
.TP
17
 
x0 
18
 
: real vector (initial value of variable to be minimized).
19
 
.TP
20
 
f
21
 
: value of optimal cost (\fVf=costf(xopt)\fR)
22
 
.TP
23
 
xopt
24
 
: best value of \fVx\fR found.
25
 
.TP
26
 
contr 
27
 
: \fV'b',binf,bsup\fR  with \fVbinf\fR and \fVbsup\fR real vectors with same
28
 
dimension as \fVx0\fR. \fVbinf\fR and \fVbsup\fR are lower and upper bounds on \fVx\fR.
29
 
.TP
30
 
"algo"
31
 
: \fV'qn'\fR or \fV'gc'\fR or \fV'nd'\fR . This string stands for quasi-Newton (default), 
32
 
conjugate gradient or non-differentiable respectively. 
33
 
Note that \fV'nd'\fR does not accept bounds on \fVx\fR ).
34
 
.TP
35
 
df0 
36
 
: real scalar. Guessed decreasing of \fVf\fR at first iteration.
37
 
(\fVdf0=1\fR is the default value).
38
 
.TP
39
 
mem :
40
 
 integer, number of variables used to approximate the 
41
 
Hessian, (\fValgo='gc' or 'nd'\fR). Default value is around 6.
42
 
.TP
43
 
stop 
44
 
:  sequence of optional parameters controlling the 
45
 
convergence of the algorithm.
46
 
\fV
47
 
            stop=  'ar',nap, [iter [,epsg [,epsf [,epsx]]]]\fR
48
 
.RS
49
 
.TP
50
 
"ar"
51
 
: reserved keyword for stopping rule selection defined as follows:
52
 
.TP
53
 
nap 
54
 
: maximum number of calls to \fVcostf\fR allowed.
55
 
.TP
56
 
iter  
57
 
: maximum number of iterations allowed.
58
 
.TP
59
 
epsg  
60
 
: threshold on gradient norm.
61
 
.TP
62
 
epsf  
63
 
: threshold controlling decreasing of \fVf\fR
64
 
.TP
65
 
epsx 
66
 
: threshold controlling variation of \fVx\fR.
67
 
This vector (possibly matrix) of same size as \fVx0\fR can be used
68
 
to scale \fVx\fR.
69
 
.RE
70
 
.TP
71
 
"in" 
72
 
: reserved  keyword for initialization of parameters
73
 
used when \fVcostf\fR in given as a Fortran routine (see below).
74
 
.TP
75
 
"imp=iflag" 
76
 
: named argument used to set the trace mode. \fViflag=0\fR nothing
77
 
(execpt errors) is reported, \fViflag=1\fR initial and final reports,
78
 
\fViflag=2\fR adds a report per iteration, \fViflag>2\fR add reports on
79
 
linear search. Warning, most of these reports are written on the
80
 
Scilab standard output.
81
 
.TP
82
 
gradopt
83
 
:  gradient of \fVcostf\fR at \fVxopt\fR
84
 
.TP
85
 
work
86
 
: working array for hot restart for quasi-Newton method.
87
 
This array is automatically initialized by \fVoptim\fR when
88
 
\fVoptim\fR is invoked. It can be used as input parameter to 
89
 
speed-up the calculations.
90
 
.SH DESCRIPTION
91
 
Non-linear optimization routine for programs without constraints or with bound constraints: 
92
 
.nf
93
 
min costf(x) w.r.t x.
94
 
.fi
95
 
\fVcostf\fR is an "external" i.e function, or list or Fortran routine (see "external").
96
 
This external must return \fVf\fR (\fVcostf(x)\fR) and \fVg\fR (gradient of \fVcostf\fR)
97
 
given \fVx\fR.
98
 
.LP
99
 
If \fVcostf\fR is a function, the calling sequence for \fVcostf\fR must be:
100
 
.nf
101
 
[f,g,ind]=costf(x,ind).
102
 
.fi
103
 
Here, \fVcostf\fR is a function which returns \fVf\fR, value (real number) of
104
 
cost function at \fVx\fR, and \fVg\fR, gradient vector of cost function at \fVx\fR.
105
 
The variable \fVind\fR is used by \fVoptim\fR and is described below.
106
 
.LP
107
 
If \fVind=2\fR (resp. \fV3, 4\fR), \fVcostf\fR must provide \fVf\fR (resp. \fVg, f\fR and \fVg\fR).
108
 
.LP
109
 
If \fVind=1\fR nothing is computed (used for display purposes only).
110
 
.LP
111
 
On output, \fVind<0\fR  means that \fVf\fR cannot be evaluated at \fVx\fR and
112
 
\fVind=0\fR interrupts the optimization.
113
 
.LP
114
 
If \fVcostf\fR is a character string, it refers to the name of a Fortran routine
115
 
which must be linked to Scilab (see examples in the routines \fVfoptim.f\fR 
116
 
and e.g. \fVgenros.f\fR in the directory SCIDIR/default)
117
 
.LP
118
 
Dynamic link of Fortran routine is also possible (help \fVlink\fR).
119
 
.LP
120
 
Here, the generic calling sequence for the Fortran subroutine is: 
121
 
\fVfunction costf(ind,n,x,f,g,ti,tr,td)\fR
122
 
.LP
123
 
\fVind\fR has the same meaning as above if set to \fV0,1,2\fR but the 
124
 
values \fVind=10\fR and \fVind=11\fR are now valid. 
125
 
These values are used for initializations (see below).
126
 
.LP
127
 
\fVn\fR is the dimension of \fVx\fR, \fVx\fR is an \fVn\fR vector, 
128
 
\fVti,tr,td\fR are working arrays.
129
 
.LP
130
 
The Fortran function \fVcostf\fR must return \fVf\fR and the vector \fVg\fR,
131
 
given \fVx, ind, n, ti, tr, td\fR.
132
 
.LP
133
 
If \fVcostf\fR is given as a Fortran routine, it is possible to initialize
134
 
parameters or to send Scilab variables to this routine. 
135
 
.LP
136
 
This facility is managed by the parameter \fV'in\fR.
137
 
.LP
138
 
If the string \fV'in'\fR is present, initialization is done by Fortran:
139
 
\fVoptim\fR makes two calls to the Fortran function \fVcostf\fR, once with
140
 
\fVind=10\fR and once with \fVind=11\fR. In this case, for \fVind=10\fR,
141
 
\fVcostf\fR must set the dimensions \fVnti, ntr, ntd\fR of \fVti, tr, td\fR 
142
 
in the \fVcommon/nird/nti, ntr, ntd\fR and, for \fVind=11\fR, \fVcostf\fR
143
 
must initialize the vectors \fVti , tr, td\fR (integer vector, real vector,
144
 
double precision vector respectively).
145
 
.LP
146
 
In the calling sequence of \fVoptim\fR, the string \fV'in'\fR can be 
147
 
replaced by \fV'ti', valti ,'td' , valtd\fR. Then, the Fortran function
148
 
\fVcostf(ind, x, f, g, ti, tr, td)\fR is evaluated with \fVti=valti\fR
149
 
and \fVtd=valtd\fR whatever the value of \fVind\fR.
150
 
Thus, the Scilab variables \fVvalti\fR and \fVvaltd\fR (integer vector and
151
 
real vector) are sent to the Fortran function \fVcostf\fR.
152
 
.LP
153
 
It is also possible to save the content of of the working arrays
154
 
\fVti\fR and \fVtd\fR. This is possible by adding the strings 'si' and/or 'sd'
155
 
at the ned of the calling sequence of \fVoptim\fR.
156
 
Then, the output variables must be: \fV[f,[x,[g],[to]]],[ti],[td]]\fR.
157
 
.SH EXAMPLES
158
 
.nf
159
 
xref=[1;2;3];x0=[1;-1;1]
160
 
deff('[f,g,ind]=cost(x,ind)','f=0.5*norm(x-xref)^2,g=x-xref');
161
 
[f,xopt]=optim(cost,x0)      //Simplest call
162
 
[f,xopt,gopt]=optim(cost,x0,'gc')  // By conjugate gradient
163
 
[f,xopt,gopt]=optim(cost,x0,'nd')  //Seen as non differentiable
164
 
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0) //  Bounds on x
165
 
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc') //  Bounds on x
166
 
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc','ar',3)
167
 
// Here, 3 calls to cost are allowed.
168
 
// Now calling the Fortran subroutine "genros" in SCIDIR/default/Ex-optim.f
169
 
// See also the link function for dynamically linking an objective function
170
 
[f,xopt,gopt]=optim('genros',[1;2;3])    //Rosenbrock's function
171
 
.fi
172
 
.SH SEE ALSO
173
 
external, quapro, linpro, datafit, leastsq