quapro pushed out as a toolbox
[scilab.git] / scilab / modules / optimization / help / en_US / qld.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="qld" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:ns3="http://www.w3.org/1999/xhtml"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:db="http://docbook.org/ns/docbook">
9   <info>
10     <pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (Wed, 26 Mar 2008)
11     $</pubdate>
12   </info>
13
14   <refnamediv>
15     <refname>qld</refname>
16
17     <refpurpose>linear quadratic programming solver</refpurpose>
18   </refnamediv>
19
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22
23     <synopsis>[x,lagr]=qld(Q,p,C,b,ci,cs,me [,tol])
24 [x,lagr,info]=qld(Q,p,C,b,ci,cs,me [,tol])</synopsis>
25   </refsynopsisdiv>
26
27   <refsection>
28     <title>Parameters</title>
29
30     <variablelist>
31       <varlistentry>
32         <term>Q</term>
33
34         <listitem>
35           <para>real positive definite symmetric matrix (dimension <literal>n
36           x n</literal>).</para>
37         </listitem>
38       </varlistentry>
39
40       <varlistentry>
41         <term>p</term>
42
43         <listitem>
44           <para>real (column) vector (dimension <literal> n</literal>)</para>
45         </listitem>
46       </varlistentry>
47
48       <varlistentry>
49         <term>C</term>
50
51         <listitem>
52           <para>real matrix (dimension <literal> (me + md) x
53           n</literal>)</para>
54         </listitem>
55       </varlistentry>
56
57       <varlistentry>
58         <term>b</term>
59
60         <listitem>
61           <para>RHS column vector (dimension <literal> (me +
62           md)</literal>)</para>
63         </listitem>
64       </varlistentry>
65
66       <varlistentry>
67         <term>ci</term>
68
69         <listitem>
70           <para>column vector of lower-bounds (dimension
71           <literal>n</literal>). If there are no lower bound constraints, put
72           <literal>ci = []</literal>. If some components of
73           <literal>x</literal> are bounded from below, set the other
74           (unconstrained) values of <literal>ci</literal> to a very large
75           negative number (e.g. <literal>ci(j) =
76           -number_properties('huge')</literal>.</para>
77         </listitem>
78       </varlistentry>
79
80       <varlistentry>
81         <term>cs</term>
82
83         <listitem>
84           <para>column vector of upper-bounds. (Same remarks as above).</para>
85         </listitem>
86       </varlistentry>
87
88       <varlistentry>
89         <term>me</term>
90
91         <listitem>
92           <para>number of equality constraints (i.e. <literal>C(1:me,:)*x =
93           b(1:me)</literal>)</para>
94         </listitem>
95       </varlistentry>
96
97       <varlistentry>
98         <term>tol</term>
99
100         <listitem>
101           <para>:Floatting point number, required précision.</para>
102         </listitem>
103       </varlistentry>
104
105       <varlistentry>
106         <term>x</term>
107
108         <listitem>
109           <para>optimal solution found.</para>
110         </listitem>
111       </varlistentry>
112
113       <varlistentry>
114         <term>lagr</term>
115
116         <listitem>
117           <para>vector of Lagrange multipliers. If lower and upper-bounds
118           <literal>ci,cs</literal> are provided, <literal>lagr</literal> has
119           <literal>n + me + md</literal> components and
120           <literal>lagr(1:n)</literal> is the Lagrange vector associated with
121           the bound constraints and <literal>lagr (n+1 : n + me +
122           md)</literal> is the Lagrange vector associated with the linear
123           constraints. (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.</para>
127         </listitem>
128       </varlistentry>
129
130       <varlistentry>
131         <term>info</term>
132
133         <listitem>
134           <para>integer, return the execution status instead of sending
135           errors.</para>
136
137           <para>info==1 : Too many iterations needed</para>
138
139           <para>info==2 : Accuracy insufficient to statisfy convergence
140           criterion</para>
141
142           <para>info==5 : Length of working array is too short</para>
143
144           <para>info==10: The constraints are inconsistent</para>
145         </listitem>
146       </varlistentry>
147     </variablelist>
148   </refsection>
149
150   <refsection>
151     <title>Description</title>
152
153     <para>Minimize <literal> 0.5*x'*Q*x + p'*x</literal></para>
154
155     <para>under the constraints</para>
156
157     <programlisting>
158
159  C(j,:) x = b(j),  j=1,...,me
160  C(j,:) x &lt;= b(j), j=me+1,...,me+md
161  ci &lt;= x &lt;= cs
162    
163     </programlisting>
164
165     <para>This function requires <literal>Q</literal> to be positive definite,
166     if it is not the case, one may use the The contributed toolbox "<emphasis
167     role="bold">quapro</emphasis>".</para>
168   </refsection>
169
170   <refsection>
171     <title>Examples</title>
172
173     <programlisting role="example">
174
175 //Find x in R^6 such that:
176 //C1*x = b1 (3 equality constraints i.e me=3)
177 C1= [1,-1,1,0,3,1;
178     -1,0,-3,-4,5,6;
179      2,5,3,0,1,0];
180 b1=[1;2;3];
181 //C2*x &lt;= b2 (2 inequality constraints)
182 C2=[0,1,0,1,2,-1;
183     -1,0,2,1,1,0];
184 b2=[-1;2.5];
185 //with  x between ci and cs:
186 ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
187 //and minimize 0.5*x'*Q*x + p'*x with
188 p=[1;2;3;4;5;6]; Q=eye(6,6);
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
199   <refsection>
200     <title>See Also</title>
201
202     <simplelist type="inline">
203       <member>
204         <link linkend="qpsolve">qpsolve</link>
205       </member>
206
207       <member>
208         <link linkend="optim">optim</link>
209       </member>
210
211       <para>The contributed toolbox "quapro" may also be of interest, in
212       particular for singular <literal>Q</literal>.</para>
213     </simplelist>
214   </refsection>
215
216   <refsection>
217     <title>Authors</title>
218
219     <variablelist>
220       <varlistentry>
221         <term>K.Schittkowski</term>
222
223         <listitem>
224           <para>, University of Bayreuth, Germany</para>
225         </listitem>
226       </varlistentry>
227
228       <varlistentry>
229         <term>A.L. Tits and J.L. Zhou</term>
230
231         <listitem>
232           <para>, University of Maryland</para>
233         </listitem>
234       </varlistentry>
235     </variablelist>
236   </refsection>
237
238   <refsection>
239     <title>Used Functions</title>
240
241     <para><literal>ql0001.f</literal> in <literal>modules/optimization/src/fortran/ql0001.f</literal></para>
242   </refsection>
243 </refentry>