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