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