c6df8626b79fc53ec284c966f5bf4efdbd00a16a
[scilab.git] / 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>