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