* Bug #8210 fixed - Inserting UMFPACK examples in the Demos gui as demos
[scilab.git] / scilab / modules / umfpack / help / en_US / taucs_chget.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="taucs_chget">
3     <refnamediv>
4         <refname>taucs_chget</refname>
5         <refpurpose>retrieve the Cholesky factorization at the scilab level  </refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>[Ct,p] = taucs_chget(C_ptr)</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>C_ptr  </term>
16                 <listitem>
17                     <para>a pointer to the Cholesky factorization (C,p : A(p,p)=CC')</para>
18                 </listitem>
19             </varlistentry>
20             <varlistentry>
21                 <term>Ct  </term>
22                 <listitem>
23                     <para>a scilab sparse matrix (you get the upper triangle i.e. Ct is equal to C') </para>
24                 </listitem>
25             </varlistentry>
26             <varlistentry>
27                 <term>p  </term>
28                 <listitem>
29                     <para>column vector storing the permutation</para>
30                 </listitem>
31             </varlistentry>
32         </variablelist>
33     </refsection>
34     <refsection>
35         <title>Description</title>
36         <para>
37             This function  may be used if you want  to plot  the sparse
38             pattern  of the Cholesky factorization (or if you  code something which
39             use the factors). Traditionally, the factorization is written :
40         </para>
41         <programlisting role=""><![CDATA[ 
42 P A P' = C C'
43  ]]></programlisting>
44         <para>
45             with P' the permutation matrix associated to the permutation p.
46             As we get the upper triangle Ct (= C'), in scilab syntax we
47             can write :
48         </para>
49         <programlisting role=""><![CDATA[ 
50 A(p,p) = Ct' * Ct
51  ]]></programlisting>
52     </refsection>
53     <refsection>
54         <title>Examples</title>
55         <programlisting role="example"><![CDATA[
56 // Example #1 : a small linear test system
57 A = sparse( [ 2 -1  0  0  0;
58              -1  2 -1  0  0;
59               0 -1  2 -1  0;
60               0  0 -1  2 -1;
61               0  0  0 -1  2] );
62 Cp = taucs_chfact(A);
63 [Ct, p] = taucs_chget(Cp);
64 full(A(p,p) - Ct'*Ct)  // this must be near the null matrix
65 taucs_chdel(Cp)
66  ]]></programlisting>
67         
68         <programlisting role="example"><![CDATA[
69 // Example #2 a real example
70 // first load a sparse matrix
71 [A] = ReadHBSparse(SCI+"/modules/umfpack/demos/bcsstk24.rsa");
72 // compute the factorization
73 Cptr = taucs_chfact(A);
74 // retrieve the factor at scilab level
75 [Ct, p] = taucs_chget(Cptr);
76 // plot the initial matrix
77 xset("window",0) ; clf()
78 PlotSparse(A) ; xtitle("Initial matrix A (bcsstk24.rsa)")
79 // plot the permuted matrix
80 B = A(p,p);
81 xset("window",1) ; clf()
82 PlotSparse(B) ; xtitle("Permuted matrix B = A(p,p)")
83 // plot the upper triangle Ct
84 xset("window",2) ; clf()
85 PlotSparse(Ct) ; xtitle("The pattern of Ct (A(p,p) = C*Ct)")
86 // retrieve cnz
87 [OK, n, cnz] = taucs_chinfo(Cptr)
88 // cnz is superior to the realnumber of non zeros elements of C :
89 cnz_exact = nnz(Ct)
90 // do not forget to clear memory
91 taucs_chdel(Cptr)
92  ]]></programlisting>
93         <scilab:image>
94             [A] = ReadHBSparse(SCI+"/modules/umfpack/demos/bcsstk24.rsa");
95             Cptr = taucs_chfact(A);
96             [Ct, p] = taucs_chget(Cptr);
97             PlotSparse(A) ; xtitle("Initial matrix A (bcsstk24.rsa)")
98         </scilab:image>
99     </refsection>
100     <refsection role="see also">
101         <title>See Also</title>
102         <simplelist type="inline">
103             <member>
104                 <link linkend="taucs_chfact">taucs_chfact</link>
105             </member>
106             <member>
107                 <link linkend="taucs_chsolve">taucs_chsolve</link>
108             </member>
109             <member>
110                 <link linkend="taucs_chdel">taucs_chdel</link>
111             </member>
112             <member>
113                 <link linkend="taucs_chinfo">taucs_chinfo</link>
114             </member>
115             <member>
116                 <link linkend="taucs_chget">taucs_chget</link>
117             </member>
118             <member>
119                 <link linkend="cond2sp">cond2sp</link>
120             </member>
121         </simplelist>
122     </refsection>
123 </refentry>