* Bug 15884 fixed: bode() layout improved
[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(.., "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>as last optional argument: displays the Bode plot versus Angular frequencies
102                       in rad/s, instead of versus frequencies in Hz.
103                     </para>
104                 </listitem>
105             </varlistentry>
106         </variablelist>
107     </refsection>
108     <refsection>
109         <title>Description</title>
110         <para>Bode plot, i.e magnitude and phase of the frequency
111             response of the linear dynamical system <literal>sl</literal>.
112         </para>
113         <para>
114             <literal>sl</literal> can be a continuous-time or
115             discrete-time SIMO system given by its state space,
116             rational transfer function (see <link
117             linkend="syslin">syslin</link>) or <link
118             linkend="zpk">zpk</link> representation. In case of
119             multi-output the outputs are plotted with different
120             colors.
121         </para>
122         <para>
123             The frequencies are given by the bounds <literal>fmin,fmax</literal>
124             (in Hz) or by a row-vector (or a matrix for multi-output)
125             <literal>frq</literal>.
126         </para>
127         <para>
128             <literal>step</literal> is the ( logarithmic ) discretization step.
129             (see <literal>calfrq</literal> for the choice of default value).
130         </para>
131         <para>
132             <literal>db,phi</literal> are the matrices of modulus (in Db) and
133             phases (in degrees). (One row for each response).
134         </para>
135         <para>
136             <literal>repf</literal> matrix of complex numbers. One row for each
137             response.
138         </para>
139         <para>
140             Default values for <literal>fmin</literal> and
141             <literal>fmax</literal> are <literal>1.d-3</literal>,
142             <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
143             <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
144             if <literal>sl</literal> is discrete-time. Automatic discretization of
145             frequencies is made by <literal>calfrq</literal>.
146         </para>
147         <para>
148             The
149             <link linkend="datatips">datatips</link>
150             tool may be used
151             to display data along the phase and modulus curves.
152         </para>
153     </refsection>
154     <refsection>
155         <title>Examples</title>
156         <programlisting role="example"><![CDATA[
157 s = poly(0, 's');
158 h = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
159
160 clf(); bode(h, 0.01, 100);
161  ]]></programlisting>
162         <para>
163             <scilab:image localized="true">
164                 s = poly(0, 's');
165                 h = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
166                 clf(); bode(h, 0.01, 100);
167             </scilab:image>
168         </para>
169         <programlisting role="example"><![CDATA[
170 s = poly(0, 's');
171 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
172 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
173 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
174 h2 = syslin('c', num/den);
175
176 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
177  ]]></programlisting>
178         <para>
179             <scilab:image localized="true">
180                 s = poly(0, 's');
181                 h1 = syslin('c', (s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
182                 num = 22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
183                 den = 22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4;
184                 h2 = syslin('c', num/den);
185                 clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
186             </scilab:image>
187         </para>
188         <programlisting role="example"><![CDATA[
189 s = %s;
190 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
191 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
192 f_min = .0001; f_max = 16; // Frequencies in Hz
193
194 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
195  ]]></programlisting>
196         <para>
197             <scilab:image localized="true">
198                 s = %s;
199                 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
200                 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
201                 f_min = .0001; f_max = 16; // Frequencies in Hz
202                 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
203             </scilab:image>
204         </para>
205     </refsection>
206     <refsection role="see also">
207         <title>See also</title>
208         <simplelist type="inline">
209             <member>
210                 <link linkend="bode_asymp">bode_asymp</link>
211             </member>
212             <member>
213                 <link linkend="black">black</link>
214             </member>
215             <member>
216                 <link linkend="nyquist">nyquist</link>
217             </member>
218             <member>
219                 <link linkend="gainplot">gainplot</link>
220             </member>
221             <member>
222                 <link linkend="repfreq">repfreq</link>
223             </member>
224             <member>
225                 <link linkend="g_margin">g_margin</link>
226             </member>
227             <member>
228                 <link linkend="p_margin">p_margin</link>
229             </member>
230             <member>
231                 <link linkend="calfrq">calfrq</link>
232             </member>
233             <member>
234                 <link linkend="phasemag">phasemag</link>
235             </member>
236             <member>
237                 <link linkend="datatips">datatips</link>
238             </member>
239         </simplelist>
240     </refsection>
241     <refsection role="history">
242         <title>History</title>
243         <revhistory>
244             <revision>
245                 <revnumber>5.5.0</revnumber>
246                 <revdescription>
247                   <para><literal>"rad"</literal> option added.</para>
248                 </revdescription>
249             </revision>
250             <revision>
251                 <revnumber>6.0</revnumber>
252                 <revdescription>
253                     <para>handling zpk representation</para>
254                 </revdescription>
255             </revision>
256         </revhistory>
257     </refsection>
258 </refentry>