scilab/modules/linear_algebra/help/en_US/matrix/det.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2008 - INRIA
   5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   6  * Copyright (C) 2021 - Samuel GOUGEON - Le Mans Université
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  19           xml:lang="en" xml:id="det">
  20     <refnamediv>
  21         <refname>det</refname>
  22         <refpurpose>determinant of a square matrix</refpurpose>
  23     </refnamediv>
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             d = det(X)
  28             [e,m] = det(X)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Arguments</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>X</term>
  36                 <listitem>
  37                     square matrix of real or complex numbers, polynomials, or rationals.
  38                     Sparse-encoded matrices accepted.
  39                     <para/>
  40                 </listitem>
  41             </varlistentry>
  42             <varlistentry>
  43                 <term>d</term>
  44                 <listitem>
  45                     Scalar of the <varname>X</varname>'s type: the determinant of
  46                     <varname>X</varname>. If <varname>X</varname> is sparse-encoded,
  47                     <varname>d</varname> is dense.
  48                     <para/>
  49                 </listitem>
  50             </varlistentry>
  51             <varlistentry>
  52                 <term>m</term>
  53                 <listitem>
  54                     real or complex number: the determinant base 10 mantissa, with
  55                     <literal>abs(m) ∈ [1,10)</literal>. Not supported for <varname>X</varname>
  56                     polynomial or rational.
  57                     <para/>
  58                 </listitem>
  59             </varlistentry>
  60             <varlistentry>
  61                 <term>e</term>
  62                 <listitem>
  63                     integer: the determinant base 10 exponent, such that
  64                     <literal>d = m * 10<superscript>e</superscript></literal>.
  65                     Not supported for <varname>X</varname> polynomial or rational.
  66                     <para/>
  67                 </listitem>
  68             </varlistentry>
  69         </variablelist>
  70     </refsection>
  71     <refsection>
  72         <title>Description</title>
  73         <para>
  74             <emphasis role="bold">d = det(X)</emphasis> yields the determinant of the matrix
  75             <varname>X</varname>.
  76         </para>
  77         <para>
  78             For a polynomial or rational matrix, <literal>d=det(X)</literal> uses <literal>determ(..)</literal>
  79             whose algorithm is based on the FFT.
  80             <literal>d=detr(X)</literal> can be alternatively used, based on the Leverrier algorithm.
  81             Both methods yield equivalent results. For rational matrices, turning off <code>simp_mode(%f)</code>
  82             might be required to get identical results.
  83         </para>
  84         <para>
  85             <emphasis role="bold">[e, m] = det(X)</emphasis> can be used only for a matrix of numbers.
  86             This syntax allows to overcome computation's underflow or overflow, when <literal>abs(d)</literal>
  87             is smaller than
  88             <literal>number_properties("tiny")</literal> ≈ 2.23 10<superscript>-308</superscript> or
  89             bigger than <literal>number_properties("huge")</literal> ≈ 1.80 10<superscript>308</superscript>.
  90         </para>
  91         <para>
  92             For denses matrices, <literal>det(..)</literal> is based on the Lapack routines
  93             DGETRF for real matrices and  ZGETRF for the complex case.
  94         </para>
  95         <para>
  96             For sparse matrices, the determinant is obtained from LU factorization thanks to the umfpack library.
  97         </para>
  98     </refsection>
  99     <refsection>
 100         <title>Examples</title>
 101         <programlisting role="example"><![CDATA[
 102 A = rand(3,3)*5;
 103 det(A)
 104 [e, m] = det(A)
 105
 106 // Matrix of complex numbers:
 107 // A = grand(3,3,"uin",0,10) + grand(3,3,"uin",0,10)*%i
 108 A = [3+%i, 9+%i*3, 9+%i ; 8+%i*8, 4+%i*3, 7+%i*7 ; 4, 6+%i*2, 6+%i*9]
 109 det(A)
 110 [e, m] = det(A)
 111 abs(m)  // in [1, 10)
 112      ]]></programlisting>
 113         <screen><![CDATA[
 114 --> A = rand(3,3)*5;
 115 --> det(A)
 116  ans  =
 117   -10.805163
 118
 119 --> [e, m] = det(A)
 120  e  =
 121    1.
 122  m  =
 123   -1.0805163
 124
 125 --> // Matrix of complex numbers:
 126 --> A = [3+%i, 9+%i*3, 9+%i ; 8+%i*8, 4+%i*3, 7+%i*7 ; 4, 6+%i*2, 6+%i*9]
 127  A  =
 128    3. + i     9. + 3.i   9. + i
 129    8. + 8.i   4. + 3.i   7. + 7.i
 130    4. + 0.i   6. + 2.i   6. + 9.i
 131
 132 --> det(A)
 133  ans  =
 134    745. - 225.i
 135
 136 --> [e, m] = det(A)
 137  e  =
 138    2.
 139  m  =
 140    7.45 - 2.25i
 141
 142 --> abs(m)  // in [1, 10)
 143  ans  =
 144    7.7823518
 145 ]]></screen>
 146         <para/>
 147         <para>
 148             Very big or small determinants: underflow and overflow handling:
 149         </para>
 150         <programlisting role="example"><![CDATA[
 151 // Very big determinant:
 152 n = 1000;
 153 A = rand(n, n);
 154 det(A)
 155 [e, m] = det(A)
 156
 157 // Very small determinant (of a sparse-encoded matrix):
 158 A = (triu(sprand(n,n,1)) + diag(rand(1,n)))/1.5;
 159 det(A)
 160 prod(diag(A))
 161 [e, m] = det(A)
 162 A = A/2;
 163 det(A)
 164 [e, m] = det(A)
 165      ]]></programlisting>
 166         <screen><![CDATA[
 167 --> // Very big determinant:
 168 --> A = rand(n, n);
 169 --> det(A)
 170  ans  =
 171   -Inf
 172
 173 --> [e, m] = det(A)  // -3.1199e743
 174  e  =
 175    743.
 176  m  =
 177   -3.1198687
 178
 179 --> // Very small determinant (of a sparse-encoded matrix):
 180 --> n = 1000;
 181 --> A = (triu(sprand(n,n,1)) + diag(rand(1,n)))/1.5;
 182 --> det(A)
 183  ans  =
 184    5.21D-236
 185
 186 --> prod(diag(A))
 187  ans  =
 188    5.21D-236
 189
 190 --> [e, m] = det(A)
 191  e  =
 192   -236.
 193  m  =
 194    5.2119757
 195
 196 --> A = A/2;
 197 --> det(A)
 198  ans  =
 199    0.
 200
 201 --> [e, m] = det(A)
 202  e  =
 203   -537.
 204  m  =
 205    4.8641473
 206 ]]></screen>
 207         <para/>
 208         <para>
 209             Determinant of a polynomial matrix:
 210         </para>
 211         <programlisting role="example"><![CDATA[
 212 s = %s;
 213 det([s, 1+s ; 2-s, s^2])
 214
 215 w = ssrand(2,2,4);
 216 roots(det(systmat(w))),trzeros(w)   //zeros of linear system
 217      ]]></programlisting>
 218         <screen><![CDATA[
 219 --> det([s, 1+s ; 2-s, s^2])
 220  ans  =
 221   -2 -s +s² +s³
 222
 223 --> w = ssrand(2,2,4);
 224 --> roots(det(systmat(w))),trzeros(w)
 225  ans  =
 226   -3.1907522 + 0.i
 227    2.3596502 + 0.i
 228
 229  ans  =
 230    2.3596502 + 0.i
 231   -3.1907522 + 0.i
 232 ]]></screen>
 233     </refsection>
 234     <refsection role="see also">
 235         <title>See also</title>
 236         <simplelist type="inline">
 237             <member>
 238                 <link linkend="detr">detr</link>
 239             </member>
 240             <member>
 241                 <link linkend="determ">determ</link>
 242             </member>
 243             <member>
 244                 <link linkend="simp_mode">simp_mode</link>
 245             </member>
 246         </simplelist>
 247     </refsection>
 248     <refsection role="history">
 249         <title>History</title>
 250         <revhistory>
 251             <revision>
 252                 <revnumber>6.1.1</revnumber>
 253                 <revdescription>
 254                     [e,m]=det(X) syntax extended to sparse matrices.
 255                 </revdescription>
 256             </revision>
 257         </revhistory>
 258     </refsection>
 259 </refentry>