License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / cacsd / help / en_US / plot_display / nyquist.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  * 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" 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="nyquist" xml:lang="en">
17     <refnamediv>
18         <refname>nyquist</refname>
19         <refpurpose>nyquist plot</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>
24             nyquist( sl,[fmin,fmax] [,step] [,comments] [,symmetry])
25             nyquist( sl, frq [,comments] [,symmetry])
26             nyquist(frq,db,phi [,comments] [,symmetry])
27             nyquist(frq, repf [,comments] [,symmetry])
28         </synopsis>
29     </refsynopsisdiv>
30     <refsection>
31         <title>Arguments</title>
32         <variablelist>
33             <varlistentry>
34                 <term>sl</term>
35                 <listitem>
36                     <para>
37                         a continuous or discrete time SIMO linear dynamical system ( see: <link linkend="syslin">syslin</link>).
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>fmin,fmax</term>
43                 <listitem>
44                     <para>real scalars (frequency lower and upper bounds (in Hz)).</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>step</term>
49                 <listitem>
50                     <para>real (logarithmic discretization step), if not given
51                         an adaptative discretization is used.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>comments</term>
57                 <listitem>
58                     <para>string vector (captions).</para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>symmetry</term>
63                 <listitem>
64                     <para>a boolean, default value is %t.</para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>frq</term>
69                 <listitem>
70                     <para>vector or matrix of frequencies (in Hz) (one row for each
71                         output of <literal>sl</literal>).
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>db,phi</term>
77                 <listitem>
78                     <para>real matrices of modulus (in dB) and phases (in degree) (one
79                         row for each output of <literal>sl</literal>).
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>repf</term>
85                 <listitem>
86                     <para>matrix of complex numbers. Frequency response (one row for
87                         each output of <literal>sl</literal>)
88                     </para>
89                 </listitem>
90             </varlistentry>
91         </variablelist>
92     </refsection>
93     <refsection>
94         <title>Description</title>
95         <para>Nyquist plot i.e Imaginary part versus Real part of the
96             frequency response of <literal>sl</literal>. If the
97             <literal>symmetry</literal> argument is true or omitted the
98             Nyquist plot displays the symmetric graph (positive and negative
99             frequencies).
100         </para>
101         <para>
102             For continuous time systems <literal>sl(2*%i*%pi*w)</literal> is
103             plotted. For discrete time system or discretized systems
104             <literal>sl(exp(2*%i*%pi*w*fd)</literal> is used ( <literal>fd=1</literal>
105             for discrete time systems and <literal>fd=sl('dt')</literal> for
106             discretized systems )
107         </para>
108         <para>
109             <literal>sl</literal> can be a continuous-time or discrete-time SIMO
110             system (see <literal>syslin</literal>). In case of multi-output the
111             outputs are plotted with different symbols.
112         </para>
113         <para>
114             The frequencies are given by the bounds <literal>fmin,fmax</literal>
115             (in Hz) or by a row-vector (or a matrix for multi-output)
116             <literal>frq</literal>.
117         </para>
118         <para>
119             <literal>step</literal> is the ( logarithmic ) discretization step.
120             (see <literal>calfrq</literal> for the choice of default value).
121         </para>
122         <para>
123             <literal>comments</literal> is a vector of character strings
124             (captions).
125         </para>
126         <para>
127             <literal>db,phi</literal> are the matrices of modulus (in Db) and
128             phases (in degrees). (One row for each response).
129         </para>
130         <para>
131             <literal>repf</literal> is a matrix of complex numbers. One row for
132             each response.
133         </para>
134         <para>
135             Default values for <literal>fmin</literal> and
136             <literal>fmax</literal> are <literal>1.d-3</literal>,
137             <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
138             <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
139             if <literal>sl</literal> is discrete-time.
140         </para>
141         <para>Automatic discretization of frequencies is made by
142             <link linkend="calfrq">calfrq</link>.
143         </para>
144         <para>To obtain the value of the frequency at a selected point(s) you can
145             activate the <link linkend="datatips">datatips</link> manager and
146             click the desired point on the nyquist curve(s).
147         </para>
148     </refsection>
149     <refsection>
150         <title>Graphics entities organization</title>
151         <para>
152             The <literal>nyquist</literal> function creates a compound
153             object for each SISO system. The following piece of code allows
154             to get the handle on the compound object of the ith system:
155         </para>
156         <programlisting role="getcompound"><![CDATA[
157     ax=gca();//handle on current axes
158     hi=ax.children($+i-1)// the handle on the compound object of the ith system
159     ]]></programlisting>
160         <para>
161             This compound object has two children: a compound object that
162             defines the small arrows (a compound of small polylines)  and the curve labels  (a compound of texts)  and a polyline
163             which is the curve itself. The following piece of code shows how
164             one can customize a particular nyquist curve display.
165         </para>
166         <programlisting role="customize"><![CDATA[
167     hi.children(1).visible='off'; //hides the arrows and labels
168     hi.children(2).thickness=2; //make the curve thicker
169
170     ]]></programlisting>
171     </refsection>
172     <refsection>
173         <title>Examples</title>
174         <programlisting role="example"><![CDATA[
175     //Nyquist curve
176     s=poly(0,'s')
177     h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
178     h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
179     clf();    nyquist(h1)
180     // add a datatip
181     ax=gca();
182     h_h=ax.children($).children(2);//handle on Nyquist curve of h
183     tip=datatipCreate(h_h,[1.331,0.684]);
184     datatipSetOrientation(tip,"upper left");
185     ]]></programlisting>
186         <para>
187             <scilab:image localized="true">
188                 s=poly(0,'s')
189                 h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
190                 h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
191                 nyquist(h1)
192                 ax=gca();
193                 h_h=ax.children($).children(2);
194                 tip=datatipCreate(h_h,[1.331,0.684]);
195                 datatipSetOrientation(tip,"upper left");
196             </scilab:image>
197         </para>
198         <programlisting role="example"><![CDATA[
199     //Hall chart as a grid for nyquist
200     s=poly(0,'s');
201     Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
202     //two degree of freedom PID
203     tau=0.2;xsi=1.2;
204     PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau^2*s^2));
205     clf();
206     nyquist([Plant;Plant*PID],0.5,100,["Plant";"Plant and PID corrector"]);
207     hallchart(colors=color('light gray')*[1 1])
208     //move the caption in the lower right corner
209     ax=gca();Leg=ax.children(1);
210     Leg.legend_location="in_upper_left";
211     ]]></programlisting>
212         <para>
213             <scilab:image localized="true">
214                 s=poly(0,'s');
215                 Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
216                 tau=0.2;xsi=1.2;
217                 PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau^2*s^2));
218                 clf();
219                 nyquist([Plant;Plant*PID],0.5,100,["Plant";"Plant and PID corrector"]);
220                 hallchart(colors=color('light gray')*[1 1])
221                 ax=gca();Leg=ax.children(1);
222                 Leg.legend_location="in_upper_left";
223                 
224             </scilab:image>
225         </para>
226     </refsection>
227     <refsection role="see also">
228         <title>See Also</title>
229         <simplelist type="inline">
230             <member>
231                 <link linkend="syslin">syslin</link>
232             </member>
233             <member>
234                 <link linkend="bode">bode</link>
235             </member>
236             <member>
237                 <link linkend="black">black</link>
238             </member>
239             <member>
240                 <link linkend="nyquistfrequencybounds">nyquistfrequencybounds</link>
241             </member>
242             <member>
243                 <link linkend="calfrq">calfrq</link>
244             </member>
245             <member>
246                 <link linkend="freq">freq</link>
247             </member>
248             <member>
249                 <link linkend="repfreq">repfreq</link>
250             </member>
251             <member>
252                 <link linkend="phasemag">phasemag</link>
253             </member>
254             <member>
255                 <link linkend="datatips">datatips</link>
256             </member>
257         </simplelist>
258     </refsection>
259 </refentry>