← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/sparse/help/en_US/decomposition/lufact.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/sparse/help/en_US/decomposition/lufact.xml
11
11
 *
12
12
 -->
13
13
<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" version="5.0-subset Scilab" xml:lang="en" xml:id="lufact">
14
 
  <refnamediv>
15
 
    <refname>lufact</refname>
16
 
    <refpurpose> sparse lu factorization</refpurpose>
17
 
  </refnamediv>
18
 
  <refsynopsisdiv>
19
 
    <title>Calling Sequence</title>
20
 
    <synopsis>[hand,rk]=lufact(A,prec)</synopsis>
21
 
  </refsynopsisdiv>
22
 
  <refsection>
23
 
    <title>Arguments</title>
24
 
    <variablelist>
25
 
      <varlistentry>
26
 
        <term>A</term>
27
 
        <listitem>
28
 
          <para>square sparse matrix</para>
29
 
        </listitem>
30
 
      </varlistentry>
31
 
      <varlistentry>
32
 
        <term>hand</term>
33
 
        <listitem>
34
 
          <para>handle to sparse lu factors</para>
35
 
        </listitem>
36
 
      </varlistentry>
37
 
      <varlistentry>
38
 
        <term>rk</term>
39
 
        <listitem>
40
 
          <para>integer  (rank of A)</para>
41
 
        </listitem>
42
 
      </varlistentry>
43
 
      <varlistentry>
44
 
        <term>prec</term>
45
 
        <listitem>
46
 
          <para>
47
 
            a vector of size two <literal>prec=[eps,reps]</literal> giving the absolute and relative  thresolds.
48
 
          </para>
49
 
        </listitem>
50
 
      </varlistentry>
51
 
    </variablelist>
52
 
  </refsection>
53
 
  <refsection>
54
 
    <title>Description</title>
55
 
    <para>
56
 
      <literal>[hand,rk]=lufact(A)</literal> performs the lu factorization of sparse matrix <literal>A</literal>.
57
 
      <literal>hand</literal> (no display) is used by <literal>lusolve</literal> (for solving linear
58
 
      system) and <literal>luget</literal> (for retrieving the factors).
59
 
      <literal>hand</literal> should be cleared by the command: <literal>ludel(hand)</literal>;
60
 
    </para>
61
 
    <para>
62
 
      The A matrix needs not be full rank but must be square 
63
 
      (since A is assumed sparse one may add zeros if necessary to squaring
64
 
      down A).
65
 
    </para>
66
 
    <variablelist>
67
 
      <varlistentry>
68
 
        <term>eps :</term>
69
 
        <listitem>
70
 
          <para>
71
 
            The absolute magnitude an element must have to be considered as a pivot candidate, except as a last resort.  This number should be set significantly smaller than the smallest diagonal element that is is expected to be placed in the matrix. the default  value is <literal>%eps</literal>.
72
 
          </para>
73
 
        </listitem>
74
 
      </varlistentry>
75
 
      <varlistentry>
76
 
        <term>reps :</term>
77
 
        <listitem>
78
 
          <para>This number determines what the pivot relative threshold will be.  It should be between zero and one.  If it is one then the pivoting method becomes complete pivoting, which is very slow and tends to fill up the matrix.  If it is set close to zero the pivoting method becomes strict Markowitz with no threshold.  The pivot threshold is used to eliminate pivot candidates that would cause excessive element growth if they were used.  Element growth is the cause of roundoff error. Element growth occurs even in well-conditioned matrices. Setting the reps large will reduce element growth and roundoff error, but setting it too large will cause execution time to be excessive and will result in a large number of fill-ins.  If this occurs, accuracy can actually be degraded because of the large number of operations required on the matrix due to the large number of fill-ins.  A good value seems to be 0.001 which is the default value.  The default is chosen by giving a value larger than one or less than or equal to zero.  This value should be increased and the matrix resolved if growth is found to be excessive.  Changing the pivot threshold does not improve performance on matrices where growth is low, as is often the case with ill-conditioned matrices. reps was chosen for use with nearly diagonally dominant matrices such as node- and modified-node admittance matrices.  For these matrices it is usually best to use diagonal pivoting.  For matrices without a strong diagonal, it is usually best to use a larger threshold, such as 0.01 or 0.1.</para>
79
 
        </listitem>
80
 
      </varlistentry>
81
 
    </variablelist>
82
 
  </refsection>
83
 
  <refsection>
84
 
    <title>Examples</title>
85
 
    <programlisting role="example"><![CDATA[ 
 
14
    <refnamediv>
 
15
        <refname>lufact</refname>
 
16
        <refpurpose> sparse lu factorization</refpurpose>
 
17
    </refnamediv>
 
18
    <refsynopsisdiv>
 
19
        <title>Calling Sequence</title>
 
20
        <synopsis>[hand,rk]=lufact(A,prec)</synopsis>
 
21
    </refsynopsisdiv>
 
22
    <refsection>
 
23
        <title>Arguments</title>
 
24
        <variablelist>
 
25
            <varlistentry>
 
26
                <term>A</term>
 
27
                <listitem>
 
28
                    <para>square sparse matrix</para>
 
29
                </listitem>
 
30
            </varlistentry>
 
31
            <varlistentry>
 
32
                <term>hand</term>
 
33
                <listitem>
 
34
                    <para>handle to sparse lu factors</para>
 
35
                </listitem>
 
36
            </varlistentry>
 
37
            <varlistentry>
 
38
                <term>rk</term>
 
39
                <listitem>
 
40
                    <para>integer  (rank of A)</para>
 
41
                </listitem>
 
42
            </varlistentry>
 
43
            <varlistentry>
 
44
                <term>prec</term>
 
45
                <listitem>
 
46
                    <para>
 
47
                        a vector of size two <literal>prec=[eps,reps]</literal> giving the absolute and relative  thresolds.
 
48
                    </para>
 
49
                </listitem>
 
50
            </varlistentry>
 
51
        </variablelist>
 
52
    </refsection>
 
53
    <refsection>
 
54
        <title>Description</title>
 
55
        <para>
 
56
            <literal>[hand,rk]=lufact(A)</literal> performs the lu factorization of sparse matrix <literal>A</literal>.
 
57
            <literal>hand</literal> (no display) is used by <literal>lusolve</literal> (for solving linear
 
58
            system) and <literal>luget</literal> (for retrieving the factors).
 
59
            <literal>hand</literal> should be cleared by the command: <literal>ludel(hand)</literal>;
 
60
        </para>
 
61
        <para>
 
62
            The A matrix needs not be full rank but must be square 
 
63
            (since A is assumed sparse one may add zeros if necessary to squaring
 
64
            down A).
 
65
        </para>
 
66
        <variablelist>
 
67
            <varlistentry>
 
68
                <term>eps :</term>
 
69
                <listitem>
 
70
                    <para>
 
71
                        The absolute magnitude an element must have to be considered as a pivot candidate, except as a last resort.  This number should be set significantly smaller than the smallest diagonal element that is is expected to be placed in the matrix. the default  value is <literal>%eps</literal>.
 
72
                    </para>
 
73
                </listitem>
 
74
            </varlistentry>
 
75
            <varlistentry>
 
76
                <term>reps :</term>
 
77
                <listitem>
 
78
                    <para>This number determines what the pivot relative threshold will be.  It should be between zero and one.  If it is one then the pivoting method becomes complete pivoting, which is very slow and tends to fill up the matrix.  If it is set close to zero the pivoting method becomes strict Markowitz with no threshold.  The pivot threshold is used to eliminate pivot candidates that would cause excessive element growth if they were used.  Element growth is the cause of roundoff error. Element growth occurs even in well-conditioned matrices. Setting the reps large will reduce element growth and roundoff error, but setting it too large will cause execution time to be excessive and will result in a large number of fill-ins.  If this occurs, accuracy can actually be degraded because of the large number of operations required on the matrix due to the large number of fill-ins.  A good value seems to be 0.001 which is the default value.  The default is chosen by giving a value larger than one or less than or equal to zero.  This value should be increased and the matrix resolved if growth is found to be excessive.  Changing the pivot threshold does not improve performance on matrices where growth is low, as is often the case with ill-conditioned matrices. reps was chosen for use with nearly diagonally dominant matrices such as node- and modified-node admittance matrices.  For these matrices it is usually best to use diagonal pivoting.  For matrices without a strong diagonal, it is usually best to use a larger threshold, such as 0.01 or 0.1.</para>
 
79
                </listitem>
 
80
            </varlistentry>
 
81
        </variablelist>
 
82
    </refsection>
 
83
    <refsection>
 
84
        <title>Examples</title>
 
85
        <programlisting role="example"><![CDATA[ 
86
86
a=rand(5,5);b=rand(5,1);A=sparse(a);
87
87
[h,rk]=lufact(A);
88
88
x=lusolve(h,b);a*x-b
89
89
ludel(h)
90
90
 ]]></programlisting>
91
 
  </refsection>
92
 
  <refsection role="see also">
93
 
    <title>See Also</title>
94
 
    <simplelist type="inline">
95
 
      <member>
96
 
        <link linkend="sparse">sparse</link>
97
 
      </member>
98
 
      <member>
99
 
        <link linkend="lusolve">lusolve</link>
100
 
      </member>
101
 
      <member>
102
 
        <link linkend="luget">luget</link>
103
 
      </member>
104
 
    </simplelist>
105
 
  </refsection>
 
91
    </refsection>
 
92
    <refsection role="see also">
 
93
        <title>See Also</title>
 
94
        <simplelist type="inline">
 
95
            <member>
 
96
                <link linkend="sparse">sparse</link>
 
97
            </member>
 
98
            <member>
 
99
                <link linkend="lusolve">lusolve</link>
 
100
            </member>
 
101
            <member>
 
102
                <link linkend="luget">luget</link>
 
103
            </member>
 
104
        </simplelist>
 
105
    </refsection>
106
106
</refentry>