damp function added in CACSD module
[scilab.git] / scilab / modules / cacsd / help / en_US / damp.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Add some comments about XML file
4 -->
5 <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" version="5.0-subset Scilab" xml:lang="en_US" xml:id="damp">
6   <info>
7     <pubdate>$LastChangedDate: 05-05-2011 $</pubdate>
8   </info>
9   <refnamediv>
10     <refname>damp</refname>
11     <refpurpose>Natural frequencies and damping factors. </refpurpose>
12   </refnamediv>
13   <refsynopsisdiv>
14     <title>Calling Sequence</title>
15     <synopsis>
16       [wn,z] = damp(sys)
17       [wn,z] = damp(P [,dt])
18       [wn,z] = damp(R [,dt])
19     </synopsis>
20   </refsynopsisdiv>
21   <refsection>
22     <title>Parameters</title>
23     <variablelist>
24       <varlistentry>
25         <term>sys</term>
26         <listitem>
27           <para>
28             A linear dynamical system (see <link linkend="syslin">syslin</link>).
29           </para>
30         </listitem>
31       </varlistentry>
32       <varlistentry>
33         <term>P</term>
34         <listitem>
35           <para>
36             An array of polynomials.
37           </para>
38         </listitem>
39       </varlistentry>
40       <varlistentry>
41         <term>P</term>
42         <listitem>
43           <para>
44             An array of real or complex floating point numbers.
45           </para>
46         </listitem>
47       </varlistentry>
48       <varlistentry>
49         <term>dt</term>
50         <listitem>
51           <para>
52             A non negative scalar, with default value 0.
53           </para>
54         </listitem>
55       </varlistentry>
56       <varlistentry>
57         <term>wn</term>
58         <listitem>
59           <para>
60             vector of floating point numbers in increasing
61             order: the natural pulsation in rd/s.
62           </para>
63         </listitem>
64       </varlistentry>
65       <varlistentry>
66         <term>z</term>
67         <listitem>
68           <para>
69             vector of floating point numbers: the damping factors.
70           </para>
71         </listitem>
72       </varlistentry>
73     </variablelist>
74   </refsection>
75   <refsection>
76     <title>Description</title>
77     <para>
78       The denominator second order continuous time transfer function
79       with complex poles can be written as <literal>s^2+2*z*wn*s+wn^2</literal> where<literal>z</literal>
80       is the damping factor and <literal>wn </literal>the natural pulsation.
81     </para>
82     <para>
83       If <literal>sys</literal> is a continuous time system,
84       <literal>[wn,z] = damp(sys)</literal> returns in <literal>wn</literal> the natural
85       pulsation <latex>\omega_n</latex>(in rd/s) and in <literal>z</literal> the damping factors
86       <latex>\xi</latex> of the poles of the linear dynamical system
87       <literal>sys</literal>. The <literal>wn</literal> and
88       <literal>z</literal> arrays are ordered according to the increasing
89       pulsation order.
90     </para>
91     <para>
92       If <literal>sys</literal> is a discrete time system
93       <literal>[wn,z] = damp(sys)</literal> returns in
94       <literal>wn</literal> the natural pulsation
95       <latex>\omega_n</latex>(in rd/s) and in <literal>z</literal> the
96       damping factors <latex>\xi</latex> of the continuous time
97       equivalent poles of <literal>sys</literal>. The
98       <literal>wn</literal> and <literal>z</literal> arrays are
99       ordered according to the increasing pulsation order.
100     </para>
101     <para><literal>[wn,z] = damp(P)</literal>  returns in
102       <literal>wn</literal> the natural pulsation
103       <latex>\omega_n</latex>(in rd/s) and in <literal>z</literal> the
104       damping factors <latex>\xi</latex> of the set of roots of the polynomials
105       stored in the <literal>P</literal> array.  If
106       <literal>dt</literal> is given and non 0, the roots are first
107       converted to their continuous time equivalents.
108
109       The <literal>wn</literal> and <literal>z</literal> arrays are ordered
110       according to the increasing pulsation order.
111     </para>
112     <para><literal>[wn,z] = damp(R)</literal>  returns in
113       <literal>wn</literal> the natural pulsation
114       <latex>\omega_n</latex>(in rd/s) and in <literal>z</literal> the
115       damping factors <latex>\xi</latex> of  the set of roots stored in the
116       <literal>R</literal> array. 
117
118       If <literal>dt</literal> is given and non 0, the roots are first
119       converted to their continuous time equivalents.
120       <literal>wn(i)</literal> and <literal>z(i)</literal> are the the
121       natural pulsation and damping factor of <literal>R(i)</literal>.
122     </para>
123   </refsection>
124   <refsection>
125     <title>Examples</title>
126     <programlisting role="example"><![CDATA[
127     s=%s;
128     num=22801+4406.18*s+382.37*s^2+21.02*s^3+s^4;
129     den=22952.25+4117.77*s+490.63*s^2+33.06*s^3+s^4
130     h=syslin('c',num/den);
131     [wn,z] = damp(h)
132     ]]></programlisting>
133     <para>
134 The following example illustrates the effect of the damping factor on
135 the frequency response of a second order system.
136  </para>
137     <programlisting role="example"><![CDATA[
138    s=%s;
139    wn=1;
140    clf();
141    Z=[0.95 0.7 0.5 0.3 0.13 0.0001];
142    for k=1:size(Z,'*')
143      z=Z(k)
144      H=syslin('c',1+5*s+10*s^2,s^2+2*z*wn*s+wn^2);
145      gainplot(H,0.01,1)
146      p=gce();p=p.children;
147      p.foreground=k;
148    end
149    title("$\frac{1+5 s+10 s^2}{\omega_n^2+2\omega_n\xi s+s^2}, \quad \omega_n=1$")
150    legend('$\xi='+string(Z)+'$')
151    plot(wn/(2*%pi)*[1 1],[0 70],'r') //natural pulsation
152    ]]></programlisting>
153     <para>
154    It produces this plot:
155  </para>
156     <para>
157       <inlinemediaobject>
158         <imageobject>
159           <imagedata fileref="../images/damp.svg"/>
160         </imageobject>
161       </inlinemediaobject>
162     </para>
163     <para>
164 Computing the natural pulsations and daping ratio for a set of roots:
165  </para>
166     <programlisting role="example"><![CDATA[
167     [wn,z] = damp((1:5)+%i)
168     ]]></programlisting>
169   </refsection>
170   <refsection>
171     <title>See Also</title>
172     <simplelist type="inline">
173       <member>
174         <link linkend="spec">spec</link>
175       </member>
176       <member>
177         <link linkend="roots">roots</link>
178       </member>
179     </simplelist>
180   </refsection>
181   <refsection>
182     <title>Authors</title>
183     <simplelist type="vert">
184       <member>Serge Steer, INRIA</member>
185     </simplelist>
186   </refsection>
187 </refentry>