3640ef4c0ced968ca7930071617adcc2fdd0a20e
[scilab.git] / scilab / modules / optimization / help / en_US / neldermead / neldermead.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!--
3  * Ajouter ici d'√©ventuels commentaires sur le fichier XML
4 -->
5 <refentry version="5.0-subset Scilab" xml:id="neldermead" xml:lang="fr"
6           xmlns="http://docbook.org/ns/docbook"
7           xmlns:xlink="http://www.w3.org/1999/xlink"
8           xmlns:svg="http://www.w3.org/2000/svg"
9           xmlns:ns4="http://www.w3.org/1999/xhtml"
10           xmlns:mml="http://www.w3.org/1998/Math/MathML"
11           xmlns:db="http://docbook.org/ns/docbook">
12   <info>
13     <pubdate>$LastChangedDate: 16-12-2008 $</pubdate>
14   </info>
15
16   <refnamediv>
17     <refname>neldermead</refname>
18
19     <refpurpose>Provides several direct search optimization algorithms based
20     on the simplex method.</refpurpose>
21   </refnamediv>
22
23   <refsynopsisdiv>
24     <title>SYNOPSIS</title>
25
26     <synopsis>
27 newobj = neldermead_new ()
28 this = neldermead_destroy (this)
29 this = neldermead_configure (this,key,value)
30 value = neldermead_cget (this,key)
31 this = neldermead_display ( this )
32 value = neldermead_get ( this , key )
33 this = neldermead_search ( this )
34 this = neldermead_restart ( this )
35 [ this , xdata , ydata , zdata ] = neldermead_contour ( this , xmin , xmax , ymin , ymax , nx , ny )
36 </synopsis>
37   </refsynopsisdiv>
38
39   <refsection>
40     <title>Description</title>
41
42     <para>This class provides several direct search optimization algorithms
43     based on the simplex method.</para>
44
45     <para>The optimization problem to solve is the minimization of a cost
46     function, with bounds and nonlinear constraints</para>
47
48     <programlisting role="example"> 
49 min f(x)
50 l_i &lt;= x_i &lt;= h_i, i = 1,n
51 g_i(x) &lt;= 0, i = 1,nbineq
52  </programlisting>
53
54     <para>where</para>
55
56     <variablelist>
57       <varlistentry>
58         <term>n</term>
59
60         <listitem>
61           <para>number of variables</para>
62         </listitem>
63       </varlistentry>
64
65       <varlistentry>
66         <term>nbineq</term>
67
68         <listitem>
69           <para>number of inequality constraints</para>
70         </listitem>
71       </varlistentry>
72     </variablelist>
73
74     <para>The provided algorithms are direct search algorithms, i.e.
75     algorithms which do not use the derivative of the cost function. They are
76     based on the update of a simplex, which is a set of k&gt;=n+1 vertices,
77     where each vertex is associated with one point and one function
78     value.</para>
79
80     <para>The following algorithms are available :</para>
81
82     <variablelist>
83       <varlistentry>
84         <term>Spendley, Hext and Himsworth fixed size simplex method</term>
85
86         <listitem>
87           <para>This algorithm solves an unconstrained optimization problem
88           with a fixed sized simplex made of k=n+1 vertices.</para>
89         </listitem>
90       </varlistentry>
91
92       <varlistentry>
93         <term>Nelder and Mead variable size simplex method</term>
94
95         <listitem>
96           <para>This algorithm solves an unconstrained optimization problem
97           with a variable sized simplex made of k=n+1 vertices.</para>
98         </listitem>
99       </varlistentry>
100
101       <varlistentry>
102         <term>Box complex method</term>
103
104         <listitem>
105           <para>This algorithm solves an constrained optimization problem with
106           a variable sized simplex made of an arbitrary k number of vertices
107           (k=2n is recommended by Box).</para>
108         </listitem>
109       </varlistentry>
110     </variablelist>
111   </refsection>
112
113   <refsection>
114     <title>Design</title>
115
116     <para>The neldermead component is built on top of the <link
117     linkend="optimbase">optimbase</link> and <link
118     linkend="optimsimplex">optimsimplex</link> components.</para>
119   </refsection>
120
121   <refsection>
122     <title>Functions</title>
123
124     <para>The following functions are available.</para>
125
126     <variablelist>
127       <varlistentry>
128         <term>newobj = neldermead_new ()</term>
129
130         <listitem>
131           <para>Creates a new neldermead object.</para>
132
133           <variablelist>
134             <varlistentry>
135               <term>newobj</term>
136
137               <listitem>
138                 <para>The new object.</para>
139               </listitem>
140             </varlistentry>
141           </variablelist>
142         </listitem>
143       </varlistentry>
144
145       <varlistentry>
146         <term>this = neldermead_destroy (this)</term>
147
148         <listitem>
149           <para>Destroy the given object.</para>
150
151           <variablelist>
152             <varlistentry>
153               <term>this</term>
154
155               <listitem>
156                 <para>The current object.</para>
157               </listitem>
158             </varlistentry>
159           </variablelist>
160         </listitem>
161       </varlistentry>
162
163       <varlistentry>
164         <term>this = neldermead_configure (this,key,value)</term>
165
166         <listitem>
167           <para>Configure the current object with the given value for the
168           given key.</para>
169
170           <variablelist>
171             <varlistentry>
172               <term>this</term>
173
174               <listitem>
175                 <para>The current object.</para>
176               </listitem>
177             </varlistentry>
178
179             <varlistentry>
180               <term>key</term>
181
182               <listitem>
183                 <para>the key to configure. The following keys are
184                 available.</para>
185
186                 <variablelist>
187                   <varlistentry>
188                     <term>-verbose</term>
189
190                     <listitem>
191                       <para>set to 1 to enable verbose logging. (default is
192                       0)</para>
193                     </listitem>
194                   </varlistentry>
195
196                   <varlistentry>
197                     <term>-verbosetermination</term>
198
199                     <listitem>
200                       <para>set to 1 to enable verbose termination logging.
201                       (default is 0)</para>
202                     </listitem>
203                   </varlistentry>
204
205                   <varlistentry>
206                     <term>-x0</term>
207
208                     <listitem>
209                       <para>the initial guess, as a n x 1 column vector, where
210                       n is the number of variables.</para>
211                     </listitem>
212                   </varlistentry>
213
214                   <varlistentry>
215                     <term>-maxfunevals</term>
216
217                     <listitem>
218                       <para>the maximum number of function evalutations
219                       (default is 100). If this criteria is triggered, the
220                       status of the optimization is set to
221                       "maxfuneval".</para>
222                     </listitem>
223                   </varlistentry>
224
225                   <varlistentry>
226                     <term>-maxiter</term>
227
228                     <listitem>
229                       <para>the maximum number of iterations (default is 100).
230                       If this criteria is triggered, the status of the
231                       optimization is set to "maxiter".</para>
232                     </listitem>
233                   </varlistentry>
234
235                   <varlistentry>
236                     <term>-tolfunabsolute</term>
237
238                     <listitem>
239                       <para>the absolute tolerance for the function value
240                       (default is 0.0).</para>
241                     </listitem>
242                   </varlistentry>
243
244                   <varlistentry>
245                     <term>-tolfunrelative</term>
246
247                     <listitem>
248                       <para>the relative tolerance for the function value
249                       (default is %eps).</para>
250                     </listitem>
251                   </varlistentry>
252
253                   <varlistentry>
254                     <term>-tolfunmethod</term>
255
256                     <listitem>
257                       <para>the method used for the tolerance on function
258                       value in the termination criteria.</para>
259
260                       <para>The following values are available :
261                       "absolute+relative", "relative", "absolute", "disabled"
262                       (default is "disabled"). If this criteria is triggered,
263                       the status of the optimization is set to "tolf".</para>
264                     </listitem>
265                   </varlistentry>
266
267                   <varlistentry>
268                     <term>-tolxabsolute</term>
269
270                     <listitem>
271                       <para>the absolute tolerance on x (default is
272                       0.0).</para>
273                     </listitem>
274                   </varlistentry>
275
276                   <varlistentry>
277                     <term>-tolxrelative</term>
278
279                     <listitem>
280                       <para>the relative tolerance on x (default is
281                       %eps).</para>
282                     </listitem>
283                   </varlistentry>
284
285                   <varlistentry>
286                     <term>-tolxmethod</term>
287
288                     <listitem>
289                       <para>the method used for the tolerance on x in the
290                       termination criteria.</para>
291
292                       <para>The following values are available : "relative",
293                       "absolute", "disabled" (default is "relative"). If this
294                       criteria is triggered, the status of the optimization is
295                       set to "tolx".</para>
296                     </listitem>
297                   </varlistentry>
298
299                   <varlistentry>
300                     <term>-function</term>
301
302                     <listitem>
303                       <para>the objective function, which computes the value
304                       of the cost and the non linear constraints, if
305                       any.</para>
306
307                       <para>See below for the details of the communication
308                       between the optimization system and the cost
309                       function.</para>
310                     </listitem>
311                   </varlistentry>
312
313                   <varlistentry>
314                     <term>-costfargument</term>
315
316                     <listitem>
317                       <para>an additionnal argument, passed to the cost
318                       function.</para>
319                     </listitem>
320                   </varlistentry>
321
322                   <varlistentry>
323                     <term>-outputcommand</term>
324
325                     <listitem>
326                       <para>a command which is called back for output.</para>
327
328                       <para>See below for the details of the communication
329                       between the optimization system and the output command
330                       function.</para>
331                     </listitem>
332                   </varlistentry>
333
334                   <varlistentry>
335                     <term>-outputcommandarg</term>
336
337                     <listitem>
338                       <para>an additionnal argument, passed to the output
339                       command.</para>
340                     </listitem>
341                   </varlistentry>
342
343                   <varlistentry>
344                     <term>-numberofvariables</term>
345
346                     <listitem>
347                       <para>the number of variables to optimize (default is
348                       0).</para>
349                     </listitem>
350                   </varlistentry>
351
352                   <varlistentry>
353                     <term>-storehistory</term>
354
355                     <listitem>
356                       <para>set to 1 to enable the history storing (default is
357                       0).</para>
358                     </listitem>
359                   </varlistentry>
360
361                   <varlistentry>
362                     <term>-boundsmin</term>
363
364                     <listitem>
365                       <para>the minimum bounds for the parameters, as an array
366                       of values (default is empty, i.e. there are no
367                       bounds).</para>
368                     </listitem>
369                   </varlistentry>
370
371                   <varlistentry>
372                     <term>-boundsmax</term>
373
374                     <listitem>
375                       <para>the maximum bounds for the parameters, as an array
376                       of values (default is empty, i.e. there are no
377                       bounds).</para>
378                     </listitem>
379                   </varlistentry>
380
381                   <varlistentry>
382                     <term>-nbineqconst</term>
383
384                     <listitem>
385                       <para>the number of inequality constraints (default is
386                       0)</para>
387                     </listitem>
388                   </varlistentry>
389
390                   <varlistentry>
391                     <term>-method</term>
392
393                     <listitem>
394                       <para>the name of the algorithm to use. The following
395                       methods are available :</para>
396
397                       <variablelist>
398                         <varlistentry>
399                           <term>"fixed"</term>
400
401                           <listitem>
402                             <para>the Spendley et al. fixed simplex shape
403                             algorithm. This algorithm is for unconstrained
404                             problems (i.e. bounds and non linear constraints are
405                             not taken into account)</para>
406                           </listitem>
407                         </varlistentry>
408
409                         <varlistentry>
410                           <term>"variable"</term>
411
412                           <listitem>
413                             <para>the Nelder-Mead variable simplex shape
414                             algorithm. This algorithm is for unconstrained
415                             problems (i.e. bounds and non linear constraints are
416                             not taken into account)</para>
417                           </listitem>
418                         </varlistentry>
419
420                         <varlistentry>
421                           <term>"box"</term>
422
423                           <listitem>
424                             <para>the Box complex algorithm. This algorithm
425                             takes into account bounds and nonlinear inequality
426                             constraints.</para>
427                           </listitem>
428                         </varlistentry>
429                       </variablelist>
430                     </listitem>
431                   </varlistentry>
432
433                   <varlistentry>
434                     <term>-simplex0method</term>
435
436                     <listitem>
437                       <para>the method to use to compute the initial simplex.
438                       The first vertex in the simplex is always the initial
439                       guess associated with the -x0 option. The following
440                       methods are available :</para>
441
442                       <variablelist>
443                         <varlistentry>
444                           <term>"given"</term>
445
446                           <listitem>
447                             <para>the coordinates associated with the -coords0
448                             option are used to compute the initial simplex, with
449                             arbitrary number of vertices.</para>
450
451                             <para>This allow the user to setup the initial
452                             simplex by a specific method which is not provided
453                             by the current component (for example with a simplex
454                             computed from a design of experiments). This allows
455                             also to configure the initial simplex so that a
456                             specific behaviour of the algorithm an be reproduced
457                             (for example the Mac Kinnon test case).</para>
458
459                             <para>The given matrix is expected to have n rows
460                             and k columns, where n is the dimension of the
461                             problem and k is the number of vertices.</para>
462                           </listitem>
463                         </varlistentry>
464
465                         <varlistentry>
466                           <term>"axes"</term>
467
468                           <listitem>
469                             <para>the simplex is computed from the coordinate
470                             axes and the length associated with the
471                             -simplex0length option.</para>
472                           </listitem>
473                         </varlistentry>
474
475                         <varlistentry>
476                           <term>"spendley"</term>
477
478                           <listitem>
479                             <para>the simplex is computed so that it is regular
480                             with the length associated with the -simplex0length
481                             option (i.e. all the edges have the same
482                             length).</para>
483                           </listitem>
484                         </varlistentry>
485
486                         <varlistentry>
487                           <term>"pfeffer"</term>
488
489                           <listitem>
490                             <para>the simplex is computed from an heuristic, in
491                             the neighborhood of the initial guess. This initial
492                             simplex depends on the -simplex0deltausual and
493                             -simplex0deltazero.</para>
494                           </listitem>
495                         </varlistentry>
496
497                         <varlistentry>
498                           <term>"randbounds"</term>
499
500                           <listitem>
501                             <para>the simplex is computed from the bounds and a
502                             random number. This option is available only if
503                             bounds are available : if bounds are not available,
504                             an error is generated. This method is usually
505                             associated with Box's algorithm. The number of
506                             vertices in the simplex is taken from the
507                             -boxnbpoints option.</para>
508                           </listitem>
509                         </varlistentry>
510                       </variablelist>
511                     </listitem>
512                   </varlistentry>
513
514                   <varlistentry>
515                     <term>-coords0</term>
516
517                     <listitem>
518                       <para>the coordinates of the vertices of the initial
519                       simplex. If the -simplex0method option is set to
520                       "given", these coordinates are used to compute the
521                       initial simplex. This matrix is expected to have shape
522                       nbve x n where nbve is the number of vertices and n is
523                       the number of variables.</para>
524                     </listitem>
525                   </varlistentry>
526
527                   <varlistentry>
528                     <term>-simplex0length</term>
529
530                     <listitem>
531                       <para>the length to use when the initial simplex is
532                       computed with the "axes" or "spendley" methods. If the
533                       initial simplex is computed from "spendley" method, the
534                       length is expected to be a scalar value. If the initial
535                       simplex is computed from "axes" method, it may be either
536                       a scalar value or a vector of values, with rank n, where
537                       n is the number of variables.</para>
538                     </listitem>
539                   </varlistentry>
540
541                   <varlistentry>
542                     <term>-simplex0deltausual</term>
543
544                     <listitem>
545                       <para>the relative delta for non-zero parameters in
546                       "pfeffer" method. The default value is 0.05.</para>
547                     </listitem>
548                   </varlistentry>
549
550                   <varlistentry>
551                     <term>-simplex0deltazero</term>
552
553                     <listitem>
554                       <para>the absolute delta for non-zero parameters in
555                       "pfeffer" method. The default value is 0.0075.</para>
556                     </listitem>
557                   </varlistentry>
558
559                   <varlistentry>
560                     <term>-rho</term>
561
562                     <listitem>
563                       <para>the reflection coefficient. This parameter is used
564                       when the -method option is set to "fixed" or "variable".
565                       The default value is 1.0.</para>
566                     </listitem>
567                   </varlistentry>
568
569                   <varlistentry>
570                     <term>-chi</term>
571
572                     <listitem>
573                       <para>the expansion coefficient. This parameter is used
574                       when the -method option is set to "variable". The
575                       default value is 2.0.</para>
576                     </listitem>
577                   </varlistentry>
578
579                   <varlistentry>
580                     <term>-gamma</term>
581
582                     <listitem>
583                       <para>the contraction coefficient. This parameter is
584                       used when the -method option is set to "variable". The
585                       default value is 0.5.</para>
586                     </listitem>
587                   </varlistentry>
588
589                   <varlistentry>
590                     <term>-sigma</term>
591
592                     <listitem>
593                       <para>the shrinkage coefficient. This parameter is used
594                       when the -method option is set to "fixed" or "variable".
595                       The default value is 0.5.</para>
596                     </listitem>
597                   </varlistentry>
598
599                   <varlistentry>
600                     <term>-tolfstdeviationmethod</term>
601
602                     <listitem>
603                       <para>set to "enabled" to enable the termination
604                       criteria based on the standard deviation of the function
605                       values in the simplex. The default value is "disabled".
606                       If this criteria is triggered, the status of the
607                       optimization is set to "tolfstdev".</para>
608
609                       <para>This criteria is suggested by Nelder and
610                       Mead.</para>
611                     </listitem>
612                   </varlistentry>
613
614                   <varlistentry>
615                     <term>-tolfstdeviation</term>
616
617                     <listitem>
618                       <para>the absolute tolerance on standard deviation. The
619                       default value is 0.0.</para>
620                     </listitem>
621                   </varlistentry>
622
623                   <varlistentry>
624                     <term>-tolsimplexizemethod</term>
625
626                     <listitem>
627                       <para>set to "disabled" to disable the tolerance on the
628                       simplex size. The default value is "enabled". If this
629                       criteria is triggered, the status of the optimization is
630                       set to "tolsize".</para>
631
632                       <para>When this criteria is enabled, the values of the
633                       options -tolsimplexizeabsolute and
634                       -tolsimplexizerelative are used in the termination
635                       criteria. The method to compute the size is the
636                       "sigmaplus" method.</para>
637                     </listitem>
638                   </varlistentry>
639
640                   <varlistentry>
641                     <term>-tolsimplexizeabsolute</term>
642
643                     <listitem>
644                       <para>the absolute tolerance on the simplex size. The
645                       default value is 0.0.</para>
646                     </listitem>
647                   </varlistentry>
648
649                   <varlistentry>
650                     <term>-tolsimplexizerelative</term>
651
652                     <listitem>
653                       <para>the relative tolerance on the simplex size. The
654                       default value is %eps.</para>
655                     </listitem>
656                   </varlistentry>
657
658                   <varlistentry>
659                     <term>-tolssizedeltafvmethod</term>
660
661                     <listitem>
662                       <para>set to "enabled" to enable the termination
663                       criteria based on the size of the simplex and the
664                       difference of function value in the simplex. The default
665                       value is "disabled". If this criteria is triggered, the
666                       status of the optimization is set to
667                       "tolsizedeltafv".</para>
668
669                       <para>This termination criteria uses the values of the
670                       options -tolsimplexizeabsolute and -toldeltafv. This
671                       criteria is identical to Matlab's fminsearch.</para>
672                     </listitem>
673                   </varlistentry>
674
675                   <varlistentry>
676                     <term>-toldeltafv</term>
677
678                     <listitem>
679                       <para>the absolute tolerance on the difference between
680                       the highest and the lowest function values.</para>
681                     </listitem>
682                   </varlistentry>
683
684                   <varlistentry>
685                     <term>-kelleystagnationflag</term>
686
687                     <listitem>
688                       <para>set to 1 to enable the termination criteria using
689                       Kelley's stagnation detection, based on sufficient
690                       decrease condition. The default value is 0. If this
691                       criteria is triggered, the status of the optimization is
692                       set to "kelleystagnation".</para>
693                     </listitem>
694                   </varlistentry>
695
696                   <varlistentry>
697                     <term>-kelleynormalizationflag</term>
698
699                     <listitem>
700                       <para>set to 0 to disable the normalization of the alpha
701                       coefficient in Kelley's stagnation detection, i.e. use
702                       the value of the option -kelleystagnationalpha0 as is.
703                       Default value is 1, i.e. the simplex gradient of the
704                       initial simplex is taken into account in the stagnation
705                       detection.</para>
706                     </listitem>
707                   </varlistentry>
708
709                   <varlistentry>
710                     <term>-kelleystagnationalpha0</term>
711
712                     <listitem>
713                       <para>the parameter used in Kelley's stagnation
714                       detection. The default value is 1.e-4.</para>
715                     </listitem>
716                   </varlistentry>
717
718                   <varlistentry>
719                     <term>-restartflag</term>
720
721                     <listitem>
722                       <para>set to 1 to enable the automatic restart of the
723                       algorithm. Default value is 0.</para>
724                     </listitem>
725                   </varlistentry>
726
727                   <varlistentry>
728                     <term>-restartdetection</term>
729
730                     <listitem>
731                       <para>the method to detect if the automatic restart must
732                       be performed. The following methods are available
733                       :</para>
734
735                       <variablelist>
736                         <varlistentry>
737                           <term>"oneill"</term>
738
739                           <listitem>
740                             <para>the factorial local optimality test by O'Neill
741                             is used. If the test finds a local point which is
742                             better than the computed optimum, a restart is
743                             performed.</para>
744                           </listitem>
745                         </varlistentry>
746
747                         <varlistentry>
748                           <term>"kelley"</term>
749
750                           <listitem>
751                             <para>the sufficient decrease condition by O'Neill
752                             is used. If the test finds that the status of the
753                             optimization is "kelleystagnation", a restart is
754                             performed. This status may be generated if the
755                             -kelleystagnationflag option is set to 1.</para>
756                           </listitem>
757                         </varlistentry>
758                       </variablelist>
759
760                       <para>The default method is "oneill".</para>
761                     </listitem>
762                   </varlistentry>
763
764                   <varlistentry>
765                     <term>-restartmax</term>
766
767                     <listitem>
768                       <para>the maximum number of restarts, when automatic
769                       restart is enabled via the -restartflag option. Default
770                       value is 3.</para>
771                     </listitem>
772                   </varlistentry>
773
774                   <varlistentry>
775                     <term>-restarteps</term>
776
777                     <listitem>
778                       <para>the absolute epsilon value used to check for
779                       optimality in the factorial O'Neill restart detection.
780                       The default value is %eps.</para>
781                     </listitem>
782                   </varlistentry>
783
784                   <varlistentry>
785                     <term>-restartstep</term>
786
787                     <listitem>
788                       <para>the absolute step length used to check for
789                       optimality in the factorial O'Neill restart detection.
790                       The default value is 1.0.</para>
791                     </listitem>
792                   </varlistentry>
793
794                   <varlistentry>
795                     <term>-restartsimplexmethod</term>
796
797                     <listitem>
798                       <para>the method to compute the initial simplex after a
799                       restart. The following methods are available.</para>
800
801                       <variablelist>
802                         <varlistentry>
803                           <term>"given"</term>
804
805                           <listitem>
806                             <para>the coordinates associated with the -coords0
807                             option are used to compute the initial simplex, with
808                             arbitrary number of vertices.</para>
809
810                             <para>This allow the user to setup the initial
811                             simplex by a specific method which is not provided
812                             by the current component (for example with a simplex
813                             computed from a design of experiments). This allows
814                             also to configure the initial simplex so that a
815                             specific behaviour of the algorithm an be reproduced
816                             (for example the Mac Kinnon test case).</para>
817
818                             <para>The given matrix is expected to have n rows
819                             and k columns, where n is the dimension of the
820                             problem and k is the number of vertices.</para>
821                           </listitem>
822                         </varlistentry>
823
824                         <varlistentry>
825                           <term>"axes"</term>
826
827                           <listitem>
828                             <para>the simplex is computed from the coordinate
829                             axes and the length associated with the
830                             -simplex0length option.</para>
831                           </listitem>
832                         </varlistentry>
833
834                         <varlistentry>
835                           <term>"spendley"</term>
836
837                           <listitem>
838                             <para>the simplex is computed so that it is regular
839                             with the length associated with the -simplex0length
840                             option (i.e. all the edges have the same
841                             length).</para>
842                           </listitem>
843                         </varlistentry>
844
845                         <varlistentry>
846                           <term>"pfeffer"</term>
847
848                           <listitem>
849                             <para>the simplex is computed from an heuristic, in
850                             the neighborhood of the initial guess. This initial
851                             simplex depends on the -simplex0deltausual and
852                             -simplex0deltazero.</para>
853                           </listitem>
854                         </varlistentry>
855
856                         <varlistentry>
857                           <term>"randbounds"</term>
858
859                           <listitem>
860                             <para>the simplex is computed from the bounds and a
861                             random number. This option is available only if
862                             bounds are available : if bounds are not available,
863                             an error is generated. This method is usually
864                             associated with Box's algorithm. The number of
865                             vertices in the simplex is taken from the
866                             -boxnbpoints option.</para>
867                           </listitem>
868                         </varlistentry>
869
870                         <varlistentry>
871                           <term>"oriented"</term>
872
873                           <listitem>
874                             <para>the simplex is computed so that it is
875                             oriented, as suggested by C.T. Kelley.</para>
876                           </listitem>
877                         </varlistentry>
878                       </variablelist>
879
880                       <para>The default method is "oriented".</para>
881                     </listitem>
882                   </varlistentry>
883
884                   <varlistentry>
885                     <term>-boxnbpoints</term>
886
887                     <listitem>
888                       <para>the number of points in the initial simplex, when
889                       the -restartsimplexmethod option is set to "randbounds".
890                       The default value is so that the number of points is
891                       twice the number of variables of the problem.</para>
892                     </listitem>
893                   </varlistentry>
894
895                   <varlistentry>
896                     <term>-nbineqloops</term>
897
898                     <listitem>
899                       <para>the number of loops to perform in Box and Box-Guin
900                       algorithms to scale the trial point for function
901                       improvement or into the constraints. Default value is
902                       10.</para>
903                     </listitem>
904                   </varlistentry>
905
906                   <varlistentry>
907                     <term>-ineqscaling</term>
908
909                     <listitem>
910                       <para>the scaling coefficient used to scale the trial
911                       point for function improvement or into the constraints.
912                       Default value is 0.5</para>
913                     </listitem>
914                   </varlistentry>
915                 </variablelist>
916               </listitem>
917             </varlistentry>
918
919             <varlistentry>
920               <term>value</term>
921
922               <listitem>
923                 <para>the value.</para>
924               </listitem>
925             </varlistentry>
926           </variablelist>
927         </listitem>
928       </varlistentry>
929
930       <varlistentry>
931         <term>value = neldermead_cget (this,key)</term>
932
933         <listitem>
934           <para>Get the value for the given key. If the key is unknown,
935           generates an error.</para>
936
937           <variablelist>
938             <varlistentry>
939               <term>this</term>
940
941               <listitem>
942                 <para>The current object.</para>
943               </listitem>
944             </varlistentry>
945
946             <varlistentry>
947               <term>key</term>
948
949               <listitem>
950                 <para>the name of the key to quiery. The list of available
951                 keys is the same as for the neldermead_configure
952                 function.</para>
953               </listitem>
954             </varlistentry>
955           </variablelist>
956         </listitem>
957       </varlistentry>
958
959       <varlistentry>
960         <term>value = neldermead_get ( this , key )</term>
961
962         <listitem>
963           <para>Get the value for the given key. If the key is unknown,
964           generates an error.</para>
965
966           <variablelist>
967             <varlistentry>
968               <term>this</term>
969
970               <listitem>
971                 <para>The current object.</para>
972               </listitem>
973             </varlistentry>
974
975             <varlistentry>
976               <term>key</term>
977
978               <listitem>
979                 <para>the key to get.</para>
980
981                 <para>The following keys are available :</para>
982
983                 <variablelist>
984                   <varlistentry>
985                     <term>-funevals</term>
986
987                     <listitem>
988                       <para>the number of function evaluations</para>
989                     </listitem>
990                   </varlistentry>
991
992                   <varlistentry>
993                     <term>-iterations</term>
994
995                     <listitem>
996                       <para>the number of iterations</para>
997                     </listitem>
998                   </varlistentry>
999
1000                   <varlistentry>
1001                     <term>-xopt</term>
1002
1003                     <listitem>
1004                       <para>the x optimum, as a n x 1 column vector, where n
1005                       is the number of variables.</para>
1006                     </listitem>
1007                   </varlistentry>
1008
1009                   <varlistentry>
1010                     <term>-fopt</term>
1011
1012                     <listitem>
1013                       <para>the optimum cost function value</para>
1014                     </listitem>
1015                   </varlistentry>
1016
1017                   <varlistentry>
1018                     <term>-historyxopt</term>
1019
1020                     <listitem>
1021                       <para>an array, with nbiter values, containing the
1022                       history of x during the iterations.</para>
1023
1024                       <para>This array is available after optimization if the
1025                       history storing was enabled with the -storehistory
1026                       option.</para>
1027                     </listitem>
1028                   </varlistentry>
1029
1030                   <varlistentry>
1031                     <term>-historyfopt</term>
1032
1033                     <listitem>
1034                       <para>an array, with nbiter values, containing the
1035                       history of the function value during the
1036                       iterations.</para>
1037
1038                       <para>This array is available after optimization if the
1039                       history storing was enabled with the -storehistory
1040                       option.</para>
1041                     </listitem>
1042                   </varlistentry>
1043
1044                   <varlistentry>
1045                     <term>-fx0</term>
1046
1047                     <listitem>
1048                       <para>the function value for the initial guess</para>
1049                     </listitem>
1050                   </varlistentry>
1051
1052                   <varlistentry>
1053                     <term>-status</term>
1054
1055                     <listitem>
1056                       <para>a string containing the status of the
1057                       optimization. See below for details about the
1058                       optimization status.</para>
1059                     </listitem>
1060                   </varlistentry>
1061
1062                   <varlistentry>
1063                     <term>-historysimplex</term>
1064
1065                     <listitem>
1066                       <para>a matrix containing the history of the simplex
1067                       during the iterations. This matrix has rank nbiter x
1068                       nbve x n, where nbiter is the number of iterations, nbve
1069                       is the number of vertices in the simplex and n is the
1070                       number of variables.</para>
1071                     </listitem>
1072                   </varlistentry>
1073
1074                   <varlistentry>
1075                     <term>-simplexopt</term>
1076
1077                     <listitem>
1078                       <para>the optimum simplex. This is a simplex object,
1079                       which is suitable for processing with the simplex
1080                       interface.</para>
1081                     </listitem>
1082                   </varlistentry>
1083
1084                   <varlistentry>
1085                     <term>-restartnb</term>
1086
1087                     <listitem>
1088                       <para>the number of actual restarts performed.</para>
1089                     </listitem>
1090                   </varlistentry>
1091                 </variablelist>
1092
1093                 <para>Most fields are available only after an optimization has
1094                 been performed with one call to the neldermead_search
1095                 method.</para>
1096               </listitem>
1097             </varlistentry>
1098           </variablelist>
1099         </listitem>
1100       </varlistentry>
1101
1102       <varlistentry>
1103         <term>this = neldermead_display ( this )</term>
1104
1105         <listitem>
1106           <para>Display the current settings in the console.</para>
1107
1108           <variablelist>
1109             <varlistentry>
1110               <term>this</term>
1111
1112               <listitem>
1113                 <para>The current object.</para>
1114               </listitem>
1115             </varlistentry>
1116           </variablelist>
1117         </listitem>
1118       </varlistentry>
1119
1120       <varlistentry>
1121         <term>this = neldermead_search ( this )</term>
1122
1123         <listitem>
1124           <para>Performs the optimization associated with the method
1125           associated with the -method option and find the optimum.</para>
1126
1127           <variablelist>
1128             <varlistentry>
1129               <term>this</term>
1130
1131               <listitem>
1132                 <para>The current object.</para>
1133               </listitem>
1134             </varlistentry>
1135           </variablelist>
1136
1137           <para>If the -restartflag option is enabled, automatic restarts are
1138           performed, based on the -restartdetection option.</para>
1139         </listitem>
1140       </varlistentry>
1141
1142       <varlistentry>
1143         <term>this = neldermead_restart ( this )</term>
1144
1145         <listitem>
1146           <para>Restarts the optimization by updating the simplex and
1147           performing a new search.</para>
1148
1149           <variablelist>
1150             <varlistentry>
1151               <term>this</term>
1152
1153               <listitem>
1154                 <para>The current object.</para>
1155               </listitem>
1156             </varlistentry>
1157           </variablelist>
1158         </listitem>
1159       </varlistentry>
1160     </variablelist>
1161   </refsection>
1162
1163   <refsection>
1164     <title>The cost function</title>
1165
1166     <para>The option -function allows to configure the cost function. The cost
1167     function is used to compute the cost and the value of the nonlinear
1168     inequality constraints.</para>
1169
1170     <para>In the more general case, the cost function is expected to have the
1171     following header</para>
1172
1173     <programlisting role="example"> 
1174 function y = myfunction(x, index, data)
1175  </programlisting>
1176
1177     <para>where</para>
1178
1179     <variablelist>
1180       <varlistentry>
1181         <term>x</term>
1182
1183         <listitem>
1184           <para>the current point</para>
1185         </listitem>
1186       </varlistentry>
1187
1188       <varlistentry>
1189         <term>index</term>
1190
1191         <listitem>
1192           <para>optional, an integer representing the value to compute</para>
1193         </listitem>
1194       </varlistentry>
1195
1196       <varlistentry>
1197         <term>data</term>
1198
1199         <listitem>
1200           <para>optional, a user-defined data.</para>
1201
1202           <para>This argument is configured with the -costfargument
1203           option.</para>
1204         </listitem>
1205       </varlistentry>
1206
1207       <varlistentry>
1208         <term>y</term>
1209
1210         <listitem>
1211           <para>the result</para>
1212         </listitem>
1213       </varlistentry>
1214     </variablelist>
1215
1216     <para>The index input parameter has the following meaning</para>
1217
1218     <variablelist>
1219       <varlistentry>
1220         <term>index = 1 (or no index)</term>
1221
1222         <listitem>
1223           <para>the result is the value of the cost function</para>
1224         </listitem>
1225       </varlistentry>
1226
1227       <varlistentry>
1228         <term>index = 2</term>
1229
1230         <listitem>
1231           <para>the result is the value of the non-linear inequality
1232           constraints, as an array of values</para>
1233         </listitem>
1234       </varlistentry>
1235
1236       <varlistentry>
1237         <term>index = 3</term>
1238
1239         <listitem>
1240           <para>the result is an array, which content is the following. At
1241           index #1, the value of the cost function. At index #2 to the end,
1242           the list of values of the nonlinear inequality constraints.</para>
1243         </listitem>
1244       </varlistentry>
1245     </variablelist>
1246
1247     <para>In the most simple case, the cost function is expected to have the
1248     following header</para>
1249
1250     <programlisting role="example"> 
1251 function y = myfunction(x)
1252  </programlisting>
1253
1254     <para>where x is the current point and y is the value of the cost. This
1255     case is associated with an unconstrained problem without any additionnal
1256     parameter.</para>
1257   </refsection>
1258
1259   <refsection>
1260     <title>The output function</title>
1261
1262     <para>The option -outputcommand allows to configure a command which is
1263     called back at the start of the optimization, at each iteration and at the
1264     end of the optimization.</para>
1265
1266     <para>The output function must have the following header</para>
1267
1268     <programlisting role="example"> 
1269 function outputcmd(state, data, myobj)
1270  </programlisting>
1271
1272     <para>where</para>
1273
1274     <variablelist>
1275       <varlistentry>
1276         <term>state</term>
1277
1278         <listitem>
1279           <para>a string representing the current state of the algorithm.
1280           Available values are "init", "iter", "done".</para>
1281         </listitem>
1282       </varlistentry>
1283
1284       <varlistentry>
1285         <term>data</term>
1286
1287         <listitem>
1288           <para>a tlist containing at least the following entries</para>
1289
1290           <variablelist>
1291             <varlistentry>
1292               <term>x</term>
1293
1294               <listitem>
1295                 <para>the current optimum</para>
1296               </listitem>
1297             </varlistentry>
1298
1299             <varlistentry>
1300               <term>fval</term>
1301
1302               <listitem>
1303                 <para>the current function value</para>
1304               </listitem>
1305             </varlistentry>
1306
1307             <varlistentry>
1308               <term>iteration</term>
1309
1310               <listitem>
1311                 <para>the current iteration index</para>
1312               </listitem>
1313             </varlistentry>
1314
1315             <varlistentry>
1316               <term>funccount</term>
1317
1318               <listitem>
1319                 <para>the number of function evaluations</para>
1320               </listitem>
1321             </varlistentry>
1322           </variablelist>
1323         </listitem>
1324       </varlistentry>
1325
1326       <varlistentry>
1327         <term>myobj</term>
1328
1329         <listitem>
1330           <para>a user-defined parameter.</para>
1331
1332           <para>This input parameter is defined with the -outputcommandarg
1333           option.</para>
1334         </listitem>
1335       </varlistentry>
1336     </variablelist>
1337
1338     <para>The output function may be used when debugging the specialized
1339     optimization algorithm, so that a verbose logging is produced. It may also
1340     be used to write one or several report files in a specialized format
1341     (ASCII, LaTeX, Excel, Hdf5, etc...). The user-defined parameter may be
1342     used in that case to store file names or logging options.</para>
1343
1344     <para>The data tlist argument may contain more fields than the current
1345     presented ones. These additionnal fields may contain values which are
1346     specific to the specialized algorithm, such as the simplex in a
1347     Nelder-Mead method, the gradient of the cost function in a BFGS method,
1348     etc...</para>
1349   </refsection>
1350
1351   <refsection>
1352     <title>Termination</title>
1353
1354     <para>The current component takes into account for several generic
1355     termination criterias. Specialized termination criterias should be
1356     implemented in specialized optimization algorithms, by calling the
1357     optimization_termination function and adding external criterias, rather
1358     than by modification of this function.</para>
1359
1360     <para>The optimization_terminate function uses a set of rules to compute
1361     if the termination occurs, which leads to an optimization status which is
1362     equal to one of the following : "continue", "maxiter", "maxfunevals",
1363     "tolf", "tolx", "tolfstdev", "tolsize", "tolsizedeltafv",
1364     "kelleystagnation". The set of rules is the following.</para>
1365
1366     <itemizedlist>
1367       <listitem>
1368         <para>By default, the status is "continue" and the terminate flag is
1369         0.</para>
1370       </listitem>
1371
1372       <listitem>
1373         <para>The number of iterations is examined and compared to the
1374         -maxiter option : if the following condition</para>
1375
1376         <programlisting role="example"> 
1377 iterations &gt;= maxiter
1378  </programlisting>
1379
1380         <para>is true, then the status is set to "maxiter" and terminate is
1381         set to 1.</para>
1382       </listitem>
1383
1384       <listitem>
1385         <para>The number of function evaluations and compared to the
1386         -maxfunevals option is examined : if the following condition</para>
1387
1388         <programlisting role="example"> 
1389 funevals &gt;= maxfunevals
1390  </programlisting>
1391
1392         <para>is true, then the status is set to "maxfuneval" and terminate is
1393         set to 1.</para>
1394       </listitem>
1395
1396       <listitem>
1397         <para>The tolerance on function value is examined depending on the
1398         value of the -tolfunmethod.</para>
1399
1400         <variablelist>
1401           <varlistentry>
1402             <term>"disabled"</term>
1403
1404             <listitem>
1405               <para>then the criteria is just ignored.</para>
1406             </listitem>
1407           </varlistentry>
1408
1409           <varlistentry>
1410             <term>"enabled"</term>
1411
1412             <listitem>
1413               <para>if the following condition</para>
1414
1415               <programlisting role="example"> 
1416 abs(currentfopt) &lt; tolfunrelative * abs(previousfopt) + tolfunabsolute
1417  </programlisting>
1418
1419               <para>is true, then the status is set to "tolf" and terminate is
1420               set to 1.</para>
1421             </listitem>
1422           </varlistentry>
1423         </variablelist>
1424
1425         <para>The relative termination criteria on the function value works
1426         well if the function value at optimum is near zero. In that case, the
1427         function value at initial guess fx0 may be used as
1428         previousfopt.</para>
1429
1430         <para>The absolute termination criteria on the function value works if
1431         the user has an accurate idea of the optimum function value.</para>
1432       </listitem>
1433
1434       <listitem>
1435         <para>The tolerance on x is examined depending on the value of the
1436         -tolxmethod.</para>
1437
1438         <variablelist>
1439           <varlistentry>
1440             <term>"disabled"</term>
1441
1442             <listitem>
1443               <para>then the criteria is just ignored.</para>
1444             </listitem>
1445           </varlistentry>
1446
1447           <varlistentry>
1448             <term>"enabled"</term>
1449
1450             <listitem>
1451               <para>if the following condition</para>
1452
1453               <programlisting role="example"> 
1454 norm(currentxopt - previousxopt) &lt; tolxrelative * norm(currentxopt) + tolxabsolute
1455  </programlisting>
1456
1457               <para>is true, then the status is set to "tolx" and terminate is
1458               set to 1.</para>
1459             </listitem>
1460           </varlistentry>
1461         </variablelist>
1462
1463         <para>The relative termination criteria on the function value works
1464         well if x at optimum is different from zero. In that case, the
1465         condition measures the distance between two iterates.</para>
1466
1467         <para>The absolute termination criteria on the function value works if
1468         the user has an accurate idea of the scale of the optimum x. If the
1469         optimum x is near 0, the relative tolerance will not work and the
1470         absolute tolerance is more appropriate.</para>
1471       </listitem>
1472
1473       <listitem>
1474         <para>The absolute tolerance on standard deviation of the function
1475         value is examined depending on the value of the -tolfstdeviationmethod
1476         option.</para>
1477
1478         <variablelist>
1479           <varlistentry>
1480             <term>"disabled"</term>
1481
1482             <listitem>
1483               <para>then the criteria is just ignored.</para>
1484             </listitem>
1485           </varlistentry>
1486
1487           <varlistentry>
1488             <term>"enabled"</term>
1489
1490             <listitem>
1491               <para>if the following condition</para>
1492
1493               <programlisting role="example"> 
1494 st_deviation(fv) &lt; tolfstdeviation
1495  </programlisting>
1496
1497               <para>is true where fv is an array containing the function
1498               values in the simplex, then the status is set to "tolfstdev" and
1499               terminate is set to 1.</para>
1500             </listitem>
1501           </varlistentry>
1502         </variablelist>
1503       </listitem>
1504
1505       <listitem>
1506         <para>The absolute tolerance on simplex size is examined depending on
1507         the value of the -tolsimplexizemethod option.</para>
1508
1509         <variablelist>
1510           <varlistentry>
1511             <term>"disabled"</term>
1512
1513             <listitem>
1514               <para>then the criteria is just ignored.</para>
1515             </listitem>
1516           </varlistentry>
1517
1518           <varlistentry>
1519             <term>"enabled"</term>
1520
1521             <listitem>
1522               <para>if the following condition</para>
1523
1524               <programlisting role="example"> 
1525 ssize &lt; tolsimplexizerelative * simplexsize0 + tolsimplexizeabsolute
1526  </programlisting>
1527
1528               <para>is true where simplexsize0 is the size of the simplex at
1529               iteration 0, then the status is set to "tolsize" and terminate
1530               is set to 1.</para>
1531             </listitem>
1532           </varlistentry>
1533         </variablelist>
1534       </listitem>
1535
1536       <listitem>
1537         <para>The absolute tolerance on simplex size and absolute difference
1538         of function value is examined depending on the value of the
1539         -tolssizedeltafvmethod option.</para>
1540
1541         <variablelist>
1542           <varlistentry>
1543             <term>"disabled"</term>
1544
1545             <listitem>
1546               <para>then the criteria is just ignored.</para>
1547             </listitem>
1548           </varlistentry>
1549
1550           <varlistentry>
1551             <term>"enabled"</term>
1552
1553             <listitem>
1554               <para>if both the following conditions</para>
1555
1556               <programlisting role="example"> 
1557 ssize &lt; tolsimplexizeabsolute 
1558  </programlisting>
1559
1560               <programlisting role="example"> 
1561 shiftfv &lt; toldeltafv
1562  </programlisting>
1563
1564               <para>is true where ssize is the current simplex size and
1565               shiftfv is the absolute value of the difference of function
1566               value between the highest and lowest vertices, then the status
1567               is set to "tolsizedeltafv" and terminate is set to 1.</para>
1568             </listitem>
1569           </varlistentry>
1570         </variablelist>
1571       </listitem>
1572
1573       <listitem>
1574         <para>The stagnation condition based on Kelley sufficient decrease
1575         condition is examined depending on the value of the
1576         -kelleystagnationflag option.</para>
1577
1578         <variablelist>
1579           <varlistentry>
1580             <term>"disabled"</term>
1581
1582             <listitem>
1583               <para>then the criteria is just ignored.</para>
1584             </listitem>
1585           </varlistentry>
1586
1587           <varlistentry>
1588             <term>"enabled"</term>
1589
1590             <listitem>
1591               <para>if the following condition</para>
1592
1593               <programlisting role="example"> 
1594 newfvmean &lt;= oldfvmean - alpha * sg' * sg
1595  </programlisting>
1596
1597               <para>is true where newfvmean (resp. oldfvmean) is the function
1598               value average in the current iteration (resp. in the previous
1599               iteration), then the status is set to "kelleystagnation" and
1600               terminate is set to 1. Here, alpha is a non-dimensional
1601               coefficient and sg is the simplex gradient.</para>
1602             </listitem>
1603           </varlistentry>
1604         </variablelist>
1605       </listitem>
1606     </itemizedlist>
1607   </refsection>
1608
1609   <refsection>
1610     <title>Kelley's stagnation detection</title>
1611
1612     <para>The stagnation detection criteria suggested by Kelley is based on a
1613     sufficient decrease condition, which requires a parameter alpha &gt; 0 to
1614     be defined. The -kelleynormalizationflag option allows to configure the
1615     method to use to compute this alpha parameter : two methods are available,
1616     where each method corresponds to a different paper by Kelley :</para>
1617
1618     <variablelist>
1619       <varlistentry>
1620         <term>constant</term>
1621
1622         <listitem>
1623           <para>In "Detection and Remediation of Stagnation in the
1624           Nelder--Mead Algorithm Using a Sufficient Decrease Condition",
1625           Kelley uses a constant alpha, with the suggested value 1.e-4, which
1626           is is typical choice for line search method.</para>
1627         </listitem>
1628       </varlistentry>
1629
1630       <varlistentry>
1631         <term>normalized</term>
1632
1633         <listitem>
1634           <para>in "Iterative Methods for Optimization", Kelley uses a
1635           normalized alpha, computed from the following formula</para>
1636
1637           <programlisting role="example"> 
1638 alpha = alpha0 * sigma0 / nsg
1639  </programlisting>
1640
1641           <para>where sigma0 is the size of the initial simplex and nsg is the
1642           norm of the simplex gradient for the initial guess point.</para>
1643         </listitem>
1644       </varlistentry>
1645     </variablelist>
1646   </refsection>
1647
1648   <refsection>
1649     <title>O'Neil factorial optimality test</title>
1650
1651     <para>In "Algorithm AS47 - Function minimization using a simplex
1652     procedure", R. O'Neil presents a fortran 77 implementation of the simplex
1653     method. A factorial test is used to check if the computed optimum point is
1654     a local minimum. If the -restartdetection option is set to "oneill", that
1655     factorial test is used to see if a restart should be performed.</para>
1656   </refsection>
1657
1658   <refsection>
1659     <title>Example #1</title>
1660
1661     <para>In the following example, we solve the Rosenbrock test case. We
1662     begin by defining the Rosenbrock function, which takes 2 input arguments
1663     and returns the objective. The classical starting point [-1.2 1.0] is
1664     used. The neldermead_new creates a new neldermead object. Then we use the
1665     neldermead_configure method to configure the parameters of the problem.
1666     The initial simplex is computed from the axes and the single length 1.0
1667     (this is the default, but is explicitely written here as an example). The
1668     variable simplex algorithm by Nelder and Mead is used, which corresponds
1669     to the -method "variable" option. The neldermead_search function performs
1670     the search for the minimum. Once the minimum is found, the
1671     neldermead_contour allows to compute the data required by the contour
1672     function. This is possible since our problem involves only 2 parameters.
1673     This function uses the cost function previously configured to compute the
1674     required data. The contour plot is directly drawn from the data provided
1675     by neldermead_contour. Then we plot the initial guess on the contour plot
1676     as a blue dot. The neldermead_get function is used to get the optimum,
1677     which is associated with the -xopt option. The optimum is plot on the
1678     contour plot as a red dot.</para>
1679
1680     <programlisting role="example">
1681 mprintf("Defining Rosenbrock function...\n");
1682 function y = rosenbrock (x)
1683   y = 100*(x(2)-x(1)^2)^2+(1-x(1))^2;
1684 endfunction
1685 x0 = [-1.2 1.0]';
1686 mprintf("x0=%s\n",strcat(string(x0)," "));
1687 mprintf("Creating object...\n");
1688 nm = neldermead_new ();
1689 mprintf("Configuring object...\n");
1690 nm = neldermead_configure(nm,"-numberofvariables",2);
1691 nm = neldermead_configure(nm,"-function",rosenbrock);
1692 nm = neldermead_configure(nm,"-x0",x0);
1693 nm = neldermead_configure(nm,"-maxiter",200);
1694 nm = neldermead_configure(nm,"-maxfunevals",300);
1695 nm = neldermead_configure(nm,"-tolfunrelative",10*%eps);
1696 nm = neldermead_configure(nm,"-tolxrelative",10*%eps);
1697 nm = neldermead_configure(nm,"-simplex0method","axes");
1698 nm = neldermead_configure(nm,"-simplex0length",1.0);
1699 nm = neldermead_configure(nm,"-method","variable");
1700 nm = neldermead_configure(nm,"-verbose",0);
1701 nm = neldermead_configure(nm,"-verbosetermination",0);
1702 mprintf("Searching for minimum...\n");
1703 nm = neldermead_search(nm);
1704 mprintf("Plot contour...\n");
1705 [nm , xdata , ydata , zdata ] = neldermead_contour ( nm , xmin = -2.0 , xmax = 2.0 , ymin = -2.0 , ymax = 2.0 , nx = 100 , ny = 100 );
1706 wnum = 100001;
1707 my_handle             = scf(wnum);
1708 contour ( xdata , ydata , zdata , [1 10 100 500 1000 2000] )
1709 // Plot starting point
1710 mprintf("x0 : blue dot\n");
1711 plot(x0(1),x0(2));
1712 my_handle.children.children(1).children.mark_mode="on";
1713 my_handle.children.children(1).children.mark_size = 5;
1714 my_handle.children.children(1).children.mark_foreground = 2;
1715 mprintf("xopt : red dot\n");
1716 xopt = neldermead_get(nm,"-xopt");
1717 plot(xopt(1),xopt(2));
1718 my_handle.children.children(1).children.mark_mode="on";
1719 my_handle.children.children(1).children.mark_size = 5;
1720 my_handle.children.children(1).children.mark_foreground = 5;
1721
1722 nm = neldermead_destroy(nm);
1723 </programlisting>
1724
1725     <para>The -verbose option allows to get detailed informations about the
1726     current optimization process. The following is a sample output for an
1727     optimization based on the Nelder and Mead variable-shape simplex
1728     algorithm. Only the output corresponding to the iteration #156 is
1729     displayed. In order to display specific outputs (or to create specific
1730     output files and graphics), the -outputcommand option should be
1731     used.</para>
1732
1733     <programlisting role="example">
1734 =================================================================
1735 Iteration #156 (total = 156)
1736 Function Eval #297
1737 Xopt : 1 1
1738 Fopt : 6.871176e-027
1739 DeltaFv : 2.880999e-026
1740 Center : 1 1
1741 Size : 2.548515e-013
1742 Vertex #1/3 : fv=0.000000, x=1.000000 1.000000
1743 Vertex #2/3 : fv=0.000000, x=1.000000 1.000000
1744 Vertex #3/3 : fv=0.000000, x=1.000000 1.000000
1745 nmplot_outputcmd (1)
1746 Reflect
1747 xbar=1 1
1748 Function Evaluation #298 is [1.155D-25] at [1 1]
1749 xr=[1 1], f(xr)=0.000000
1750 Contract - inside
1751 Function Evaluation #299 is [6.023D-27] at [1 1]
1752 xc=1 1, f(xc)=0.000000
1753   &gt; Perform Inside Contraction
1754 Sort
1755 </programlisting>
1756   </refsection>
1757
1758   <refsection>
1759     <title>TODO</title>
1760
1761     <variablelist>
1762       <varlistentry>
1763         <term>Box-Guin algorithm</term>
1764
1765         <listitem>
1766           <para>add the Box-Guin algoritm as a 4th method</para>
1767
1768           <para>This algorithm solves an constrained optimization problem with
1769           a variable sized simplex made of an arbitrary k number of vertices.
1770           This is an update of Box's algorithm.</para>
1771         </listitem>
1772       </varlistentry>
1773
1774       <varlistentry>
1775         <term>add the optimization of the Rosenbrock test case, with the
1776         interactive plot thanks to the -outputcommand option</term>
1777       </varlistentry>
1778
1779       <varlistentry>
1780         <term>add a sample output with the verbose option.</term>
1781       </varlistentry>
1782     </variablelist>
1783   </refsection>
1784
1785   <refsection>
1786     <title>Bibliography</title>
1787
1788     <para>"Sequential Application of Simplex Designs in Optimisation and
1789     Evolutionary Operation", Spendley, W. and Hext, G. R. and Himsworth, F.
1790     R., American Statistical Association and American Society for Quality,
1791     1962</para>
1792
1793     <para>"A Simplex Method for Function Minimization", Nelder, J. A. and
1794     Mead, R., The Computer Journal, 1965</para>
1795
1796     <para>"A New Method of Constrained Optimization and a Comparison With
1797     Other Methods", M. J. Box, The Computer Journal 1965 8(1):42-52, 1965 by
1798     British Computer Society</para>
1799
1800     <para>"Discussion and correspondence: modification of the complex method
1801     of constrained optimization", J. A. Guin, The Computer Journal,
1802     1968</para>
1803
1804     <para>"Detection and Remediation of Stagnation in the Nelder--Mead
1805     Algorithm Using a Sufficient Decrease Condition", Kelley C. T., SIAM J. on
1806     Optimization, 1999</para>
1807
1808     <para>"Iterative Methods for Optimization", C. T. Kelley, SIAM Frontiers
1809     in Applied Mathematics, 1999</para>
1810
1811     <para>"Algorithm AS47 - Function minimization using a simplex procedure",
1812     O'Neill, R., Applied Statistics, 1971</para>
1813   </refsection>
1814
1815   <refsection>
1816     <title>Authors</title>
1817
1818     <para>Michael Baudin, 2008-2009</para>
1819   </refsection>
1820
1821   <refsection>
1822     <title>See Also</title>
1823
1824     <simplelist type="inline">
1825       <member><link linkend="optimbase">optimbase</link></member>
1826
1827       <member><link linkend="optimsimplex">optimsimplex</link></member>
1828
1829       <member><link linkend="optimsimplex">nmplot</link></member>
1830     </simplelist>
1831   </refsection>
1832 </refentry>