quapro pushed out as a toolbox
[scilab.git] / scilab / modules / optimization / help / en_US / qp_solve.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="qp_solve" 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>qp_solve</refname>
15
16     <refpurpose>linear quadratic programming solver builtin</refpurpose>
17   </refnamediv>
18
19   <refsynopsisdiv>
20     <title>Calling Sequence</title>
21
22     <synopsis>[x [,iact [,iter [,f]]]]=qp_solve(Q,p1,C1,b,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>me</term>
67
68         <listitem>
69           <para>number of equality constraints (i.e. <literal>x'*C(:,1:me) =
70           b(1:me)'</literal>)</para>
71         </listitem>
72       </varlistentry>
73
74       <varlistentry>
75         <term>x</term>
76
77         <listitem>
78           <para>optimal solution found.</para>
79         </listitem>
80       </varlistentry>
81
82       <varlistentry>
83         <term>iact</term>
84
85         <listitem>
86           <para>vector, indicator of active constraints. The first non zero
87           entries give the index of the active constraints</para>
88         </listitem>
89       </varlistentry>
90
91       <varlistentry>
92         <term>iter</term>
93
94         <listitem>
95           <para>. 2x1 vector, first component gives the number of "main"
96           iterations, the second one says how many constraints were deleted
97           after they became active.</para>
98         </listitem>
99       </varlistentry>
100     </variablelist>
101   </refsection>
102
103   <refsection>
104     <title>Description</title>
105
106     <para>Minimize <literal> 0.5*x'*Q*x - p'*x</literal></para>
107
108     <para>under the constraints</para>
109
110     <programlisting>
111
112  x' C(:,j) = b(j),  j=1,...,me
113  x' C(:,j) &gt;= b(j), j=me+1,...,me+md
114    
115     </programlisting>
116
117     <para>This function requires <literal>Q</literal> to be positive definite,
118     if it is not the case, one may use the contributed <emphasis
119     role="bold">quapro toolbox</emphasis>.</para>
120
121     <para>This is a builtin associated with the Berwin A. Turlach code. Use
122     preferabily the <link linkend="qpgen">qpgen</link> function built on it
123     which handles variable boundaries and match the <emphasis
124     role="bold">quapro</emphasis> problem definition</para>
125   </refsection>
126
127   <refsection>
128     <title>Examples</title>
129
130     <programlisting role="example">
131
132 //Find x in R^6 such that:
133 //x'*C1 = b1 (3 equality constraints i.e me=3)
134 C1= [ 1,-1, 2;
135      -1, 0, 5;
136       1,-3, 3;
137       0,-4, 0;
138       3, 5, 1;
139       1, 6, 0];
140 b1=[1;2;3];
141
142 //x'*C2 &gt;= b2 (2 inequality constraints)
143 C2= [ 0 ,1;
144      -1, 0;
145       0,-2;
146      -1,-1;
147      -2,-1;
148       1, 0];
149 b2=[ 1;-2.5];
150
151 //and minimize 0.5*x'*Q*x - p'*x with
152 p=[-1;-2;-3;-4;-5;-6]; Q=eye(6,6);
153
154 me=3;
155 [x,iact,iter,f]=qp_solve(Q,p,[C1 C2],[b1;b2],me)
156 //Only linear constraints (1 to 4) are active 
157  
158   </programlisting>
159   </refsection>
160
161   <refsection>
162     <title>See Also</title>
163
164     <simplelist type="inline">
165       <member><link linkend="optim">optim</link></member>
166
167       <member><link linkend="qld">qld</link></member>
168     </simplelist>
169
170     <para>The contributed toolbox "quapro" may also be of interest, in
171     particular for singular <literal>Q</literal>.</para>
172   </refsection>
173
174   <refsection>
175     <title>Authors</title>
176
177     <variablelist>
178       <varlistentry>
179         <term>S. Steer</term>
180
181         <listitem>
182           <para>, INRIA (Scilab interface)</para>
183         </listitem>
184       </varlistentry>
185
186       <varlistentry>
187         <term>Berwin A. Turlach</term>
188
189         <listitem>
190           <para>,School of Mathematics and Statistics (M019), The University
191           of Western Australia, Crawley, AUSTRALIA (solver code)</para>
192         </listitem>
193       </varlistentry>
194     </variablelist>
195   </refsection>
196
197   <refsection>
198     <title>Used Functions</title>
199
200     <para>qpgen2.f and &gt;qpgen1.f (also named QP.solve.f) developped by
201     Berwin A. Turlach according to the Goldfarb/Idnani algorithm</para>
202   </refsection>
203 </refentry>