* Bug #9577 fixed - Optimization: setting neldermead_configure(-numberofvariables...
[scilab.git] / scilab / modules / optimization / help / en_US / neldermead / neldermead.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - 2009 - INRIA - Michael Baudin
5  * Copyright (C) 2009 - 2011 - DIGITEO - Michael Baudin
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="neldermead" xml:lang="fr">
15     <refnamediv>
16         <refname>neldermead</refname>
17         <refpurpose>
18             Provides direct search optimization algorithms.
19         </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>SYNOPSIS</title>
23         <synopsis>
24             newobj = neldermead_new ()
25             this = neldermead_destroy (this)
26             this = neldermead_configure (this,key,value)
27             value = neldermead_cget (this,key)
28             value = neldermead_get ( this , key )
29             this = neldermead_search ( this )
30             this = neldermead_restart ( this )
31             [ this , result ] = neldermead_function ( this , x )
32             stop = neldermead_defaultoutput(state, data)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Description</title>
37         <para>
38             This class provides several direct search optimization algorithms
39             based on the simplex method.
40         </para>
41         <para>
42             The optimization problem to solve is the minimization of a cost
43             function, with bounds and nonlinear constraints
44         </para>
45         <screen>
46             min f(x)
47             l_i &lt;= x_i &lt;= h_i, i = 1,n
48             g_i(x) &gt;= 0, i = 1,nbineq
49         </screen>
50         <para>where</para>
51         <variablelist>
52             <varlistentry>
53                 <term>n</term>
54                 <listitem>
55                     <para>number of variables</para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>nbineq</term>
60                 <listitem>
61                     <para>number of inequality constraints</para>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65         <para>
66             The provided algorithms are direct search algorithms, i.e.
67             algorithms which do not use the derivative of the cost function. They are
68             based on the update of a simplex, which is a set of k&gt;=n+1 vertices,
69             where each vertex is associated with one point and one function
70             value.
71         </para>
72         <para>The following algorithms are available :</para>
73         <variablelist>
74             <varlistentry>
75                 <term>Spendley, Hext and Himsworth fixed shape simplex method</term>
76                 <listitem>
77                     <para>
78                         This algorithm solves an unconstrained optimization problem
79                         with a fixed shape simplex made of k=n+1 vertices.
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>Nelder and Mead variable shape simplex method</term>
85                 <listitem>
86                     <para>
87                         This algorithm solves an unconstrained optimization problem
88                         with a variable shape simplex made of k=n+1 vertices.
89                     </para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>Box complex method</term>
94                 <listitem>
95                     <para>
96                         This algorithm solves an constrained optimization problem with
97                         a variable shape simplex made of an arbitrary k number of vertices
98                         (k=2n is recommended by Box).
99                     </para>
100                 </listitem>
101             </varlistentry>
102         </variablelist>
103         <para>
104             See the demonstrations, in the Optimization section, for an overview
105             of this component.
106         </para>
107         <para>
108             See the "Nelder-Mead User's Manual" on Scilab's wiki and on the
109             Scilab forge for further information.
110         </para>
111     </refsection>
112     <refsection>
113         <title>Design</title>
114         <para>
115             The neldermead component is built on top of the <link linkend="optimbase_overview">optimbase</link> and <link linkend="optimsimplex_overview">optimsimplex</link> components.
116         </para>
117     </refsection>
118     <refsection>
119         <title>Functions</title>
120         <para>The following functions are available.</para>
121         <variablelist>
122             <varlistentry>
123                 <term xml:id="neldermead_new">newobj = neldermead_new ()</term>
124                 <listitem>
125                     <para>Creates a new neldermead object.</para>
126                     <variablelist>
127                         <varlistentry>
128                             <term>newobj</term>
129                             <listitem>
130                                 <para>The new object.</para>
131                             </listitem>
132                         </varlistentry>
133                     </variablelist>
134                 </listitem>
135             </varlistentry>
136             <varlistentry>
137                 <term xml:id="neldermead_destroy">this = neldermead_destroy (this)</term>
138                 <listitem>
139                     <para>Destroy the given object.</para>
140                     <variablelist>
141                         <varlistentry>
142                             <term>this</term>
143                             <listitem>
144                                 <para>The current object.</para>
145                             </listitem>
146                         </varlistentry>
147                     </variablelist>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term xml:id="neldermead_configure">this = neldermead_configure (this,key,value)</term>
152                 <listitem>
153                     <para>
154                         Configure the current object with the given value for the
155                         given key.
156                     </para>
157                     <variablelist>
158                         <varlistentry>
159                             <term>this</term>
160                             <listitem>
161                                 <para>The current object.</para>
162                             </listitem>
163                         </varlistentry>
164                         <varlistentry>
165                             <term>key</term>
166                             <listitem>
167                                 <para>
168                                     the key to configure. The following keys are
169                                     available.
170                                 </para>
171                                 <para>
172                                     <emphasis>Basic.</emphasis>
173                                 </para>
174                                 <variablelist>
175                                     <varlistentry>
176                                         <term>-numberofvariables</term>
177                                         <listitem>
178                                             <para>
179                                                 a 1-by-1 matrix of doubles, positive, integer value,
180                                                 the number of variables to optimize (default numberofvariables = 0).
181                                             </para>
182                                             <para>
183                                                 This does not need to be set if <literal>-x0</literal> key has been set before,
184                                                 because the <literal>-x0</literal> key sets <literal>-numberofvariables</literal>
185                                                 to the size of the column vector <literal>x0</literal>.
186                                             </para>
187                                         </listitem>
188                                     </varlistentry>
189                                     <varlistentry>
190                                         <term>-function</term>
191                                         <listitem>
192                                             <para>
193                                                 a function or a list, the objective function.
194                                                 This function computes the value
195                                                 of the cost and the non linear constraints, if
196                                                 any.
197                                             </para>
198                                             <para>
199                                                 There is no default value, i.e. the user must
200                                                 provide <literal>f</literal>.
201                                             </para>
202                                             <para>
203                                                 See below for the details of the communication
204                                                 between the optimization system and the cost
205                                                 function.
206                                             </para>
207                                         </listitem>
208                                     </varlistentry>
209                                     <varlistentry>
210                                         <term>-x0</term>
211                                         <listitem>
212                                             <para>
213                                                 a n-by-1 matrix of doubles, where
214                                                 n is the number of variables, the initial guess.
215                                             </para>
216                                             <para>
217                                                 There is no default value, i.e. the user must
218                                                 provide <literal>x0</literal>.
219                                             </para>
220                                         </listitem>
221                                     </varlistentry>
222                                 </variablelist>
223                                 <para>
224                                     <emphasis>Output.</emphasis>
225                                 </para>
226                                 <variablelist>
227                                     <varlistentry>
228                                         <term>-outputcommand</term>
229                                         <listitem>
230                                             <para>
231                                                 a function or a list, a function which is called back for output.
232                                             </para>
233                                             <para>
234                                                 The default output function is empty, meaning that there is
235                                                 no output.
236                                             </para>
237                                             <para>
238                                                 See below for the details of the communication
239                                                 between the optimization system and the output command
240                                                 function.
241                                             </para>
242                                         </listitem>
243                                     </varlistentry>
244                                     <varlistentry>
245                                         <term>-storehistory</term>
246                                         <listitem>
247                                             <para>
248                                                 a 1-by-1 matrix of booleans, set to %t to enable the history storing (default
249                                                 storehistory = %f).
250                                             </para>
251                                         </listitem>
252                                     </varlistentry>
253                                     <varlistentry>
254                                         <term>-verbose</term>
255                                         <listitem>
256                                             <para>
257                                                 a 1-by-1 matrix of doubles, positive, integer value, set to 1 to
258                                                 enable verbose logging (default verbose = 0).
259                                             </para>
260                                         </listitem>
261                                     </varlistentry>
262                                     <varlistentry>
263                                         <term>-verbosetermination</term>
264                                         <listitem>
265                                             <para>
266                                                 a 1-by-1 matrix of doubles, positive, integer value,
267                                                 set to 1 to enable verbose termination logging (default verbosetermination = 0).
268                                             </para>
269                                         </listitem>
270                                     </varlistentry>
271                                 </variablelist>
272                                 <para>
273                                     <emphasis>Bounds and constraints.</emphasis>
274                                 </para>
275                                 <variablelist>
276                                     <varlistentry>
277                                         <term>-boundsmin</term>
278                                         <listitem>
279                                             <para>
280                                                 a n-by-1 matrix of doubles, the minimum bounds for the parameters
281                                                 where n is the number of variables (default boundsmin = [], i.e. there are no
282                                                 minimum bounds).
283                                             </para>
284                                         </listitem>
285                                     </varlistentry>
286                                     <varlistentry>
287                                         <term>-boundsmax</term>
288                                         <listitem>
289                                             <para>
290                                                 a n-by-1 matrix of doubles, the maximum bounds for the parameters
291                                                 where n is the number of variables (default boundsmax = [], i.e. there are no
292                                                 maximum bounds).
293                                             </para>
294                                         </listitem>
295                                     </varlistentry>
296                                     <varlistentry>
297                                         <term>-nbineqconst</term>
298                                         <listitem>
299                                             <para>
300                                                 a 1-by-1 matrix of doubles, positive, integer value,
301                                                 the number of inequality constraints (default nbineqconst = 0).
302                                             </para>
303                                         </listitem>
304                                     </varlistentry>
305                                 </variablelist>
306                                 <para>
307                                     <emphasis>Initialization.</emphasis>
308                                 </para>
309                                 <variablelist>
310                                     <varlistentry>
311                                         <term>-simplex0method</term>
312                                         <listitem>
313                                             <para>
314                                                 a 1-by-1 matrix of strings, the method to use to compute the initial
315                                                 simplex (default simplex0method = "axes").
316                                                 The first vertex in the simplex is always the initial
317                                                 guess associated with the -x0 option. The following
318                                                 methods are available :
319                                             </para>
320                                             <variablelist>
321                                                 <varlistentry>
322                                                     <term>"given"</term>
323                                                     <listitem>
324                                                         <para>
325                                                             the coordinates associated with the -coords0
326                                                             option are used to compute the initial simplex, with
327                                                             arbitrary number of vertices.
328                                                         </para>
329                                                         <para>
330                                                             This allow the user to setup the initial
331                                                             simplex by a specific method which is not provided
332                                                             by the current component (for example with a simplex
333                                                             computed from a design of experiments). This allows
334                                                             also to configure the initial simplex so that a
335                                                             specific behaviour of the algorithm an be reproduced
336                                                             (for example the Mac Kinnon test case).
337                                                         </para>
338                                                         <para>
339                                                             The given matrix is expected to have n rows
340                                                             and k columns, where n is the dimension of the
341                                                             problem and k is the number of vertices.
342                                                         </para>
343                                                     </listitem>
344                                                 </varlistentry>
345                                                 <varlistentry>
346                                                     <term>"axes"</term>
347                                                     <listitem>
348                                                         <para>
349                                                             the simplex is computed from the coordinate
350                                                             axes and the length associated with the
351                                                             -simplex0length option.
352                                                         </para>
353                                                     </listitem>
354                                                 </varlistentry>
355                                                 <varlistentry>
356                                                     <term>"spendley"</term>
357                                                     <listitem>
358                                                         <para>
359                                                             the simplex is computed so that it is regular
360                                                             with the length associated with the -simplex0length
361                                                             option (i.e. all the edges have the same
362                                                             length).
363                                                         </para>
364                                                     </listitem>
365                                                 </varlistentry>
366                                                 <varlistentry>
367                                                     <term>"pfeffer"</term>
368                                                     <listitem>
369                                                         <para>
370                                                             the simplex is computed from a heuristic, in
371                                                             the neighborhood of the initial guess. This initial
372                                                             simplex depends on the -simplex0deltausual and
373                                                             -simplex0deltazero.
374                                                         </para>
375                                                     </listitem>
376                                                 </varlistentry>
377                                                 <varlistentry>
378                                                     <term>"randbounds"</term>
379                                                     <listitem>
380                                                         <para>
381                                                             the simplex is computed from the bounds and a
382                                                             random number. This option is available only if
383                                                             bounds are available : if bounds are not available,
384                                                             an error is generated. This method is usually
385                                                             associated with Box's algorithm. The number of
386                                                             vertices in the simplex is taken from the
387                                                             -boxnbpoints option.
388                                                         </para>
389                                                     </listitem>
390                                                 </varlistentry>
391                                             </variablelist>
392                                         </listitem>
393                                     </varlistentry>
394                                     <varlistentry>
395                                         <term>-coords0</term>
396                                         <listitem>
397                                             <para>
398                                                 a nbve-by-n matrix of doubles, where nbve is the number of vertices and n is
399                                                 the number of variables, the coordinates of the vertices of the initial
400                                                 simplex (default coords0=[]).
401                                                 If the -simplex0method option is set to
402                                                 "given", these coordinates are used to compute the
403                                                 initial simplex.
404                                             </para>
405                                         </listitem>
406                                     </varlistentry>
407                                     <varlistentry>
408                                         <term>-simplex0length</term>
409                                         <listitem>
410                                             <para>
411                                                 a 1-by-1 matrix of doubles, the length to use when the initial simplex is
412                                                 computed with the "axes" or "spendley" methods (default simplex0length = 1).
413                                                 If the initial simplex is computed from "spendley" method, the
414                                                 length is expected to be a scalar value. If the initial
415                                                 simplex is computed from "axes" method, it may be either
416                                                 a scalar value or a vector of values, with rank n, where
417                                                 n is the number of variables.
418                                             </para>
419                                         </listitem>
420                                     </varlistentry>
421                                     <varlistentry>
422                                         <term>-simplex0deltausual</term>
423                                         <listitem>
424                                             <para>
425                                                 a 1-by-1 matrix of doubles, the relative delta for non-zero parameters in
426                                                 "pfeffer" method (default simplex0deltausual = 0.05).
427                                             </para>
428                                         </listitem>
429                                     </varlistentry>
430                                     <varlistentry>
431                                         <term>-simplex0deltazero</term>
432                                         <listitem>
433                                             <para>
434                                                 a 1-by-1 matrix of doubles, the absolute delta for non-zero parameters in
435                                                 "pfeffer" method (default simplex0deltazero = 0.0075).
436                                             </para>
437                                         </listitem>
438                                     </varlistentry>
439                                 </variablelist>
440                                 <para>
441                                     <emphasis>Termination.</emphasis>
442                                 </para>
443                                 <variablelist>
444                                     <varlistentry>
445                                         <term>-maxfunevals</term>
446                                         <listitem>
447                                             <para>
448                                                 a 1-by-1 matrix of doubles, positive, integer value,
449                                                 the maximum number of function evaluations
450                                                 (default maxfunevals = 100).
451                                                 If this criteria is triggered, the status of the optimization is set to
452                                                 "maxfuneval".
453                                             </para>
454                                         </listitem>
455                                     </varlistentry>
456                                     <varlistentry>
457                                         <term>-maxiter</term>
458                                         <listitem>
459                                             <para>
460                                                 a 1-by-1 matrix of doubles, positive, integer value,
461                                                 the maximum number of iterations (default maxiter = 100).
462                                                 If this criteria is triggered, the status of the
463                                                 optimization is set to "maxiter".
464                                             </para>
465                                         </listitem>
466                                     </varlistentry>
467                                     <varlistentry>
468                                         <term>-tolfunabsolute</term>
469                                         <listitem>
470                                             <para>
471                                                 a 1-by-1 matrix of doubles, positive, the absolute tolerance for the function value
472                                                 (default tolfunabsolute = 0).
473                                             </para>
474                                         </listitem>
475                                     </varlistentry>
476                                     <varlistentry>
477                                         <term>-tolfunrelative</term>
478                                         <listitem>
479                                             <para>
480                                                 a 1-by-1 matrix of doubles, positive, the relative tolerance for the function value
481                                                 (default tolfunrelative = %eps).
482                                             </para>
483                                         </listitem>
484                                     </varlistentry>
485                                     <varlistentry>
486                                         <term>-tolfunmethod</term>
487                                         <listitem>
488                                             <para>
489                                                 a 1-by-1 matrix of booleans, set to %t to enable termination with
490                                                 tolerance on function value (default tolfunmethod = %f).
491                                             </para>
492                                             <para>
493                                                 If this criteria is triggered, the
494                                                 status of the optimization is set to "tolf".
495                                             </para>
496                                         </listitem>
497                                     </varlistentry>
498                                     <varlistentry>
499                                         <term>-tolxabsolute</term>
500                                         <listitem>
501                                             <para>
502                                                 a 1-by-1 matrix of doubles, positive, the absolute tolerance
503                                                 on x (default tolxabsolute = 0).
504                                             </para>
505                                         </listitem>
506                                     </varlistentry>
507                                     <varlistentry>
508                                         <term>-tolxrelative</term>
509                                         <listitem>
510                                             <para>
511                                                 a 1-by-1 matrix of doubles, positive, the relative
512                                                 tolerance on x (default tolxrelative = sqrt(%eps)).
513                                             </para>
514                                         </listitem>
515                                     </varlistentry>
516                                     <varlistentry>
517                                         <term>-tolxmethod</term>
518                                         <listitem>
519                                             <para>
520                                                 a 1-by-1 matrix of booleans, set to %t to enable the tolerance on x in the
521                                                 termination criteria (default tolxmethod = %t).
522                                             </para>
523                                             <para>
524                                                 If this criteria is triggered, the
525                                                 status of the optimization is set to "tolx".
526                                             </para>
527                                         </listitem>
528                                     </varlistentry>
529                                     <varlistentry>
530                                         <term>-tolsimplexizemethod</term>
531                                         <listitem>
532                                             <para>
533                                                 a 1-by-1 matrix of booleans, set to %f to disable the tolerance on the simplex
534                                                 size (default tolsimplexizemethod = %t). If this criteria is
535                                                 triggered, the status of the optimization is set to
536                                                 "tolsize".
537                                             </para>
538                                             <para>
539                                                 When this criteria is enabled, the values of the
540                                                 options -tolsimplexizeabsolute and
541                                                 -tolsimplexizerelative are used in the termination
542                                                 criteria. The method to compute the size is the
543                                                 "sigmaplus" method.
544                                             </para>
545                                         </listitem>
546                                     </varlistentry>
547                                     <varlistentry>
548                                         <term>-tolsimplexizeabsolute</term>
549                                         <listitem>
550                                             <para>
551                                                 a 1-by-1 matrix of doubles, positive, the absolute tolerance on the
552                                                 simplex size (default tolsimplexizeabsolute = 0).
553                                             </para>
554                                         </listitem>
555                                     </varlistentry>
556                                     <varlistentry>
557                                         <term>-tolsimplexizerelative</term>
558                                         <listitem>
559                                             <para>
560                                                 a 1-by-1 matrix of doubles, positive, the relative tolerance on the
561                                                 simplex size (default tolsimplexizerelative = %eps).
562                                             </para>
563                                         </listitem>
564                                     </varlistentry>
565                                     <varlistentry>
566                                         <term>-tolssizedeltafvmethod</term>
567                                         <listitem>
568                                             <para>
569                                                 a 1-by-1 matrix of booleans, set to %t to enable the termination criteria based
570                                                 on the size of the simplex and the difference of
571                                                 function value in the simplex (default tolssizedeltafvmethod = %f).
572                                                 If this criteria is triggered, the status of the
573                                                 optimization is set to "tolsizedeltafv".
574                                             </para>
575                                             <para>
576                                                 This termination criteria uses the values of the
577                                                 options -tolsimplexizeabsolute and -toldeltafv. This
578                                                 criteria is identical to Matlab's fminsearch.
579                                             </para>
580                                         </listitem>
581                                     </varlistentry>
582                                     <varlistentry>
583                                         <term>-toldeltafv</term>
584                                         <listitem>
585                                             <para>
586                                                 a 1-by-1 matrix of doubles, positive, the absolute tolerance on the difference between
587                                                 the highest and the lowest function values (default toldeltafv = %eps).
588                                             </para>
589                                         </listitem>
590                                     </varlistentry>
591                                 </variablelist>
592                                 <para>
593                                     <emphasis>Algorithm.</emphasis>
594                                 </para>
595                                 <variablelist>
596                                     <varlistentry>
597                                         <term>-method</term>
598                                         <listitem>
599                                             <para>
600                                                 a 1-by-1 matrix of strings, the name of the algorithm to use (default method = "variable").
601                                                 The following methods are available :
602                                             </para>
603                                             <variablelist>
604                                                 <varlistentry>
605                                                     <term>"fixed"</term>
606                                                     <listitem>
607                                                         <para>
608                                                             the Spendley et al. fixed simplex shape
609                                                             algorithm. This algorithm is for unconstrained
610                                                             problems (i.e. bounds and non linear constraints are
611                                                             not taken into account)
612                                                         </para>
613                                                     </listitem>
614                                                 </varlistentry>
615                                                 <varlistentry>
616                                                     <term>"variable"</term>
617                                                     <listitem>
618                                                         <para>
619                                                             the Nelder-Mead variable simplex shape
620                                                             algorithm. This algorithm is for unconstrained
621                                                             problems (i.e. bounds and non linear constraints are
622                                                             not taken into account)
623                                                         </para>
624                                                     </listitem>
625                                                 </varlistentry>
626                                                 <varlistentry>
627                                                     <term>"box"</term>
628                                                     <listitem>
629                                                         <para>
630                                                             the Box complex algorithm. This algorithm
631                                                             takes into account bounds and nonlinear inequality
632                                                             constraints.
633                                                         </para>
634                                                     </listitem>
635                                                 </varlistentry>
636                                                 <varlistentry>
637                                                     <term>"mine"</term>
638                                                     <listitem>
639                                                         <para>
640                                                             the user-defined algorithm, associated with the
641                                                             <literal>-mymethod</literal>option. See below for details.
642                                                         </para>
643                                                     </listitem>
644                                                 </varlistentry>
645                                             </variablelist>
646                                         </listitem>
647                                     </varlistentry>
648                                     <varlistentry>
649                                         <term>-mymethod</term>
650                                         <listitem>
651                                             <para>
652                                                 a function, a user-derined simplex algorithm. See below for
653                                                 details (default is empty).
654                                             </para>
655                                         </listitem>
656                                     </varlistentry>
657                                 </variablelist>
658                                 <para>
659                                     <emphasis>Options of the "variable" algorithm.</emphasis>
660                                 </para>
661                                 <variablelist>
662                                     <varlistentry>
663                                         <term>-rho</term>
664                                         <listitem>
665                                             <para>
666                                                 a 1-by-1 matrix of doubles, the reflection coefficient. This parameter is used
667                                                 when the -method option is set to "fixed" or "variable" (default rho = 1).
668                                             </para>
669                                         </listitem>
670                                     </varlistentry>
671                                     <varlistentry>
672                                         <term>-chi</term>
673                                         <listitem>
674                                             <para>
675                                                 a 1-by-1 matrix of doubles, the expansion coefficient. This parameter is used
676                                                 when the -method option is set to "variable" (default chi = 2).
677                                             </para>
678                                         </listitem>
679                                     </varlistentry>
680                                     <varlistentry>
681                                         <term>-gamma</term>
682                                         <listitem>
683                                             <para>
684                                                 a 1-by-1 matrix of doubles, the contraction coefficient. This parameter is
685                                                 used when the -method option is set to "variable" (default gamma = 0.5).
686                                             </para>
687                                         </listitem>
688                                     </varlistentry>
689                                     <varlistentry>
690                                         <term>-sigma</term>
691                                         <listitem>
692                                             <para>
693                                                 a 1-by-1 matrix of doubles, the shrinkage coefficient. This parameter is used
694                                                 when the -method option is set to "fixed" or "variable" (default sigma = 0.5).
695                                             </para>
696                                         </listitem>
697                                     </varlistentry>
698                                 </variablelist>
699                                 <para>
700                                     <emphasis>Option of "box" algorithm.</emphasis>
701                                 </para>
702                                 <variablelist>
703                                     <varlistentry>
704                                         <term>-scalingsimplex0</term>
705                                         <listitem>
706                                             <para>
707                                                 a 1-by-1 matrix of strings, the algorithm used to scale the initial simplex into
708                                                 the nonlinear constraints (default scalingsimplex0 = "tox0").
709                                                 The following two algorithms are provided :
710                                             </para>
711                                             <itemizedlist>
712                                                 <listitem>
713                                                     <para>
714                                                         "tox0": scales the vertices toward the initial guess.
715                                                     </para>
716                                                 </listitem>
717                                                 <listitem>
718                                                     <para>
719                                                         "tocenter": scales the vertices toward the centroid, as recommended by Box.
720                                                     </para>
721                                                 </listitem>
722                                             </itemizedlist>
723                                             <para>
724                                                 If the centroid happens to be unfeasible, because the constraints are
725                                                 not convex, the scaling of the initial simplex toward the centroid
726                                                 may fail. Since the initial guess is always feasible, scaling toward
727                                                 the initial guess cannot fail.
728                                                 The default value is "tox0".
729                                             </para>
730                                         </listitem>
731                                     </varlistentry>
732                                     <varlistentry>
733                                         <term>-boxnbpoints</term>
734                                         <listitem>
735                                             <para>
736                                                 a 1-by-1 matrix of doubles, positive, integer value, the number
737                                                 of points in the initial simplex, when
738                                                 the -simplex0method is set to <literal>"randbounds"</literal>
739                                                 (default boxnbpoints = 2*n, where n is the number of variables of the problem).
740                                                 The value of this option is also use to update the simplex when a
741                                                 restart is performed and the <literal>-restartsimplexmethod</literal>
742                                                 option is set to <literal>"randbounds"</literal>.
743                                             </para>
744                                         </listitem>
745                                     </varlistentry>
746                                     <varlistentry>
747                                         <term>-boxineqscaling</term>
748                                         <listitem>
749                                             <para>
750                                                 a 1-by-1 matrix of doubles, in the interval [0,1], the scaling coefficient used to scale the trial
751                                                 point for function improvement or into the constraints of Box's
752                                                 algorithm (default boxineqscaling = 0.5).
753                                             </para>
754                                         </listitem>
755                                     </varlistentry>
756                                     <varlistentry>
757                                         <term>-guinalphamin</term>
758                                         <listitem>
759                                             <para>
760                                                 a 1-by-1 matrix of doubles, positive, the minimum value of alpha when scaling the vertices of the
761                                                 simplex into nonlinear constraints in Box's algorithm (default guinalphamin = 1.e-5).
762                                             </para>
763                                         </listitem>
764                                     </varlistentry>
765                                     <varlistentry>
766                                         <term>-boxreflect</term>
767                                         <listitem>
768                                             <para>
769                                                 a 1-by-1 matrix of doubles, positive, the reflection factor in
770                                                 Box's algorithm (default = 1.3).
771                                             </para>
772                                         </listitem>
773                                     </varlistentry>
774                                     <varlistentry>
775                                         <term>-boxtermination</term>
776                                         <listitem>
777                                             <para>
778                                                 a 1-by-1 matrix of booleans, set to %t to enable Box termination criteria (default boxtermination = %f).
779                                             </para>
780                                         </listitem>
781                                     </varlistentry>
782                                     <varlistentry>
783                                         <term>-boxtolf</term>
784                                         <listitem>
785                                             <para>
786                                                 a 1-by-1 matrix of doubles, positive, the absolute tolerance on difference of function values in the
787                                                 simplex, suggested by Box (default boxtolf = 1.e-5). This tolerance is used if
788                                                 the -boxtermination option is set to %t.
789                                                 
790                                             </para>
791                                         </listitem>
792                                     </varlistentry>
793                                     <varlistentry>
794                                         <term>-boxnbmatch</term>
795                                         <listitem>
796                                             <para>
797                                                 a 1-by-1 matrix of doubles, positive, integer value,
798                                                 the number of consecutive match of Box termination criteria (default boxnbmatch = 5).
799                                             </para>
800                                         </listitem>
801                                     </varlistentry>
802                                     <varlistentry>
803                                         <term>-boxboundsalpha</term>
804                                         <listitem>
805                                             <para>
806                                                 a 1-by-1 matrix of doubles, positive, the parameter used to project the vertices into the
807                                                 bounds in Box's algorithm (default boxboundsalpha = 1.e-6).
808                                             </para>
809                                         </listitem>
810                                     </varlistentry>
811                                 </variablelist>
812                                 <para>
813                                     <emphasis>Auto-Restart.</emphasis>
814                                 </para>
815                                 <variablelist>
816                                     <varlistentry>
817                                         <term>-kelleystagnationflag</term>
818                                         <listitem>
819                                             <para>
820                                                 a 1-by-1 matrix of booleans, set to %t to enable the termination criteria using
821                                                 Kelley's stagnation detection, based on sufficient
822                                                 decrease condition (default kelleystagnationflag = %f). If this
823                                                 criteria is triggered, the status of the optimization is
824                                                 set to "kelleystagnation".
825                                             </para>
826                                         </listitem>
827                                     </varlistentry>
828                                     <varlistentry>
829                                         <term>-kelleynormalizationflag</term>
830                                         <listitem>
831                                             <para>
832                                                 a 1-by-1 matrix of booleans, set to %f to disable the normalization of the
833                                                 alpha coefficient in Kelley's stagnation detection, i.e.
834                                                 use the value of the option -kelleystagnationalpha0 as
835                                                 is (default kelleynormalizationflag = %t, i.e. the simplex gradient of
836                                                 the initial simplex is taken into account in the
837                                                 stagnation detection).
838                                             </para>
839                                         </listitem>
840                                     </varlistentry>
841                                     <varlistentry>
842                                         <term>-kelleystagnationalpha0</term>
843                                         <listitem>
844                                             <para>
845                                                 a 1-by-1 matrix of doubles, the parameter used in Kelley's stagnation
846                                                 detection (default kelleystagnationalpha0 = 1.e-4).
847                                             </para>
848                                         </listitem>
849                                     </varlistentry>
850                                     <varlistentry>
851                                         <term>-restartflag</term>
852                                         <listitem>
853                                             <para>
854                                                 a 1-by-1 matrix of booleans, set to %t to enable the automatic restart of the
855                                                 algorithm (default restartflag = %f).
856                                             </para>
857                                         </listitem>
858                                     </varlistentry>
859                                     <varlistentry>
860                                         <term>-restartdetection</term>
861                                         <listitem>
862                                             <para>
863                                                 a 1-by-1 matrix of strings, the method to detect if the automatic restart must
864                                                 be performed (default restartdetection = "oneil").
865                                                 The following methods are available:
866                                             </para>
867                                             <variablelist>
868                                                 <varlistentry>
869                                                     <term>"oneill"</term>
870                                                     <listitem>
871                                                         <para>
872                                                             the factorial local optimality test by O'Neill
873                                                             is used. If the test finds a local point which is
874                                                             better than the computed optimum, a restart is
875                                                             performed.
876                                                         </para>
877                                                     </listitem>
878                                                 </varlistentry>
879                                                 <varlistentry>
880                                                     <term>"kelley"</term>
881                                                     <listitem>
882                                                         <para>
883                                                             the sufficient decrease condition by O'Neill
884                                                             is used. If the test finds that the status of the
885                                                             optimization is "kelleystagnation", a restart is
886                                                             performed. This status may be generated if the
887                                                             -kelleystagnationflag option is set to %t.
888                                                         </para>
889                                                     </listitem>
890                                                 </varlistentry>
891                                             </variablelist>
892                                             <para>The default method is "oneill".</para>
893                                         </listitem>
894                                     </varlistentry>
895                                     <varlistentry>
896                                         <term>-restartmax</term>
897                                         <listitem>
898                                             <para>
899                                                 a 1-by-1 matrix of doubles, the maximum number of restarts, when automatic
900                                                 restart is enabled via the -restartflag option (default
901                                                 restartmax=3).
902                                             </para>
903                                         </listitem>
904                                     </varlistentry>
905                                     <varlistentry>
906                                         <term>-restarteps</term>
907                                         <listitem>
908                                             <para>
909                                                 a 1-by-1 matrix of doubles, the relative epsilon value used to check for
910                                                 optimality in the factorial O'Neill restart detection (default restarteps = %eps).
911                                             </para>
912                                         </listitem>
913                                     </varlistentry>
914                                     <varlistentry>
915                                         <term>-restartstep</term>
916                                         <listitem>
917                                             <para>
918                                                 a 1-by-1 or a n-by-1 matrix of doubles, positive, where n is the number of
919                                                 variables in the problem, the absolute step length used to check for
920                                                 optimality in the factorial O'Neill restart detection (default restartstep = 1).
921                                             </para>
922                                         </listitem>
923                                     </varlistentry>
924                                     <varlistentry>
925                                         <term>-restartsimplexmethod</term>
926                                         <listitem>
927                                             <para>
928                                                 a 1-by-1 matrix of strings, the method to compute the initial simplex after a
929                                                 restart (default restartsimplexmethod = "oriented"). The following methods are available.
930                                             </para>
931                                             <variablelist>
932                                                 <varlistentry>
933                                                     <term>"given"</term>
934                                                     <listitem>
935                                                         <para>
936                                                             the coordinates associated with the -coords0
937                                                             option are used to compute the initial simplex, with
938                                                             arbitrary number of vertices.
939                                                         </para>
940                                                         <para>
941                                                             This allow the user to setup the initial
942                                                             simplex by a specific method which is not provided
943                                                             by the current component (for example with a simplex
944                                                             computed from a design of experiments). This allows
945                                                             also to configure the initial simplex so that a
946                                                             specific behaviour of the algorithm an be reproduced
947                                                             (for example the Mc Kinnon test case).
948                                                         </para>
949                                                         <para>
950                                                             The given matrix is expected to have n rows
951                                                             and k columns, where n is the dimension of the
952                                                             problem and k is the number of vertices.
953                                                         </para>
954                                                     </listitem>
955                                                 </varlistentry>
956                                                 <varlistentry>
957                                                     <term>"axes"</term>
958                                                     <listitem>
959                                                         <para>
960                                                             the simplex is computed from the coordinate
961                                                             axes and the length associated with the
962                                                             -simplex0length option.
963                                                         </para>
964                                                     </listitem>
965                                                 </varlistentry>
966                                                 <varlistentry>
967                                                     <term>"spendley"</term>
968                                                     <listitem>
969                                                         <para>
970                                                             the simplex is computed so that it is regular
971                                                             with the length associated with the -simplex0length
972                                                             option (i.e. all the edges have the same
973                                                             length).
974                                                         </para>
975                                                     </listitem>
976                                                 </varlistentry>
977                                                 <varlistentry>
978                                                     <term>"pfeffer"</term>
979                                                     <listitem>
980                                                         <para>
981                                                             the simplex is computed from a heuristic, in
982                                                             the neighborhood of the initial guess. This initial
983                                                             simplex depends on the -simplex0deltausual and
984                                                             -simplex0deltazero.
985                                                         </para>
986                                                     </listitem>
987                                                 </varlistentry>
988                                                 <varlistentry>
989                                                     <term>"randbounds"</term>
990                                                     <listitem>
991                                                         <para>
992                                                             the simplex is computed from the bounds and a
993                                                             random number. This option is available only if
994                                                             bounds are available : if bounds are not available,
995                                                             an error is generated. This method is usually
996                                                             associated with Box's algorithm. The number of
997                                                             vertices in the simplex is taken from the
998                                                             -boxnbpoints option.
999                                                         </para>
1000                                                     </listitem>
1001                                                 </varlistentry>
1002                                                 <varlistentry>
1003                                                     <term>"oriented"</term>
1004                                                     <listitem>
1005                                                         <para>
1006                                                             the simplex is computed so that it is
1007                                                             oriented, as suggested by C.T. Kelley.
1008                                                         </para>
1009                                                     </listitem>
1010                                                 </varlistentry>
1011                                             </variablelist>
1012                                             <para>The default method is "oriented".</para>
1013                                         </listitem>
1014                                     </varlistentry>
1015                                 </variablelist>
1016                             </listitem>
1017                         </varlistentry>
1018                         <varlistentry>
1019                             <term>value</term>
1020                             <listitem>
1021                                 <para>the value.</para>
1022                             </listitem>
1023                         </varlistentry>
1024                     </variablelist>
1025                 </listitem>
1026             </varlistentry>
1027             <varlistentry>
1028                 <term xml:id="neldermead_cget">value = neldermead_cget (this,key)</term>
1029                 <listitem>
1030                     <para>
1031                         Get the value for the given key. If the key is unknown,
1032                         generates an error.
1033                     </para>
1034                     <variablelist>
1035                         <varlistentry>
1036                             <term>this</term>
1037                             <listitem>
1038                                 <para>The current object.</para>
1039                             </listitem>
1040                         </varlistentry>
1041                         <varlistentry>
1042                             <term>key</term>
1043                             <listitem>
1044                                 <para>
1045                                     the name of the key to quiery. The list of available
1046                                     keys is the same as for the neldermead_configure
1047                                     function.
1048                                 </para>
1049                             </listitem>
1050                         </varlistentry>
1051                     </variablelist>
1052                 </listitem>
1053             </varlistentry>
1054             <varlistentry>
1055                 <term xml:id="neldermead_get">value = neldermead_get ( this , key )</term>
1056                 <listitem>
1057                     <para>
1058                         Get the value for the given key. If the key is unknown,
1059                         generates an error.
1060                     </para>
1061                     <para>
1062                         Most fields are available only after an optimization has
1063                         been performed with one call to the neldermead_search
1064                         method.
1065                     </para>
1066                     <variablelist>
1067                         <varlistentry>
1068                             <term>this</term>
1069                             <listitem>
1070                                 <para>The current object.</para>
1071                             </listitem>
1072                         </varlistentry>
1073                         <varlistentry>
1074                             <term>key</term>
1075                             <listitem>
1076                                 <para>the key to get.</para>
1077                                 <para>The following keys are available :</para>
1078                                 <variablelist>
1079                                     <varlistentry>
1080                                         <term>-funevals</term>
1081                                         <listitem>
1082                                             <para>the number of function evaluations</para>
1083                                         </listitem>
1084                                     </varlistentry>
1085                                     <varlistentry>
1086                                         <term>-iterations</term>
1087                                         <listitem>
1088                                             <para>the number of iterations</para>
1089                                         </listitem>
1090                                     </varlistentry>
1091                                     <varlistentry>
1092                                         <term>-xopt</term>
1093                                         <listitem>
1094                                             <para>
1095                                                 the x optimum, as a n x 1 column vector, where n
1096                                                 is the number of variables.
1097                                             </para>
1098                                         </listitem>
1099                                     </varlistentry>
1100                                     <varlistentry>
1101                                         <term>-fopt</term>
1102                                         <listitem>
1103                                             <para>the optimum cost function value</para>
1104                                         </listitem>
1105                                     </varlistentry>
1106                                     <varlistentry>
1107                                         <term>-historyxopt</term>
1108                                         <listitem>
1109                                             <para>
1110                                                 an array, with nbiter values, containing the
1111                                                 history of x during the iterations.
1112                                             </para>
1113                                             <para>
1114                                                 This array is available after optimization if the
1115                                                 history storing was enabled with the -storehistory
1116                                                 option.
1117                                             </para>
1118                                         </listitem>
1119                                     </varlistentry>
1120                                     <varlistentry>
1121                                         <term>-historyfopt</term>
1122                                         <listitem>
1123                                             <para>
1124                                                 an array, with nbiter values, containing the
1125                                                 history of the function value during the
1126                                                 iterations.
1127                                             </para>
1128                                             <para>
1129                                                 This array is available after optimization if the
1130                                                 history storing was enabled with the -storehistory
1131                                                 option.
1132                                             </para>
1133                                         </listitem>
1134                                     </varlistentry>
1135                                     <varlistentry>
1136                                         <term>-fx0</term>
1137                                         <listitem>
1138                                             <para>the function value for the initial guess</para>
1139                                         </listitem>
1140                                     </varlistentry>
1141                                     <varlistentry>
1142                                         <term>-status</term>
1143                                         <listitem>
1144                                             <para>
1145                                                 a string containing the status of the
1146                                                 optimization. See below for details about the
1147                                                 optimization status.
1148                                             </para>
1149                                         </listitem>
1150                                     </varlistentry>
1151                                     <varlistentry>
1152                                         <term>-historysimplex</term>
1153                                         <listitem>
1154                                             <para>
1155                                                 a matrix containing the history of the simplex
1156                                                 during the iterations. This matrix has rank nbiter x
1157                                                 nbve x n, where nbiter is the number of iterations, nbve
1158                                                 is the number of vertices in the simplex and n is the
1159                                                 number of variables.
1160                                             </para>
1161                                         </listitem>
1162                                     </varlistentry>
1163                                     <varlistentry>
1164                                         <term>-simplex0</term>
1165                                         <listitem>
1166                                             <para>
1167                                                 the initial simplex. This is a simplex object,
1168                                                 which is suitable for processing with the optimsimplex
1169                                                 component.
1170                                             </para>
1171                                         </listitem>
1172                                     </varlistentry>
1173                                     <varlistentry>
1174                                         <term>-simplexopt</term>
1175                                         <listitem>
1176                                             <para>
1177                                                 the optimum simplex. This is a simplex object,
1178                                                 which is suitable for processing with the optimsimplex
1179                                                 component.
1180                                             </para>
1181                                         </listitem>
1182                                     </varlistentry>
1183                                     <varlistentry>
1184                                         <term>-restartnb</term>
1185                                         <listitem>
1186                                             <para>the number of actual restarts performed.</para>
1187                                         </listitem>
1188                                     </varlistentry>
1189                                 </variablelist>
1190                             </listitem>
1191                         </varlistentry>
1192                     </variablelist>
1193                 </listitem>
1194             </varlistentry>
1195             <varlistentry>
1196                 <term xml:id="neldermead_search">this = neldermead_search ( this )</term>
1197                 <listitem>
1198                     <para>
1199                         Performs the optimization associated with the method
1200                         associated with the -method option and find the optimum.
1201                     </para>
1202                     <variablelist>
1203                         <varlistentry>
1204                             <term>this</term>
1205                             <listitem>
1206                                 <para>The current object.</para>
1207                             </listitem>
1208                         </varlistentry>
1209                     </variablelist>
1210                     <para>
1211                         If the -restartflag option is enabled, automatic restarts are
1212                         performed, based on the -restartdetection option.
1213                     </para>
1214                 </listitem>
1215             </varlistentry>
1216             <varlistentry>
1217                 <term xml:id="neldermead_restart">this = neldermead_restart ( this )</term>
1218                 <listitem>
1219                     <para>
1220                         Restarts the optimization by updating the simplex and
1221                         performing a new search.
1222                     </para>
1223                     <variablelist>
1224                         <varlistentry>
1225                             <term>this</term>
1226                             <listitem>
1227                                 <para>The current object.</para>
1228                             </listitem>
1229                         </varlistentry>
1230                     </variablelist>
1231                 </listitem>
1232             </varlistentry>
1233             <varlistentry>
1234                 <term xml:id="neldermead_function">[ this , result ] = neldermead_function ( this , x )</term>
1235                 <listitem>
1236                     <para>Call the cost function and return the value.</para>
1237                     <variablelist>
1238                         <varlistentry>
1239                             <term>this</term>
1240                             <listitem>
1241                                 <para>The current object.</para>
1242                             </listitem>
1243                         </varlistentry>
1244                         <varlistentry>
1245                             <term>x</term>
1246                             <listitem>
1247                                 <para>the point where the function is to be evaluated</para>
1248                             </listitem>
1249                         </varlistentry>
1250                         <varlistentry>
1251                             <term>index</term>
1252                             <listitem>
1253                                 <para>
1254                                     optional, a flag to pass to the cost function (default
1255                                     = 1). See the section "The cost function" for available values
1256                                     of index.
1257                                 </para>
1258                             </listitem>
1259                         </varlistentry>
1260                     </variablelist>
1261                 </listitem>
1262             </varlistentry>
1263             <varlistentry>
1264                 <term xml:id="neldermead_defaultoutput">stop = neldermead_defaultoutput(state, data)</term>
1265                 <listitem>
1266                     <para>
1267                         Prints messages at an iteration. 
1268                     </para>
1269                     <para>
1270                         This function provides a default implementation for the output function. 
1271                         There is one line by iteration, presenting the number of iterations, the 
1272                         number of function evaluations, the current function value and the 
1273                         current algorithm step.
1274                     </para>
1275                     <para>
1276                         See "The output function" section below for a description of the input and 
1277                         output arguments. 
1278                         See in the Examples section below for examples of this function.
1279                     </para>
1280                 </listitem>
1281             </varlistentry>
1282         </variablelist>
1283     </refsection>
1284     <refsection>
1285         <title>The cost function</title>
1286         <para>
1287             The option <literal>-function</literal> allows to configure the cost function. The cost
1288             function is used to compute the objective function value <literal>f</literal>.
1289             If the <literal>-nbineqconst</literal> option is configured to a non-zero value, the cost function
1290             must also compute the value of the nonlinear, positive, inequality constraints <literal>c</literal>.
1291             Depending of these options, the cost function can have one of the following headers :
1292         </para>
1293         <screen>
1294             [ f , index ] = costf ( x , index )
1295             [ f , c , index ] = costf ( x , index )
1296         </screen>
1297         <para>where</para>
1298         <variablelist>
1299             <varlistentry>
1300                 <term>x</term>
1301                 <listitem>
1302                     <para>the current point, as a column vector</para>
1303                 </listitem>
1304             </varlistentry>
1305             <varlistentry>
1306                 <term>index</term>
1307                 <listitem>
1308                     <para>optional, an integer representing the value to compute</para>
1309                 </listitem>
1310             </varlistentry>
1311             <varlistentry>
1312                 <term>f</term>
1313                 <listitem>
1314                     <para>the value of the cost function</para>
1315                 </listitem>
1316             </varlistentry>
1317             <varlistentry>
1318                 <term>c</term>
1319                 <listitem>
1320                     <para>the value of the non-linear, positive, inequality constraints</para>
1321                 </listitem>
1322             </varlistentry>
1323         </variablelist>
1324         <para>
1325             The index input parameter tells to the cost function what is expected
1326             in the output arguments. It has the following meaning
1327         </para>
1328         <variablelist>
1329             <varlistentry>
1330                 <term>index = 2</term>
1331                 <listitem>
1332                     <para>
1333                         compute <literal>f</literal>
1334                     </para>
1335                 </listitem>
1336             </varlistentry>
1337             <varlistentry>
1338                 <term>index = 5</term>
1339                 <listitem>
1340                     <para>
1341                         compute <literal>c</literal>
1342                     </para>
1343                 </listitem>
1344             </varlistentry>
1345             <varlistentry>
1346                 <term>index = 6</term>
1347                 <listitem>
1348                     <para>
1349                         compute <literal>f</literal> and <literal>c</literal>
1350                     </para>
1351                 </listitem>
1352             </varlistentry>
1353         </variablelist>
1354         <para>
1355             In the most simplex case, there is no additionnal cost function argument and no nonlinear constraints.
1356             In this case, the cost function is expected to have the following header
1357         </para>
1358         <screen>
1359             [ f , index ]= myfunction ( x , index )
1360         </screen>
1361         <para>
1362             It might happen that the function requires additionnal arguments to be evaluated.
1363             In this case, we can use the following feature.
1364             The argument <literal>fun</literal> can also be the list <literal>(myfun,a1,a2,...)</literal>.
1365             In this case <literal>myfun</literal>, the first element in the list, must be a function and must
1366             have the header:
1367             <screen>
1368                 [ f , index ] = myfun ( x , index , a1, a2, ... )
1369                 [ f , c , index ] = myfun ( x , index , a1, a2, ...)
1370             </screen>
1371             where the input arguments <literal>a1, a2, ...</literal>
1372             are automatically appended at the end of the calling sequence.
1373         </para>
1374     </refsection>
1375     <refsection>
1376         <title>The output function</title>
1377         <para>
1378             The option -outputcommand allows to configure a command which is
1379             called back at the start of the optimization, at each iteration and at the
1380             end of the optimization.
1381         </para>
1382         <para>The output function must have the following header</para>
1383         <screen>
1384             stop = outputcmd(state, data)
1385         </screen>
1386         <para>where</para>
1387         <variablelist>
1388             <varlistentry>
1389                 <term>state</term>
1390                 <listitem>
1391                     <para>
1392                         a string representing the current state of the algorithm.
1393                         Available values are "init", "iter", "done".
1394                     </para>
1395                 </listitem>
1396             </varlistentry>
1397             <varlistentry>
1398                 <term>data</term>
1399                 <listitem>
1400                     <para>a data structure containing at least the following entries</para>
1401                     <variablelist>
1402                         <varlistentry>
1403                             <term>x</term>
1404                             <listitem>
1405                                 <para>the current optimum</para>
1406                             </listitem>
1407                         </varlistentry>
1408                         <varlistentry>
1409                             <term>fval</term>
1410                             <listitem>
1411                                 <para>the current function value</para>
1412                             </listitem>
1413                         </varlistentry>
1414                         <varlistentry>
1415                             <term>iteration</term>
1416                             <listitem>
1417                                 <para>the current iteration index</para>
1418                             </listitem>
1419                         </varlistentry>
1420                         <varlistentry>
1421                             <term>funccount</term>
1422                             <listitem>
1423                                 <para>the number of function evaluations</para>
1424                             </listitem>
1425                         </varlistentry>
1426                         <varlistentry>
1427                             <term>simplex</term>
1428                             <listitem>
1429                                 <para>the current simplex</para>
1430                             </listitem>
1431                         </varlistentry>
1432                         <varlistentry>
1433                             <term>step</term>
1434                             <listitem>
1435                                 <para>
1436                                     the previous step in the algorithm. The following values
1437                                     are available : "init", "done", "reflection", "expansion",
1438                                     "insidecontraction", "outsidecontraction", "reflectionnext",
1439                                     "shrink".
1440                                 </para>
1441                             </listitem>
1442                         </varlistentry>
1443                     </variablelist>
1444                 </listitem>
1445             </varlistentry>
1446             <varlistentry>
1447                 <term>stop</term>
1448                 <listitem>
1449                     <para>
1450                         a 1-by-1 matrix of booleans, set to true to stop the
1451                         algorithm, set to false to continue the optimization.
1452                     </para>
1453                 </listitem>
1454             </varlistentry>
1455         </variablelist>
1456         <para>
1457             It might happen that the output function requires additionnal arguments to be evaluated.
1458             In this case, we can use the following feature.
1459             The argument <literal>outputcmd</literal> can also be the list <literal>(outf,a1,a2,...)</literal>.
1460             In this case <literal>outf</literal>, the first element in the list, must be a function and must
1461             have the header:
1462             <screen>
1463                 stop = outf ( state, data, a1, a2, ... )
1464             </screen>
1465             where the input arguments <literal>a1, a2, ...</literal>
1466             are automatically appended at the end of the calling sequence.
1467         </para>
1468         <para>
1469             If the output function sets the <literal>stop</literal> variable to true,
1470             then the optimization alorithm stops and the status of the optimization is
1471             set to <literal>"userstop"</literal>.
1472         </para>
1473     </refsection>
1474     <refsection>
1475         <title>Termination</title>
1476         <para>
1477             The current component takes into account for several generic
1478             termination criterias.
1479         </para>
1480         <para>The following termination criterias are enabled by default :</para>
1481         <itemizedlist>
1482             <listitem>
1483                 <para>-maxiter,</para>
1484             </listitem>
1485             <listitem>
1486                 <para>-maxfunevals,</para>
1487             </listitem>
1488             <listitem>
1489                 <para>-tolxmethod.</para>
1490             </listitem>
1491             <listitem>
1492                 <para>-tolsimplexizemethod.</para>
1493             </listitem>
1494         </itemizedlist>
1495         <para>
1496             The optimization_terminate function uses a set of rules to compute
1497             if the termination occurs, which leads to an optimization status which is
1498             equal to one of the following : "continue", "maxiter", "maxfunevals",
1499             "tolf", "tolx", "tolsize", "tolsizedeltafv",
1500             "kelleystagnation", "tolboxf", "tolvariance". The value of the status may also
1501             be a user-defined string, in the case where a user-defined termination
1502             function has been set.
1503         </para>
1504         <para>The following set of rules is examined in this order.</para>
1505         <itemizedlist>
1506             <listitem>
1507                 <para>
1508                     By default, the status is <literal>"continue"</literal> and the <literal>terminate</literal> flag is
1509                     %f.
1510                 </para>
1511             </listitem>
1512             <listitem>
1513                 <para>
1514                     The number of iterations is examined and compared to the
1515                     <literal>-maxiter</literal> option : if the following condition
1516                 </para>
1517                 <screen>
1518                     iterations &gt;= maxiter
1519                 </screen>
1520                 <para>
1521                     is true, then the status is set to "maxiter" and terminate is
1522                     set to %t.
1523                 </para>
1524             </listitem>
1525             <listitem>
1526                 <para>
1527                     The number of function evaluations and compared to the
1528                     <literal>-maxfunevals</literal> option is examined : if the following condition
1529                 </para>
1530                 <screen>
1531                     funevals &gt;= maxfunevals
1532                 </screen>
1533                 <para>
1534                     is true, then the status is set to <literal>"maxfuneval"</literal> and <literal>terminate</literal> is
1535                     set to %t.
1536                 </para>
1537             </listitem>
1538             <listitem>
1539                 <para>
1540                     The tolerance on function value is examined depending on the
1541                     value of the <literal>-tolfunmethod</literal>.
1542                 </para>
1543                 <variablelist>
1544                     <varlistentry>
1545                         <term>%f</term>
1546                         <listitem>
1547                             <para>then the criteria is just ignored.</para>
1548                         </listitem>
1549                     </varlistentry>
1550                     <varlistentry>
1551                         <term>%t</term>
1552                         <listitem>
1553                             <para>if the following condition</para>
1554                             <screen>
1555                                 abs(currentfopt) &lt; tolfunrelative * abs(previousfopt) + tolfunabsolute
1556                             </screen>
1557                             <para>
1558                                 is true, then the status is set to "tolf" and terminate is
1559                                 set to %t.
1560                             </para>
1561                         </listitem>
1562                     </varlistentry>
1563                 </variablelist>
1564                 <para>
1565                     The relative termination criteria on the function value works
1566                     well if the function value at optimum is near zero. In that case, the
1567                     function value at initial guess fx0 may be used as
1568                     <literal>previousfopt</literal>.
1569                 </para>
1570                 <para>
1571                     This criteria is sensitive to the <literal>-tolfunrelative</literal>
1572                     and <literal>-tolfunabsolute</literal> options.
1573                 </para>
1574                 <para>
1575                     The absolute termination criteria on the function value works if
1576                     the user has an accurate idea of the optimum function value.
1577                 </para>
1578             </listitem>
1579             <listitem>
1580                 <para>
1581                     The tolerance on x is examined depending on the value of the
1582                     -tolxmethod.
1583                 </para>
1584                 <variablelist>
1585                     <varlistentry>
1586                         <term>%f</term>
1587                         <listitem>
1588                             <para>then the criteria is just ignored.</para>
1589                         </listitem>
1590                     </varlistentry>
1591                     <varlistentry>
1592                         <term>%t</term>
1593                         <listitem>
1594                             <para>if the following condition</para>
1595                             <screen>
1596                                 norm(xopt - previousxopt) &lt; tolxrelative * norm(xopt) + tolxabsolute
1597                             </screen>
1598                             <para>
1599                                 is true, then the status is set to <literal>"tolx"</literal> and <literal>terminate</literal> is
1600                                 set to %t.
1601                             </para>
1602                         </listitem>
1603                     </varlistentry>
1604                 </variablelist>
1605                 <para>
1606                     This criteria is sensitive to the <literal>-tolxrelative</literal>
1607                     and <literal>-tolxabsolute</literal> options.
1608                 </para>
1609                 <para>
1610                     The relative termination criteria on x works well if x at
1611                     optimum is different from zero. In that case, the condition measures
1612                     the distance between two iterates.
1613                 </para>
1614                 <para>
1615                     The absolute termination criteria on x works if the user has an
1616                     accurate idea of the scale of the optimum x. If the optimum x is near
1617                     0, the relative tolerance will not work and the absolute tolerance is
1618                     more appropriate.
1619                 </para>
1620             </listitem>
1621             <listitem>
1622                 <para>
1623                     The tolerance on simplex size is examined depending on
1624                     the value of the <literal>-tolsimplexizemethod</literal> option.
1625                 </para>
1626                 <variablelist>
1627                     <varlistentry>
1628                         <term>%f</term>
1629                         <listitem>
1630                             <para>then the criteria is just ignored.</para>
1631                         </listitem>
1632                     </varlistentry>
1633                     <varlistentry>
1634                         <term>%t</term>
1635                         <listitem>
1636                             <para>if the following condition</para>
1637                             <screen>
1638                                 ssize &lt; tolsimplexizerelative * simplexsize0 + tolsimplexizeabsolute
1639                             </screen>
1640                             <para>
1641                                 is true where <literal>simplexsize0</literal> is the size of the simplex at
1642                                 iteration 0, then the <literal>status</literal> is set to <literal>"tolsize"</literal>
1643                                 and <literal>terminate</literal> is set to %t.
1644                             </para>
1645                             <para>
1646                                 The size of the simplex is computed from the "sigmaplus" method of the
1647                                 <literal>optimsimplex</literal> component.
1648                                 This criteria is sensitive to the <literal>-tolsimplexizeabsolute</literal> and
1649                                 the <literal>-tolsimplexizerelative</literal> options.
1650                             </para>
1651                         </listitem>
1652                     </varlistentry>
1653                 </variablelist>
1654             </listitem>
1655             <listitem>
1656                 <para>
1657                     The absolute tolerance on simplex size and absolute difference
1658                     of function value is examined depending on the value of the
1659                     -tolssizedeltafvmethod option.
1660                 </para>
1661                 <variablelist>
1662                     <varlistentry>
1663                         <term>%f</term>
1664                         <listitem>
1665                             <para>then the criteria is just ignored.</para>
1666                         </listitem>
1667                     </varlistentry>
1668                     <varlistentry>
1669                         <term>%t</term>
1670                         <listitem>
1671                             <para>if both the following conditions</para>
1672                             <screen>
1673                                 ssize &lt; tolsimplexizeabsolute
1674                             </screen>
1675                             <screen>
1676                                 shiftfv &lt; toldeltafv
1677                             </screen>
1678                             <para>
1679                                 is true where <literal>ssize</literal> is the current simplex size and
1680                                 <literal>shiftfv</literal> is the absolute value of the difference of function
1681                                 value between the highest and lowest vertices, then the status
1682                                 is set to <literal>"tolsizedeltafv"</literal> and <literal>terminate</literal> is set to %t.
1683                             </para>
1684                         </listitem>
1685                     </varlistentry>
1686                 </variablelist>
1687             </listitem>
1688             <listitem>
1689                 <para>
1690                     The stagnation condition based on Kelley sufficient decrease
1691                     condition is examined depending on the value of the
1692                     <literal>-kelleystagnationflag</literal> option.
1693                 </para>
1694                 <variablelist>
1695                     <varlistentry>
1696                         <term>%f</term>
1697                         <listitem>
1698                             <para>then the criteria is just ignored.</para>
1699                         </listitem>
1700                     </varlistentry>
1701                     <varlistentry>
1702                         <term>%t</term>
1703                         <listitem>
1704                             <para>if the following condition</para>
1705                             <screen>
1706                                 newfvmean &lt;= oldfvmean - alpha * sg' * sg
1707                             </screen>
1708                             <para>
1709                                 is true where <literal>newfvmean</literal> (resp. <literal>oldfvmean</literal>) is the function
1710                                 value average in the current iteration (resp. in the previous
1711                                 iteration), then the status is set to "kelleystagnation" and
1712                                 terminate is set to %t. Here, <literal>alpha</literal> is a non-dimensional
1713                                 coefficient and <literal>sg</literal> is the simplex gradient.
1714                             </para>
1715                         </listitem>
1716                     </varlistentry>
1717                 </variablelist>
1718             </listitem>
1719             <listitem>
1720                 <para>
1721                     The termination condition suggested by Box
1722                     is examined depending on the value of the
1723                     -boxtermination option.
1724                 </para>
1725                 <variablelist>
1726                     <varlistentry>
1727                         <term>%f</term>
1728                         <listitem>
1729                             <para>then the criteria is just ignored.</para>
1730                         </listitem>
1731                     </varlistentry>
1732                     <varlistentry>
1733                         <term>%t</term>
1734                         <listitem>
1735                             <para>if both the following conditions</para>
1736                             <screen>
1737                                 shiftfv &lt; boxtolf
1738                             </screen>
1739                             <screen>
1740                                 boxkount == boxnbmatch
1741                             </screen>
1742                             <para>
1743                                 is true where <literal>shiftfv </literal>is the difference of function value
1744                                 between the best and worst vertices, and <literal>boxkount</literal> is the number of
1745                                 consecutive iterations where this criteria is met,
1746                                 then the status is set to "tolboxf" and
1747                                 terminate is set to %t.
1748                                 Here, the <literal>boxtolf</literal> parameter is the value associated with
1749                                 the <literal>-boxtolf</literal> option
1750                                 and is a user-defined absolute tolerance on the function value.
1751                                 The <literal>boxnbmatch</literal> parameter is the value associated with
1752                                 the <literal>-boxnbmatch</literal> option
1753                                 and is the user-defined number of consecutive match.
1754                             </para>
1755                         </listitem>
1756                     </varlistentry>
1757                 </variablelist>
1758             </listitem>
1759             <listitem>
1760                 <para>
1761                     The termination condition based on the variance of the function values in the simplex
1762                     is examined depending on the value of the
1763                     <literal>-tolvarianceflag</literal> option.
1764                 </para>
1765                 <variablelist>
1766                     <varlistentry>
1767                         <term>%f</term>
1768                         <listitem>
1769                             <para>then the criteria is just ignored.</para>
1770                         </listitem>
1771                     </varlistentry>
1772                     <varlistentry>
1773                         <term>%t</term>
1774                         <listitem>
1775                             <para>if the following condition</para>
1776                             <screen>
1777                                 var &lt; tolrelativevariance * variancesimplex0 + tolabsolutevariance
1778                             </screen>
1779                             <para>
1780                                 is true where <literal>var </literal>is the variance of the function values
1781                                 in the simplex,
1782                                 then the status is set to "tolvariance" and
1783                                 terminate is set to %t.
1784                                 Here, the <literal>tolrelativevariance</literal> parameter is the value associated with
1785                                 the <literal>-tolrelativevariance</literal> option
1786                                 and is a user-defined relative tolerance on the variance of the function values.
1787                                 The <literal>tolabsolutevariance</literal> parameter is the value associated with
1788                                 the <literal>-tolabsolutevariance</literal> option
1789                                 and is the user-defined absolute tolerance of the variance of the function values.
1790                             </para>
1791                         </listitem>
1792                     </varlistentry>
1793                 </variablelist>
1794             </listitem>
1795         </itemizedlist>
1796     </refsection>
1797     <refsection>
1798         <title>Kelley's stagnation detection</title>
1799         <para>
1800             The stagnation detection criteria suggested by Kelley is based on a
1801             sufficient decrease condition, which requires a parameter alpha &gt; 0 to
1802             be defined. The -kelleynormalizationflag option allows to configure the
1803             method to use to compute this alpha parameter : two methods are available,
1804             where each method corresponds to a different paper by Kelley :
1805         </para>
1806         <variablelist>
1807             <varlistentry>
1808                 <term>constant</term>
1809                 <listitem>
1810                     <para>
1811                         In "Detection and Remediation of Stagnation in the
1812                         Nelder--Mead Algorithm Using a Sufficient Decrease Condition",
1813                         Kelley uses a constant alpha, with the suggested value 1.e-4, which
1814                         is is typical choice for line search method.
1815                     </para>
1816                 </listitem>
1817             </varlistentry>
1818             <varlistentry>
1819                 <term>normalized</term>
1820                 <listitem>
1821                     <para>
1822                         in "Iterative Methods for Optimization", Kelley uses a
1823                         normalized alpha, computed from the following formula
1824                     </para>
1825                     <screen>
1826                         alpha = alpha0 * sigma0 / nsg
1827                     </screen>
1828                     <para>
1829                         where sigma0 is the size of the initial simplex and nsg is the
1830                         norm of the simplex gradient for the initial guess point.
1831                     </para>
1832                 </listitem>
1833             </varlistentry>
1834         </variablelist>
1835     </refsection>
1836     <refsection>
1837         <title>O'Neill factorial optimality test</title>
1838         <para>
1839             In "Algorithm AS47 - Function minimization using a simplex
1840             procedure", R. O'Neill presents a fortran 77 implementation of the simplex
1841             method. A factorial test is used to check if the computed optimum point is
1842             a local minimum. If the -restartdetection option is set to "oneill", that
1843             factorial test is used to see if a restart should be performed.
1844             O'Neill's factorial test requires <literal>2n</literal> function evaluations, where <literal>n</literal>
1845             is the number of variables.
1846         </para>
1847     </refsection>
1848     <refsection>
1849         <title>User-defined algorithm</title>
1850         <para>
1851             The <literal>-mymethod</literal> option allows to configure a user-defined
1852             simplex-based algorithm. The reason for this option is that many simplex-based
1853             variants of Nelder-Mead's algorithm have been developed over the years,
1854             with specific goals. While it is not possible to provide them all, it is very convenient
1855             to use the current structure without being forced to make many developments.
1856         </para>
1857         <para>
1858             The value of the <literal>-mymethod</literal> option is expected to be
1859             a Scilab function with the following header
1860         </para>
1861         <screen>
1862             this = myalgorithm ( this )
1863         </screen>
1864         <para>
1865             where <literal>this</literal> is the current object.
1866         </para>
1867         <para>
1868             In order to use the user-defined algorithm, the <literal>-method</literal> option must
1869             be set to "mine". In this case, the component performs the optimization
1870             exactly as if the user-defined algorithm was provided by the component.
1871         </para>
1872         <para>
1873             The user interested in that feature may use the internal scripts provided in the
1874             distribution as templates and tune his own algorithm from that point.
1875             There is of course no warranty that the
1876             user-defined algorithm improves on the standard algorithm, so that users
1877             use this feature at their own risks.
1878         </para>
1879     </refsection>
1880     <refsection>
1881         <title>Example #1: basic use</title>
1882         <para>
1883             In the following example, we solve a simple quadratic test case. We
1884             begin by defining the cost function, which takes 2 input arguments and
1885             returns the objective. The classical starting point [-1.2 1.0] is used.
1886             The neldermead_new creates a new neldermead object. Then we use the
1887             neldermead_configure method to configure the parameters of the problem. We
1888             use all default settings and perform the search for the optimum. The
1889             neldermead_display function is used to display the state of the
1890             optimization and the neldermead_get is used to retrieve the optimum
1891             parameters.
1892         </para>
1893         <programlisting role="example"><![CDATA[ 
1894 function [ f , index ] = quadratic ( x , index )
1895   f = x(1)^2 + x(2)^2;
1896 endfunction
1897 x0 = [1.0 1.0].';
1898 nm = neldermead_new ();
1899 nm = neldermead_configure(nm,"-numberofvariables",2);
1900 nm = neldermead_configure(nm,"-function",quadratic);
1901 nm = neldermead_configure(nm,"-x0",x0);
1902 nm = neldermead_search(nm);
1903 nm
1904 xopt = neldermead_get(nm,"-xopt");
1905 nm = neldermead_destroy(nm);
1906  ]]></programlisting>
1907     </refsection>
1908     <refsection>
1909         <title>Example #2: customized use</title>
1910         <para>
1911             In the following example, we solve the Rosenbrock test case. We
1912             begin by defining the Rosenbrock function, which takes 2 input arguments
1913             and returns the objective. The classical starting point [-1.2 1.0] is
1914             used. The neldermead_new creates a new neldermead object. Then we use the
1915             neldermead_configure method to configure the parameters of the problem.
1916             The initial simplex is computed from the axes and the single length 1.0
1917             (this is the default, but is explicitly written here as an example). The
1918             variable simplex algorithm by Nelder and Mead is used, which corresponds
1919             to the -method "variable" option. The neldermead_search function performs
1920             the search for the minimum. Once the minimum is found, the
1921             neldermead_contour allows to compute the data required by the contour
1922             function. This is possible since our problem involves only 2 parameters.
1923             This function uses the cost function previously configured to compute the
1924             required data. The contour plot is directly drawn from the data provided
1925             by neldermead_contour. Then we plot the initial guess on the contour plot
1926             as a blue dot. The neldermead_get function is used to get the optimum,
1927             which is associated with the -xopt option. The optimum is plot on the
1928             contour plot as a red dot.
1929         </para>
1930         <programlisting role="example"><![CDATA[ 
1931 function [ f , index ] = rosenbrock ( x , index )
1932   f = 100*(x(2)-x(1)^2)^2+(1-x(1))^2;
1933 endfunction
1934 x0 = [-1.2 1.0]'
1935 nm = neldermead_new ();
1936 nm = neldermead_configure(nm,"-numberofvariables",2);
1937 nm = neldermead_configure(nm,"-function",rosenbrock);
1938 nm = neldermead_configure(nm,"-x0",x0);
1939 nm = neldermead_configure(nm,"-maxiter",200);
1940 nm = neldermead_configure(nm,"-maxfunevals",300);
1941 nm = neldermead_configure(nm,"-tolfunrelative",10*%eps);
1942 nm = neldermead_configure(nm,"-tolxrelative",10*%eps);
1943 nm = neldermead_configure(nm,"-simplex0method","axes");
1944 nm = neldermead_configure(nm,"-simplex0length",1.0);
1945 nm = neldermead_configure(nm,"-method","variable");
1946 nm = neldermead_configure(nm,"-verbose",1);
1947 nm = neldermead_configure(nm,"-verbosetermination",1);
1948 nm = neldermead_search(nm);
1949 xopt = neldermead_get(nm,"-xopt")
1950 nm = neldermead_destroy(nm);
1951 // Contouring the function.
1952 function f = rosenbrockC ( x1 , x2 )
1953   index = 2
1954   [ f , index ] = rosenbrock ( [x1,x2]' , index )
1955 endfunction
1956 xdata = linspace ( -2 , 2 , 100 );
1957 ydata = linspace ( -1 , 2 , 100 );
1958 h = scf();
1959 contour ( xdata , ydata , rosenbrockC , [2 10 100 500 1000 2000] )
1960 // Plot starting point: x0 : blue dot
1961 plot(x0(1),x0(2),"bo");
1962 // xopt : red star
1963 plot(xopt(1),xopt(2),"r*");
1964  ]]></programlisting>
1965         <para>
1966             The -verbose option allows to get detailed information about the
1967             current optimization process. The following is a sample output for an
1968             optimization based on the Nelder and Mead variable-shape simplex
1969             algorithm. Only the output corresponding to the iteration #156 is
1970             displayed. In order to display specific outputs (or to create specific
1971             output files and graphics), the -outputcommand option should be
1972             used.
1973         </para>
1974         <screen><![CDATA[ 
1975 [...]
1976 Iteration #156 (total = 156)
1977 Function Eval #299
1978 Xopt : [1 1]
1979 Fopt : 6.871D-27
1980 DeltaFv : 2.881D-26
1981 Center : [1 1]
1982 Size : 2.549D-13
1983 Optim Simplex Object:
1984 =====================
1985 nbve: 3
1986 n: 2
1987 x: 3-by-2 matrix
1988 fv: 3-by-1 matrix
1989   > Termination ?
1990   > iterations=156 >= maxiter=200
1991   > funevals=299 >= maxfunevals=300
1992   > e(x)=8.798D-15 < 2.220D-15 * 1.4142136 + 0
1993   > Terminate = F, status = continue
1994   > simplex size=2.549D-13 < 0 + 2.220D-16 * 1
1995   > Terminate = F, status = continue
1996 Reflect
1997 xbar=1 1
1998 Function Evaluation #300, index=2, x= [1 1]
1999 xr=[1 1], f(xr)=0.000000
2000 Contract - inside
2001 Function Evaluation #301, index=2, x= [1 1]
2002 xc=1 1, f(xc)=0.000000
2003   > Perform Inside Contraction
2004 Sort
2005 [...]
2006  ]]></screen>
2007     </refsection>
2008     <refsection>
2009         <title>Example #3: use output function</title>
2010         <para>
2011             There are several ways to print intermediate messages or plots during the 
2012             optimization process. 
2013             The first method is to set the "-verbose" option to 1, 
2014             which prints a lot of detailed information. 
2015             The other method is to use the <literal>"-outputcommand"</literal> option. 
2016             We can either set it to the <literal>neldermead_defaultoutput</literal> or 
2017             define our own function. 
2018             In this section, we present the methods based on the <literal>"-outputcommand"</literal> option. 
2019         </para>
2020         <para>
2021             In the following example, we use the <literal>"-outputcommand"</literal>option and 
2022             set it to the <literal>neldermead_defaultoutput</literal> 
2023             default output function. 
2024             This function prints one line by iteration, with the main optimization information.
2025         </para>
2026         <programlisting role="example"><![CDATA[ 
2027 function [ f , index ] = quadratic ( x , index )
2028   f = x(1)^2 + x(2)^2;
2029 endfunction
2030 x0 = [1.0 1.0].';
2031 nm = neldermead_new ();
2032 nm = neldermead_configure(nm,"-numberofvariables",2);
2033 nm = neldermead_configure(nm,"-function",quadratic);
2034 nm = neldermead_configure(nm,"-x0",x0);
2035 nm = neldermead_configure(nm,"-outputcommand",neldermead_defaultoutput);
2036 nm = neldermead_search(nm);
2037 nm = neldermead_destroy(nm);
2038  ]]></programlisting>
2039         <para>
2040             The previous script produces the following output.
2041         </para>
2042         <screen>
2043             Initialization
2044             Iter. #0, Feval #5, Fval = 2 -- init
2045             Iter. #1, Feval #5, Fval = 2 -- init
2046             Iter. #2, Feval #6, Fval = 2 -- reflection
2047             Iter. #3, Feval #8, Fval = 0.5 -- expansion
2048             Iter. #4, Feval #9, Fval = 0.5 -- reflection
2049             [...]
2050             Iter. #48, Feval #92, Fval = 8.557D-13 -- reflection
2051             Iter. #49, Feval #94, Fval = 7.893D-13 -- insidecontraction
2052             Iter. #50, Feval #96, Fval = 1.601D-13 -- insidecontraction
2053             Iter. #51, Feval #98, Fval = 1.291D-13 -- insidecontraction
2054             Iter. #52, Feval #100, Fval = 3.139D-14 -- outsidecontraction
2055             =================================
2056             End of Optimization
2057             Iter. #52, Feval #100, Fval = 3.139D-14 -- done
2058         </screen>
2059         <para>
2060             In the following example, we define our own output function "myoutputcmd", which takes the current state
2061             as its first argument. The state is a string which can contain "init",
2062             "iter" or "done", depending on the status of the optimization. The data
2063             input argument is a tlist, which contains the data associated with the
2064             current iteration. In this case, we use the fields to print a message in
2065             the console. 
2066         </para>
2067         <programlisting role="example"><![CDATA[ 
2068 function [ f , index ] = rosenbrock ( x , index )
2069   f = 100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
2070 endfunction
2071
2072 function stop = myoutputcmd ( state , data )
2073   iter = data.iteration
2074   if ( state == "init" ) then
2075     mprintf ( "=================================\n");
2076     mprintf ( "Initialization\n");
2077   elseif ( state == "done" ) then
2078     mprintf ( "=================================\n");
2079     mprintf ( "End of Optimization\n");
2080   end
2081   fc = data.funccount
2082   fval = data.fval
2083   x = data.x
2084   simplex = data.simplex
2085   // Simplex is a data structure, which can be managed
2086   // by the optimsimplex class.
2087   ssize = optimsimplex_size ( simplex )
2088   mprintf ( "Iter. #%3d, Feval #%3d, Fval = %.1e, x = %s, S = %.1e\n", ..
2089     iter, fc, fval, strcat(string(x)," "), ssize);
2090   stop = %f
2091 endfunction
2092
2093 nm = neldermead_new ();
2094 nm = neldermead_configure(nm,"-numberofvariables",2);
2095 nm = neldermead_configure(nm,"-function",rosenbrock);
2096 nm = neldermead_configure(nm,"-x0",[-1.2 1.0]');
2097 nm = neldermead_configure(nm,"-maxiter",200);
2098 nm = neldermead_configure(nm,"-maxfunevals",300);
2099 nm = neldermead_configure(nm,"-tolfunrelative",10*%eps);
2100 nm = neldermead_configure(nm,"-tolxrelative",10*%eps);
2101 nm = neldermead_configure(nm,"-simplex0method","axes");
2102 nm = neldermead_configure(nm,"-simplex0length",1.0);
2103 nm = neldermead_configure(nm,"-method","variable");
2104 nm = neldermead_configure(nm,"-verbose",0);
2105 nm = neldermead_configure(nm,"-verbosetermination",0);
2106 nm = neldermead_configure(nm,"-outputcommand",myoutputcmd);
2107 nm = neldermead_search(nm);
2108 nm = neldermead_destroy(nm);
2109  ]]></programlisting>
2110         <para>
2111             The previous script produces the following output.
2112         </para>
2113         <screen>
2114             =================================
2115             Initialization
2116             Iter. #  0, Feval #  5, Fval = 2.4e+001, x = -1.2 1, S = 1.0e+000
2117             Iter. #  1, Feval #  5, Fval = 2.4e+001, x = -1.2 1, S = 1.0e+000
2118             Iter. #  2, Feval #  7, Fval = 2.4e+001, x = -1.2 1, S = 1.0e+000
2119             Iter. #  3, Feval #  9, Fval = 2.4e+001, x = -1.2 1, S = 1.0e+000
2120             Iter. #  4, Feval # 11, Fval = 1.0e+001, x = -1.0125 0.78125, S = 6.0e-001
2121             Iter. #  5, Feval # 13, Fval = 4.7e+000, x = -1.028125 1.1328125, S = 3.5e-001
2122             ...
2123             Iter. #155, Feval #297, Fval = 2.0e-026, x = 1 1, S = 4.6e-013
2124             Iter. #156, Feval #299, Fval = 6.9e-027, x = 1 1, S = 2.5e-013
2125             Iter. #157, Feval #301, Fval = 6.0e-027, x = 1 1, S = 2.8e-013
2126             =================================
2127             End of Optimization
2128             Iter. #157, Feval #301, Fval = 6.0e-027, x = 1 1, S = 2.8e-013
2129         </screen>
2130         <para>
2131             As another example of use, we could format the message so
2132             that it uses LaTeX formatting rules, which may allow the user to directly
2133             copy and paste the output into a LaTeX report.
2134         </para>
2135     </refsection>
2136     <refsection>
2137         <title>Example #4: Optimization with bounds</title>
2138         <para>
2139             The <literal>neldermead</literal> solver can optimize problems with
2140             bounds.
2141             To do this, we can use Box's algorithm, which projects the simplex
2142             into the bounds during the optimization.
2143             In this case, the initial guess must be located within the bounds.
2144         </para>
2145         <para>
2146             In the following example, we find the minimum of a quadratic function
2147             within given bounds.
2148             In order to compute the initial simplex, we use randomized bounds, that is,
2149             we compute k random vertices uniformly distributed within the bounds.
2150             The default value is so that the number of points is twice the number of
2151             variables of the problem.
2152             In this particular case, we have n=2 variables and k=4 vertices.
2153         </para>
2154         <programlisting role="example"><![CDATA[ 
2155 function [ f , index ] = myquad ( x , index )
2156     f = x(1)^2 + x(2)^2
2157 endfunction
2158 rand("seed" , 0)
2159 x0 = [1.3 1.8].';
2160 nm = neldermead_new ();
2161 nm = neldermead_configure(nm,"-numberofvariables",2);
2162 nm = neldermead_configure(nm,"-function",myquad);
2163 nm = neldermead_configure(nm,"-x0",x0);
2164 nm = neldermead_configure(nm,"-method","box");
2165 nm = neldermead_configure(nm,"-boundsmin",[1 1]);
2166 nm = neldermead_configure(nm,"-boundsmax",[2 2]);
2167 nm = neldermead_configure(nm,"-simplex0method","randbounds");
2168 nm = neldermead_search(nm);
2169 xopt = neldermead_get(nm,"-xopt") // Should be [1 1]
2170 fopt = neldermead_get(nm,"-fopt") // Should be 2
2171 nm = neldermead_destroy(nm);
2172  ]]></programlisting>
2173     </refsection>
2174     <refsection>
2175         <title>Example #5: Optimization with nonlinear constraints</title>
2176         <para>
2177             The <literal>neldermead</literal> solver can optimize problems with
2178             nonlinear constraints.
2179             In the following example, we solve Rosenbrock's Post Office problem, which
2180             has both bounds and linear constraints.
2181             In our example, we will manage the linear constraints as general non-linear
2182             constraints (i.e. the solver does not make a difference if the constraints are
2183             linear or non-linear).
2184             This example was first
2185             presented in "An automatic method for finding the greatest or least value of a function",
2186             Rosenbrock, 1960.
2187             This example was first used with the complex method of Box in
2188             "Algorithm 454: The complex method for constrained optimization" by
2189             Richardson, Kuester, 1971.
2190             Richardson and Kuester found the minimum function value
2191             F=-3456, with X1 = 24.01, X2 = 12.00, X3 = 12.00 and
2192             72 Iterations were necessary for them to get this result.
2193         </para>
2194         <para>
2195             In the following function, we define the function <literal>fpostoffice</literal>,
2196             which returns both the objective function <literal>f</literal> and the
2197             constraint value <literal>c</literal>.
2198             The original constraint is the "double" inequality constraint
2199             <literal>0&lt;=x(1) + 2 * x(2) + 2 * x(3) &lt;=72</literal>.
2200             To take this constraint into account, we turn it into two separate, positive,
2201             constraints and set <literal>c</literal> as a 1-by-2 matrix of doubles.
2202         </para>
2203         <programlisting role="example"><![CDATA[ 
2204   function [ f , c , index ] = fpostoffice ( x , index )
2205     f = []
2206     c = []
2207     if ( index==2 | index==6 ) then
2208       f = -x(1) * x(2) * x(3)
2209     end
2210     
2211     if ( index==5 | index==6 ) then
2212       c1 = x(1) + 2 * x(2) + 2 * x(3)
2213       c2 = 72 - c1
2214       c = [c1 c2]
2215     end
2216   endfunction
2217  ]]></programlisting>
2218         <para>
2219             In the following script, we solve Rosenbrock's Post Office problem.
2220             First, we initialize the random number generator, so that the results are always the
2221             same.
2222             Then, we check that the cost function is correctly defined and that the
2223             constraints are satisfied at the initial guess.
2224             Then we configure the algorithm so that Box's algorithm is used and
2225             setup the bounds of the problem.
2226             We configure the parameters of the algorithm as suggested by Box.
2227         </para>
2228         <programlisting role="example"><![CDATA[ 
2229   rand("seed" , 0);
2230   x0 = [1.0 1.0 1.0].';
2231   // Compute f(x0) : should be close to -1
2232   fx0 = fpostoffice ( x0 , 2 )
2233   // Compute the constraints: cx0 should be [5 67]
2234   [ fx0 , cx0, index ] = fpostoffice ( x0 , 6 )
2235   // Compute f(xopt) : fopt should be -3456
2236   xopt = [24 12 12].';
2237   fopt = fpostoffice ( xopt );
2238   // Setup optimization
2239   nm = neldermead_new ();
2240   nm = neldermead_configure(nm,"-numberofvariables",3);
2241   nm = neldermead_configure(nm,"-function",fpostoffice);
2242   nm = neldermead_configure(nm,"-x0",x0);
2243   nm = neldermead_configure(nm,"-maxiter",300);
2244   nm = neldermead_configure(nm,"-maxfunevals",300);
2245   nm = neldermead_configure(nm,"-method","box");
2246   nm = neldermead_configure(nm,"-boundsmin",[0.0 0.0 0.0]);
2247   nm = neldermead_configure(nm,"-boundsmax",[42.0 42.0 42.0]);
2248   // Configure like Box
2249   nm = neldermead_configure(nm,"-simplex0method","randbounds");
2250   nm = neldermead_configure(nm,"-nbineqconst",2);
2251   nm = neldermead_configure(nm,"-tolxmethod" , %f );
2252   nm = neldermead_configure(nm,"-tolsimplexizemethod",%f);
2253   nm = neldermead_configure(nm,"-boxtermination" , %t );
2254   nm = neldermead_configure(nm,"-boxtolf" , 0.001 );
2255   nm = neldermead_configure(nm,"-boxboundsalpha" , 0.0001 );
2256   //
2257   // Check that the cost function is correctly connected.
2258   [ nm , result ] = neldermead_function ( nm , x0 );
2259   //
2260   // Perform optimization
2261   nm = neldermead_search(nm);
2262   xcomp = neldermead_get(nm,"-xopt")
2263   // Compare with the exact optimum:
2264   xopt
2265   fcomp = neldermead_get(nm,"-fopt")
2266   // Compare with the exact function value:
2267   fopt
2268   nm = neldermead_destroy(nm);
2269  ]]></programlisting>
2270         <para>
2271             In general, we should not expect too much from this algorithm with
2272             nonlinear constraints.
2273             Indeed, some cases require thousands of iterations to converge to
2274             an optimum, because the nonlinear constraints leave a too small
2275             space for the simplex to evolve.
2276         </para>
2277     </refsection>
2278     <refsection>
2279         <title>Example #6: Passing extra parameters</title>
2280         <para>
2281             In the following example, we solve a simple quadratic test case.
2282             Notice that the objective function has two extra parameters
2283             <literal>a</literal> and <literal>b</literal>.
2284             This is why the "-function" option is set as a list,
2285             where the first element is the function and the
2286             remaining elements are the extra parameters.
2287         </para>
2288         <programlisting role="example"><![CDATA[ 
2289 function [ f , index ] = quadratic_ab ( x , index , a , b )
2290   f = a * x(1)^2 + b * x(2)^2;
2291 endfunction
2292 x0 = [1.0 1.0].';
2293 nm = neldermead_new ();
2294 nm = neldermead_configure(nm,"-numberofvariables",2);
2295 a = 1;
2296 b = 2;
2297 nm = neldermead_configure(nm,"-function",list(quadratic_ab,a,b));
2298 nm = neldermead_configure(nm,"-x0",x0);
2299 nm = neldermead_search(nm);
2300 xopt = neldermead_get(nm,"-xopt")
2301 nm = neldermead_destroy(nm);
2302  ]]></programlisting>
2303     </refsection>
2304     <refsection>
2305         <title>Example #7: Restarting without bounds</title>
2306         <para>
2307             In the following example, we reproduce the experiment 
2308             published by Ken McKinnon in 1998. 
2309             For this particular function and this particular initial simplex,
2310             the Nelder-Mead algorithm converges to a nonstationnary point. 
2311         </para>
2312         <para>
2313             We first define the objective function, the initial simplex 
2314             and the expected solution of this unconstrained optimization problem.
2315         </para>
2316         <programlisting role="example"><![CDATA[ 
2317 function [ f , index ] = mckinnon ( x , index )
2318   tau = 3
2319   theta = 6
2320   phi = 400
2321   if ( x(1) <= 0 )
2322     f = theta*phi*abs(x(1))^tau+x(2)*(1+x(2))
2323   else
2324     f = theta*x(1)^tau+x(2)*(1+x(2))
2325   end
2326 endfunction
2327
2328 // The initial simplex
2329 lambda1 = (1.0 + sqrt(33))/8;
2330 lambda2 = (1.0 - sqrt(33))/8;
2331 coords0 = [
2332 1  1
2333 0  0 
2334 lambda1 lambda2
2335 ];
2336
2337 // The expected solution
2338 xstar = [0;-0.5];
2339 fstar = -0.25;
2340  ]]></programlisting>
2341         <para>
2342             Then we run the algorithm two times in sequence. 
2343             At the end of the first optimization process, the algorithm has 
2344             converged to the point [0,0] which is nonstationnary. 
2345             This is why we restart the algorithm and get the correct minimum.
2346         </para>
2347         <programlisting role="example"><![CDATA[ 
2348 nm = neldermead_new ();
2349 nm = neldermead_configure(nm,"-numberofvariables",2);
2350 nm = neldermead_configure(nm,"-function",mckinnon);
2351 nm = neldermead_configure(nm,"-x0",[1.0 1.0]');
2352 nm = neldermead_configure(nm,"-tolsimplexizerelative",1.e-4);
2353 nm = neldermead_configure(nm, "-maxiter",200);
2354 nm = neldermead_configure(nm, "-maxfunevals",500);
2355 nm = neldermead_configure(nm,"-simplex0method","given");
2356 nm = neldermead_configure(nm,"-coords0",coords0);
2357 nm = neldermead_configure(nm,"-method","variable");
2358 // Search #1: fails
2359 nm = neldermead_search(nm);
2360 xopt = neldermead_get(nm,"-xopt")
2361 fopt = neldermead_get(nm,"-fopt")
2362 iterations = neldermead_get(nm,"-iterations")
2363 status = neldermead_get(nm,"-status")
2364 // Search #2: succeeds
2365 nm = neldermead_restart ( nm );
2366 xopt = neldermead_get(nm,"-xopt")
2367 fopt = neldermead_get(nm,"-fopt")
2368 iterations = neldermead_get(nm,"-iterations")
2369 status = neldermead_get(nm,"-status")
2370 nm = neldermead_destroy(nm);
2371  ]]></programlisting>
2372         <para>
2373             We can also use the automatic stagnation detection method 
2374             created by Kelley, so that the algorithm automatically restart 
2375             the algorithm when needed.
2376         </para>
2377         <programlisting role="example"><![CDATA[ 
2378 nm = neldermead_new ();
2379 nm = neldermead_configure(nm,"-numberofvariables",2);
2380 nm = neldermead_configure(nm,"-function",mckinnon);
2381 nm = neldermead_configure(nm,"-x0",[1.0 1.0]');
2382 nm = neldermead_configure(nm,"-tolsimplexizerelative",1.e-4);
2383 nm = neldermead_configure(nm, "-maxiter",200);
2384 nm = neldermead_configure(nm, "-maxfunevals",500);
2385 nm = neldermead_configure(nm,"-simplex0method","given");
2386 nm = neldermead_configure(nm,"-coords0",coords0);
2387 nm = neldermead_configure(nm,"-method","variable");
2388 nm = neldermead_configure(nm,"-kelleystagnationflag",%t);
2389 nm = neldermead_configure(nm,"-restartflag",%t);
2390 nm = neldermead_configure(nm,"-restartdetection","kelley");
2391 nm = neldermead_search(nm);
2392 xopt = neldermead_get(nm,"-xopt")
2393 fopt = neldermead_get(nm,"-fopt")
2394 iterations = neldermead_get(nm,"-iterations")
2395 restartnb = neldermead_get ( nm , "-restartnb" )
2396 status = neldermead_get(nm,"-status")
2397 nm = neldermead_destroy(nm);
2398  ]]></programlisting>
2399         <para>
2400             See the demonstrations to get a graphical plot of the 
2401             intermediate simplices in Mc Kinnon's experiment.
2402         </para>
2403     </refsection>
2404     <refsection>
2405         <title>Example #8: Restarting with bounds</title>
2406         <para>
2407             In the following experimeant, we solve an optimization problem 
2408             with bounds. 
2409             We use Box's algorithm, which is the only algorithm which manages bounds.
2410             We use the randomized bounds simplex both for the initial simplex and 
2411             for the restart simplex.
2412         </para>
2413         <programlisting role="example"><![CDATA[ 
2414 function [ f , index ] = myquad ( x , index )
2415     f = x(1)^2 + x(2)^2 + x(3)^2
2416 endfunction
2417 x0 = [1.2 1.9,1.5].';
2418 // The solution
2419 xstar = [1;1;1];
2420 fstar = 3;
2421 //
2422 nm = neldermead_new ();
2423 nm = neldermead_configure(nm,"-numberofvariables",3);
2424 nm = neldermead_configure(nm,"-function",myquad);
2425 nm = neldermead_configure(nm,"-x0",x0);
2426 nm = neldermead_configure(nm,"-method","box");
2427 nm = neldermead_configure(nm,"-boundsmin",[1 1 1]);
2428 nm = neldermead_configure(nm,"-boundsmax",[2 2 2]);
2429 nm = neldermead_configure(nm,"-simplex0method","randbounds");
2430 nm = neldermead_search(nm);
2431 nm = neldermead_configure(nm,"-maxiter",200);
2432 nm = neldermead_configure(nm,"-maxfunevals",200);
2433 nm = neldermead_configure(nm,"-restartsimplexmethod","randbounds");
2434 nm = neldermead_restart(nm);
2435 xopt = neldermead_get(nm,"-xopt")
2436 fopt = neldermead_get(nm,"-fopt")
2437 status = neldermead_get(nm,"-status")
2438 nm = neldermead_destroy(nm);
2439  ]]></programlisting>
2440     </refsection>
2441     <refsection>
2442         <title>Changes in Scilab 5.4</title>
2443         <para>
2444             Many changes have been done in Scilab 5.4, which simplify the use of the
2445             neldermead component.
2446         </para>
2447         <para>
2448             Tagged -costfargument option of optimbase as obsolete: will be
2449             maintained for backward compatibility until 5.4.1.
2450             The -fun option can now be a list, where the element #1 is a
2451             function, and the elements #2 to the end are automatically appended to
2452             the calling sequence.
2453             To update your code, replace:
2454         </para>
2455         <screen>
2456             nm = neldermead_configure(nm,"-function",myfun);
2457             nm = neldermead_configure(nm,"-costfargument",mystuff);
2458         </screen>
2459         <para>
2460             with
2461         </para>
2462         <screen>
2463             nm = neldermead_configure(nm,"-function",list(myfun,mystuff));
2464         </screen>
2465         <para>
2466             Tagged -outputcommandarg option of optimbase as obsolete: will be
2467             maintained for backward compatibility until 5.4.1.
2468             The -outputcommand option can now be a list, where the element #1 is
2469             a function, and the elements #2 to the end are automatically appended
2470             to the calling sequence.
2471             To update your code, replace:
2472         </para>
2473         <screen>
2474             nm = neldermead_configure(nm,"-outputcommand",myoutputfun);
2475             nm = neldermead_configure(nm,"-outputcommandarg",mystuff);
2476         </screen>
2477         <para>
2478             with:
2479         </para>
2480         <screen>
2481             nm = neldermead_configure(nm,"-outputcommand",list(myoutputfun,mystuff));
2482         </screen>
2483         <para>
2484             Tagged "outputfun(x,optimValues,state)" calling sequence of fminsearch
2485             as obsolete: will be maintained for backward compatibility until
2486             5.4.1.
2487             The new calling sequence is "stop=outputfun(x,optimValues,state)"
2488             To update your code, replace:
2489         </para>
2490         <screen>
2491             function outfun ( x , optimValues , state )
2492             [...]
2493             endfunction
2494         </screen>
2495         <para>
2496             with:
2497         </para>
2498         <screen>
2499             function stop = outfun ( x , optimValues , state )
2500             [...]
2501             stop = %f
2502             endfunction
2503         </screen>
2504         <para>
2505             Tagged "myoutputfun(state,data)" calling sequence of neldermead
2506             as obsolete: will be maintained for backward compatibility until
2507             5.4.1.
2508             The new calling sequence is "stop=myoutputfun(state,data)"
2509             To update your code, replace:
2510         </para>
2511         <screen>
2512             function myoutputfun ( state , data )
2513             [...]
2514             endfunction
2515         </screen>
2516         <para>
2517             with:
2518         </para>
2519         <screen>
2520             function stop = myoutputfun ( state , data )
2521             [...]
2522             stop = %f
2523             endfunction
2524         </screen>
2525         <para>
2526             Tagged "-myterminateflag" and "-myterminate" options as obsolete:
2527             will be maintained for backward compatibility until 5.4.1.
2528             To update your code, replace:
2529         </para>
2530         <screen>
2531             function [ this , terminate , status ] = myoldterminate ( this , simplex )
2532             ssize = optimsimplex_size ( simplex , "sigmaplus" );
2533             if ( ssize &lt; 1.e-2 ) then
2534             terminate = %t;
2535             status = "mysize";
2536             else
2537             terminate = %f
2538             end
2539             endfunction
2540         </screen>
2541         <para>
2542             with :
2543         </para>
2544         <screen>
2545             function stop = myoutputcmd ( state , data )
2546             simplex = data.simplex
2547             ssize = optimsimplex_size ( simplex , "sigmaplus" );
2548             if ( ssize &lt; 1.e-2 ) then
2549             stop = %t;
2550             else
2551             stop = %f
2552             end
2553             endfunction
2554         </screen>
2555         <para>
2556             and replace the configuration:
2557         </para>
2558         <screen>
2559             nm = neldermead_configure(nm,"-myterminateflag",%t);
2560             nm = neldermead_configure(nm,"-myterminate",myoldterminate);
2561         </screen>
2562         <para>
2563             with:
2564         </para>
2565         <screen>
2566             nm = neldermead_configure(nm,"-outputcommand",myoutputcmd);
2567         </screen>
2568         <para>
2569             Tagged "-tolvarianceflag", "-tolabsolutevariance", and 
2570             "-tolrelativevariance" options as obsolete:
2571             will be maintained for backward compatibility until 5.4.1.
2572             To update your code, create an output function:
2573         </para>
2574         <screen>
2575             function stop = myoutputcmd ( state, data, tolrelativevariance, tolabsolutevariance, variancesimplex0 )
2576             simplex = data.simplex
2577             stop = %f
2578             if ( state == "iter") then
2579             var = optimsimplex_fvvariance ( simplex )
2580             if ( var &lt; tolrelativevariance * variancesimplex0 + tolabsolutevariance ) then
2581             stop = %t;
2582             end
2583             end
2584             endfunction
2585         </screen>
2586         <para>
2587             Create the initial simplex and compute the variance 
2588             of the function values:
2589         </para>
2590         <screen>
2591             x0 = [1.1 1.1]';
2592             simplex0 = optimsimplex_new ( "axes" , x0.' );
2593             coords0 = optimsimplex_getallx(simplex0);
2594             variancesimplex0 = optimsimplex_fvvariance ( simplex0 );
2595         </screen>
2596         <para>
2597             Finally, replace the configuration:
2598         </para>
2599         <screen>
2600             nm = neldermead_configure(nm,"-tolvarianceflag",%t);
2601             nm = neldermead_configure(nm,"-tolabsolutevariance",1.e-4);
2602             nm = neldermead_configure(nm,"-tolrelativevariance",1.e-4);
2603         </screen>
2604         <para>
2605             with:
2606         </para>
2607         <screen>
2608             tolabsolutevariance = 1.e-4;
2609             tolrelativevariance = 1.e-4;
2610             stopfun = list(myoutputcmd, tolrelativevariance, tolabsolutevariance, variancesimplex0);
2611             nm = neldermead_configure(nm,"-outputcommand",stopfun);
2612         </screen>
2613     </refsection>
2614     <refsection>
2615         <title>Spendley et al. implementation notes</title>
2616         <para>
2617             The original paper may be implemented with several variations, which
2618             might lead to different results. This section defines what algorithmic
2619             choices have been used.
2620         </para>
2621         <para>The paper states the following rules.</para>
2622         <itemizedlist>
2623             <listitem>
2624                 <para>
2625                     "Rule 1. Ascertain the lowest reading y, of yi ... yk+1 Complete
2626                     a new simplex Sp by excluding the point Vp corresponding to y, and
2627                     replacing it by V* defined as above."
2628                 </para>
2629             </listitem>
2630             <listitem>
2631                 <para>
2632                     "Rule 2. If a result has occurred in (k + 1) successive
2633                     simplexes, and is not then eliminated by application of Rule 1, do not
2634                     move in the direction indicated by Rule 1, or at all, but discard the
2635                     result and replace it by a new observation at the same point."
2636                 </para>
2637             </listitem>
2638             <listitem>
2639                 <para>
2640                     "Rule 3. If y is the lowest reading in So , and if the next
2641                     observation made, y* , is the lowest reading in the new simplex S , do
2642                     not apply Rule 1 and return to So from Sp . Move out of S, by
2643                     rejecting the second lowest reading (which is also the second lowest
2644                     reading in So)."
2645                 </para>
2646             </listitem>
2647         </itemizedlist>
2648         <para>
2649             We implement the following "rules" of the Spendley et al.
2650             method.
2651         </para>
2652         <itemizedlist>
2653             <listitem>
2654                 <para>
2655                     Rule 1 is strictly applied, but the reflection is done by
2656                     reflection the high point, since we minimize a function instead of
2657                     maximizing it, like Spendley.
2658                 </para>
2659             </listitem>
2660             <listitem>
2661                 <para>
2662                     Rule 2 is NOT implemented, as we expect that the function
2663                     evaluation is not subject to errors.
2664                 </para>
2665             </listitem>
2666             <listitem>
2667                 <para>
2668                     Rule 3 is applied, ie reflection with respect to next to high
2669                     point.
2670                 </para>
2671             </listitem>
2672         </itemizedlist>
2673         <para>
2674             The original paper does not mention any shrink step. When the
2675             original algorithm cannot improve the function value with reflection
2676             steps, the basic algorithm stops. In order to make the current
2677             implementation of practical value, a shrink step is included, with
2678             shrinkage factor sigma. This perfectly fits into to the spirit of the
2679             original paper. Notice that the shrink step make the rule #3 (reflection
2680             with respect to next-to-worst vertex) unnecessary. Indeed, the minimum
2681             required steps are the reflection and shrinkage. Never the less, the rule
2682             #3 has been kept in order to make the algorithm as close as it can be to
2683             the original.
2684         </para>
2685     </refsection>
2686     <refsection>
2687         <title>Nelder-Mead implementation notes</title>
2688         <para>
2689             The purpose of this section is to analyse the current implementation of Nelder-Mead's algorithm.
2690         </para>
2691         <para>
2692             The algorithm that we use is described in "Iterative Methods for Optimization" by C. T. Kelley.
2693         </para>
2694         <para>
2695             The original paper uses a "greedy" expansion, in which the expansion point
2696             is accepted whatever its function value. The current implementation,
2697             as most implementations, uses the expansion point only if it improves
2698             over the reflection point, that is,
2699         </para>
2700         <itemizedlist>
2701             <listitem>
2702                 <para>
2703                     if fe&lt;fr, then the expansion point is accepted,
2704                 </para>
2705             </listitem>
2706             <listitem>
2707                 <para>
2708                     if not, the reflection point is accepted.
2709                 </para>
2710             </listitem>
2711         </itemizedlist>
2712         <para>
2713             The termination criteria suggested by Nelder and Mead is based on an
2714             absolute tolerance on the standard deviation of the function values in the simplex.
2715             We provide this original termination criteria with the <literal>-tolvarianceflag</literal>
2716             option, which is disabled by default.
2717         </para>
2718     </refsection>
2719     <refsection>
2720         <title>Box's complex algorithm implementation notes</title>
2721         <para>
2722             In this section, we analyse the current implementation of Box's complex method.
2723         </para>
2724         <para>
2725             The initial simplex can be computed as in Box's paper, but this may not
2726             be safe. In his paper, Box suggest that if a vertex of the initial simplex
2727             does not satisfy the non linear constraints, then it should be "moved halfway
2728             toward the centroid of those points already selected". This behaviour
2729             is available when the <literal>-scalingsimplex0</literal> option is set to
2730             <literal>"tocenter"</literal>. It may happen, as suggested by Guin, that
2731             the centroid is not feasible. This may happen if the constraints are not
2732             convex. In this case, the initial simplex cannot be computed. This is why
2733             we provide the <literal>"tox0"</literal> option, which allows to compute the
2734             initial simplex by scaling toward the initial guess, which is always feasible.
2735         </para>
2736         <para>
2737             In Box's paper, the scaling into the non linear constraints is performed
2738             "toward" the centroid, that is, by using a scaling factor equal to 0.5.
2739             This default scaling factor might be sub-optimal in certain situations.
2740             This is why we provide the <literal>-boxineqscaling</literal> option,
2741             which allows to configure the scaling factor.
2742         </para>
2743         <para>
2744             In Box's paper, whether we are concerned with the initial simplex or with the
2745             simplex at a given iteration, the scaling for the non linear constraints is performed
2746             without end. This is because Box's hypothesis is that "ultimately, a satisfactory
2747             point will be found". As suggested by Guin, if the process fails, the algorithm
2748             goes into an infinite loop. In order to avoid this, we perform the scaling until
2749             a minimum scaling value is reached, as defined by the <literal>-guinalphamin</literal>
2750             option.
2751         </para>
2752         <para>
2753             We have taken into account for the comments by Guin, but it should be emphasized
2754             that the current implementation is still as close as possible to Box's
2755             algorithm and is not Guin's algorithm. More precisely, during the iterations,
2756             the scaling for the non linear constraints is still performed toward the centroid,
2757             be it feasible or not.
2758         </para>
2759     </refsection>
2760     <refsection>
2761         <title>Bibliography</title>
2762         <para>
2763             "Sequential Application of Simplex Designs in Optimisation and
2764             Evolutionary Operation", Spendley, W. and Hext, G. R. and Himsworth, F.
2765             R., American Statistical Association and American Society for Quality,
2766             1962
2767         </para>
2768         <para>
2769             "A Simplex Method for Function Minimization", Nelder, J. A. and
2770             Mead, R., The Computer Journal, 1965
2771         </para>
2772         <para>
2773             "A New Method of Constrained Optimization and a Comparison With
2774             Other Methods", M. J. Box, The Computer Journal 1965 8(1):42-52, 1965 by
2775             British Computer Society
2776         </para>
2777         <para>
2778             "Discussion and correspondence: modification of the complex method
2779             of constrained optimization", J. A. Guin, The Computer Journal,
2780             1968
2781         </para>
2782         <para>
2783             "Detection and Remediation of Stagnation in the Nelder--Mead
2784             Algorithm Using a Sufficient Decrease Condition", Kelley C. T., SIAM J. on
2785             Optimization, 1999
2786         </para>
2787         <para>
2788             "Iterative Methods for Optimization", C. T. Kelley, SIAM Frontiers
2789             in Applied Mathematics, 1999
2790         </para>
2791         <para>
2792             "Algorithm AS47 - Function minimization using a simplex procedure",
2793             O'Neill, R., Applied Statistics, 1971
2794         </para>
2795         <para>
2796             "Nelder Mead's User Manual", Consortium Scilab - Digiteo, Michael
2797             Baudin, 2010
2798         </para>
2799         <para>
2800             Ken McKinnon, Convergence of the Nelder-Mead simplex method to a nonstationary point, 
2801             SIAM Journal on Optimization, Volume 9, Number 1, 1998, pages 148-158.
2802         </para>
2803     </refsection>
2804     <refsection role="see also">
2805         <title>See Also</title>
2806         <simplelist type="inline">
2807             <member>
2808                 <link linkend="optimbase_new">optimbase_new</link>
2809             </member>
2810             <member>
2811                 <link linkend="optimsimplex_new">optimsimplex_new</link>
2812             </member>
2813             <member>
2814                 <link linkend="optimbase_overview">optimbase</link>
2815             </member>
2816             <member>
2817                 <link linkend="optimsimplex_overview">optimsimplex</link>
2818             </member>
2819             <member>
2820                 <link linkend="nmplot">nmplot</link>
2821             </member>
2822         </simplelist>
2823     </refsection>
2824 </refentry>