Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[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     <informalequation>
154       <mediaobject>
155         <imageobject>
156           <imagedata align="center" fileref="../mml/qld_equation_1.mml" />
157         </imageobject>
158       </mediaobject>
159     </informalequation>
160
161     <para>This function requires <literal>Q</literal> to be positive definite,
162     if it is not the case, one may use the The contributed toolbox "<emphasis
163     role="bold">quapro</emphasis>".</para>
164   </refsection>
165
166   <refsection>
167     <title>Examples</title>
168
169     <programlisting role="example"><![CDATA[ 
170 //Find x in R^6 such that:
171 //C1*x = b1 (3 equality constraints i.e me=3)
172 C1= [1,-1,1,0,3,1;
173     -1,0,-3,-4,5,6;
174      2,5,3,0,1,0];
175 b1=[1;2;3];
176
177 //C2*x <= b2 (2 inequality constraints)
178 C2=[0,1,0,1,2,-1;
179     -1,0,2,1,1,0];
180 b2=[-1;2.5];
181
182 //with  x between ci and cs:
183 ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
184
185 //and minimize 0.5*x'*Q*x + p'*x with
186 p=[1;2;3;4;5;6]; Q=eye(6,6);
187
188 //No initial point is given;
189 C=[C1;C2];
190 b=[b1;b2];
191 me=3;
192 [x,lagr]=qld(Q,p,C,b,ci,cs,me)
193 //Only linear constraints (1 to 4) are active (lagr(1:6)=0):
194  ]]></programlisting>
195   </refsection>
196
197   <refsection>
198     <title>See Also</title>
199
200     <simplelist type="inline">
201       <member><link linkend="qpsolve">qpsolve</link></member>
202
203       <member><link linkend="optim">optim</link></member>
204     </simplelist>
205
206     <para>The contributed toolbox "quapro" may also be of interest, in
207     particular for singular <literal>Q</literal>.</para>
208   </refsection>
209
210   <refsection>
211     <title>Authors</title>
212
213     <variablelist>
214       <varlistentry>
215         <term>K.Schittkowski</term>
216
217         <listitem>
218           <para>, University of Bayreuth, Germany</para>
219         </listitem>
220       </varlistentry>
221
222       <varlistentry>
223         <term>A.L. Tits and J.L. Zhou</term>
224
225         <listitem>
226           <para>, University of Maryland</para>
227         </listitem>
228       </varlistentry>
229     </variablelist>
230   </refsection>
231
232   <refsection>
233     <title>Used Functions</title>
234
235     <para><literal>ql0001.f</literal> in
236     <literal>modules/optimization/src/fortran/ql0001.f</literal></para>
237   </refsection>
238 </refentry>