* Bug 10668 fixed: bloc2ss() page was inaccurate
[scilab.git] / scilab / modules / elementary_functions / help / en_US / signalprocessing / bloc2ss.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 - Serge STEER
5  * Copyright (C) 2008 - INRIA - Francois DELEBECQUE
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="bloc2ss" xml:lang="en">
21     <refnamediv>
22         <refname>bloc2ss</refname>
23         <refpurpose>block-diagram to state-space conversion</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>sl = bloc2ss(blocd)</synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>blocd</term>
34                 <listitem>
35                     <para>list</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>sl</term>
40                 <listitem>
41                     <para>list</para>
42                 </listitem>
43             </varlistentry>
44         </variablelist>
45     </refsection>
46     <refsection>
47         <title>Description</title>
48         <para>Given a block-diagram representation of a linear system
49             <literal>bloc2ss</literal> converts this representation to a state-space
50             linear system. The first element of the list <literal>blocd</literal> must
51             be the string <literal>'blocd'</literal>. Each other element of this list
52             is itself a list of one the following types :
53         </para>
54         <programlisting><![CDATA[
55 list('transfer','name_of_linear_system')
56  ]]></programlisting>
57         <programlisting><![CDATA[
58 list('link','name_of_link',
59              [number_of_upstream_box,upstream_box_port],
60              [downstream_box_1,downstream_box_1_portnumber],
61              [downstream_box_2,downstream_box_2_portnumber],
62              ...)
63  ]]></programlisting>
64         <para>
65             The strings <literal>'transfer'</literal> and
66             <literal>'link'</literal> are keywords which indicate the type of element
67             in the block diagram.
68         </para>
69         <para>Case 1 : the second parameter of the list is a character string
70             which may refer (for a possible further evaluation) to the Scilab name of
71             a linear system given in state-space representation
72             (<literal>syslin</literal> list) or in transfer form (matrix of
73             rationals).
74         </para>
75         <para>To each transfer block is associated an integer. To each input and
76             output of a transfer block is also associated its number, an integer (see
77             examples)
78         </para>
79         <para>Case 2 : the second kind of element in a block-diagram
80             representation is a link. A link links one output of a block represented
81             by the pair <literal>[number_of_upstream_box,upstream_box_port]</literal>,
82             to different inputs of other blocks. Each such input is represented by the
83             pair
84             <literal>[downstream_box_i,downstream_box_i_portnumber]</literal>.
85         </para>
86         <para>The different elements of a block-diagram can be defined in an
87             arbitrary order.
88         </para>
89         <para>For example</para>
90         <para>
91             [1] <literal>S1*S2</literal> with unit feedback.
92         </para>
93         <para>
94             There are 3 transfers <literal>S1</literal> (number
95             <literal>n_s1=2</literal>) , <literal>S2</literal> (number
96             <literal>n_s2=3</literal>) and an adder (number
97             <literal>n_add=4</literal>) with symbolic transfer function
98             <literal>['1','1']</literal>.
99         </para>
100         <para>
101             There are 4 links:
102             <itemizedlist>
103               <listitem>
104                 The first one (named <literal>'U'</literal>) links the input
105                 (port 0 of fictitious block -1, omitted) to port 1 of the adder.
106               </listitem>
107               <listitem>
108                 The second one links the (output)port 1 of the adder to the (input)port 1 of system
109                 <literal>S1</literal>.
110               </listitem>
111               <listitem>
112                 The third one links the (output)port 1 of <literal>S1</literal> to
113                 the (input)port 1 of <literal>S2</literal>.
114               </listitem>
115               <listitem>
116                 The fourth link (named <literal>'Y'</literal>) links (output)port 1 of
117                 <literal>S2</literal> to the output (port 0 of fictitious block -1,
118                 omitted) and to (input)port 2 of the adder.
119               </listitem>
120           </itemizedlist>
121         </para>
122     </refsection>
123     <refsection>
124         <title>Examples</title>
125         <programlisting role="example"><![CDATA[
126 //Initialization
127 syst=list('blocd'); l=1;
128
129 //Systems
130 l=l+1;
131 n_s1=l;
132 syst(l)=list('transfer','S1');  //System 1
133 l=l+1;
134 n_s2=l;
135 syst(l)=list('transfer','S2');  //System 2
136 l=l+1;
137 n_adder=l;
138 syst(l)=list('transfer',['1','1']);  //adder
139
140 //Links
141 // Inputs  -1 --> input 1
142 l=l+1;
143 syst(l)=list('link','U1',[-1],[n_adder,1]);
144
145 // Internal
146 l=l+1;
147 syst(l)=list('link',' ',[n_adder,1],[n_s1,1]);
148 l=l+1;
149 syst(l)=list('link',' ',[n_s1,1],[n_s2,1]);
150
151 // Outputs // -1 -> output 1
152 l=l+1;
153 syst(l)=list('link','Y',[n_s2,1],[-1],[n_adder,2]);
154  ]]></programlisting>
155         <para>
156             With <literal>s=poly(0,'s'); S1=1/(s+1);S2=1/s;</literal> the result
157             of the evaluation call <literal>sl=bloc2ss(syst);</literal> is a
158             state-space representation for <literal>1/(s^2+s-1)</literal>.
159         </para>
160         <para>[2] Example of LFT (Linear Fractional Transformation):</para>
161         <programlisting role="example"><![CDATA[
162 //Initialization
163 syst=list('blocd');
164 l=1;
165
166 //System (2x2 blocks plant)
167 l=l+1;
168 n_s=l;
169 syst(l)=list('transfer',['P11','P12';'P21','P22']);
170
171 //Controller
172 l=l+1;
173 n_k=l;
174 syst(l)=list('transfer','k');
175
176 //Links
177 l=l+1;
178 syst(l)=list('link','w',[-1],[n_s,1]);
179 l=l+1;
180 syst(l)=list('link','z',[n_s,1],[-1]);
181 l=l+1;
182 syst(l)=list('link','u',[n_k,1],[n_s,2]);
183 l=l+1;
184 syst(l)=list('link','y',[n_s,2],[n_k,1]);
185  ]]></programlisting>
186         <para>With</para>
187         <programlisting role="example"><![CDATA[
188 A=[0,1;0,0];
189 B=[1;1];
190 C=[1,1];
191 D=poly(0,'s');
192 P=syslin('c',A,B,C,D);
193  ]]></programlisting>
194     </refsection>
195     <refsection role="see also">
196         <title>See also</title>
197         <simplelist type="inline">
198             <member>
199                 <link linkend="poly">poly</link>
200             </member>
201         </simplelist>
202     </refsection>
203 </refentry>