help pages: toeplitz overhauled. diag, sparse, speye improved
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / toeplitz.xml
index 926abf2..c2d8f06 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
+ * Copyright (C) 2017 - Samuel GOUGEON
  *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="toeplitz" xml:lang="en">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+    xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+    xmlns:scilab="http://www.scilab.org" xml:id="toeplitz" xml:lang="en">
     <refnamediv>
         <refname>toeplitz</refname>
-        <refpurpose>Toeplitz matrix</refpurpose>
+        <refpurpose>Toeplitz matrix (chosen constant diagonal bands)</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>A=toeplitz(c [,r])</synopsis>
+        <synopsis>
+            A = toeplitz(c)
+            A = toeplitz(c, r)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>a,c,r</term>
+                <term>c, r</term>
                 <listitem>
-                    <para>constant, polynomial or string matrices</para>
+                    <para>
+                        vectors or matrices of booleans, numbers, polynomials, rationals, or texts,
+                        dense or sparse encoded (booleans or numbers).
+                    </para>
+                    <para>
+                        <varname>c</varname> are values expected on the first column and subsequent
+                        lower diagonals. <varname>r</varname> are values expected on the first row
+                        and subsequent upper diagonals.
+                    </para>
+                    <para>
+                        If both <literal>c</literal> and <literal>r</literal> are provided,
+                        <literal>c(1)==r(1)</literal> is required.
+                    </para>
+                    <para>
+                        The types of <literal>c</literal> and <literal>r</literal> must be compatible
+                        w.r.t. the concatenation.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>A</term>
+                <listitem>
+                    <para>
+                     Matrix of the type of <varname>c</varname> and <varname>r</varname>
+                    (with usual types priorities)
+                    </para>
+                    <para>
+                        <varname>A</varname> is of size <literal>[size(c,"*"), size(c,"*")]</literal>
+                        or <literal>[size(c,"*"), size(r,"*")]</literal>.
+                    </para>
+                    <para>
+                        <varname>A</varname> is sparse encoded as soon as either <varname>c</varname>
+                        or <varname>r</varname> or both are sparse encoded.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>A=toeplitz(c [,r])</literal> returns the Toeplitz matrix whose first row is <literal>r</literal>
-            and first column is <literal>c</literal>. <literal>c(1)</literal> must be
-            equal to <literal>r(1)</literal>. <literal>toeplitz(c)</literal> returns
-            the symmetric Toeplitz matrix.
+            <literal>A=toeplitz(c, r)</literal> returns the Toeplitz matrix whose first row is
+            <literal>r</literal> and first column is <literal>c</literal>.
+            <literal>toeplitz(c)</literal> returns the symmetric Toeplitz matrix.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-A=toeplitz(1:5);
+toeplitz(0:3)
+ ]]></programlisting>
+    <screen><![CDATA[
+--> toeplitz(0:3)
+ ans  =
+   0.   1.   2.   3.
+   1.   0.   1.   2.
+   2.   1.   0.   1.
+   3.   2.   1.   0.
+]]></screen>
+    <para/>
+    <programlisting role="example"><![CDATA[
+toeplitz([0 1 0 0 ], [0 -1 -2 0 0 0])
+ ]]></programlisting>
+    <screen><![CDATA[
+--> toeplitz([0 1 0 0 ], [0 -1 -2 0 0 0])
+ ans  =
+   0.  -1.  -2.   0.   0.   0.
+   1.   0.  -1.  -2.   0.   0.
+   0.   1.   0.  -1.  -2.   0.
+   0.   0.   1.   0.  -1.  -2.
+]]></screen>
+    <para/>
+    <para>With sparse encoded arrays: </para>
+    <programlisting role="example"><![CDATA[
+v = [0 1:2 0 0];
+S = toeplitz(v, sparse(-v));
+typeof(S)
+full(S)
+ ]]></programlisting>
+    <screen><![CDATA[
+--> typeof(S)
+ ans  =
+ sparse
 
-T=toeplitz(1:5,1:2:7);T1=[1 3 5 7;2 1 3 5;3 2 1 3;4 3 2 1;5 4 3 2];
-T-T1
+--> full(S)
+ ans  =
+   0.  -1.  -2.   0.   0.
+   1.   0.  -1.  -2.   0.
+   2.   1.   0.  -1.  -2.
+   0.   2.   1.   0.  -1.
+   0.   0.   2.   1.   0.
+]]></screen>
+    <para/>
+    <para>With texts: </para>
+    <programlisting role="example"><![CDATA[
+toeplitz(["-" "A" "B" "C"],["-" "a" "b" "c" "d" "e"])
+ ]]></programlisting>
+    <screen><![CDATA[
+--> toeplitz(["-" "A" "B" "C"],["-" "a" "b" "c" "d" "e"])
+ ans  =
+!-  a  b  c  d  e  !
+!A  -  a  b  c  d  !
+!B  A  -  a  b  c  !
+!C  B  A  -  a  b  !
+]]></screen>
+    <para/>
+    <para>With polynomials: </para>
+    <programlisting role="example"><![CDATA[
+toeplitz([%s %s^2 %s^3], [%s 1:4])
+ ]]></programlisting>
+    <screen><![CDATA[
+--> toeplitz([%s %s^2 %s^3], [%s 1:4])
+ ans  =
+   s    1    2   3   4
 
-s=poly(0,'s');
-t=toeplitz([s,s+1,s^2,1-s]);
-t1=[s,1+s,s*s,1-s;1+s,s,1+s,s*s;s*s,1+s,s,1+s;1-s,s*s,1+s,s]
-t-t1
+    2
+   s    s    1   2   3
 
-t=toeplitz(['1','2','3','4']);
-t1=['1','2','3','4';'2','1','2','3';'3','2','1','2';'4','3','2','1']
- ]]></programlisting>
+    3    2
+   s    s    s   1   2
+]]></screen>
+    <para/>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="matrix">matrix</link>
+                <link linkend="diag">diag</link>
+            </member>
+            <member>
+                <link linkend="eye">eye</link>
             </member>
             <member>
                 <link linkend="testmatrix">testmatrix</link>