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