Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / neldermead / nmplot.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="nmplot" 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>nmplot</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 = nmplot_new ()
28 this = nmplot_destroy (this)
29 this = nmplot_configure (this,key,value)
30 value = nmplot_cget (this,key)
31 this = nmplot_display ( this )
32 value = nmplot_get ( this , key )
33 this = nmplot_search ( this )
34 this = nmplot_restart ( this )
35 [ this , xdata , ydata , zdata ] = nmplot_contour ( this , xmin , xmax , ymin , ymax , nx , ny )
36 this = nmplot_historyplot ( this , datafile  , mytitle , myxlabel , myylabel )
37 this = nmplot_simplexhistory ( this , colorforeground , markforeground , markstyle )
38 </synopsis>
39   </refsynopsisdiv>
40
41   <refsection>
42     <title>Description</title>
43
44     <para>This class provides several direct search optimization algorithms
45     based on the simplex method.</para>
46
47     <para>The goal of this class is to provide a neldermead component with
48     plotting features. It enables to make fast plots of the algorithm progress
49     through the iterations.</para>
50
51     <para>It is a specialized neldermead class, with a specific output
52     command. This output function allows to store the history of several datas
53     through the iterations of the algorithm. These datas are :</para>
54
55     <itemizedlist>
56       <listitem>
57         <para>the history of the coordinates of the simplex ,</para>
58       </listitem>
59
60       <listitem>
61         <para>the history of the function value (averaged on the
62         vertices),</para>
63       </listitem>
64
65       <listitem>
66         <para>the history of the minimum function value in the simplex,</para>
67       </listitem>
68
69       <listitem>
70         <para>the history of the size of the simplex (as computed with the
71         sigma+ method).</para>
72       </listitem>
73     </itemizedlist>
74
75     <para>These data are stored into several data files during the
76     optimization process. Several methods allows to plot the data stored into
77     these data files.</para>
78   </refsection>
79
80   <refsection>
81     <title>Design</title>
82
83     <para>The nmplot component is built on top of the <link
84     linkend="optimbase">neldermead</link> component. The -outputcommand option
85     (of the neldermead class) is not available since the nmplot class uses its
86     own output function. Additionnal options -simplexfn, -fbarfn, -foptfn and
87     -sigmafn are provided, which allows to configure the file names where the
88     data is stored.</para>
89
90     <para>The nmplot class can be considered as a sample test case of the
91     -outputcommand option of the neldermead class. It gives an example of the
92     situation where the user wants to get specialized outputs out of the
93     neldermead class.</para>
94   </refsection>
95
96   <refsection>
97     <title>Functions</title>
98
99     <para>The following functions are available.</para>
100
101     <variablelist>
102       <varlistentry>
103         <term>newobj = nmplot_new ()</term>
104
105         <listitem>
106           <para>Creates a new nmplot object.</para>
107
108           <variablelist>
109             <varlistentry>
110               <term>newobj</term>
111
112               <listitem>
113                 <para>The new object.</para>
114               </listitem>
115             </varlistentry>
116           </variablelist>
117         </listitem>
118       </varlistentry>
119
120       <varlistentry>
121         <term>this = nmplot_destroy (this)</term>
122
123         <listitem>
124           <para>Destroy the given object.</para>
125
126           <variablelist>
127             <varlistentry>
128               <term>this</term>
129
130               <listitem>
131                 <para>The current object.</para>
132               </listitem>
133             </varlistentry>
134           </variablelist>
135         </listitem>
136       </varlistentry>
137
138       <varlistentry>
139         <term>this = nmplot_configure (this,key,value)</term>
140
141         <listitem>
142           <para>Configure the current object with the given value for the
143           given key.</para>
144
145           <variablelist>
146             <varlistentry>
147               <term>this</term>
148
149               <listitem>
150                 <para>The current object.</para>
151               </listitem>
152             </varlistentry>
153
154             <varlistentry>
155               <term>key</term>
156
157               <listitem>
158                 <para>the key to configure. The following keys are
159                 available.</para>
160
161                 <variablelist>
162                   <varlistentry>
163                     <term>-verbose</term>
164
165                     <listitem>
166                       <para>set to 1 to enable verbose logging. (default is
167                       0)</para>
168                     </listitem>
169                   </varlistentry>
170
171                   <varlistentry>
172                     <term>-verbosetermination</term>
173
174                     <listitem>
175                       <para>set to 1 to enable verbose termination logging.
176                       (default is 0)</para>
177                     </listitem>
178                   </varlistentry>
179
180                   <varlistentry>
181                     <term>-x0</term>
182
183                     <listitem>
184                       <para>the initial guess, as a n x 1 column vector, where
185                       n is the number of variables.</para>
186                     </listitem>
187                   </varlistentry>
188
189                   <varlistentry>
190                     <term>-maxfunevals</term>
191
192                     <listitem>
193                       <para>the maximum number of function evalutations
194                       (default is 100). If this criteria is triggered, the
195                       status of the optimization is set to
196                       "maxfuneval".</para>
197                     </listitem>
198                   </varlistentry>
199
200                   <varlistentry>
201                     <term>-maxiter</term>
202
203                     <listitem>
204                       <para>the maximum number of iterations (default is 100).
205                       If this criteria is triggered, the status of the
206                       optimization is set to "maxiter".</para>
207                     </listitem>
208                   </varlistentry>
209
210                   <varlistentry>
211                     <term>-tolfunabsolute</term>
212
213                     <listitem>
214                       <para>the absolute tolerance for the function value
215                       (default is 0.0).</para>
216                     </listitem>
217                   </varlistentry>
218
219                   <varlistentry>
220                     <term>-tolfunrelative</term>
221
222                     <listitem>
223                       <para>the relative tolerance for the function value
224                       (default is %eps).</para>
225                     </listitem>
226                   </varlistentry>
227
228                   <varlistentry>
229                     <term>-tolfunmethod</term>
230
231                     <listitem>
232                       <para>the method used for the tolerance on function
233                       value in the termination criteria.</para>
234
235                       <para>The following values are available :
236                       "absolute+relative", "relative", "absolute", "disabled"
237                       (default is "disabled"). If this criteria is triggered,
238                       the status of the optimization is set to "tolf".</para>
239                     </listitem>
240                   </varlistentry>
241
242                   <varlistentry>
243                     <term>-tolxabsolute</term>
244
245                     <listitem>
246                       <para>the absolute tolerance on x (default is
247                       0.0).</para>
248                     </listitem>
249                   </varlistentry>
250
251                   <varlistentry>
252                     <term>-tolxrelative</term>
253
254                     <listitem>
255                       <para>the relative tolerance on x (default is
256                       %eps).</para>
257                     </listitem>
258                   </varlistentry>
259
260                   <varlistentry>
261                     <term>-tolxmethod</term>
262
263                     <listitem>
264                       <para>the method used for the tolerance on x in the
265                       termination criteria.</para>
266
267                       <para>The following values are available : "relative",
268                       "absolute", "disabled" (default is "relative"). If this
269                       criteria is triggered, the status of the optimization is
270                       set to "tolx".</para>
271                     </listitem>
272                   </varlistentry>
273
274                   <varlistentry>
275                     <term>-function</term>
276
277                     <listitem>
278                       <para>the objective function, which computes the value
279                       of the cost and the non linear constraints, if
280                       any.</para>
281
282                       <para>See below for the details of the communication
283                       between the optimization system and the cost
284                       function.</para>
285                     </listitem>
286                   </varlistentry>
287
288                   <varlistentry>
289                     <term>-costfargument</term>
290
291                     <listitem>
292                       <para>an additionnal argument, passed to the cost
293                       function.</para>
294                     </listitem>
295                   </varlistentry>
296
297                   <varlistentry>
298                     <term>-outputcommand</term>
299
300                     <listitem>
301                       <para>a command which is called back for output.</para>
302
303                       <para>See below for the details of the communication
304                       between the optimization system and the output command
305                       function.</para>
306                     </listitem>
307                   </varlistentry>
308
309                   <varlistentry>
310                     <term>-outputcommandarg</term>
311
312                     <listitem>
313                       <para>an additionnal argument, passed to the output
314                       command.</para>
315                     </listitem>
316                   </varlistentry>
317
318                   <varlistentry>
319                     <term>-numberofvariables</term>
320
321                     <listitem>
322                       <para>the number of variables to optimize (default is
323                       0).</para>
324                     </listitem>
325                   </varlistentry>
326
327                   <varlistentry>
328                     <term>-storehistory</term>
329
330                     <listitem>
331                       <para>set to 1 to enable the history storing (default is
332                       0).</para>
333                     </listitem>
334                   </varlistentry>
335
336                   <varlistentry>
337                     <term>-boundsmin</term>
338
339                     <listitem>
340                       <para>the minimum bounds for the parameters, as an array
341                       of values (default is empty, i.e. there are no
342                       bounds).</para>
343                     </listitem>
344                   </varlistentry>
345
346                   <varlistentry>
347                     <term>-boundsmax</term>
348
349                     <listitem>
350                       <para>the maximum bounds for the parameters, as an array
351                       of values (default is empty, i.e. there are no
352                       bounds).</para>
353                     </listitem>
354                   </varlistentry>
355
356                   <varlistentry>
357                     <term>-nbineqconst</term>
358
359                     <listitem>
360                       <para>the number of inequality constraints (default is
361                       0)</para>
362                     </listitem>
363                   </varlistentry>
364
365                   <varlistentry>
366                     <term>-method</term>
367
368                     <listitem>
369                       <para>the name of the algorithm to use. The following
370                       methods are available :</para>
371
372                       <variablelist>
373                         <varlistentry>
374                           <term>"fixed"</term>
375
376                           <listitem>
377                             <para>the Spendley et al. fixed simplex shape
378                             algorithm. This algorithm is for unconstrained
379                             problems (i.e. bounds and non linear constraints are
380                             not taken into account)</para>
381                           </listitem>
382                         </varlistentry>
383
384                         <varlistentry>
385                           <term>"variable"</term>
386
387                           <listitem>
388                             <para>the Nelder-Mead variable simplex shape
389                             algorithm. This algorithm is for unconstrained
390                             problems (i.e. bounds and non linear constraints are
391                             not taken into account)</para>
392                           </listitem>
393                         </varlistentry>
394
395                         <varlistentry>
396                           <term>"box"</term>
397
398                           <listitem>
399                             <para>the Box complex algorithm. This algorithm
400                             takes into account bounds and nonlinear inequality
401                             constraints.</para>
402                           </listitem>
403                         </varlistentry>
404                       </variablelist>
405                     </listitem>
406                   </varlistentry>
407
408                   <varlistentry>
409                     <term>-simplex0method</term>
410
411                     <listitem>
412                       <para>the method to use to compute the initial simplex.
413                       The first vertex in the simplex is always the initial
414                       guess associated with the -x0 option. The following
415                       methods are available :</para>
416
417                       <variablelist>
418                         <varlistentry>
419                           <term>"given"</term>
420
421                           <listitem>
422                             <para>the coordinates associated with the -coords0
423                             option are used to compute the initial simplex, with
424                             arbitrary number of vertices.</para>
425
426                             <para>This allow the user to setup the initial
427                             simplex by a specific method which is not provided
428                             by the current component (for example with a simplex
429                             computed from a design of experiments). This allows
430                             also to configure the initial simplex so that a
431                             specific behaviour of the algorithm an be reproduced
432                             (for example the Mac Kinnon test case).</para>
433
434                             <para>The given matrix is expected to have n rows
435                             and k columns, where n is the dimension of the
436                             problem and k is the number of vertices.</para>
437                           </listitem>
438                         </varlistentry>
439
440                         <varlistentry>
441                           <term>"axes"</term>
442
443                           <listitem>
444                             <para>the simplex is computed from the coordinate
445                             axes and the length associated with the
446                             -simplex0length option.</para>
447                           </listitem>
448                         </varlistentry>
449
450                         <varlistentry>
451                           <term>"spendley"</term>
452
453                           <listitem>
454                             <para>the simplex is computed so that it is regular
455                             with the length associated with the -simplex0length
456                             option (i.e. all the edges have the same
457                             length).</para>
458                           </listitem>
459                         </varlistentry>
460
461                         <varlistentry>
462                           <term>"pfeffer"</term>
463
464                           <listitem>
465                             <para>the simplex is computed from an heuristic, in
466                             the neighborhood of the initial guess. This initial
467                             simplex depends on the -simplex0deltausual and
468                             -simplex0deltazero.</para>
469                           </listitem>
470                         </varlistentry>
471
472                         <varlistentry>
473                           <term>"randbounds"</term>
474
475                           <listitem>
476                             <para>the simplex is computed from the bounds and a
477                             random number. This option is available only if
478                             bounds are available : if bounds are not available,
479                             an error is generated. This method is usually
480                             associated with Box's algorithm. The number of
481                             vertices in the simplex is taken from the
482                             -boxnbpoints option.</para>
483                           </listitem>
484                         </varlistentry>
485                       </variablelist>
486                     </listitem>
487                   </varlistentry>
488
489                   <varlistentry>
490                     <term>-coords0</term>
491
492                     <listitem>
493                       <para>the coordinates of the vertices of the initial
494                       simplex. If the -simplex0method option is set to
495                       "given", these coordinates are used to compute the
496                       initial simplex. This matrix is expected to have shape
497                       nbve x n where nbve is the number of vertices and n is
498                       the number of variables.</para>
499                     </listitem>
500                   </varlistentry>
501
502                   <varlistentry>
503                     <term>-simplex0length</term>
504
505                     <listitem>
506                       <para>the length to use when the initial simplex is
507                       computed with the "axes" or "spendley" methods. If the
508                       initial simplex is computed from "spendley" method, the
509                       length is expected to be a scalar value. If the initial
510                       simplex is computed from "axes" method, it may be either
511                       a scalar value or a vector of values, with rank n, where
512                       n is the number of variables.</para>
513                     </listitem>
514                   </varlistentry>
515
516                   <varlistentry>
517                     <term>-simplex0deltausual</term>
518
519                     <listitem>
520                       <para>the relative delta for non-zero parameters in
521                       "pfeffer" method. The default value is 0.05.</para>
522                     </listitem>
523                   </varlistentry>
524
525                   <varlistentry>
526                     <term>-simplex0deltazero</term>
527
528                     <listitem>
529                       <para>the absolute delta for non-zero parameters in
530                       "pfeffer" method. The default value is 0.0075.</para>
531                     </listitem>
532                   </varlistentry>
533
534                   <varlistentry>
535                     <term>-rho</term>
536
537                     <listitem>
538                       <para>the reflection coefficient. This parameter is used
539                       when the -method option is set to "fixed" or "variable".
540                       The default value is 1.0.</para>
541                     </listitem>
542                   </varlistentry>
543
544                   <varlistentry>
545                     <term>-chi</term>
546
547                     <listitem>
548                       <para>the expansion coefficient. This parameter is used
549                       when the -method option is set to "variable". The
550                       default value is 2.0.</para>
551                     </listitem>
552                   </varlistentry>
553
554                   <varlistentry>
555                     <term>-gamma</term>
556
557                     <listitem>
558                       <para>the contraction coefficient. This parameter is
559                       used when the -method option is set to "variable". The
560                       default value is 0.5.</para>
561                     </listitem>
562                   </varlistentry>
563
564                   <varlistentry>
565                     <term>-sigma</term>
566
567                     <listitem>
568                       <para>the shrinkage coefficient. This parameter is used
569                       when the -method option is set to "fixed" or "variable".
570                       The default value is 0.5.</para>
571                     </listitem>
572                   </varlistentry>
573
574                   <varlistentry>
575                     <term>-tolfstdeviationmethod</term>
576
577                     <listitem>
578                       <para>set to "enabled" to enable the termination
579                       criteria based on the standard deviation of the function
580                       values in the simplex. The default value is "disabled".
581                       If this criteria is triggered, the status of the
582                       optimization is set to "tolfstdev".</para>
583
584                       <para>This criteria is suggested by Nelder and
585                       Mead.</para>
586                     </listitem>
587                   </varlistentry>
588
589                   <varlistentry>
590                     <term>-tolfstdeviation</term>
591
592                     <listitem>
593                       <para>the absolute tolerance on standard deviation. The
594                       default value is 0.0.</para>
595                     </listitem>
596                   </varlistentry>
597
598                   <varlistentry>
599                     <term>-tolsimplexizemethod</term>
600
601                     <listitem>
602                       <para>set to "disabled" to disable the tolerance on the
603                       simplex size. The default value is "enabled". If this
604                       criteria is triggered, the status of the optimization is
605                       set to "tolsize".</para>
606
607                       <para>When this criteria is enabled, the values of the
608                       options -tolsimplexizeabsolute and
609                       -tolsimplexizerelative are used in the termination
610                       criteria. The method to compute the size is the
611                       "sigmaplus" method.</para>
612                     </listitem>
613                   </varlistentry>
614
615                   <varlistentry>
616                     <term>-tolsimplexizeabsolute</term>
617
618                     <listitem>
619                       <para>the absolute tolerance on the simplex size. The
620                       default value is 0.0.</para>
621                     </listitem>
622                   </varlistentry>
623
624                   <varlistentry>
625                     <term>-tolsimplexizerelative</term>
626
627                     <listitem>
628                       <para>the relative tolerance on the simplex size. The
629                       default value is %eps.</para>
630                     </listitem>
631                   </varlistentry>
632
633                   <varlistentry>
634                     <term>-tolssizedeltafvmethod</term>
635
636                     <listitem>
637                       <para>set to "enabled" to enable the termination
638                       criteria based on the size of the simplex and the
639                       difference of function value in the simplex. The default
640                       value is "disabled". If this criteria is triggered, the
641                       status of the optimization is set to
642                       "tolsizedeltafv".</para>
643
644                       <para>This termination criteria uses the values of the
645                       options -tolsimplexizeabsolute and -toldeltafv. This
646                       criteria is identical to Matlab's fminsearch.</para>
647                     </listitem>
648                   </varlistentry>
649
650                   <varlistentry>
651                     <term>-toldeltafv</term>
652
653                     <listitem>
654                       <para>the absolute tolerance on the difference between
655                       the highest and the lowest function values.</para>
656                     </listitem>
657                   </varlistentry>
658
659                   <varlistentry>
660                     <term>-kelleystagnationflag</term>
661
662                     <listitem>
663                       <para>set to 1 to enable the termination criteria using
664                       Kelley's stagnation detection, based on sufficient
665                       decrease condition. The default value is 0. If this
666                       criteria is triggered, the status of the optimization is
667                       set to "kelleystagnation".</para>
668                     </listitem>
669                   </varlistentry>
670
671                   <varlistentry>
672                     <term>-kelleynormalizationflag</term>
673
674                     <listitem>
675                       <para>set to 0 to disable the normalization of the alpha
676                       coefficient in Kelley's stagnation detection, i.e. use
677                       the value of the option -kelleystagnationalpha0 as is.
678                       Default value is 1, i.e. the simplex gradient of the
679                       initial simplex is taken into account in the stagnation
680                       detection.</para>
681                     </listitem>
682                   </varlistentry>
683
684                   <varlistentry>
685                     <term>-kelleystagnationalpha0</term>
686
687                     <listitem>
688                       <para>the parameter used in Kelley's stagnation
689                       detection. The default value is 1.e-4.</para>
690                     </listitem>
691                   </varlistentry>
692
693                   <varlistentry>
694                     <term>-restartflag</term>
695
696                     <listitem>
697                       <para>set to 1 to enable the automatic restart of the
698                       algorithm. Default value is 0.</para>
699                     </listitem>
700                   </varlistentry>
701
702                   <varlistentry>
703                     <term>-restartdetection</term>
704
705                     <listitem>
706                       <para>the method to detect if the automatic restart must
707                       be performed. The following methods are available
708                       :</para>
709
710                       <variablelist>
711                         <varlistentry>
712                           <term>"oneill"</term>
713
714                           <listitem>
715                             <para>the factorial local optimality test by O'Neill
716                             is used. If the test finds a local point which is
717                             better than the computed optimum, a restart is
718                             performed.</para>
719                           </listitem>
720                         </varlistentry>
721
722                         <varlistentry>
723                           <term>"kelley"</term>
724
725                           <listitem>
726                             <para>the sufficient decrease condition by O'Neill
727                             is used. If the test finds that the status of the
728                             optimization is "kelleystagnation", a restart is
729                             performed. This status may be generated if the
730                             -kelleystagnationflag option is set to 1.</para>
731                           </listitem>
732                         </varlistentry>
733                       </variablelist>
734
735                       <para>The default method is "oneill".</para>
736                     </listitem>
737                   </varlistentry>
738
739                   <varlistentry>
740                     <term>-restartmax</term>
741
742                     <listitem>
743                       <para>the maximum number of restarts, when automatic
744                       restart is enabled via the -restartflag option. Default
745                       value is 3.</para>
746                     </listitem>
747                   </varlistentry>
748
749                   <varlistentry>
750                     <term>-restarteps</term>
751
752                     <listitem>
753                       <para>the absolute epsilon value used to check for
754                       optimality in the factorial O'Neill restart detection.
755                       The default value is %eps.</para>
756                     </listitem>
757                   </varlistentry>
758
759                   <varlistentry>
760                     <term>-restartstep</term>
761
762                     <listitem>
763                       <para>the absolute step length used to check for
764                       optimality in the factorial O'Neill restart detection.
765                       The default value is 1.0.</para>
766                     </listitem>
767                   </varlistentry>
768
769                   <varlistentry>
770                     <term>-restartsimplexmethod</term>
771
772                     <listitem>
773                       <para>the method to compute the initial simplex after a
774                       restart. The following methods are available.</para>
775
776                       <variablelist>
777                         <varlistentry>
778                           <term>"given"</term>
779
780                           <listitem>
781                             <para>the coordinates associated with the -coords0
782                             option are used to compute the initial simplex, with
783                             arbitrary number of vertices.</para>
784
785                             <para>This allow the user to setup the initial
786                             simplex by a specific method which is not provided
787                             by the current component (for example with a simplex
788                             computed from a design of experiments). This allows
789                             also to configure the initial simplex so that a
790                             specific behaviour of the algorithm an be reproduced
791                             (for example the Mac Kinnon test case).</para>
792
793                             <para>The given matrix is expected to have n rows
794                             and k columns, where n is the dimension of the
795                             problem and k is the number of vertices.</para>
796                           </listitem>
797                         </varlistentry>
798
799                         <varlistentry>
800                           <term>"axes"</term>
801
802                           <listitem>
803                             <para>the simplex is computed from the coordinate
804                             axes and the length associated with the
805                             -simplex0length option.</para>
806                           </listitem>
807                         </varlistentry>
808
809                         <varlistentry>
810                           <term>"spendley"</term>
811
812                           <listitem>
813                             <para>the simplex is computed so that it is regular
814                             with the length associated with the -simplex0length
815                             option (i.e. all the edges have the same
816                             length).</para>
817                           </listitem>
818                         </varlistentry>
819
820                         <varlistentry>
821                           <term>"pfeffer"</term>
822
823                           <listitem>
824                             <para>the simplex is computed from an heuristic, in
825                             the neighborhood of the initial guess. This initial
826                             simplex depends on the -simplex0deltausual and
827                             -simplex0deltazero.</para>
828                           </listitem>
829                         </varlistentry>
830
831                         <varlistentry>
832                           <term>"randbounds"</term>
833
834                           <listitem>
835                             <para>the simplex is computed from the bounds and a
836                             random number. This option is available only if
837                             bounds are available : if bounds are not available,
838                             an error is generated. This method is usually
839                             associated with Box's algorithm. The number of
840                             vertices in the simplex is taken from the
841                             -boxnbpoints option.</para>
842                           </listitem>
843                         </varlistentry>
844
845                         <varlistentry>
846                           <term>"oriented"</term>
847
848                           <listitem>
849                             <para>the simplex is computed so that it is
850                             oriented, as suggested by C.T. Kelley.</para>
851                           </listitem>
852                         </varlistentry>
853                       </variablelist>
854
855                       <para>The default method is "oriented".</para>
856                     </listitem>
857                   </varlistentry>
858
859                   <varlistentry>
860                     <term>-boxnbpoints</term>
861
862                     <listitem>
863                       <para>the number of points in the initial simplex, when
864                       the -restartsimplexmethod option is set to "randbounds".
865                       The default value is so that the number of points is
866                       twice the number of variables of the problem.</para>
867                     </listitem>
868                   </varlistentry>
869
870                   <varlistentry>
871                     <term>-nbineqloops</term>
872
873                     <listitem>
874                       <para>the number of loops to perform in Box and Box-Guin
875                       algorithms to scale the trial point for function
876                       improvement or into the constraints. Default value is
877                       10.</para>
878                     </listitem>
879                   </varlistentry>
880
881                   <varlistentry>
882                     <term>-ineqscaling</term>
883
884                     <listitem>
885                       <para>the scaling coefficient used to scale the trial
886                       point for function improvement or into the constraints.
887                       Default value is 0.5</para>
888                     </listitem>
889                   </varlistentry>
890
891                   <varlistentry>
892                     <term>-simplexfn</term>
893
894                     <listitem>
895                       <para>the name of the file containing the history of the
896                       simplex. Default value is the empty string.</para>
897                     </listitem>
898                   </varlistentry>
899
900                   <varlistentry>
901                     <term>-fbarfn</term>
902
903                     <listitem>
904                       <para>the name of the file containing the history of the
905                       function value, averaged on the vertices of the simplex.
906                       Default value is the empty string.</para>
907                     </listitem>
908                   </varlistentry>
909
910                   <varlistentry>
911                     <term>-foptfn</term>
912
913                     <listitem>
914                       <para>the name of the file containing the history of the
915                       minimum function value in the simplex. Default value is
916                       the empty string.</para>
917                     </listitem>
918                   </varlistentry>
919
920                   <varlistentry>
921                     <term>-sigmafn</term>
922
923                     <listitem>
924                       <para>the name of the file containing the history of the
925                       size of the simplex. Default value is the empty
926                       string.</para>
927                     </listitem>
928                   </varlistentry>
929                 </variablelist>
930               </listitem>
931             </varlistentry>
932
933             <varlistentry>
934               <term>value</term>
935
936               <listitem>
937                 <para>the value.</para>
938               </listitem>
939             </varlistentry>
940           </variablelist>
941         </listitem>
942       </varlistentry>
943
944       <varlistentry>
945         <term>value = nmplot_cget (this,key)</term>
946
947         <listitem>
948           <para>Get the value for the given key. If the key is unknown,
949           generates an error.</para>
950
951           <variablelist>
952             <varlistentry>
953               <term>this</term>
954
955               <listitem>
956                 <para>The current object.</para>
957               </listitem>
958             </varlistentry>
959
960             <varlistentry>
961               <term>key</term>
962
963               <listitem>
964                 <para>the name of the key to quiery. The list of available
965                 keys is the same as for the nmplot_configure function.</para>
966               </listitem>
967             </varlistentry>
968           </variablelist>
969         </listitem>
970       </varlistentry>
971
972       <varlistentry>
973         <term>value = nmplot_get ( this , key )</term>
974
975         <listitem>
976           <para>Get the value for the given key. If the key is unknown,
977           generates an error.</para>
978
979           <variablelist>
980             <varlistentry>
981               <term>this</term>
982
983               <listitem>
984                 <para>The current object.</para>
985               </listitem>
986             </varlistentry>
987
988             <varlistentry>
989               <term>key</term>
990
991               <listitem>
992                 <para>the key to get.</para>
993
994                 <para>The following keys are available :</para>
995
996                 <variablelist>
997                   <varlistentry>
998                     <term>-funevals</term>
999
1000                     <listitem>
1001                       <para>the number of function evaluations</para>
1002                     </listitem>
1003                   </varlistentry>
1004
1005                   <varlistentry>
1006                     <term>-iterations</term>
1007
1008                     <listitem>
1009                       <para>the number of iterations</para>
1010                     </listitem>
1011                   </varlistentry>
1012
1013                   <varlistentry>
1014                     <term>-xopt</term>
1015
1016                     <listitem>
1017                       <para>the x optimum, as a n x 1 column vector, where n
1018                       is the number of variables.</para>
1019                     </listitem>
1020                   </varlistentry>
1021
1022                   <varlistentry>
1023                     <term>-fopt</term>
1024
1025                     <listitem>
1026                       <para>the optimum cost function value</para>
1027                     </listitem>
1028                   </varlistentry>
1029
1030                   <varlistentry>
1031                     <term>-historyxopt</term>
1032
1033                     <listitem>
1034                       <para>an array, with nbiter values, containing the
1035                       history of x during the iterations.</para>
1036
1037                       <para>This array is available after optimization if the
1038                       history storing was enabled with the -storehistory
1039                       option.</para>
1040                     </listitem>
1041                   </varlistentry>
1042
1043                   <varlistentry>
1044                     <term>-historyfopt</term>
1045
1046                     <listitem>
1047                       <para>an array, with nbiter values, containing the
1048                       history of the function value during the
1049                       iterations.</para>
1050
1051                       <para>This array is available after optimization if the
1052                       history storing was enabled with the -storehistory
1053                       option.</para>
1054                     </listitem>
1055                   </varlistentry>
1056
1057                   <varlistentry>
1058                     <term>-fx0</term>
1059
1060                     <listitem>
1061                       <para>the function value for the initial guess</para>
1062                     </listitem>
1063                   </varlistentry>
1064
1065                   <varlistentry>
1066                     <term>-status</term>
1067
1068                     <listitem>
1069                       <para>a string containing the status of the
1070                       optimization. See below for details about the
1071                       optimization status.</para>
1072                     </listitem>
1073                   </varlistentry>
1074
1075                   <varlistentry>
1076                     <term>-historysimplex</term>
1077
1078                     <listitem>
1079                       <para>a matrix containing the history of the simplex
1080                       during the iterations. This matrix has rank nbiter x
1081                       nbve x n, where nbiter is the number of iterations, nbve
1082                       is the number of vertices in the simplex and n is the
1083                       number of variables.</para>
1084                     </listitem>
1085                   </varlistentry>
1086
1087                   <varlistentry>
1088                     <term>-simplexopt</term>
1089
1090                     <listitem>
1091                       <para>the optimum simplex. This is a simplex object,
1092                       which is suitable for processing with the simplex
1093                       interface.</para>
1094                     </listitem>
1095                   </varlistentry>
1096
1097                   <varlistentry>
1098                     <term>-restartnb</term>
1099
1100                     <listitem>
1101                       <para>the number of actual restarts performed.</para>
1102                     </listitem>
1103                   </varlistentry>
1104                 </variablelist>
1105
1106                 <para>Most fields are available only after an optimization has
1107                 been performed with one call to the neldermead_search
1108                 method.</para>
1109               </listitem>
1110             </varlistentry>
1111           </variablelist>
1112         </listitem>
1113       </varlistentry>
1114
1115       <varlistentry>
1116         <term>this = nmplot_display ( this )</term>
1117
1118         <listitem>
1119           <para>Display the current settings in the console.</para>
1120
1121           <variablelist>
1122             <varlistentry>
1123               <term>this</term>
1124
1125               <listitem>
1126                 <para>The current object.</para>
1127               </listitem>
1128             </varlistentry>
1129           </variablelist>
1130         </listitem>
1131       </varlistentry>
1132
1133       <varlistentry>
1134         <term>this = nmplot_search ( this )</term>
1135
1136         <listitem>
1137           <para>Performs the optimization associated with the method
1138           associated with the -method option and find the optimum.</para>
1139
1140           <variablelist>
1141             <varlistentry>
1142               <term>this</term>
1143
1144               <listitem>
1145                 <para>The current object.</para>
1146               </listitem>
1147             </varlistentry>
1148           </variablelist>
1149
1150           <para>If the -restartflag option is enabled, automatic restarts are
1151           performed, based on the -restartdetection option.</para>
1152         </listitem>
1153       </varlistentry>
1154
1155       <varlistentry>
1156         <term>this = nmplot_restart ( this )</term>
1157
1158         <listitem>
1159           <para>Restarts the optimization by updating the simplex and
1160           performing a new search.</para>
1161
1162           <variablelist>
1163             <varlistentry>
1164               <term>this</term>
1165
1166               <listitem>
1167                 <para>The current object.</para>
1168               </listitem>
1169             </varlistentry>
1170           </variablelist>
1171         </listitem>
1172       </varlistentry>
1173
1174       <varlistentry>
1175         <term>[ this , xdata , ydata , zdata ] = nmplot_contour ( this , xmin
1176         , xmax , ymin , ymax , nx , ny )</term>
1177
1178         <listitem>
1179           <para>Plot the contours of the cost function. The cost function must
1180           be a function with two parameters.</para>
1181
1182           <variablelist>
1183             <varlistentry>
1184               <term>this</term>
1185
1186               <listitem>
1187                 <para>The current object.</para>
1188               </listitem>
1189             </varlistentry>
1190
1191             <varlistentry>
1192               <term>xmin , xmax , ymin , ymax</term>
1193
1194               <listitem>
1195                 <para>the bounds for the contour plot</para>
1196               </listitem>
1197             </varlistentry>
1198
1199             <varlistentry>
1200               <term>nx , ny</term>
1201
1202               <listitem>
1203                 <para>the number of points in the directions x, y</para>
1204               </listitem>
1205             </varlistentry>
1206
1207             <varlistentry>
1208               <term>xdata , ydata , zdata</term>
1209
1210               <listitem>
1211                 <para>vectors of data, as required by the contour
1212                 function</para>
1213               </listitem>
1214             </varlistentry>
1215           </variablelist>
1216         </listitem>
1217       </varlistentry>
1218
1219       <varlistentry>
1220         <term>nmplot_simplexhistory ( this , colorforeground , markforeground
1221         , markstyle )</term>
1222
1223         <listitem>
1224           <para>Plots the simplex history on the current graphic window. The
1225           colorforeground , markforeground , markstyle options are provided to
1226           produce fast plots. Specific settings can still be applied with the
1227           usual graphic features.</para>
1228
1229           <variablelist>
1230             <varlistentry>
1231               <term>this</term>
1232
1233               <listitem>
1234                 <para>The current object.</para>
1235               </listitem>
1236             </varlistentry>
1237
1238             <varlistentry>
1239               <term>colorforeground</term>
1240
1241               <listitem>
1242                 <para>the color of the foreground for the simplices. Default
1243                 value is 5.</para>
1244               </listitem>
1245             </varlistentry>
1246
1247             <varlistentry>
1248               <term>markforeground</term>
1249
1250               <listitem>
1251                 <para>the foreground mark for the simplices. Default value is
1252                 3.</para>
1253               </listitem>
1254             </varlistentry>
1255
1256             <varlistentry>
1257               <term>markstyle</term>
1258
1259               <listitem>
1260                 <para>the mark style for the simplices. Default value is
1261                 9.</para>
1262               </listitem>
1263             </varlistentry>
1264           </variablelist>
1265         </listitem>
1266       </varlistentry>
1267
1268       <varlistentry>
1269         <term>nmplot_historyplot ( this , datafile , mytitle , myxlabel ,
1270         myylabel )</term>
1271
1272         <listitem>
1273           <para>Plots the history from the given data file on the current
1274           graphic window. The mytitle, myxlabel, myylabel options are provided
1275           as a way to produce plots faster. Specific settings can still be
1276           applied with the usual graphic features.</para>
1277
1278           <variablelist>
1279             <varlistentry>
1280               <term>this</term>
1281
1282               <listitem>
1283                 <para>The current object.</para>
1284               </listitem>
1285             </varlistentry>
1286
1287             <varlistentry>
1288               <term>datafile</term>
1289
1290               <listitem>
1291                 <para>the data file which contains the history. The file is
1292                 expected to be formatted in a way similar to the files
1293                 associated with the -fbarfn, -foptfn and -sigmafn files. The
1294                 default value is the value of the -foptfn option.</para>
1295               </listitem>
1296             </varlistentry>
1297
1298             <varlistentry>
1299               <term>mytitle</term>
1300
1301               <listitem>
1302                 <para>the title of the plot. Default value is the empty
1303                 string.</para>
1304               </listitem>
1305             </varlistentry>
1306
1307             <varlistentry>
1308               <term>myxlabel</term>
1309
1310               <listitem>
1311                 <para>the x label for the plot. Default value is the empty
1312                 string.</para>
1313               </listitem>
1314             </varlistentry>
1315
1316             <varlistentry>
1317               <term>myylabel</term>
1318
1319               <listitem>
1320                 <para>the y label for the plot. Default value is the empty
1321                 string.</para>
1322               </listitem>
1323             </varlistentry>
1324           </variablelist>
1325         </listitem>
1326       </varlistentry>
1327     </variablelist>
1328   </refsection>
1329
1330   <refsection>
1331     <title>Example</title>
1332
1333     <para>In the following example, we use the fixed shape Spendley et al.
1334     simplex algorithm and find the minimum of a quadratic function. We begin
1335     by defining a quadratic function associated with 2 input variables. We
1336     then define an nmplot object and configure the object so that the "fixed"
1337     shape simplex algorithm is used with the regular initial simplex
1338     associated with the "spendley" key. Four files are configured, which will
1339     contain the history of the simplex, the history of fbar, fopt and sigma
1340     through the iterations. The search is performed by the nmplot_search
1341     function, which writes the 4 data files during the iterations. The
1342     nmplot_contour function is called in order to compute the arrays xdata,
1343     ydata and zdata which are required as input to the contour function. The
1344     nmplot_simplexhistory then uses the history of the simplex, as stored in
1345     the rosenbrock.fixed.history.simplex.txt data file, and plot the various
1346     simplices on the contour plot. The nmplot_historyplot is used with the
1347     files rosenbrock.fixed.history.fbar.txt, rosenbrock.fixed.history.fopt.txt
1348     and rosenbrock.fixed.history.sigma.txt, which produces 3 plots of the
1349     history of the optimization algorithm through the iterations.</para>
1350
1351     <programlisting role="example"> 
1352 mprintf("Defining quadratic function...\n");
1353 function y = quadratic (x)
1354   y = x(1)^2 + x(2)^2 - x(1) * x(2);
1355 endfunction
1356
1357 mprintf("Creating nmplot object...\n");
1358 nm = nmplot_new ();
1359 nm = nmplot_configure(nm,"-numberofvariables",2);
1360 nm = nmplot_configure(nm,"-function",quadratic);
1361 nm = nmplot_configure(nm,"-x0",[2.0 2.0]');
1362 nm = nmplot_configure(nm,"-maxiter",100);
1363 nm = nmplot_configure(nm,"-maxfunevals",300);
1364 nm = nmplot_configure(nm,"-tolxrelative",1.e-8);
1365 nm = nmplot_configure(nm,"-simplex0method","spendley");
1366 nm = nmplot_configure(nm,"-method","fixed");
1367 //
1368 // Setup output files
1369 //
1370 nm = nmplot_configure(nm,"-simplexfn","rosenbrock.fixed.history.simplex.txt");
1371 nm = nmplot_configure(nm,"-fbarfn","rosenbrock.fixed.history.fbar.txt");
1372 nm = nmplot_configure(nm,"-foptfn","rosenbrock.fixed.history.fopt.txt");
1373 nm = nmplot_configure(nm,"-sigmafn","rosenbrock.fixed.history.sigma.txt");
1374 //
1375 // Perform optimization
1376 //
1377 mprintf("Searching for minimum...\n");
1378 nm = nmplot_search(nm);
1379 nmplot_display(nm);
1380 // Plot the contours of the cost function and the simplex history
1381 mprintf("Plotting contour...\n");
1382 [nm , xdata , ydata , zdata ] = nmplot_contour ( nm , xmin = -2.0 , xmax = 4.0 , ymin = -2.0 , ymax = 4.0 , nx = 100 , ny = 100 );
1383 f = scf();
1384 contour ( xdata , ydata , zdata , [0.1 1.0 2.0 5.0 10.0 15.0 20.0] )
1385 nmplot_simplexhistory ( nm );
1386 mprintf("Plotting history of fbar...\n");
1387 f = scf();
1388 nmplot_historyplot ( nm , "rosenbrock.fixed.history.fbar.txt" , ...
1389   mytitle = "Function Value Average" , myxlabel = "Iterations" );
1390 mprintf("Plotting history of fopt...\n");
1391 f = scf();
1392 nmplot_historyplot ( nm , "rosenbrock.fixed.history.fopt.txt" , ...
1393   mytitle = "Minimum Function Value" , myxlabel = "Iterations" );
1394 mprintf("Plotting history of sigma...\n");
1395 f = scf();
1396 nmplot_historyplot ( nm , "rosenbrock.fixed.history.sigma.txt" , ...
1397   mytitle = "Maximum Oriented length" , myxlabel = "Iterations" );
1398 deletefile("rosenbrock.fixed.history.simplex.txt");
1399 deletefile("rosenbrock.fixed.history.fbar.txt");
1400 deletefile("rosenbrock.fixed.history.fopt.txt");
1401 deletefile("rosenbrock.fixed.history.sigma.txt");
1402 nm = nmplot_destroy(nm);
1403
1404
1405  </programlisting>
1406   </refsection>
1407
1408   <refsection>
1409     <title>TODO</title>
1410
1411     <itemizedlist>
1412       <listitem>
1413         <para>add an example</para>
1414       </listitem>
1415     </itemizedlist>
1416   </refsection>
1417
1418   <refsection>
1419     <title>Authors</title>
1420
1421     <para>Michael Baudin - INRIA - 2008-2009</para>
1422
1423     <para>Michael Baudin - Digiteo - 2009</para>
1424   </refsection>
1425
1426   <refsection>
1427     <title>See Also</title>
1428
1429     <simplelist type="inline">
1430       <member><link linkend="optimbase">neldermead</link></member>
1431     </simplelist>
1432   </refsection>
1433 </refentry>