help pages: toeplitz overhauled. diag, sparse, speye improved
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / diag.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  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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:ns5="http://www.w3.org/1999/xhtml"
18         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19         xmlns:scilab="http://www.scilab.org" xml:id="diag" xml:lang="en">
20     <refnamediv>
21         <refname>diag</refname>
22         <refpurpose>diagonal including or extracting</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27            y = diag(vm)
28            y = diag(vm, k)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>vm</term>
36                 <listitem>
37                     <para>vector or matrix (full or sparse storage)</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>k</term>
42                 <listitem>
43                     <para>integer (default value 0)</para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>y</term>
48                 <listitem>
49                     <para>vector or matrix</para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>
57             for <literal>vm</literal> a (row or column) n-vector
58             <literal>diag(vm)</literal> returns a diagonal matrix with entries of
59             <literal>vm</literal> along the main diagonal.
60         </para>
61         <para>
62             <literal>diag(vm,k)</literal> is a
63             <literal>(n+abs(k))x(n+abs(k))</literal> matrix with the entries of
64             <literal>vm</literal> along the kth diagonal. <literal>k=0</literal> is
65             the main diagonal <literal>k&gt;0</literal> is for upper diagonals and
66             <literal>k&lt;0</literal> for lower diagonals.
67         </para>
68         <para>
69             For a matrix <literal>vm</literal>, <literal>diag(vm,k)</literal> is
70             the column vector made of entries of the kth diagonal of
71             <literal>vm</literal>. <literal>diag(vm)</literal> is the main diagonal of
72             <literal>vm</literal>. <literal>diag(diag(x))</literal> is a diagonal
73             matrix.
74         </para>
75         <para>
76             If <literal>vm</literal> is a sparse matrix
77             <literal>diag(vm,k)</literal> returns a sparse matrix.
78         </para>
79         <para>To construct a diagonal linear system, use <literal>sysdiag</literal>.
80         </para>
81         <para>
82             Note that <literal>eye(A).*A</literal> returns a diagonal matrix
83             made with the diagonal entries of <literal>A</literal>. This is valid for
84             any matrix (constant, polynomial, rational, state-space linear
85             system,...).
86         </para>
87     </refsection>
88     <refsection>
89         <title>Examples</title>
90         <programlisting role="example"><![CDATA[
91 diag([1,2])
92
93 A=[1,2;3,4];
94 diag(A)  // main diagonal
95 diag(A,1)
96
97 diag(sparse(1:10))  // sparse diagonal matrix
98
99 // form a tridiagonal matrix of size 2*m+1
100 m=5;diag(-m:m) +  diag(ones(2*m,1),1) +diag(ones(2*m,1),-1)
101  ]]></programlisting>
102     </refsection>
103     <refsection role="see also">
104         <title>See also</title>
105         <simplelist type="inline">
106             <member>
107                 <link linkend="toeplitz">toeplitz</link>
108             </member>
109             <member>
110                 <link linkend="eye">eye</link>
111             </member>
112             <member>
113                 <link linkend="sysdiag">sysdiag</link>
114             </member>
115             <member>
116                 <link linkend="spec">spec</link>
117             </member>
118             <member>
119                 <link linkend="bdiag">bdiag</link>
120             </member>
121         </simplelist>
122     </refsection>
123 </refentry>