Optimization module: minor improvements in qpsolve() and qld() docs
[scilab.git] / scilab / modules / optimization / help / en_US / qld.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="qld" xml:lang="en">
3     <refnamediv>
4         <refname>qld</refname>
5         <refpurpose>linear quadratic programming solver</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>
10             [x [,lagr [,info]]] = qld(Q, p, C, b, ci, cs, me [,tol])
11         </synopsis>
12     </refsynopsisdiv>
13     <refsection>
14         <title>Arguments</title>
15         <variablelist>
16             <varlistentry>
17                 <term>Q</term>
18                 <listitem>
19                     <para>
20                         real positive definite symmetric matrix (dimension <literal>
21                             n
22                             x n
23                         </literal>
24                         ).
25                     </para>
26                 </listitem>
27             </varlistentry>
28             <varlistentry>
29                 <term>p</term>
30                 <listitem>
31                     <para>
32                         real (column) vector (dimension <literal> n</literal>)
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>C</term>
38                 <listitem>
39                     <para>
40                         real matrix (dimension <literal>
41                             (me + md) x
42                             n
43                         </literal>
44                         )
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>b</term>
50                 <listitem>
51                     <para>
52                         RHS column vector (dimension <literal>
53                             (me +
54                             md)
55                         </literal>
56                         )
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>ci</term>
62                 <listitem>
63                     <para>
64                         column vector of lower-bounds (dimension
65                         <literal>n</literal>). If there are no lower bound constraints, put
66                         <literal>ci = []</literal>. If some components of
67                         <literal>x</literal> are bounded from below, set the other
68                         (unconstrained) values of <literal>ci</literal> to a very large
69                         negative number (e.g. <literal>
70                             ci(j) =
71                             -number_properties('huge')
72                         </literal>
73                         .
74                     </para>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>cs</term>
79                 <listitem>
80                     <para>column vector of upper-bounds. (Same remarks as above).</para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>me</term>
85                 <listitem>
86                     <para>
87                         number of equality constraints (i.e. <literal>
88                             C(1:me,:)*x =
89                             b(1:me)
90                         </literal>
91                         )
92                     </para>
93                 </listitem>
94             </varlistentry>
95             <varlistentry>
96                 <term>tol</term>
97                 <listitem>
98                     <para>Floatting point number, required precision.</para>
99                 </listitem>
100             </varlistentry>
101             <varlistentry>
102                 <term>x</term>
103                 <listitem>
104                     <para>optimal solution found.</para>
105                 </listitem>
106             </varlistentry>
107             <varlistentry>
108                 <term>lagr</term>
109                 <listitem>
110                     <para>
111                         vector of Lagrange multipliers.
112                         <para>
113                             If lower and upper-bounds
114                             <literal>ci, cs</literal> are provided, <literal>lagr</literal> has
115                             <literal>me + md + 2* n</literal> components. The components <literal>lagr(1:me + md)</literal>
116                             are associated with
117                             the linear constraints and <literal>
118                                 lagr (me + md + 1 : 2 * n)
119                             </literal>
120                             are associated with the lower and upper bounds constraints.
121                         </para>
122                         <para>
123                             If an upper-bound (resp. lower-bound) constraint
124                             <literal>i</literal> is active <literal>lagr(i)</literal> is &gt; 0
125                             (resp. &lt;0). If no bounds are provided, <literal>lagr</literal>
126                             has only <literal>me + md</literal> components.
127                         </para>
128                         <para>
129                             On successful termination, all values of <literal>lagr</literal> with respect to inequalities
130                             and bounds should be greater or equal to zero.
131                         </para>
132                     </para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>info</term>
137                 <listitem>
138                     <para>
139                         integer, return the execution status instead of sending
140                         errors.
141                     </para>
142                     <para>info==1 : Too many iterations needed</para>
143                     <para>
144                         info==2 : Accuracy insufficient to statisfy convergence
145                         criterion
146                     </para>
147                     <para>info==5 : Length of working array is too short</para>
148                     <para>info==10: The constraints are inconsistent</para>
149                 </listitem>
150             </varlistentry>
151         </variablelist>
152     </refsection>
153     <refsection>
154         <title>Description</title>
155         <informalequation>
156             <mediaobject>
157                 <imageobject>
158                     <imagedata align="center" fileref="../mml/qld_equation_1.mml"/>
159                 </imageobject>
160             </mediaobject>
161         </informalequation>
162         <para>
163             This function requires <literal>Q</literal> to be positive definite,
164             if it is not the case, one may use the contributed toolbox "<emphasis role="bold">quapro</emphasis>".
165         </para>
166     </refsection>
167     <refsection>
168         <title>Examples</title>
169         <programlisting role="example">
170             <![CDATA[ 
171 //Find x in R^6 such that:
172 //C1*x = b1 (3 equality constraints i.e me=3)
173 C1= [1,-1,1,0,3,1;
174     -1,0,-3,-4,5,6;
175      2,5,3,0,1,0];
176 b1=[1;2;3];
177
178 //C2*x <= b2 (2 inequality constraints i.e md=2)
179 C2=[0,1,0,1,2,-1;
180     -1,0,2,1,1,0];
181 b2=[-1;2.5];
182
183 //with  x between ci and cs:
184 ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
185
186 //and minimize 0.5*x'*Q*x + p'*x with
187 p=[1;2;3;4;5;6]; Q=eye(6,6);
188
189 //No initial point is given;
190 C=[C1;C2];
191 b=[b1;b2];
192 me=3;
193 [x,lagr]=qld(Q,p,C,b,ci,cs,me)
194 //Only linear constraints (1 to 4) are active (lagr(1:6)=0):
195  ]]>
196         </programlisting>
197     </refsection>
198     <refsection role="see also">
199         <title>See Also</title>
200         <simplelist type="inline">
201             <member>
202                 <link linkend="qpsolve">qpsolve</link>
203             </member>
204             <member>
205                 <link linkend="optim">optim</link>
206             </member>
207         </simplelist>
208         <para>
209             The contributed toolbox "quapro" may also be of interest, in
210             particular for singular <literal>Q</literal>.
211         </para>
212     </refsection>
213     <refsection>
214         <title>Used Functions</title>
215         <para>
216             <literal>ql0001.f</literal> in
217             <literal>modules/optimization/src/fortran/ql0001.f</literal>
218         </para>
219     </refsection>
220 </refentry>