Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / optimbase / optimbase.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="optimbase" 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>optimbase</refname>
18
19     <refpurpose>Provides an abstract class for a general optimization
20     component.</refpurpose>
21   </refnamediv>
22
23   <refsynopsisdiv>
24     <title>SYNOPSIS</title>
25
26     <synopsis>
27 newobj = optimbase_new ()
28 this = optimbase_destroy (this)
29 this = optimbase_configure (this,key,value)
30 value = optimbase_cget (this,key)
31 value = optimbase_get (this,key)
32 this = optimbase_set ( this , key , value )
33 [ this , isok ] = optimbase_checkbounds ( this )
34 [ opt , isok ] = optimbase_checkx0 ( this )
35 this = optimbase_display ( this )
36 [ this , result ] = optimbase_function ( this , x , index )
37 [ this , hasbounds ] = optimbase_hasbounds ( this )
38 value = optimbase_histget ( this , iter , key )
39 this = optimbase_histset ( this , iter , key , value )
40 this = optimbase_incriter ( this )
41 [ this , isfeasible ] = optimbase_isfeasible ( this , x )
42 this = optimbase_log (this,msg)
43 optimbase_outputcmd ( this , state , data )
44 data = optimbase_outstruct ( this )
45 [ this , p ] = optimbase_proj2bnds ( this ,  x )
46 this = optimbase_stoplog ( this , msg )
47 [this , terminate , status] = optimbase_terminate (this , previousfopt , currentfopt , previousxopt , currentxopt )
48 </synopsis>
49   </refsynopsisdiv>
50
51   <refsection>
52     <title>Purpose</title>
53
54     <para>
55       The goal of this component is to provide a building block for
56       optimization methods. The goal is to provide a building block for a large
57       class of specialized optimization methods. This component manages</para>
58       <itemizedlist>
59         <listitem>
60           <para>the number of variables,</para>
61         </listitem>
62
63         <listitem>
64           <para>the minimum and maximum bounds,</para>
65         </listitem>
66
67         <listitem>
68           <para>the number of non linear inequality constraints,</para>
69         </listitem>
70
71         <listitem>
72           <para>the cost function,</para>
73         </listitem>
74
75         <listitem>
76           <para>the logging system,</para>
77         </listitem>
78
79         <listitem>
80           <para>various termination criteria,</para>
81         </listitem>
82
83         <listitem>
84           <para>etc...</para>
85         </listitem>
86       </itemizedlist>
87   </refsection>
88
89   <refsection>
90     <title>Design</title>
91
92     <para>This toolbox is designed with Oriented Object ideas in mind.</para>
93   </refsection>
94
95   <refsection>
96     <title>Features</title>
97
98     <para>The following is a list of features the Optimbase toolbox currently
99     provides :</para>
100
101     <itemizedlist>
102       <listitem>
103         <para>Manage cost function</para>
104
105         <itemizedlist>
106           <listitem>
107             <para>optionnal additionnal argument</para>
108           </listitem>
109
110           <listitem>
111             <para>direct communication of the task to perform : cost function
112             or inequality constraints</para>
113           </listitem>
114         </itemizedlist>
115       </listitem>
116
117       <listitem>
118         <para>Manage various termination criteria, including </para>
119         <itemizedlist>
120             <listitem>
121               <para>maximum number of iterations,</para>
122             </listitem>
123
124             <listitem>
125               <para>tolerance on function value (relative or absolute),</para>
126             </listitem>
127
128             <listitem>
129               <para>tolerance on x (relative or absolute),</para>
130             </listitem>
131
132             <listitem>
133               <para>maximum number of evaluations of cost function,</para>
134             </listitem>
135         </itemizedlist>
136       </listitem>
137
138       <listitem>
139         <para>Manage the history of the convergence, including</para>
140
141         <itemizedlist>
142           <listitem>
143             <para>history of function values,</para>
144           </listitem>
145
146           <listitem>
147             <para>history of optimum point.</para>
148           </listitem>
149         </itemizedlist>
150       </listitem>
151
152       <listitem>
153         <para>Provide query features for</para>
154
155         <itemizedlist>
156           <listitem>
157             <para>the status of the optimization process,</para>
158           </listitem>
159
160           <listitem>
161             <para>the number of iterations,</para>
162           </listitem>
163
164           <listitem>
165             <para>the number of function evaluations,</para>
166           </listitem>
167
168           <listitem>
169             <para>function value at initial point,</para>
170           </listitem>
171
172           <listitem>
173             <para>function value at optimal point,</para>
174           </listitem>
175
176           <listitem>
177             <para>the optimum parameters,</para>
178           </listitem>
179
180           <listitem>
181             <para>etc...</para>
182           </listitem>
183         </itemizedlist>
184       </listitem>
185     </itemizedlist>
186   </refsection>
187
188   <refsection>
189     <title>Description</title>
190
191     <para>This set of commands allows to manage an abstract optimization
192     method. The goal is to provide a building block for a large class of
193     specialized optimization methods. This component manages the number of
194     variables, the minimum and maximum bounds, the number of non linear
195     inequality constraints, the logging system, various termination criteria,
196     the cost function, etc...</para>
197
198     <para>The optimization problem to solve is the following</para>
199
200     <programlisting role="example"><![CDATA[ 
201 min f(x)
202 l_i <= x_i <= h_i, i = 1,n
203 g_i(x) <= 0, i = 1,nbineq
204  ]]></programlisting>
205
206     <para>where</para>
207
208     <variablelist>
209       <varlistentry>
210         <term>n</term>
211
212         <listitem>
213           <para>number of variables</para>
214         </listitem>
215       </varlistentry>
216
217       <varlistentry>
218         <term>nbineq</term>
219
220         <listitem>
221           <para>number of inequality constraints</para>
222         </listitem>
223       </varlistentry>
224     </variablelist>
225   </refsection>
226
227   <refsection>
228     <title>Functions</title>
229
230     <para>The following functions are available.</para>
231
232     <variablelist>
233       <varlistentry>
234         <term>newobj = optimbase_new ()</term>
235
236         <listitem>
237           <para>Creates a new optimization object.</para>
238
239           <variablelist>
240             <varlistentry>
241               <term>newobj</term>
242
243               <listitem>
244                 <para>The new object.</para>
245               </listitem>
246             </varlistentry>
247           </variablelist>
248         </listitem>
249       </varlistentry>
250
251       <varlistentry>
252         <term>this = optimbase_destroy (this)</term>
253
254         <listitem>
255           <para>Destroy the given object.</para>
256
257           <variablelist>
258             <varlistentry>
259               <term>this</term>
260
261               <listitem>
262                 <para>The current object.</para>
263               </listitem>
264             </varlistentry>
265           </variablelist>
266         </listitem>
267       </varlistentry>
268
269       <varlistentry>
270         <term>this = optimbase_configure (this,key,value)</term>
271
272         <listitem>
273           <para>Configure the current object with the given value for the
274           given key.</para>
275
276           <variablelist>
277             <varlistentry>
278               <term>this</term>
279
280               <listitem>
281                 <para>The current object.</para>
282               </listitem>
283             </varlistentry>
284
285             <varlistentry>
286               <term>key</term>
287
288               <listitem>
289                 <para>the key to configure. The following keys are
290                 available.</para>
291
292                 <variablelist>
293                   <varlistentry>
294                     <term>-verbose</term>
295
296                     <listitem>
297                       <para>set to 1 to enable verbose logging. (default is
298                       0)</para>
299                     </listitem>
300                   </varlistentry>
301
302                   <varlistentry>
303                     <term>-verbosetermination</term>
304
305                     <listitem>
306                       <para>set to 1 to enable verbose termination logging.
307                       (default is 0)</para>
308                     </listitem>
309                   </varlistentry>
310
311                   <varlistentry>
312                     <term>-x0</term>
313
314                     <listitem>
315                       <para>the initial guess.</para>
316                     </listitem>
317                   </varlistentry>
318
319                   <varlistentry>
320                     <term>-maxfunevals</term>
321
322                     <listitem>
323                       <para>the maximum number of function evalutations
324                       (default is 100). If this criteria is triggered, the
325                       status of the optimization is set to
326                       "maxfuneval".</para>
327                     </listitem>
328                   </varlistentry>
329
330                   <varlistentry>
331                     <term>-maxiter</term>
332
333                     <listitem>
334                       <para>the maximum number of iterations (default is 100).
335                       If this criteria is triggered, the status of the
336                       optimization is set to "maxiter".</para>
337                     </listitem>
338                   </varlistentry>
339
340                   <varlistentry>
341                     <term>-tolfunabsolute</term>
342
343                     <listitem>
344                       <para>the absolute tolerance for the function value
345                       (default is 0.0).</para>
346                     </listitem>
347                   </varlistentry>
348
349                   <varlistentry>
350                     <term>-tolfunrelative</term>
351
352                     <listitem>
353                       <para>the relative tolerance for the function value
354                       (default is %eps).</para>
355                     </listitem>
356                   </varlistentry>
357
358                   <varlistentry>
359                     <term>-tolfunmethod</term>
360
361                     <listitem>
362                       <para>the method used for the tolerance on function
363                       value in the termination criteria.</para>
364
365                       <para>The following values are available : "enabled",
366                       "disabled" (default is "disabled"). If this criteria is
367                       triggered, the status of the optimization is set to
368                       "tolf".</para>
369                     </listitem>
370                   </varlistentry>
371
372                   <varlistentry>
373                     <term>-tolxabsolute</term>
374
375                     <listitem>
376                       <para>the absolute tolerance on x (default is
377                       0.0).</para>
378                     </listitem>
379                   </varlistentry>
380
381                   <varlistentry>
382                     <term>-tolxrelative</term>
383
384                     <listitem>
385                       <para>the relative tolerance on x (default is
386                       %eps).</para>
387                     </listitem>
388                   </varlistentry>
389
390                   <varlistentry>
391                     <term>-tolxmethod</term>
392
393                     <listitem>
394                       <para>the method used for the tolerance on x in the
395                       termination criteria.</para>
396
397                       <para>The following values are available : "enabled",
398                       "disabled" (default is "enabled"). If this criteria is
399                       triggered, the status of the optimization is set to
400                       "tolx".</para>
401                     </listitem>
402                   </varlistentry>
403
404                   <varlistentry>
405                     <term>-function</term>
406
407                     <listitem>
408                       <para>the objective function, which computes the value
409                       of the cost and the non linear constraints, if
410                       any.</para>
411
412                       <para>See below for the details of the communication
413                       between the optimization system and the cost
414                       function.</para>
415                     </listitem>
416                   </varlistentry>
417
418                   <varlistentry>
419                     <term>-costfargument</term>
420
421                     <listitem>
422                       <para>an additionnal argument, passed to the cost
423                       function.</para>
424                     </listitem>
425                   </varlistentry>
426
427                   <varlistentry>
428                     <term>-outputcommand</term>
429
430                     <listitem>
431                       <para>a command which is called back for output.</para>
432
433                       <para>See below for the details of the communication
434                       between the optimization system and the output command
435                       function.</para>
436                     </listitem>
437                   </varlistentry>
438
439                   <varlistentry>
440                     <term>-outputcommandarg</term>
441
442                     <listitem>
443                       <para>an additionnal argument, passed to the output
444                       command.</para>
445                     </listitem>
446                   </varlistentry>
447
448                   <varlistentry>
449                     <term>-numberofvariables</term>
450
451                     <listitem>
452                       <para>the number of variables to optimize (default is
453                       0).</para>
454                     </listitem>
455                   </varlistentry>
456
457                   <varlistentry>
458                     <term>-storehistory</term>
459
460                     <listitem>
461                       <para>set to 1 to enable the history storing (default is
462                       0).</para>
463                     </listitem>
464                   </varlistentry>
465
466                   <varlistentry>
467                     <term>-boundsmin</term>
468
469                     <listitem>
470                       <para>the minimum bounds for the parameters, as an array
471                       of values (default is empty, i.e. there are no
472                       bounds).</para>
473                     </listitem>
474                   </varlistentry>
475
476                   <varlistentry>
477                     <term>-boundsmax</term>
478
479                     <listitem>
480                       <para>the maximum bounds for the parameters, as an array
481                       of values (default is empty, i.e. there are no
482                       bounds).</para>
483                     </listitem>
484                   </varlistentry>
485
486                   <varlistentry>
487                     <term>-nbineqconst</term>
488
489                     <listitem>
490                       <para>the number of inequality constraints (default is
491                       0)</para>
492                     </listitem>
493                   </varlistentry>
494                 </variablelist>
495               </listitem>
496             </varlistentry>
497
498             <varlistentry>
499               <term>value</term>
500
501               <listitem>
502                 <para>the value.</para>
503               </listitem>
504             </varlistentry>
505           </variablelist>
506         </listitem>
507       </varlistentry>
508
509       <varlistentry>
510         <term>value = optimbase_cget (this,key)</term>
511
512         <listitem>
513           <para>Get the value for the given key. If the key is unknown,
514           generates an error.</para>
515
516           <variablelist>
517             <varlistentry>
518               <term>this</term>
519
520               <listitem>
521                 <para>The current object.</para>
522               </listitem>
523             </varlistentry>
524
525             <varlistentry>
526               <term>key</term>
527
528               <listitem>
529                 <para>the name of the key to quiery. The list of available
530                 keys is the same as for the optimbase_configure
531                 function.</para>
532               </listitem>
533             </varlistentry>
534           </variablelist>
535         </listitem>
536       </varlistentry>
537
538       <varlistentry>
539         <term>[ this , isok ] = optimbase_checkbounds ( this )</term>
540
541         <listitem>
542           <para>Check if the bounds are consistent and puts an error message
543           if not. One could generate an error, but errors are not testable
544           with the current system.</para>
545
546           <variablelist>
547             <varlistentry>
548               <term>this</term>
549
550               <listitem>
551                 <para>The current object.</para>
552               </listitem>
553             </varlistentry>
554           </variablelist>
555         </listitem>
556       </varlistentry>
557
558       <varlistentry>
559         <term>[ opt , isok ] = optimbase_checkx0 ( this )</term>
560
561         <listitem>
562           <para>Returns %T if the initial guess is consistent with the bounds
563           and the non linear inequality constraints, if any.</para>
564
565           <variablelist>
566             <varlistentry>
567               <term>this</term>
568
569               <listitem>
570                 <para>The current object.</para>
571               </listitem>
572             </varlistentry>
573           </variablelist>
574         </listitem>
575       </varlistentry>
576
577       <varlistentry>
578         <term>this = optimbase_display ( this )</term>
579
580         <listitem>
581           <para>Display the current settings in the console.</para>
582
583           <variablelist>
584             <varlistentry>
585               <term>this</term>
586
587               <listitem>
588                 <para>The current object.</para>
589               </listitem>
590             </varlistentry>
591           </variablelist>
592         </listitem>
593       </varlistentry>
594
595       <varlistentry>
596         <term>[ this , result ] = optimbase_function ( this , x , index
597         )</term>
598
599         <listitem>
600           <para>Call the cost function and return the value.</para>
601
602           <para>If a cost function additionnal argument is defined in current
603           object, pass it to the function. If an index is defined as input
604           argument, pass it to the function, always as second argument.</para>
605
606           <variablelist>
607             <varlistentry>
608               <term>this</term>
609
610               <listitem>
611                 <para>The current object.</para>
612               </listitem>
613             </varlistentry>
614
615             <varlistentry>
616               <term>x</term>
617
618               <listitem>
619                 <para>the current point</para>
620               </listitem>
621             </varlistentry>
622
623             <varlistentry>
624               <term>index</term>
625
626               <listitem>
627                 <para>optional, the value to compute.</para>
628
629                 <para>See below in the section "Cost function" for details on
630                 this index.</para>
631               </listitem>
632             </varlistentry>
633           </variablelist>
634         </listitem>
635       </varlistentry>
636
637       <varlistentry>
638         <term>this = optimbase_set ( this , key , value )</term>
639
640         <listitem>
641           <para>Set the value for the given key. If the key is unknown,
642           generates an error.</para>
643
644           <variablelist>
645             <varlistentry>
646               <term>this</term>
647
648               <listitem>
649                 <para>The current object.</para>
650               </listitem>
651             </varlistentry>
652
653             <varlistentry>
654               <term>key</term>
655
656               <listitem>
657                 <para>the key to set</para>
658
659                 <para>The following keys are available :</para>
660
661                 <variablelist>
662                   <varlistentry>
663                     <term>-funevals</term>
664
665                     <listitem>
666                       <para>the number of function evaluations</para>
667                     </listitem>
668                   </varlistentry>
669
670                   <varlistentry>
671                     <term>-iterations</term>
672
673                     <listitem>
674                       <para>the number of iterations</para>
675                     </listitem>
676                   </varlistentry>
677
678                   <varlistentry>
679                     <term>-xopt</term>
680
681                     <listitem>
682                       <para>the x optimum</para>
683                     </listitem>
684                   </varlistentry>
685
686                   <varlistentry>
687                     <term>-fopt</term>
688
689                     <listitem>
690                       <para>the optimum cost function value</para>
691                     </listitem>
692                   </varlistentry>
693
694                   <varlistentry>
695                     <term>-historyxopt</term>
696
697                     <listitem>
698                       <para>an array, with nbiter values, containing the
699                       history of x during the iterations.</para>
700
701                       <para>This array is available after optimization if the
702                       history storing was enabled with the -storehistory
703                       option.</para>
704                     </listitem>
705                   </varlistentry>
706
707                   <varlistentry>
708                     <term>-historyfopt</term>
709
710                     <listitem>
711                       <para>an array, with nbiter values, containing the
712                       history of the function value during the
713                       iterations.</para>
714
715                       <para>This array is available after optimization if the
716                       history storing was enabled with the -storehistory
717                       option.</para>
718                     </listitem>
719                   </varlistentry>
720
721                   <varlistentry>
722                     <term>-fx0</term>
723
724                     <listitem>
725                       <para>the function value for the initial guess</para>
726                     </listitem>
727                   </varlistentry>
728
729                   <varlistentry>
730                     <term>-status</term>
731
732                     <listitem>
733                       <para>a string containing the status of the
734                       optimization</para>
735                     </listitem>
736                   </varlistentry>
737                 </variablelist>
738               </listitem>
739             </varlistentry>
740
741             <varlistentry>
742               <term>value</term>
743
744               <listitem>
745                 <para>the value to set</para>
746               </listitem>
747             </varlistentry>
748           </variablelist>
749         </listitem>
750       </varlistentry>
751
752       <varlistentry>
753         <term>value = optimbase_get (this,key)</term>
754
755         <listitem>
756           <para>Get the value for the given key. If the key is unknown,
757           generates an error. This command corresponds with options which are
758           not available directly to the optimbase_configure function, but are
759           computed internally.</para>
760
761           <variablelist>
762             <varlistentry>
763               <term>this</term>
764
765               <listitem>
766                 <para>The current object.</para>
767               </listitem>
768             </varlistentry>
769
770             <varlistentry>
771               <term>key</term>
772
773               <listitem>
774                 <para>the name of the key to quiery.</para>
775
776                 <para>The list of available keys is the same as the
777                 optimbase_set function.</para>
778               </listitem>
779             </varlistentry>
780           </variablelist>
781         </listitem>
782       </varlistentry>
783
784       <varlistentry>
785         <term>[ this , hasbounds ] = optimbase_hasbounds ( this )</term>
786
787         <listitem>
788           <para>Returns %T if current problem has bounds.</para>
789
790           <variablelist>
791             <varlistentry>
792               <term>this</term>
793
794               <listitem>
795                 <para>The current object.</para>
796               </listitem>
797             </varlistentry>
798           </variablelist>
799         </listitem>
800       </varlistentry>
801
802       <varlistentry>
803         <term>this = optimbase_histset ( this , iter , key , value )</term>
804
805         <listitem>
806           <para>Set the history value at given iteration for the given key. If
807           the key is unknown, generates an error.</para>
808
809           <variablelist>
810             <varlistentry>
811               <term>this</term>
812
813               <listitem>
814                 <para>The current object.</para>
815               </listitem>
816             </varlistentry>
817
818             <varlistentry>
819               <term>iter</term>
820
821               <listitem>
822                 <para>the iteration number to get</para>
823               </listitem>
824             </varlistentry>
825
826             <varlistentry>
827               <term>key</term>
828
829               <listitem>
830                 <para>the name of the key to quiery.</para>
831
832                 <para>The list of available keys is the following : "-xopt",
833                 "-fopt".</para>
834               </listitem>
835             </varlistentry>
836
837             <varlistentry>
838               <term>value</term>
839
840               <listitem>
841                 <para>the value to set</para>
842               </listitem>
843             </varlistentry>
844           </variablelist>
845         </listitem>
846       </varlistentry>
847
848       <varlistentry>
849         <term>value = optimbase_histget ( this , iter , key )</term>
850
851         <listitem>
852           <para>Returns the history value at the given iteration number for
853           the given key. If the key is unknown, generates an error.</para>
854
855           <variablelist>
856             <varlistentry>
857               <term>this</term>
858
859               <listitem>
860                 <para>The current object.</para>
861               </listitem>
862             </varlistentry>
863
864             <varlistentry>
865               <term>iter</term>
866
867               <listitem>
868                 <para>the iteration number to get</para>
869               </listitem>
870             </varlistentry>
871
872             <varlistentry>
873               <term>key</term>
874
875               <listitem>
876                 <para>the name of the key to quiery.</para>
877
878                 <para>The list of available keys is the same as the
879                 optimbase_histset function.</para>
880               </listitem>
881             </varlistentry>
882           </variablelist>
883         </listitem>
884       </varlistentry>
885
886       <varlistentry>
887         <term>this = optimbase_incriter ( this )</term>
888
889         <listitem>
890           <para>Increments the number of iterations.</para>
891
892           <variablelist>
893             <varlistentry>
894               <term>this</term>
895
896               <listitem>
897                 <para>The current object.</para>
898               </listitem>
899             </varlistentry>
900           </variablelist>
901         </listitem>
902       </varlistentry>
903
904       <varlistentry>
905         <term>[ this , isfeasible ] = optimbase_isfeasible ( this , x )</term>
906
907         <listitem>
908           <para>Returns 1 if the given point satisfies bounds constraints and
909           inequality constraints. Returns 0 if the given point is not in the
910           bounds. Returns -1 if the given point does not satisfies inequality
911           constraints.</para>
912
913           <variablelist>
914             <varlistentry>
915               <term>this</term>
916
917               <listitem>
918                 <para>The current object.</para>
919               </listitem>
920             </varlistentry>
921
922             <varlistentry>
923               <term>x</term>
924
925               <listitem>
926                 <para>the current point</para>
927               </listitem>
928             </varlistentry>
929           </variablelist>
930         </listitem>
931       </varlistentry>
932
933       <varlistentry>
934         <term>this = optimbase_log (this,msg)</term>
935
936         <listitem>
937           <para>If verbose logging is enabled, prints the given message in the
938           console. If verbose logging is disabled, does nothing.</para>
939
940           <variablelist>
941             <varlistentry>
942               <term>this</term>
943
944               <listitem>
945                 <para>The current object.</para>
946               </listitem>
947             </varlistentry>
948
949             <varlistentry>
950               <term>msg</term>
951
952               <listitem>
953                 <para>the message to print</para>
954               </listitem>
955             </varlistentry>
956           </variablelist>
957         </listitem>
958       </varlistentry>
959
960       <varlistentry>
961         <term>optimbase_outputcmd ( this , state , data )</term>
962
963         <listitem>
964           <para>Calls back user's output command.</para>
965
966           <variablelist>
967             <varlistentry>
968               <term>this</term>
969
970               <listitem>
971                 <para>The current object.</para>
972               </listitem>
973             </varlistentry>
974           </variablelist>
975         </listitem>
976       </varlistentry>
977
978       <varlistentry>
979         <term>data = optimbase_outstruct ( this )</term>
980
981         <listitem>
982           <para>Returns a tlist with basic optimization fields. This tlist is
983           suitable for use as an input argument of the output function. This
984           tlist may be enriched by children (specialize) optimization
985           methods.</para>
986
987           <variablelist>
988             <varlistentry>
989               <term>this</term>
990
991               <listitem>
992                 <para>The current object.</para>
993               </listitem>
994             </varlistentry>
995           </variablelist>
996         </listitem>
997       </varlistentry>
998
999       <varlistentry>
1000         <term>[ this , p ] = optimbase_proj2bnds ( this , x )</term>
1001
1002         <listitem>
1003           <para>Returns a point, which is the projection of the given point
1004           into the bounds.</para>
1005
1006           <variablelist>
1007             <varlistentry>
1008               <term>this</term>
1009
1010               <listitem>
1011                 <para>The current object.</para>
1012               </listitem>
1013             </varlistentry>
1014
1015             <varlistentry>
1016               <term>x</term>
1017
1018               <listitem>
1019                 <para>the current point</para>
1020               </listitem>
1021             </varlistentry>
1022           </variablelist>
1023         </listitem>
1024       </varlistentry>
1025
1026       <varlistentry>
1027         <term>this = optimbase_stoplog ( this , msg )</term>
1028
1029         <listitem>
1030           <para>Prints the given stopping rule message if verbose termination
1031           is enabled. If verbose termination is disabled, does nothing.</para>
1032
1033           <variablelist>
1034             <varlistentry>
1035               <term>this</term>
1036
1037               <listitem>
1038                 <para>The current object.</para>
1039               </listitem>
1040             </varlistentry>
1041
1042             <varlistentry>
1043               <term>msg</term>
1044
1045               <listitem>
1046                 <para>the message to print</para>
1047               </listitem>
1048             </varlistentry>
1049           </variablelist>
1050         </listitem>
1051       </varlistentry>
1052
1053       <varlistentry>
1054         <term>[this , terminate , status] = optimbase_terminate (this ,
1055         previousfopt , currentfopt , previousxopt , currentxopt )</term>
1056
1057         <listitem>
1058           <para>Returns 1 if the algorithm terminates. Returns 0 if the
1059           algorithm must continue. If the -verbosetermination option is
1060           enabled, messages are printed detailing the termination intermediate
1061           steps. The optimbase_terminate function takes into account the
1062           number of iterations, the number of evaluations of the cost
1063           function, the tolerance on x and the tolerance on f. See below in
1064           the section "Termination" for more details.</para>
1065
1066           <variablelist>
1067             <varlistentry>
1068               <term>this</term>
1069
1070               <listitem>
1071                 <para>The current object.</para>
1072               </listitem>
1073             </varlistentry>
1074
1075             <varlistentry>
1076               <term>previousfopt</term>
1077
1078               <listitem>
1079                 <para>the previous value of the cost function</para>
1080               </listitem>
1081             </varlistentry>
1082
1083             <varlistentry>
1084               <term>currentfopt</term>
1085
1086               <listitem>
1087                 <para>the current value of the cost function</para>
1088               </listitem>
1089             </varlistentry>
1090
1091             <varlistentry>
1092               <term>previousxopt</term>
1093
1094               <listitem>
1095                 <para>the previous x optimum</para>
1096               </listitem>
1097             </varlistentry>
1098
1099             <varlistentry>
1100               <term>currentxopt</term>
1101
1102               <listitem>
1103                 <para>the current x optimum</para>
1104               </listitem>
1105             </varlistentry>
1106
1107             <varlistentry>
1108               <term>terminate</term>
1109
1110               <listitem>
1111                 <para>1 if the algorithm must terminate, 0 if the algorithm
1112                 must continue</para>
1113               </listitem>
1114             </varlistentry>
1115
1116             <varlistentry>
1117               <term>status</term>
1118
1119               <listitem>
1120                 <para>if terminate = 1, the detailed status of the
1121                 termination, as a string. If terminate = 0, the status is
1122                 "continue".</para>
1123
1124                 <para>The following status are available :</para>
1125
1126                 <variablelist>
1127                   <varlistentry>
1128                     <term>"maxiter"</term>
1129
1130                     <listitem>
1131                       <para>the maximum number of iterations, provided by the
1132                       -maxiter option, is reached.</para>
1133                     </listitem>
1134                   </varlistentry>
1135
1136                   <varlistentry>
1137                     <term>"maxfuneval"</term>
1138
1139                     <listitem>
1140                       <para>the maximum number of function evaluations,
1141                       provided by the -maxfunevals option, is reached</para>
1142                     </listitem>
1143                   </varlistentry>
1144
1145                   <varlistentry>
1146                     <term>"tolf"</term>
1147
1148                     <listitem>
1149                       <para>the tolerance on the function value is reached.
1150                       This status is associated with the -tolfunmethod,
1151                       -tolfunabsolute and -tolfunrelative options.</para>
1152                     </listitem>
1153                   </varlistentry>
1154
1155                   <varlistentry>
1156                     <term>"tolx"</term>
1157
1158                     <listitem>
1159                       <para>the tolerance on x is reached. This status is
1160                       associated with the -tolxmethod, -tolxabsolute and
1161                       -tolxrelative options.</para>
1162                     </listitem>
1163                   </varlistentry>
1164                 </variablelist>
1165               </listitem>
1166             </varlistentry>
1167           </variablelist>
1168         </listitem>
1169       </varlistentry>
1170     </variablelist>
1171   </refsection>
1172
1173   <refsection>
1174     <title>The cost function</title>
1175
1176     <para>The option -function allows to configure the cost function. The cost
1177     function is used to compute the cost and the value of the nonlinear
1178     inequality constraints.</para>
1179
1180     <para>In the more general case, the cost function is expected to have the
1181     following header</para>
1182
1183     <programlisting role="example"><![CDATA[ 
1184 function y = myfunction(x, index, data)
1185  ]]></programlisting>
1186
1187     <para>where</para>
1188
1189     <variablelist>
1190       <varlistentry>
1191         <term>x</term>
1192
1193         <listitem>
1194           <para>the current point</para>
1195         </listitem>
1196       </varlistentry>
1197
1198       <varlistentry>
1199         <term>index</term>
1200
1201         <listitem>
1202           <para>optional, an integer representing the value to compute</para>
1203         </listitem>
1204       </varlistentry>
1205
1206       <varlistentry>
1207         <term>data</term>
1208
1209         <listitem>
1210           <para>optional, a user-defined data.</para>
1211
1212           <para>This argument is configured with the -costfargument
1213           option.</para>
1214         </listitem>
1215       </varlistentry>
1216
1217       <varlistentry>
1218         <term>y</term>
1219
1220         <listitem>
1221           <para>the result</para>
1222         </listitem>
1223       </varlistentry>
1224     </variablelist>
1225
1226     <para>The index input parameter has the following meaning</para>
1227
1228     <variablelist>
1229       <varlistentry>
1230         <term>index = 1 (or no index)</term>
1231
1232         <listitem>
1233           <para>the result is the value of the cost function</para>
1234         </listitem>
1235       </varlistentry>
1236
1237       <varlistentry>
1238         <term>index = 2</term>
1239
1240         <listitem>
1241           <para>the result is the value of the non-linear inequality
1242           constraints, as an array of values</para>
1243         </listitem>
1244       </varlistentry>
1245
1246       <varlistentry>
1247         <term>index = 3</term>
1248
1249         <listitem>
1250           <para>the result is an array, which content is the following. At
1251           index #1, the value of the cost function. At index #2 to the end,
1252           the list of values of the nonlinear inequality constraints.</para>
1253         </listitem>
1254       </varlistentry>
1255     </variablelist>
1256
1257     <para>In the most simple case, the cost function is expected to have the
1258     following header</para>
1259
1260     <programlisting role="example"><![CDATA[ 
1261 function y = myfunction(x)
1262  ]]></programlisting>
1263
1264     <para>where x is the current point and y is the value of the cost. This
1265     case is associated with an unconstrained problem without any additionnal
1266     parameter.</para>
1267   </refsection>
1268
1269   <refsection>
1270     <title>The output function</title>
1271
1272     <para>The option -outputcommand allows to configure a command which is
1273     called back at the start of the optimization, at each iteration and at the
1274     end of the optimization.</para>
1275
1276     <para>The output function must have the following header</para>
1277
1278     <programlisting role="example"><![CDATA[ 
1279 function outputcmd(state, data, myobj)
1280  ]]></programlisting>
1281
1282     <para>where</para>
1283
1284     <variablelist>
1285       <varlistentry>
1286         <term>state</term>
1287
1288         <listitem>
1289           <para>a string representing the current state of the algorithm.
1290           Available values are "init", "iter", "done".</para>
1291         </listitem>
1292       </varlistentry>
1293
1294       <varlistentry>
1295         <term>data</term>
1296
1297         <listitem>
1298           <para>a tlist containing at least the following entries</para>
1299
1300           <variablelist>
1301             <varlistentry>
1302               <term>x</term>
1303
1304               <listitem>
1305                 <para>the current optimum</para>
1306               </listitem>
1307             </varlistentry>
1308
1309             <varlistentry>
1310               <term>fval</term>
1311
1312               <listitem>
1313                 <para>the current function value</para>
1314               </listitem>
1315             </varlistentry>
1316
1317             <varlistentry>
1318               <term>iteration</term>
1319
1320               <listitem>
1321                 <para>the current iteration index</para>
1322               </listitem>
1323             </varlistentry>
1324
1325             <varlistentry>
1326               <term>funccount</term>
1327
1328               <listitem>
1329                 <para>the number of function evaluations</para>
1330               </listitem>
1331             </varlistentry>
1332           </variablelist>
1333         </listitem>
1334       </varlistentry>
1335
1336       <varlistentry>
1337         <term>myobj</term>
1338
1339         <listitem>
1340           <para>a user-defined parameter.</para>
1341
1342           <para>This input parameter is defined with the -outputcommandarg
1343           option.</para>
1344         </listitem>
1345       </varlistentry>
1346     </variablelist>
1347
1348     <para>The output function may be used when debugging the specialized
1349     optimization algorithm, so that a verbose logging is produced. It may also
1350     be used to write one or several report files in a specialized format
1351     (ASCII, LaTeX, Excel, Hdf5, etc...). The user-defined parameter may be
1352     used in that case to store file names or logging options.</para>
1353
1354     <para>The data tlist argument may contain more fields than the current
1355     presented ones. These additionnal fields may contain values which are
1356     specific to the specialized algorithm, such as the simplex in a
1357     Nelder-Mead method, the gradient of the cost function in a BFGS method,
1358     etc...</para>
1359   </refsection>
1360
1361   <refsection>
1362     <title>Termination</title>
1363
1364     <para>The current component takes into account for several generic
1365     termination criterias. Specialized termination criterias should be
1366     implemented in specialized optimization algorithms, by calling the
1367     optimbase_termination function and adding external criterias, rather than
1368     by modification of this function.</para>
1369
1370     <para>The optimbase_terminate function uses a set of rules to compute if
1371     the termination occurs, which leads to an optimization status which is
1372     equal to one of the following : "continue", "maxiter", "maxfunevals",
1373     "tolf", "tolx". The set of rules is the following.</para>
1374
1375     <itemizedlist>
1376       <listitem>
1377         <para>By default, the status is "continue" and the terminate flag is
1378         0.</para>
1379       </listitem>
1380
1381       <listitem>
1382         <para>The number of iterations is examined and compared to the
1383         -maxiter option : if the following condition</para>
1384
1385         <programlisting role="example"><![CDATA[ 
1386 iterations >= maxiter
1387  ]]></programlisting>
1388
1389         <para>is true, then the status is set to "maxiter" and terminate is
1390         set to 1.</para>
1391       </listitem>
1392
1393       <listitem>
1394         <para>The number of function evaluations and compared to the
1395         -maxfunevals option is examined : if the following condition</para>
1396
1397         <programlisting role="example"><![CDATA[ 
1398 funevals >= maxfunevals
1399  ]]></programlisting>
1400
1401         <para>is true, then the status is set to "maxfuneval" and terminate is
1402         set to 1.</para>
1403       </listitem>
1404
1405       <listitem>
1406         <para>The tolerance on function value is examined depending on the
1407         value of the -tolfunmethod.</para>
1408
1409         <variablelist>
1410           <varlistentry>
1411             <term>"disabled"</term>
1412
1413             <listitem>
1414               <para>then the tolerance on f is just skipped.</para>
1415             </listitem>
1416           </varlistentry>
1417
1418           <varlistentry>
1419             <term>"enabled"</term>
1420
1421             <listitem>
1422               <para>if the following condition</para>
1423
1424               <programlisting role="example"><![CDATA[ 
1425 abs(currentfopt) < tolfunrelative * abs(previousfopt) + tolfunabsolute
1426  ]]></programlisting>
1427
1428               <para>is true, then the status is set to "tolf" and terminate is
1429               set to 1.</para>
1430             </listitem>
1431           </varlistentry>
1432         </variablelist>
1433
1434         <para>The relative termination criteria on the function value works
1435         well if the function value at optimum is near zero. In that case, the
1436         function value at initial guess fx0 may be used as
1437         previousfopt.</para>
1438
1439         <para>The absolute termination criteria on the function value works if
1440         the user has an accurate idea of the optimum function value.</para>
1441       </listitem>
1442
1443       <listitem>
1444         <para>The tolerance on x is examined depending on the value of the
1445         -tolxmethod.</para>
1446
1447         <variablelist>
1448           <varlistentry>
1449             <term>"disabled"</term>
1450
1451             <listitem>
1452               <para>then the tolerance on x is just skipped.</para>
1453             </listitem>
1454           </varlistentry>
1455
1456           <varlistentry>
1457             <term>"enabled"</term>
1458
1459             <listitem>
1460               <para>if the following condition</para>
1461
1462               <programlisting role="example"><![CDATA[ 
1463 norm(currentxopt - previousxopt) < tolxrelative * norm(currentxopt) + tolxabsolute
1464  ]]></programlisting>
1465
1466               <para>is true, then the status is set to "tolx" and terminate is
1467               set to 1.</para>
1468             </listitem>
1469           </varlistentry>
1470         </variablelist>
1471
1472         <para>The relative termination criteria on the function value works
1473         well if x at optimum is different from zero. In that case, the
1474         condition measures the distance between two iterates.</para>
1475
1476         <para>The absolute termination criteria on the function value works if
1477         the user has an accurate idea of the scale of the optimum x. If the
1478         optimum x is near 0, the relative tolerance will not work and the
1479         absolute tolerance is more appropriate.</para>
1480       </listitem>
1481     </itemizedlist>
1482   </refsection>
1483
1484   <refsection>
1485     <title>Example : Setting up an optimization</title>
1486
1487     <para>In the following example, one searches the minimum of the 2D
1488     Rosenbrock function. One begins by defining the function "rosenbrock"
1489     which computes the Rosenbrock function. The traditionnal initial guess
1490     [-1.2 1.0] is used. The initial simplex is computed along the axes with a
1491     length equal to 0.1. The Nelder-Mead algorithm with variable simplex size
1492     is used. The verbose mode is enabled so that messages are generated during
1493     the algorithm. After the optimization is performed, the optimum is
1494     retrieved with quiery features.</para>
1495
1496     <programlisting role="example"><![CDATA[ 
1497 function y = rosenbrock (x)
1498   y = 100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
1499 endfunction
1500
1501 opt = optimbase_new();
1502 // Check number of variables
1503 opt = optimbase_configure(opt,"-numberofvariables",2);
1504 nbvar = optimbase_cget(opt,"-numberofvariables");
1505 // Check cost function without additionnal argument
1506 opt = optimbase_configure(opt,"-function",rosenbrock);
1507 [this,f] = optimbase_function(opt, [0.0 0.0]);
1508 opt = optimbase_destroy(opt);
1509  ]]></programlisting>
1510   </refsection>
1511
1512   <refsection>
1513     <title>Authors</title>
1514
1515     <para>Michael Baudin, 2008-2009</para>
1516   </refsection>
1517
1518   <refsection>
1519     <title>TODO</title>
1520
1521     <itemizedlist>
1522         <listitem>
1523           <para>manage equality constraints</para>
1524         </listitem>
1525
1526         <listitem>
1527           <para>manage linear constraints</para>
1528         </listitem>
1529
1530         <listitem>
1531           <para>manage quadratic objective</para>
1532         </listitem>
1533
1534         <listitem>
1535           <para>manage linear objective</para>
1536         </listitem>
1537
1538         <listitem>
1539           <para>methods with derivatives : add a flag to manage for the
1540           derivatives of the cost function</para>
1541         </listitem>
1542     </itemizedlist>
1543   </refsection>
1544 </refentry>