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