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