[doc] misc. fix & improvements
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / backslash.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"
3           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
4           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
5           xml:lang="en" xml:id="backslash">
6     <refnamediv>
7         <refname>backslash</refname>
8         <refpurpose>(\) left matrix division.</refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Syntax</title>
12         <synopsis>X=A\B</synopsis>
13     </refsynopsisdiv>
14     <refsection>
15         <title>Description</title>
16         <para>
17             Backslash is the left matrix division:
18             <code>X=A\B</code> is a solution to <code>A*X=B</code>.
19         </para>
20         <para>
21             If <literal>A</literal> is square and non-singular <code>X=A\B</code> is
22             equivalent to <code>X=inv(A)*B</code> in exact arithmetic,
23             but the computations are more accurate and cheaper in floating point arithmetic.
24             Hence, to compute the solution of the linear system of equations <code>A*X=B</code>,
25             the backslash operator should be used, and the <function>inv</function> function
26             should be avoided.
27         </para>
28         <para>
29             In the case where <literal>A</literal> is square, the solution <literal>X</literal> can be computed
30             either from LU factorization or from a linear least squares solver.
31             If the condition number of <literal>A</literal> is smaller than <code>1/(10*%eps)</code> (i.e. if <literal>A</literal> is well conditioned),
32             the LU factorization with row pivoting is used.
33             If not (i.e. if <literal>A</literal> is poorly conditioned), then <literal>X</literal> is the minimum-norm solution which
34             minimizes <literal>||A*X-B||</literal> using a complete
35             orthogonal factorization of <literal>A</literal> (i.e. <literal>X</literal> is the solution of a linear least squares problem).
36         </para>
37         <para>
38             If <literal>A</literal> is not square, <literal>X</literal> is a least square solution,
39             i.e. <code>norm(A*X-B)</code> is minimal (Euclidean norm). If <literal>A</literal> is full
40             column rank, the least square solution, <code>X=A\B</code>, is uniquely
41             defined (there is a unique <literal>X</literal> which minimizes <code>norm(A*X-B)</code>).
42             If <literal>A</literal> is not full column rank, then the least square
43             solution is not unique, and <code>X=A\B</code>, in general, is not the solution
44             with minimum norm (the minimum norm solution is <code>X=pinv(A)*B</code>).
45         </para>
46         <para>
47             <code>A.\B</code>  is the matrix with <literal>(i,j)</literal> entry <literal>A(i,j)\B(i,j)</literal>.
48             If <literal>A</literal> (or <literal>B</literal>) is a scalar <code>A.\B</code> is equivalent to
49             <code>A*ones(B).\B</code> (or <code>A.\(B*ones(A))</code>.
50         </para>
51         <para>
52             <literal>A\.B</literal>  is an operator with no predefined meaning. It may be used
53             to define a new operator (see <link linkend="overloading">overloading</link>) with
54             the same precedence as <literal>*</literal> or <literal>/</literal>.
55         </para>
56     </refsection>
57     <refsection>
58         <title>Examples</title>
59         <programlisting role="example"><![CDATA[
60 A=[
61    9.   -36.    30.
62   -36.   192.  -180.
63    30.  -180.   180.
64 ];
65 b=[
66    3.
67   -24.
68    30.
69 ];
70 x=A\b
71 A*x-b // close to zero
72
73 A=rand(3,2);
74 b=[1;1;1];
75 x=A\b;
76 y=pinv(A)*b;
77 x-y
78 A=rand(2,3);b=[1;1];
79 x=A\b;
80 y=pinv(A)*b;
81 x-y, A*x-b, A*y-b
82
83 // if rank is deficient
84 A=rand(3,1)*rand(1,2);
85 b=[1;1;1];
86 x=A\b;
87 y=pinv(A)*b;
88 A*x-b, A*y-b
89 A=rand(2,1)*rand(1,3);
90 b=[1;1];
91 x=A\b;
92 y=pinv(A)*b;
93 A*x-b, A*y-b
94
95 // A benchmark of several linear solvers
96
97 [A,descr,ref,mtype] = ReadHBSparse(SCI+..
98    "/modules/umfpack/demos/bcsstk24.rsa");
99
100 b = zeros(size(A,1),1);
101
102 tic();
103 res = umfpack(A,'\',b);
104 mprintf('\nTime with umfpack: %.3f\n',toc());
105
106 tic();
107 res = linsolve(A,b);
108 mprintf('\ntime with linsolve: %.3f\n',toc());
109
110 tic();
111 res = A\b;
112 mprintf('\ntime with backslash: %.3f\n',toc());
113  ]]></programlisting>
114     </refsection>
115     <refsection role="see also">
116         <title>See also</title>
117         <simplelist type="inline">
118             <member>
119                 <link linkend="slash">slash</link>
120             </member>
121             <member>
122                 <link linkend="inv">inv</link>
123             </member>
124             <member>
125                 <link linkend="pinv">pinv</link>
126             </member>
127             <member>
128                 <link linkend="percent">percent</link>
129             </member>
130             <member>
131                 <link linkend="ieee">ieee</link>
132             </member>
133             <member>
134                 <link linkend="linsolve">linsolve</link>
135             </member>
136             <member>
137                 <link linkend="umfpack">umfpack</link>
138             </member>
139         </simplelist>
140     </refsection>
141     <refsection>
142         <title>History</title>
143         <revhistory>
144             <revision>
145                 <revnumber>5.5.0</revnumber>
146                 <revremark>
147                   The threshold level which switches between Gaussian Elimination with row pivoting
148                   and linear least squares when computing A\B is decreased from sqrt(eps) to eps.
149                 </revremark>
150             </revision>
151         </revhistory>
152     </refsection>
153 </refentry>