* Bug #12795 fixed - Cacsd doc: typo fixes
[scilab.git] / scilab / modules / cacsd / help / en_US / p_margin.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 - Serge STEER
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="p_margin">
14     <refnamediv>
15         <refname>p_margin</refname>
16         <refpurpose>phase margin and associated crossover frequency</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             [phm,fr] = p_margin(h)
22             phm=p_margin(h)
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>h</term>
30                 <listitem>
31                     <para>
32                         a SISO linear system (see :<link linkend="syslin">syslin</link>).
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>phm</term>
38                 <listitem>
39                     <para>a number, the phase margin in degree if it exists or an empty matrix.</para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>fr</term>
44                 <listitem>
45                     <para>a number, the corresponding frequency ( in hz) or an empty matrix.</para>
46                 </listitem>
47             </varlistentry>
48         </variablelist>
49     </refsection>
50     <refsection>
51         <title>Description</title>
52         <para>Given a SISO linear system in continuous or discrete time,
53             <literal>p_margin</literal> returns <literal>phm</literal>, the
54             phase margin in degree of <literal>h</literal> and
55             <literal>fr</literal>, the achieved corresponding frequency in
56             hz.
57         </para>
58         <para>The phase margin is the values of the phase at frequency
59             points where the nyquist plot of <literal>h</literal> crosses the
60             unit circle. In other words the phase margin is the difference
61             between the phase of the frequency response of
62             <literal>h</literal> and -180° when the gain of
63             <literal>h</literal> is 1.
64         </para>
65         <para>The algorithm uses polynomial root finder to solve the equations:</para>
66         <variablelist>
67             <varlistentry>
68                 <term>h(s)*h(-s)=1</term>
69                 <listitem>
70                     <para> for the continuous time case.</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>h(z)*h(1/z)=1</term>
75                 <listitem>
76                     <para> for the discrete time case.</para>
77                 </listitem>
78             </varlistentry>
79         </variablelist>
80     </refsection>
81     <refsection>
82         <title>Examples</title>
83         <programlisting role="example"><![CDATA[
84 //continuous case
85 h=syslin('c',-1+%s,3+2*%s+%s^2)
86 [p,fr]=p_margin(h)
87 [p,fr]=p_margin(h+0.7)
88 show_margins(h+0.7,'nyquist')
89
90 //discrete case
91 h = syslin(0.1,0.04798*%z+0.0464,%z^2-1.81*%z+0.9048);//ok
92 [p ,f]=p_margin(h)
93 show_margins(h,'nyquist')
94  ]]></programlisting>
95     </refsection>
96     <refsection role="see also">
97         <title>See Also</title>
98         <simplelist type="inline">
99             <member>
100                 <link linkend="g_margin">g_margin</link>
101             </member>
102             <member>
103                 <link linkend="show_margins">show_margins</link>
104             </member>
105             <member>
106                 <link linkend="repfreq">repfreq</link>
107             </member>
108             <member>
109                 <link linkend="black">black</link>
110             </member>
111             <member>
112                 <link linkend="bode">bode</link>
113             </member>
114             <member>
115                 <link linkend="nicholschart">nicholschart</link>
116             </member>
117             <member>
118                 <link linkend="nyquist">nyquist</link>
119             </member>
120         </simplelist>
121     </refsection>
122 </refentry>