d3a4b14b18c28818f2dc17ef93fce2b971fb74d1
[scilab.git] / scilab / modules / cacsd / help / en_US / linear_analysis / freq_domain / bode.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) 1996 - 2016 - INRIA - Serge Steer <serge.steer@inria.fr>
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org"  xml:id="bode" xml:lang="en">
20     <refnamediv>
21         <refname>bode</refname>
22         <refpurpose>Bode plot</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             bode(sl)
28             bode(sl, fmin, fmax)
29             bode(sl, fmin, fmax, step)
30             bode(sl, frq)
31             bode(frq, db, phi)
32             bode(frq, repf)
33             bode(.., Captions)
34             bode(.., Captions, "rad")
35         </synopsis>
36     </refsynopsisdiv>
37     <refsection>
38         <title>Arguments</title>
39         <variablelist>
40             <varlistentry>
41                 <term>sl</term>
42                 <listitem>
43                     <para>
44                         A siso or simo linear dynamical system, in state space, transfer function or zpk representations, in continuous or discrete time.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>fmin,fmax</term>
50                 <listitem>
51                     <para>real (frequency bounds (in Hz))</para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>step</term>
56                 <listitem>
57                     <para>real (logarithmic step.)</para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>frq</term>
62                 <listitem>
63                     <para>row vector or matrix (frequencies (in Hz) ) (one row for each
64                         SISO subsystem).
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>db</term>
70                 <listitem>
71                     <para>row vector or matrix ( magnitudes (in Db)). (one row for each
72                         SISO subsystem).
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>phi</term>
78                 <listitem>
79                     <para>row vector or matrix ( phases (in degree)) (one row for each
80                         SISO subsystem).
81                     </para>
82                 </listitem>
83             </varlistentry>
84             <varlistentry>
85                 <term>repf</term>
86                 <listitem>
87                     <para>row vector or matrix of complex numbers (complex frequency
88                         response).
89                     </para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>Captions</term>
94                 <listitem>
95                     <para>vector of character strings (captions).</para>
96                 </listitem>
97             </varlistentry>
98             <varlistentry>
99                 <term>"rad"</term>
100                 <listitem>
101                     <para>converts the frequency from Hz into rad/s (multiplies by 2π),
102                     </para>
103                 </listitem>
104             </varlistentry>
105         </variablelist>
106     </refsection>
107     <refsection>
108         <title>Description</title>
109         <para>Bode plot, i.e magnitude and phase of the frequency
110             response of the linear dynamical system <literal>sl</literal>.
111         </para>
112         <para>
113             <literal>sl</literal> can be a continuous-time or
114             discrete-time SIMO system given by its state space,
115             rational transfer function (see <link
116             linkend="syslin">syslin</link>) or <link
117             linkend="zpk">zpk</link> representation. In case of
118             multi-output the outputs are plotted with different
119             colors.
120         </para>
121         <para>
122             The frequencies are given by the bounds <literal>fmin,fmax</literal>
123             (in Hz) or by a row-vector (or a matrix for multi-output)
124             <literal>frq</literal>.
125         </para>
126         <para>
127             <literal>step</literal> is the ( logarithmic ) discretization step.
128             (see <literal>calfrq</literal> for the choice of default value).
129         </para>
130         <para>
131             <literal>db,phi</literal> are the matrices of modulus (in Db) and
132             phases (in degrees). (One row for each response).
133         </para>
134         <para>
135             <literal>repf</literal> matrix of complex numbers. One row for each
136             response.
137         </para>
138         <para>
139             Default values for <literal>fmin</literal> and
140             <literal>fmax</literal> are <literal>1.d-3</literal>,
141             <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
142             <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
143             if <literal>sl</literal> is discrete-time. Automatic discretization of
144             frequencies is made by <literal>calfrq</literal>.
145         </para>
146         <para>
147             The
148             <link linkend="datatips">datatips</link>
149             tool may be used
150             to display data along the phase and modulus curves.
151         </para>
152     </refsection>
153     <refsection>
154         <title>Examples</title>
155         <programlisting role="example"><![CDATA[
156 s = poly(0, 's');
157 h = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
158
159 clf(); bode(h, 0.01, 100);
160  ]]></programlisting>
161         <para>
162             <scilab:image localized="true">
163                 s = poly(0, 's');
164                 h = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
165                 clf(); bode(h, 0.01, 100);
166             </scilab:image>
167         </para>
168         <programlisting role="example"><![CDATA[
169 s = poly(0, 's');
170 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
171 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
172 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
173 h2 = syslin('c', num/den);
174
175 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
176  ]]></programlisting>
177         <para>
178             <scilab:image localized="true">
179                 s = poly(0, 's');
180                 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
181                 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
182                 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
183                 h2 = syslin('c', num/den);
184                 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
185             </scilab:image>
186         </para>
187         <programlisting role="example"><![CDATA[
188 s = %s;
189 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
190 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
191 f_min = .0001; f_max = 16; // Frequencies in Hz
192
193 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
194  ]]></programlisting>
195         <para>
196             <scilab:image localized="true">
197                 s = %s;
198                 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
199                 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
200                 f_min = .0001; f_max = 16; // Frequencies in Hz
201                 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
202             </scilab:image>
203         </para>
204     </refsection>
205     <refsection role="see also">
206         <title>See also</title>
207         <simplelist type="inline">
208             <member>
209                 <link linkend="bode_asymp">bode_asymp</link>
210             </member>
211             <member>
212                 <link linkend="black">black</link>
213             </member>
214             <member>
215                 <link linkend="nyquist">nyquist</link>
216             </member>
217             <member>
218                 <link linkend="gainplot">gainplot</link>
219             </member>
220             <member>
221                 <link linkend="repfreq">repfreq</link>
222             </member>
223             <member>
224                 <link linkend="g_margin">g_margin</link>
225             </member>
226             <member>
227                 <link linkend="p_margin">p_margin</link>
228             </member>
229             <member>
230                 <link linkend="calfrq">calfrq</link>
231             </member>
232             <member>
233                 <link linkend="phasemag">phasemag</link>
234             </member>
235             <member>
236                 <link linkend="datatips">datatips</link>
237             </member>
238         </simplelist>
239     </refsection>
240     <refsection role="history">
241         <title>History</title>
242         <revhistory>
243             <revision>
244                 <revnumber>5.5.0</revnumber>
245                 <revdescription>
246                   <para><literal>"rad"</literal> option added.</para>
247                 </revdescription>
248             </revision>
249             <revision>
250                 <revnumber>6.0</revnumber>
251                 <revdescription>
252                     <para>handling zpk representation</para>
253                 </revdescription>
254             </revision>
255         </revhistory>
256     </refsection>
257 </refentry>