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