Fix bug #12888, sysdiag also works for matrices 24/12524/6
A. Khorshidi [Thu, 12 Sep 2013 07:44:42 +0000 (09:44 +0200)]
This is just a documentation issue, sysdiag has been added to some help
files and is compatible with blkdiag (matlab).

Change-Id: Id090025e862295db3ef2e6d73ea86d3b5b3f09f1

scilab/CHANGES_5.5.X
scilab/modules/elementary_functions/help/en_US/signalprocessing/sysdiag.xml
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/_LaTeX_sysdiag.xml_1.png [new file with mode: 0644]
scilab/modules/linear_algebra/help/en_US/eigen/bdiag.xml
scilab/modules/m2sci/help/en_US/m2sci_equivalents/b/blkdiag.xml [new file with mode: 0644]

index 988937f..0ef4030 100644 (file)
@@ -675,6 +675,8 @@ Bug Fixes
 
 * Bug #12875 fixed - phasemag returned an error for input vector containing zeros.
 
+* Bug #12888 fixed - sysdiag was not documented about block diagonal matrices build.
+
 * Bug #12906 fixed - champ and champ1 help pages updated
 
 * Bug #12909 fixed - Completion on (mt)list led to a crash.
index f216041..2940e0b 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
+ * Copyright (C) 2013 - A. Khorshidi
  * 
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
@@ -13,7 +14,7 @@
 <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="sysdiag" xml:lang="en">
     <refnamediv>
         <refname>sysdiag</refname>
-        <refpurpose>block diagonal system connection</refpurpose>
+        <refpurpose>Create a block diagonal matrix from provided inputs or block diagonal system connection</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
                     <para>subsystems (i.e. gains, or linear systems in state-space or
                         transfer form)
                     </para>
+                    <para>constant, boolean, polynomial or rational matrices of any size </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>r</term>
+                <listitem>
+                    <para>a matrix with a1, a2, a3, ... on the diagonal </para>
                 </listitem>
             </varlistentry>
         </variablelist>
-        <para>Used in particular for system interconnections.</para>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Given the inputs <varname>A</varname>, <varname>B</varname> and <varname>C</varname>,
+            the output will have these matrices arranged on the diagonal:
+            <latex>\begin{bmatrix} A \ \ 0 \ \ 0 \\ 0 \ \ B \ \ 0 \\ 0 \ \ 0 \ \ C \end{bmatrix}</latex>.
+        </para>
+        <para>
+            <note>
+                If all the input matrices are square, the output is known as a <emphasis>block diagonal matrix</emphasis>.
+            </note>
+        </para>
+        <note>Used in particular for system interconnections.</note>
+        <para>
+            Beside this function, you can also use <code>sparse()</code> primitive to build a <emphasis>block diagonal sparse matrix</emphasis>.
+        </para>
+        <para>
+            For boolean matrices <code>sysdiag()</code> always returns a zero one matrix in the corresponding block
+            ("true" values are replaced by 1 and "false" value by 0).
+        </para>
+        
+        <para>
+            <code>sysdiag()</code> cannot be used to arrange matrices made of character strings,
+            but you can overload it (see: <link linkend="overloading">overloading</link>).
+        </para>
     </refsection>
     <refsection>
         <title>Remark</title>
@@ -47,6 +80,21 @@ s=poly(0,'s')
 sysdiag(rand(2,2),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])
 sysdiag(tf2ss(1/s),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])
  ]]></programlisting>
+        <programlisting role="example"><![CDATA[ 
+// a matrix of doubles: 
+A=[1 0; 0 1], B=[3 4 5; 6 7 8], C=7
+D=sysdiag(A,B,C)
+// 
+sysdiag([%t %f; %f %t], eye(2,2), ones(3,3))
+// a polynomial matrix: 
+s=%s; 
+sysdiag([s 4*s; 4 s^4], [1 s^2 s+2; 3*s 2 s^2-1])
+// a rational matrix: 
+sysdiag([1/s 2*s/(4*s+3)], [s; 4; 1/(s^2+2*s+1)])
+// a block diagonal sparse matrix:
+S=sysdiag([1 2; 3 4], [5 6; 7 8], [9 10; 11 12], [13 14; 15 16])
+S=sparse(S)
+ ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See Also</title>
@@ -60,6 +108,24 @@ sysdiag(tf2ss(1/s),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])
             <member>
                 <link linkend="feedback">feedback</link>
             </member>
+            <member>
+                <link linkend="diag">diag</link>
+            </member>
+            <member>
+                <link linkend="bdiag">bdiag</link>
+            </member>
+            <member>
+                <link linkend="sparse">sparse</link>
+            </member>
+            <member>
+                <link linkend="repmat">repmat</link>
+            </member>
         </simplelist>
     </refsection>
+    <refsection>
+        <title>References</title>
+        <para>
+            <ulink url="http://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.block_diag.html">scipy.linalg.block_diag documentation</ulink>
+        </para>
+    </refsection>
 </refentry>
index 3c74518..4e9e1b4 100644 (file)
@@ -529,6 +529,7 @@ _LaTeX_sum.xml_2.png=b4f505fff21a34a842c50a707dd320ee
 _LaTeX_sum.xml_3.png=d612fb0515b4c079f4601c435d6d0206
 _LaTeX_sum.xml_4.png=4948a5e8e21b96de5f899532c095edc0
 _LaTeX_sum.xml_5.png=87d06d76f76c0309af6fcc07606b889a
+_LaTeX_sysdiag.xml_1.png=26bcad469ac051064707c071f102456c
 _LaTeX_xcorr.xml_1.png=cf889f12f575a8118808df4285699794
 _LaTeX_xcorr.xml_10.png=3f3494a0a3abbd8e6f2fac7ab1fb4fe0
 _LaTeX_xcorr.xml_11.png=9b325b9e31e85137d1de765f43c0f8bc
diff --git a/scilab/modules/helptools/images/_LaTeX_sysdiag.xml_1.png b/scilab/modules/helptools/images/_LaTeX_sysdiag.xml_1.png
new file mode 100644 (file)
index 0000000..2df360e
Binary files /dev/null and b/scilab/modules/helptools/images/_LaTeX_sysdiag.xml_1.png differ
index 89954de..4cc6433 100644 (file)
@@ -98,6 +98,9 @@ a=rand(5,5);[ab,x,bs]=bdiag(a);ab
             <member>
                 <link linkend="spec">spec</link>
             </member>
+            <member>
+                <link linkend="sysdiag">sysdiag</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
diff --git a/scilab/modules/m2sci/help/en_US/m2sci_equivalents/b/blkdiag.xml b/scilab/modules/m2sci/help/en_US/m2sci_equivalents/b/blkdiag.xml
new file mode 100644 (file)
index 0000000..dc89594
--- /dev/null
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Clement DAVID
+ *
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at
+ * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="m2sci_blkdiag">
+    <refnamediv>
+        <refname>blkdiag (Matlab function)</refname>
+        <refpurpose>Construct block diagonal matrix from input arguments</refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Matlab/Scilab equivalent</title>
+        <informaltable border="1" width="100%">
+            <tr>
+                <td align="center">
+                    <emphasis role="bold">Matlab</emphasis>
+                </td>
+                <td align="center">
+                    <emphasis role="bold">Scilab</emphasis>
+                </td>
+            </tr>
+            <tr>
+                <td>
+                    <programlisting role="example"><![CDATA[
+blkdiag
+]]></programlisting>
+                </td>
+                <td>
+                    <programlisting role="example"><![CDATA[
+sysdiag
+]]></programlisting>
+                </td>
+            </tr>
+        </informaltable>
+    </refsection>
+</refentry>