Bug #9619: The qp_solve help page, the input arguments were different between calling...
[scilab.git] / scilab / modules / optimization / help / en_US / qp_solve.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" version="5.0-subset Scilab" xml:id="qp_solve" xml:lang="en">
3     <refnamediv>
4         <refname>qp_solve</refname>
5         <refpurpose>linear quadratic programming solver builtin</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>[x [,iact [,iter [,f]]]] = qp_solve(Q, p, C, b, me)</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>Q</term>
16                 <listitem>
17                     <para>
18                         real positive definite symmetric matrix (dimension <literal>n
19                             x n
20                         </literal>
21                         ).
22                     </para>
23                 </listitem>
24             </varlistentry>
25             <varlistentry>
26                 <term>p</term>
27                 <listitem>
28                     <para>
29                         real (column) vector (dimension <literal> n</literal>)
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>C</term>
35                 <listitem>
36                     <para>
37                         real matrix (dimension <literal> (me + md) x n</literal>).
38                         This matrix may be dense or sparse.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>b</term>
44                 <listitem>
45                     <para>
46                         RHS column vector (dimension <literal> m=(me +
47                             md)
48                         </literal>
49                         )
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>me</term>
55                 <listitem>
56                     <para>
57                         number of equality constraints (i.e. <literal>x'*C(:,1:me) =
58                             b(1:me)'
59                         </literal>
60                         )
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>x</term>
66                 <listitem>
67                     <para>optimal solution found.</para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>iact</term>
72                 <listitem>
73                     <para>vector, indicator of active constraints. The first non zero
74                         entries give the index of the active constraints
75                     </para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>iter</term>
80                 <listitem>
81                     <para>2x1 vector, first component gives the number of "main"
82                         iterations, the second one says how many constraints were deleted
83                         after they became active.
84                     </para>
85                 </listitem>
86             </varlistentry>
87         </variablelist>
88     </refsection>
89     <refsection>
90         <title>Description</title>
91         <informalequation>
92             <mediaobject>
93                 <imageobject>
94                     <imagedata align="center" fileref="../mml/qp_solve_equation_1.mml"/>
95                 </imageobject>
96             </mediaobject>
97         </informalequation>
98         <para>
99             This function requires <literal>Q</literal> to be symmetric positive
100             definite. If this hypothesis is not satisfied, one may use the contributed
101             <emphasis role="bold">quapro toolbox</emphasis>.
102         </para>
103     </refsection>
104     <refsection>
105         <title>Examples</title>
106         <programlisting role="example"><![CDATA[ 
107 // Find x in R^6 such that:
108 // x'*C1 = b1 (3 equality constraints i.e me=3)
109 C1= [ 1,-1, 2;
110      -1, 0, 5;
111       1,-3, 3;
112       0,-4, 0;
113       3, 5, 1;
114       1, 6, 0];
115 b1=[1;2;3];
116
117 // x'*C2 >= b2 (2 inequality constraints)
118 C2= [ 0 ,1;
119      -1, 0;
120       0,-2;
121      -1,-1;
122      -2,-1;
123       1, 0];
124 b2=[ 1;-2.5];
125
126 // and minimize 0.5*x'*Q*x - p'*x with
127 p=[-1;-2;-3;-4;-5;-6]; Q=eye(6,6);
128
129 me=3;
130 [x,iact,iter,f]=qp_solve(Q,p,[C1 C2],[b1;b2],me)
131 // Only linear constraints (1 to 4) are active 
132  ]]></programlisting>
133     </refsection>
134     <refsection role="see also">
135         <title>See Also</title>
136         <simplelist type="inline">
137             <member>
138                 <link linkend="optim">optim</link>
139             </member>
140             <member>
141                 <link linkend="qld">qld</link>
142             </member>
143             <member>
144                 <link linkend="qpsolve">qpsolve</link>
145             </member>
146         </simplelist>
147         <para>The contributed toolbox "quapro" may also be of interest, in
148             particular for singular <literal>Q</literal>.
149         </para>
150     </refsection>
151     <refsection>
152         <title>Memory requirements</title>
153         <para>Let r be</para>
154         <programlisting> 
155             r=min(m,n)
156         </programlisting>
157         <para>Then the memory required by qp_solve during the computations
158             is
159         </para>
160         <programlisting> 
161             2*n+r*(r+5)/2 + 2*m +1
162         </programlisting>
163     </refsection>
164     <refsection>
165         <title>References</title>
166         <itemizedlist>
167             <listitem>
168                 <para>Goldfarb, D. and Idnani, A. (1982). "Dual and Primal-Dual
169                     Methods for Solving Strictly Convex Quadratic Programs", in J.P.
170                     Hennart (ed.), Numerical Analysis, Proceedings, Cocoyoc, Mexico 1981,
171                     Vol. 909 of Lecture Notes in Mathematics, Springer-Verlag, Berlin, pp.
172                     226-239.
173                 </para>
174             </listitem>
175             <listitem>
176                 <para>Goldfarb, D. and Idnani, A. (1983). "A numerically stable dual
177                     method for solving strictly convex quadratic programs", Mathematical
178                     Programming 27: 1-33.
179                 </para>
180             </listitem>
181             <listitem>
182                 <para>QuadProg (Quadratic Programming Routines), Berwin A
183                     Turlach,<ulink url="http://www.maths.uwa.edu.au/~berwin/software/quadprog.html">http://www.maths.uwa.edu.au/~berwin/software/quadprog.html</ulink>
184                 </para>
185             </listitem>
186         </itemizedlist>
187     </refsection>
188     <refsection>
189         <title>Used Functions</title>
190         <para>qpgen2.f and &gt;qpgen1.f (also named QP.solve.f) developed by
191             Berwin A. Turlach according to the Goldfarb/Idnani algorithm
192         </para>
193     </refsection>
194 </refentry>