← Back to branch summary

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

« back to all changes in this revision

Viewing changes to modules/development_tools/help/en_US/assert/assert_cond2reqdigits.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/development_tools/help/en_US/assert/assert_cond2reqdigits.xml
12
12
 *
13
13
 -->
14
14
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="assert_cond2reqdigits" xml:lang="en">
15
 
  <refnamediv>
16
 
    <refname>assert_cond2reqdigits</refname>
17
 
    <refpurpose>Suggests the number of required digits, given the condition number.</refpurpose>
18
 
  </refnamediv>
19
 
  <refsynopsisdiv>
20
 
    <title>Calling Sequence</title>
21
 
    <synopsis>
22
 
      d = assert_cond2reqdigits ( condition )
23
 
      d = assert_cond2reqdigits ( condition , offset )
24
 
      d = assert_cond2reqdigits ( condition , offset , b )
25
 
      
26
 
    </synopsis>
27
 
  </refsynopsisdiv>
28
 
  <refsection>
29
 
    <title>Parameters</title>
30
 
    <variablelist>
31
 
      <varlistentry>
32
 
        <term>condition :</term>
33
 
        <listitem>
34
 
          <para> a matrix of doubles, the condition number. The condition number must be strictly positive.</para>
35
 
        </listitem>
36
 
      </varlistentry>
37
 
      <varlistentry>
38
 
        <term>offset :</term>
39
 
        <listitem>
40
 
          <para> a matrix of doubles, a shift for the number of required base-b digits (default offset=0). For example, offset=-1 produces a smaller number of required digits (reduces the required accuracy), offset=1 produces a larger number of required digits (increases the required accuracy).</para>
41
 
        </listitem>
42
 
      </varlistentry>
43
 
      <varlistentry>
44
 
        <term>b :</term>
45
 
        <listitem>
46
 
          <para> a matrix of doubles, integer values,  the b (default b = 10).</para>
47
 
        </listitem>
48
 
      </varlistentry>
49
 
      <varlistentry>
50
 
        <term>d :</term>
51
 
        <listitem>
52
 
          <para> a matrix of doubles, the number of required digits. This is a positive real, between 0 and 15.95, if b=10 or between 0 and 53, if b=2.</para>
53
 
        </listitem>
54
 
      </varlistentry>
55
 
    </variablelist>
56
 
  </refsection>
57
 
  <refsection>
58
 
    <title>Description</title>
59
 
    <para>
60
 
      Depending on the condition number, returns the corresponding number of required decimal digits.
61
 
    </para>
62
 
    <para>
63
 
      Any optional parameter equal to the empty matrix [] is set to its default value.
64
 
    </para>
65
 
    <para>
66
 
      We emphasize that this number of required digits is only a suggestion.
67
 
      Indeed, there may be correct reasons of using a lower or a higher relative tolerance.
68
 
    </para>
69
 
    <para>
70
 
      <itemizedlist>
71
 
        <listitem>
72
 
          Consider the case where an excellent algorithm is able to make accurate computations,
73
 
          even for an ill-conditionned problem.
74
 
          In this case, we may require more accuracy (positive offset).
75
 
        </listitem>
76
 
        <listitem>
77
 
          Consider the case where there is a trade-off between performance and accuracy, where performance wins.
78
 
          In this case, we may require less accuracy (negative offset).
79
 
        </listitem>
80
 
      </itemizedlist>
81
 
    </para>
82
 
    <para>
83
 
      Any scalar input argument is expanded to a matrix of doubles of the same size as the other input arguments.
84
 
    </para>
85
 
    <para>
86
 
      The algorithm is the following.
87
 
      We compute the base-10 logarithm of condition, then subtract the offset.
88
 
      This number represents the expected number of lost digits.
89
 
      We project it into the interval [0,dmax], where dmax -log10(2^(-53)) is the maximum
90
 
      achievable number of accurate digits for doubles.
91
 
      We compute the number of required digits d, by difference between dmax and the number
92
 
      of lost digits.
93
 
      Then the relative tolerance is 10^-d.
94
 
    </para>
95
 
    <para>
96
 
    </para>
97
 
  </refsection>
98
 
  <refsection>
99
 
    <title>Examples</title>
100
 
    <programlisting role="example"><![CDATA[
 
15
    <refnamediv>
 
16
        <refname>assert_cond2reqdigits</refname>
 
17
        <refpurpose>Suggests the number of required digits, given the condition number.</refpurpose>
 
18
    </refnamediv>
 
19
    <refsynopsisdiv>
 
20
        <title>Calling Sequence</title>
 
21
        <synopsis>
 
22
            d = assert_cond2reqdigits ( condition )
 
23
            d = assert_cond2reqdigits ( condition , offset )
 
24
            d = assert_cond2reqdigits ( condition , offset , b )
 
25
            
 
26
        </synopsis>
 
27
    </refsynopsisdiv>
 
28
    <refsection>
 
29
        <title>Parameters</title>
 
30
        <variablelist>
 
31
            <varlistentry>
 
32
                <term>condition :</term>
 
33
                <listitem>
 
34
                    <para> a matrix of doubles, the condition number. The condition number must be strictly positive.</para>
 
35
                </listitem>
 
36
            </varlistentry>
 
37
            <varlistentry>
 
38
                <term>offset :</term>
 
39
                <listitem>
 
40
                    <para> a matrix of doubles, a shift for the number of required base-b digits (default offset=0). For example, offset=-1 produces a smaller number of required digits (reduces the required accuracy), offset=1 produces a larger number of required digits (increases the required accuracy).</para>
 
41
                </listitem>
 
42
            </varlistentry>
 
43
            <varlistentry>
 
44
                <term>b :</term>
 
45
                <listitem>
 
46
                    <para> a matrix of doubles, integer values,  the b (default b = 10).</para>
 
47
                </listitem>
 
48
            </varlistentry>
 
49
            <varlistentry>
 
50
                <term>d :</term>
 
51
                <listitem>
 
52
                    <para> a matrix of doubles, the number of required digits. This is a positive real, between 0 and 15.95, if b=10 or between 0 and 53, if b=2.</para>
 
53
                </listitem>
 
54
            </varlistentry>
 
55
        </variablelist>
 
56
    </refsection>
 
57
    <refsection>
 
58
        <title>Description</title>
 
59
        <para>
 
60
            Depending on the condition number, returns the corresponding number of required decimal digits.
 
61
        </para>
 
62
        <para>
 
63
            Any optional parameter equal to the empty matrix [] is set to its default value.
 
64
        </para>
 
65
        <para>
 
66
            We emphasize that this number of required digits is only a suggestion.
 
67
            Indeed, there may be correct reasons of using a lower or a higher relative tolerance.
 
68
        </para>
 
69
        <para>
 
70
            <itemizedlist>
 
71
                <listitem>
 
72
                    Consider the case where an excellent algorithm is able to make accurate computations,
 
73
                    even for an ill-conditionned problem.
 
74
                    In this case, we may require more accuracy (positive offset).
 
75
                </listitem>
 
76
                <listitem>
 
77
                    Consider the case where there is a trade-off between performance and accuracy, where performance wins.
 
78
                    In this case, we may require less accuracy (negative offset).
 
79
                </listitem>
 
80
            </itemizedlist>
 
81
        </para>
 
82
        <para>
 
83
            Any scalar input argument is expanded to a matrix of doubles of the same size as the other input arguments.
 
84
        </para>
 
85
        <para>
 
86
            The algorithm is the following.
 
87
            We compute the base-10 logarithm of condition, then subtract the offset.
 
88
            This number represents the expected number of lost digits.
 
89
            We project it into the interval [0,dmax], where dmax -log10(2^(-53)) is the maximum
 
90
            achievable number of accurate digits for doubles.
 
91
            We compute the number of required digits d, by difference between dmax and the number
 
92
            of lost digits.
 
93
            Then the relative tolerance is 10^-d.
 
94
        </para>
 
95
        <para>
 
96
        </para>
 
97
    </refsection>
 
98
    <refsection>
 
99
        <title>Examples</title>
 
100
        <programlisting role="example"><![CDATA[
101
101
assert_cond2reqdigits ( 0 ) // 15.95459
102
102
assert_cond2reqdigits ( 1 ) // 15.95459
103
103
assert_cond2reqdigits ( 1.e1 ) // 14.95459
163
163
legend(["Offset=0","Offset=+10","Offset=-10"]);
164
164
 
165
165
   ]]></programlisting>
166
 
  </refsection>
167
 
  <refsection>
168
 
    <title>History</title>
169
 
    <revhistory>
170
 
      <revision>
171
 
        <revnumber>5.4.0</revnumber>
172
 
        <revdescription>Function introduced
173
 
        </revdescription>
174
 
      </revision>
175
 
    </revhistory>
176
 
  </refsection>
 
166
    </refsection>
 
167
    <refsection>
 
168
        <title>History</title>
 
169
        <revhistory>
 
170
            <revision>
 
171
                <revnumber>5.4.0</revnumber>
 
172
                <revdescription>Function introduced
 
173
                </revdescription>
 
174
            </revision>
 
175
        </revhistory>
 
176
    </refsection>
177
177
</refentry>