* Bug #8210 fixed - Inserting UMFPACK examples in the Demos gui as demos
[scilab.git] / scilab / modules / umfpack / help / en_US / condestsp.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="condestsp">
3     <refnamediv>
4         <refname>condestsp</refname>
5         <refpurpose>estimate the condition number of a sparse matrix  </refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>[K1] = condestsp(A, LUp, t)
10             [K1] = condestsp(A, LUp)
11             [K1] = condestsp(A, t)
12             [K1] = condestsp(A)
13         </synopsis>
14     </refsynopsisdiv>
15     <refsection>
16         <title>Arguments</title>
17         <variablelist>
18             <varlistentry>
19                 <term>A  </term>
20                 <listitem>
21                     <para>a real or complex square sparse matrix</para>
22                 </listitem>
23             </varlistentry>
24             <varlistentry>
25                 <term>LUp  </term>
26                 <listitem>
27                     <para>(optional) a pointer to (umf) LU factors of A obtained by a call to umf_lufact ; 
28                         if you have already computed the LU (= PAQ) factors it is recommended to give 
29                         this optional parameter (as the factorization may be time consuming)
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>t  </term>
35                 <listitem>
36                     <para>(optional) a positive integer (default value 2) by increasing this one 
37                         you may hope to get a better (even exact) estimate
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>K1  </term>
43                 <listitem>
44                     <para>estimated 1-norm condition number of A </para>
45                 </listitem>
46             </varlistentry>
47         </variablelist>
48     </refsection>
49     <refsection>
50         <title>Description</title>
51         <para>
52             Give an estimate of the 1-norm condition number of 
53             the sparse matrix A by Algorithm 2.4 appearing in :
54         </para>
55         <programlisting role=""><![CDATA[ 
56 "A block algorithm for matrix 1-norm estimation
57  with an application to 1-norm pseudospectra"
58  Nicholas J. Higham and Francoise Tisseur
59  Siam J. Matrix Anal. Appl., vol 21, No 4, pp 1185-1201
60  ]]></programlisting>
61         <para>
62             Noting the exact condition number <literal>K1e = ||A||_1 ||A^(-1)||_1</literal>, 
63             we have always <literal>K1 &lt;= K1e</literal> and this estimate gives in most case 
64             something superior to <literal>1/2 K1e</literal>
65         </para>
66     </refsection>
67     <refsection>
68         <title>Examples</title>
69         <programlisting role="example"><![CDATA[ 
70 A = sparse( [ 2  3  0  0  0;
71               3  0  4  0  6; 
72               0 -1 -3  2  0; 
73               0  0  1  0  0; 
74               0  4  2  0  1] );
75 K1 = condestsp(A)
76 // verif by direct computation
77 K1e = norm(A,1)*norm(inv(full(A)),1)
78
79 // another example
80 [A] = ReadHBSparse(SCI+"/modules/umfpack/demos/arc130.rua");
81 K1 = condestsp(A)
82 // this example is not so big so that we can do the verif
83 K1e = norm(A,1)*norm(inv(full(A)),1)
84
85 // if you have already the lu factors condestsp(A,Lup) is faster
86 // because lu factors are then not computed inside condestsp
87 Lup = umf_lufact(A);   
88 K1 = condestsp(A,Lup)
89 umf_ludel(Lup)         // clear memory
90  ]]></programlisting>
91     </refsection>
92     <refsection role="see also">
93         <title>See Also</title>
94         <simplelist type="inline">
95             <member>
96                 <link linkend="umf_lufact">umf_lufact</link>
97             </member>
98             <member>
99                 <link linkend="rcond">rcond</link>
100             </member>
101         </simplelist>
102     </refsection>
103 </refentry>