* Bug #8210 fixed - Inserting UMFPACK examples in the Demos gui as demos
[scilab.git] / scilab / modules / umfpack / help / en_US / umf_lufact.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="umf_lufact">
3     <refnamediv>
4         <refname>umf_lufact</refname>
5         <refpurpose>lu factorization of a sparse matrix</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>LU_ptr = umf_lufact(A)</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>A  </term>
16                 <listitem>
17                     <para>a sparse, real or complex, square or rectangular, matrix</para>
18                 </listitem>
19             </varlistentry>
20             <varlistentry>
21                 <term>LU_ptr  </term>
22                 <listitem>
23                     <para>a pointer to umf lu factors (L,U,p,q,R)</para>
24                 </listitem>
25             </varlistentry>
26         </variablelist>
27     </refsection>
28     <refsection>
29         <title>Description</title>
30         <para>
31             This function computes a LU factorization of the sparse matrix A 
32             () and return at the scilab level, 
33             a pointer (LU_ptr) to a handle of the LU factors (L,U,p,q,R) 
34             (the memory used for them is "outside" scilab stack). 
35         </para>
36         <para>
37             This function must be used in place of 
38             <link linkend="umfpack">umfpack</link>
39             if you
40             have multiple linear systems with the same matrix to solve when
41             the rhs are not known at the same time (for instance A x1 = b1
42             and A x2 = b2 but b2 depends on x1, etc...). 
43         </para>
44         <para>
45             When such a 
46             factorization have been computed, a linear system must be solved
47             with umf_lusolve (in general x = umf_lusolve(LU_ptr, b) but others
48             options are possible, see <link linkend="umf_lusolve">umf_lusolve</link>.
49             <emphasis role="bold">
50                 To free the memory used by the LU factors, use umf_ludel(LU_ptr) (<link linkend="umf_ludel">umf_ludel</link>);
51             </emphasis>
52             to retrieve the LU factors at the scilab level (for example to display their sparse 
53             patterns), use <link linkend="umf_luget">umf_luget</link>; to get some information (number of
54             non zeros in L and U), use <link linkend="umf_luinfo">umf_luinfo</link>.
55             To compute an approximation of the condition number use <link linkend="condestsp">condestsp</link>
56         </para>
57     </refsection>
58     <refsection>
59         <title>Examples</title>
60         <programlisting role="example"><![CDATA[ 
61 // this is the small linear test system from UMFPACK
62 // whom solution must be [1;2;3;4;5]
63 A = sparse( [ 2  3  0  0  0;
64               3  0  4  0  6; 
65               0 -1 -3  2  0; 
66               0  0  1  0  0; 
67               0  4  2  0  1] );
68 b = [8 ; 45; -3; 3; 19];
69 Lup = umf_lufact(A);
70 x = umf_lusolve(Lup,b)
71
72 // solve now A'x=b
73 x = umf_lusolve(Lup,b,"A''x=b")
74 norm(A'*x - b)
75
76 // do not forget to clear memory with
77 umf_ludel(Lup)
78
79 // a real (but small)  example
80 // first load a sparse matrix
81 [A] = ReadHBSparse(SCI+"/modules/umfpack/demos/arc130.rua");
82 // compute the factorization
83 Lup = umf_lufact(A); 
84 b = rand(size(A,1),1); // a random rhs
85 // use umf_lusolve for solving Ax=b
86 x = umf_lusolve(Lup,b);
87 norm(A*x - b)
88
89 // now the same thing with iterative refiment
90 x = umf_lusolve(Lup,b,"Ax=b",A);
91 norm(A*x - b)
92
93 // solve now the system A'x=b
94 x = umf_lusolve(Lup,b,"A''x=b");  // without refinement
95 norm(A'*x - b)
96 x = umf_lusolve(Lup,b,"A''x=b",A);  // with refinement
97 norm(A'*x - b)
98
99 // do not forget to clear memory
100 umf_ludel(Lup)
101  ]]></programlisting>
102     </refsection>
103     <refsection role="see also">
104         <title>See Also</title>
105         <simplelist type="inline">
106             <member>
107                 <link linkend="umfpack">umfpack</link>
108             </member>
109             <member>
110                 <link linkend="umf_luget">umf_luget</link>
111             </member>
112             <member>
113                 <link linkend="umf_lusolve">umf_lusolve</link>
114             </member>
115             <member>
116                 <link linkend="umf_ludel">umf_ludel</link>
117             </member>
118             <member>
119                 <link linkend="umf_luinfo">umf_luinfo</link>
120             </member>
121             <member>
122                 <link linkend="condestsp">condestsp</link>
123             </member>
124         </simplelist>
125     </refsection>
126 </refentry>