* Bug #12795 fixed - Cacsd doc: typo fixes
[scilab.git] / scilab / modules / cacsd / help / en_US / plot_display / phaseplot.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) 2011 - INRIA - Serge Steer <serge.steer@inria.fr>
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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="phaseplot">
14     <refnamediv>
15         <refname>phaseplot</refname>
16         <refpurpose>frequency phase plot</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             phaseplot(sl)
22             phaseplot(sl,fmin,fmax [,step] [,comments] )
23             phaseplot(frq,db,phi [,comments])
24             phaseplot(frq, repf [,comments])
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>sl</term>
32                 <listitem>
33                     <para>
34                         a single input multiple output (SIMO) linear dynamical system (see <link linkend="syslin">syslin</link>).
35                     </para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>fmin</term>
40                 <listitem>
41                     <para>real scalar: the minimum frequency (in Hz) to be represented.</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>fmax</term>
46                 <listitem>
47                     <para>real scalar: the maximum frequency (in Hz) to be represented.</para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>step</term>
52                 <listitem>
53                     <para>real scalar: the frequency discretization step (logarithmic scale)). If it is not specified the alorithm uses adaptative frequency steps.</para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>comments</term>
58                 <listitem>
59                     <para>a character string vector: the legend label to be associated with each curve. Optional value is the empty array.</para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>frq</term>
64                 <listitem>
65                     <para>a row vector or an n x m array: The frequency discretization in Hz.</para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>db</term>
70                 <listitem>
71                     <para>an n x m array: the magnitudes corresponding to
72                         <literal>frq</literal>. This argument is not used, it only
73                         appears to make <literal>phaseplot</literal> have the same
74                         calling sequence as <literal>gainplot</literal> and
75                         <literal>bode</literal>.
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>phi</term>
81                 <listitem>
82                     <para>an n x m array: the phases in degree corresponding to
83                         <literal>frq</literal>. The <literal>phaseplot</literal>
84                         function plots the curves <literal>phi(i,:)</literal> versus
85                         <literal>frq(i,:)</literal>
86                     </para>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>repf</term>
91                 <listitem>
92                     <para>an n x m complex array. The
93                         <literal>phaseplot</literal> function plots the curves
94                         <literal>phase(repf(i,:))</literal> versus
95                         <literal>frq(i,:)</literal>
96                     </para>
97                 </listitem>
98             </varlistentry>
99         </variablelist>
100     </refsection>
101     <refsection>
102         <title>Description</title>
103         <para>This function draws the phase of the frequency response of a
104             system. The system can be given under different
105             representations:
106         </para>
107         <itemizedlist>
108             <listitem>
109                 <para>
110                     <literal>phaseplot(sl,...)</literal> case
111                 </para>
112                 <para>
113                     <literal>sl</literal> can be a continuous-time or discrete-time SIMO
114                     system (see <link linkend="syslin">syslin</link>). In case of multi-output the
115                     outputs are plotted with different symbols.
116                 </para>
117                 <para>In this case the frequencies can be  given by:</para>
118                 <itemizedlist mark="point">
119                     <listitem>
120                         <para>the lower and upper bounds in Hz
121                             <literal>fmin</literal>, <literal>fmax</literal> and an
122                             optional frequency step <literal>step</literal>. The
123                             default values for <literal>fmin</literal> and
124                             <literal>fmax</literal>are <literal>1.e-3</literal>,
125                             <literal>1.e3</literal> if <literal>sl</literal> is
126                             continuous-time or <literal>1.e-3</literal>,
127                             <literal>0.5/sl.dt</literal> (nyquist frequency) if
128                             <literal>sl</literal> is discrete-time. If the
129                             <literal>step</literal> argument is omitted the function
130                             use an adaptative frequency step (see <link linkend="calfrq">calfrq</link>).
131                         </para>
132                     </listitem>
133                     <listitem>
134                         <para>
135                             a row vector or a 2D array <literal>frq</literal> which
136                             gives the frequency values in Hz. 2D array can be used for
137                             multi-output systems if one wants to have different frequency
138                             discretization for each input/output couple.
139                         </para>
140                     </listitem>
141                 </itemizedlist>
142             </listitem>
143             <listitem>
144                 <para>
145                     <literal>phaseplot(frq,...)</literal> case
146                 </para>
147                 <para>
148                     This case allows to draw frequency phase plots for previously
149                     computed frequency responses. The frequency response can be
150                     given either by it's complex representation
151                     <literal>repf</literal> or by it's magnitude phase
152                     representation <literal>db</literal>,
153                     <literal>phi</literal>.
154                 </para>
155                 <para>
156                     <literal>frq</literal> and <literal>repf</literal> must
157                     be row vectors or n x m arrays (each row represent an
158                     input/output couple).
159                 </para>
160             </listitem>
161         </itemizedlist>
162         <para>
163             The <link linkend="datatips">datatips</link> tool may be used to display data along the phase curves.
164         </para>
165     </refsection>
166     <refsection>
167         <title>Examples</title>
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     h2=syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
172     clf();phaseplot([h1;h2],0.01,100,..
173                        ["$\frac{s^2+18 s+100}{s^2+6.06 s+102.1}$";
174                         "$\frac{s^2+3.02 s+228.01}{s^2+27 s+225}$"])
175     title('Phaseplot')
176
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                 h2=syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
183                 clf();phaseplot([h1;h2],0.01,100,..
184                 ["$\frac{s^2+18 s+100}{s^2+6.06 s+102.1}$";
185                 "$\frac{s^2+3.02 s+228.01}{s^2+27 s+225}$"])
186                 title('Phaseplot')
187             </scilab:image>
188         </para>
189     </refsection>
190     <refsection role="see also">
191         <title>See Also</title>
192         <simplelist type="inline">
193             <member>
194                 <link linkend="bode">bode</link>
195             </member>
196             <member>
197                 <link linkend="gainplot">gainplot</link>
198             </member>
199             <member>
200                 <link linkend="repfreq">repfreq</link>
201             </member>
202             <member>
203                 <link linkend="calfrq">calfrq</link>
204             </member>
205             <member>
206                 <link linkend="datatips">datatips</link>
207             </member>
208         </simplelist>
209     </refsection>
210     <refsection>
211         <title>History</title>
212         <revhistory>
213             <revision>
214                 <revnumber>5.4.0</revnumber>
215                 <revremark>Function phaseplot introduced.</revremark>
216             </revision>
217         </revhistory>
218     </refsection>
219 </refentry>