9ee5c15aa60b088299c9e3144c610f9e083082bc
[scilab.git] / scilab / modules / optimization / help / en_US / qpsolve.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="qpsolve" 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>March 2008</pubdate>
11   </info>
12
13   <refnamediv>
14     <refname>qpsolve</refname>
15
16     <refpurpose>linear quadratic programming solver</refpurpose>
17   </refnamediv>
18
19   <refsynopsisdiv>
20     <title>Calling Sequence</title>
21
22     <synopsis>[x [,iact [,iter [,f]]]]=qpsolve(Q,p,C,b,ci,cs,me)</synopsis>
23   </refsynopsisdiv>
24
25   <refsection>
26     <title>Parameters</title>
27
28     <variablelist>
29       <varlistentry>
30         <term>Q</term>
31
32         <listitem>
33           <para>real positive definite symmetric matrix (dimension <literal>n
34           x n</literal>).</para>
35         </listitem>
36       </varlistentry>
37
38       <varlistentry>
39         <term>p</term>
40
41         <listitem>
42           <para>real (column) vector (dimension <literal> n</literal>)</para>
43         </listitem>
44       </varlistentry>
45
46       <varlistentry>
47         <term>C</term>
48
49         <listitem>
50           <para>real matrix (dimension <literal> (me + md) x n</literal>).
51           This matrix may be stored as either a dense matrix either a sparse
52           one.</para>
53         </listitem>
54       </varlistentry>
55
56       <varlistentry>
57         <term>b</term>
58
59         <listitem>
60           <para>RHS column vector (dimension <literal> (me +
61           md)</literal>)</para>
62         </listitem>
63       </varlistentry>
64
65       <varlistentry>
66         <term>ci</term>
67
68         <listitem>
69           <para>column vector of lower-bounds (dimension
70           <literal>n</literal>). If there are no lower bound constraints, put
71           <literal>ci = []</literal>. If some components of
72           <literal>x</literal> are bounded from below, set the other
73           (unconstrained) values of <literal>ci</literal> to a very large
74           negative number (e.g. <literal>ci(j) =
75           -number_properties('huge')</literal>.</para>
76         </listitem>
77       </varlistentry>
78
79       <varlistentry>
80         <term>cs</term>
81
82         <listitem>
83           <para>column vector of upper-bounds. (Same remarks as above).</para>
84         </listitem>
85       </varlistentry>
86
87       <varlistentry>
88         <term>me</term>
89
90         <listitem>
91           <para>number of equality constraints (i.e. <literal>C(1:me,:)*x =
92           b(1:me)</literal>)</para>
93         </listitem>
94       </varlistentry>
95
96       <varlistentry>
97         <term>x</term>
98
99         <listitem>
100           <para>optimal solution found.</para>
101         </listitem>
102       </varlistentry>
103
104       <varlistentry>
105         <term>iact</term>
106
107         <listitem>
108           <para>vector, indicator of active constraints. The first non zero
109           entries give the index of the active constraints</para>
110         </listitem>
111       </varlistentry>
112
113       <varlistentry>
114         <term>iter</term>
115
116         <listitem>
117           <para>. 2x1 vector, first component gives the number of "main"
118           iterations, the second one says how many constraints were deleted
119           after they became active.</para>
120         </listitem>
121       </varlistentry>
122     </variablelist>
123   </refsection>
124
125   <refsection>
126     <title>Description</title>
127
128     <para>Minimize <literal> 0.5*x'*Q*x + p'*x</literal></para>
129
130     <para>under the constraints</para>
131
132     <programlisting>
133
134  C(j,:) x = b(j),  j=1,...,me
135  C(j,:) x &lt;= b(j), j=me+1,...,me+md
136  ci &lt;= x &lt;= cs
137    
138     </programlisting>
139
140     <para>This function requires <literal>Q</literal> to be positive definite,
141     if it is not the case, one may use the <link
142     linkend="quapro">quapro</link> function.</para>
143   </refsection>
144
145   <refsection>
146     <title>Examples</title>
147
148     <programlisting role="example">
149
150 //Find x in R^6 such that:
151 //C1*x = b1 (3 equality constraints i.e me=3)
152 C1= [1,-1,1,0,3,1;
153     -1,0,-3,-4,5,6;
154      2,5,3,0,1,0];
155 b1=[1;2;3];
156 //C2*x &lt;= b2 (2 inequality constraints)
157 C2=[0,1,0,1,2,-1;
158     -1,0,2,1,1,0];
159 b2=[-1;2.5];
160 //with  x between ci and cs:
161 ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
162 //and minimize 0.5*x'*Q*x + p'*x with
163 p=[1;2;3;4;5;6]; Q=eye(6,6);
164 //No initial point is given;
165 C=[C1;C2] ; //
166 b=[b1;b2] ;  //
167 me=3;
168 [x,iact,iter,f]=qpsolve(Q,p,C,b,ci,cs,me)
169 //Only linear constraints (1 to 4) are active 
170  
171   </programlisting>
172   </refsection>
173
174   <refsection>
175     <title>See Also</title>
176
177     <simplelist type="inline">
178       <member><link linkend="optim">optim</link></member>
179       <member><link linkend="qp_solve">qp_solve</link></member>
180       <member><link linkend="qld">qld</link></member>
181     </simplelist>
182     <para>The contributed toolbox "quapro" may also be of interest, in
183     particular for singular <literal>Q</literal>. </para>
184   </refsection>
185
186   <refsection>
187     <title>Authors</title>
188
189     <variablelist>
190       <varlistentry>
191         <term>S. Steer</term>
192
193         <listitem>
194           <para>, INRIA (Scilab interface)</para>
195         </listitem>
196       </varlistentry>
197
198       <varlistentry>
199         <term>Berwin A. Turlach</term>
200
201         <listitem>
202           <para>,School of Mathematics and Statistics (M019), The University
203           of Western Australia, Crawley, AUSTRALIA (solver code)</para>
204         </listitem>
205       </varlistentry>
206     </variablelist>
207   </refsection>
208
209   <refsection>
210     <title>Used Functions</title>
211
212     <para>qpgen1.f (also named QP.solve.f) developped by Berwin A. Turlach
213     according to the Goldfarb/Idnani algorithm</para>
214   </refsection>
215 </refentry>