* Bug #12793 fixed (proposal 2) - Cacsd: improve the bode() plots
[scilab.git] / scilab / modules / cacsd / help / en_US / plot_display / 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) INRIA
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <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" xmlns:scilab="http://www.scilab.org"  xml:id="bode" xml:lang="en">
14     <refnamediv>
15         <refname>bode</refname>
16         <refpurpose>Bode plot</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             bode(sl, [fmin, fmax] [,step] [,comments] )
22             bode(sl, [fmin, fmax] [,step] [,comments] [,"rad"] )
23             bode(sl, frq [,comments] )
24             bode(sl, frq [,comments] [,"rad"] )
25             bode(frq, db, phi [,comments] )
26             bode(frq, repf [,comments] [,"rad"] )
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>sl</term>
34                 <listitem>
35                     <para>
36                         <literal>syslin</literal> list (SISO or SIMO linear system)
37                         in continuous or discrete time.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>fmin,fmax</term>
43                 <listitem>
44                     <para>real (frequency bounds (in Hz))</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>step</term>
49                 <listitem>
50                     <para>real (logarithmic step.)</para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>comments</term>
55                 <listitem>
56                     <para>vector of character strings (captions).</para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>frq</term>
61                 <listitem>
62                     <para>row vector or matrix (frequencies (in Hz) ) (one row for each
63                         SISO subsystem).
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>db</term>
69                 <listitem>
70                     <para>row vector or matrix ( magnitudes (in Db)). (one row for each
71                         SISO subsystem).
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>phi</term>
77                 <listitem>
78                     <para>row vector or matrix ( phases (in degree)) (one row for each
79                         SISO subsystem).
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>repf</term>
85                 <listitem>
86                     <para>row vector or matrix of complex numbers (complex frequency
87                         response).
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>"rad"</term>
93                 <listitem>
94                     <para>converts the frequency from Hz into rad/s (multiplies by 2&#960;),
95                     </para>
96                 </listitem>
97             </varlistentry>
98         </variablelist>
99     </refsection>
100     <refsection>
101         <title>Description</title>
102         <para>Bode plot, i.e magnitude and phase of the frequency response of
103             <literal>sl</literal>.
104         </para>
105         <para>
106             <literal>sl</literal> can be a continuous-time or discrete-time SIMO
107             system (see <literal>syslin</literal>). In case of multi-output the
108             outputs are plotted with different symbols.
109         </para>
110         <para>
111             The frequencies are given by the bounds <literal>fmin,fmax</literal>
112             (in Hz) or by a row-vector (or a matrix for multi-output)
113             <literal>frq</literal>.
114         </para>
115         <para>
116             <literal>step</literal> is the ( logarithmic ) discretization step.
117             (see <literal>calfrq</literal> for the choice of default value).
118         </para>
119         <para>
120             <literal>comments</literal> is a vector of character strings
121             (captions).
122         </para>
123         <para>
124             <literal>db,phi</literal> are the matrices of modulus (in Db) and
125             phases (in degrees). (One row for each response).
126         </para>
127         <para>
128             <literal>repf</literal> matrix of complex numbers. One row for each
129             response.
130         </para>
131         <para>
132             Default values for <literal>fmin</literal> and
133             <literal>fmax</literal> are <literal>1.d-3</literal>,
134             <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
135             <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
136             if <literal>sl</literal> is discrete-time. Automatic discretization of
137             frequencies is made by <literal>calfrq</literal>.
138         </para>
139         <para>
140             The
141             <link linkend="datatips">datatips</link>
142             tool may be used
143             to display data along the phase and modulus curves.
144         </para>
145     </refsection>
146     <refsection>
147         <title>Examples</title>
148         <programlisting role="example"><![CDATA[
149 s = poly(0, 's');
150 h = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
151
152 clf(); bode(h, 0.01, 100);
153  ]]></programlisting>
154         <para>
155             <scilab:image localized="true">
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                 clf(); bode(h, 0.01, 100);
159             </scilab:image>
160         </para>
161         <programlisting role="example"><![CDATA[
162 s = poly(0, 's');
163 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
164 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
165 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
166 h2 = syslin('c', num/den);
167
168 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
169  ]]></programlisting>
170         <para>
171             <scilab:image localized="true">
172                 s = poly(0, 's');
173                 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
174                 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
175                 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
176                 h2 = syslin('c', num/den);
177                 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
178             </scilab:image>
179         </para>
180         <programlisting role="example"><![CDATA[
181 s = %s;
182 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
183 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
184 f_min = .0001; f_max = 16; // Frequencies in Hz
185
186 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
187  ]]></programlisting>
188         <para>
189             <scilab:image localized="true">
190                 s = %s;
191                 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
192                 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
193                 f_min = .0001; f_max = 16; // Frequencies in Hz
194                 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
195             </scilab:image>
196         </para>
197     </refsection>
198     <refsection role="see also">
199         <title>See Also</title>
200         <simplelist type="inline">
201             <member>
202                 <link linkend="bode_asymp">bode_asymp</link>
203             </member>
204             <member>
205                 <link linkend="black">black</link>
206             </member>
207             <member>
208                 <link linkend="nyquist">nyquist</link>
209             </member>
210             <member>
211                 <link linkend="gainplot">gainplot</link>
212             </member>
213             <member>
214                 <link linkend="repfreq">repfreq</link>
215             </member>
216             <member>
217                 <link linkend="g_margin">g_margin</link>
218             </member>
219             <member>
220                 <link linkend="p_margin">p_margin</link>
221             </member>
222             <member>
223                 <link linkend="calfrq">calfrq</link>
224             </member>
225             <member>
226                 <link linkend="phasemag">phasemag</link>
227             </member>
228             <member>
229                 <link linkend="datatips">datatips</link>
230             </member>
231         </simplelist>
232     </refsection>
233 </refentry>