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