* Bug #8210 fixed - Inserting UMFPACK examples in the Demos gui as demos
[scilab.git] / scilab / modules / umfpack / help / en_US / taucs_chinfo.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_chinfo">
3     <refnamediv>
4         <refname>taucs_chinfo </refname>
5         <refpurpose>get information on Cholesky factors  </refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>[OK, n, cnz] = taucs_chinfo(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 a Cholesky factorization</para>
18                 </listitem>
19             </varlistentry>
20             <varlistentry>
21                 <term>OK  </term>
22                 <listitem>
23                     <para>a scalar boolean</para>
24                 </listitem>
25             </varlistentry>
26             <varlistentry>
27                 <term>n  </term>
28                 <listitem>
29                     <para>a scalar integer</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>cnz  </term>
34                 <listitem>
35                     <para>a scalar integer</para>
36                 </listitem>
37             </varlistentry>
38         </variablelist>
39     </refsection>
40     <refsection>
41         <title>Description</title>
42         <para>
43             This function may be used to know basic information about 
44             the Cholesky factor created with taucs_chfact :
45         </para>
46         <itemizedlist>
47             <listitem>
48                 <para>
49                     first <literal>OK</literal> is <literal>%t</literal> if <literal>C_ptr</literal> is a valid pointer to an Cholesky 
50                     factorization (and <literal>%f</literal> else)
51                 </para>
52             </listitem>
53             <listitem>
54                 <para>
55                     if <literal>OK</literal> is <literal>%t</literal> then <literal>n</literal> and <literal>cnz</literal> are respectively the 
56                     matrix order and the number of non zeros elements in the supernodal structure storing 
57                     <literal>C</literal> ; if <literal>OK</literal> is <literal>%f</literal>, <literal>n</literal> and <literal>cnz</literal> are set 
58                     to the void matrix [].
59                 </para>
60             </listitem>
61         </itemizedlist>
62     </refsection>
63     <refsection>
64         <title>Details</title>
65         <para>
66             Due to the supernodal structure used for <literal>C</literal>, <literal>cnz</literal> is larger 
67             than the exact number of non-zeros elements in <literal>C</literal> (and so this <literal>cnz</literal>
68             is a measure of the memory used internally). To get the exact <literal>cnz</literal> you may retrieve
69             the Cholesky factor with <link linkend="taucs_chget">taucs_chget</link> then apply 
70             the <link linkend="nnz">nnz</link> scilab function (see the 2d example in <link linkend="taucs_chget">taucs_chget</link>).
71         </para>
72     </refsection>
73     <refsection>
74         <title>Examples</title>
75         <programlisting role="example"><![CDATA[ 
76 // Example #1 : a small linear test system 
77 // whom solution must be [1;2;3;4;5]
78 A = sparse( [ 2 -1  0  0  0;
79              -1  2 -1  0  0; 
80               0 -1  2 -1  0; 
81               0  0 -1  2 -1; 
82               0  0  0 -1  2] );
83 b = [0 ; 0; 0; 0; 6];
84 Cp = taucs_chfact(A);
85 [OK, n, cnz]=taucs_chinfo(Cp)
86  ]]></programlisting>
87         <programlisting role="example"><![CDATA[ 
88 // Example #2 a real example
89 // first load a sparse matrix
90 [A] = ReadHBSparse(SCI+"/modules/umfpack/demos/bcsstk24.rsa");
91 // compute the factorization
92 Cp = taucs_chfact(A);
93 [OK, n, cnz]=taucs_chinfo(Cp)
94  ]]></programlisting>
95     </refsection>
96     <refsection role="see also">
97         <title>See Also</title>
98         <simplelist type="inline">
99             <member>
100                 <link linkend="taucs_chfact">taucs_chfact</link>
101             </member>
102             <member>
103                 <link linkend="taucs_chsolve">taucs_chsolve</link>
104             </member>
105             <member>
106                 <link linkend="taucs_chdel">taucs_chdel</link>
107             </member>
108             <member>
109                 <link linkend="taucs_chget">taucs_chget</link>
110             </member>
111         </simplelist>
112     </refsection>
113 </refentry>