bug 6394 fix + datatips custimization + revision of help pages
[scilab.git] / scilab / modules / cacsd / help / en_US / black.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  * 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-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="black" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (Wed, 26 Mar 2008)
22     $</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>black</refname>
27
28     <refpurpose>Black-Nichols diagram of a linear dynamical system</refpurpose>
29   </refnamediv>
30
31   <refsynopsisdiv>
32     <title>Calling Sequence</title>
33
34     <synopsis>
35       black( sl,[fmin,fmax] [,step] [,comments] )
36       black( sl,frq [,comments] )
37       black(frq,db,phi [,comments])
38       black(frq,repf [,comments])
39     </synopsis>
40   </refsynopsisdiv>
41
42   <refsection>
43     <title>Parameters</title>
44
45     <variablelist>
46       <varlistentry>
47         <term>sl</term>
48
49         <listitem>
50           <para>a continuous or discrete time SIMO linear dynamical
51           system ( see: <link linkend="syslin">syslin</link>).</para>
52         </listitem>
53       </varlistentry>
54
55       <varlistentry>
56         <term>fmin,fmax</term>
57
58         <listitem>
59           <para>real scalars (frequency bounds)</para>
60         </listitem>
61       </varlistentry>
62
63       <varlistentry>
64         <term>frq</term>
65
66         <listitem>
67           <para>row vector or matrix (frequencies)</para>
68         </listitem>
69       </varlistentry>
70
71       <varlistentry>
72         <term>db,phi</term>
73
74         <listitem>
75           <para>row vectors or matrices (modulus, phase)</para>
76         </listitem>
77       </varlistentry>
78
79       <varlistentry>
80         <term>repf</term>
81
82         <listitem>
83           <para>row vectors or matrices (complex frequency response)</para>
84         </listitem>
85       </varlistentry>
86
87       <varlistentry>
88         <term>step</term>
89
90         <listitem>
91           <para>real</para>
92         </listitem>
93       </varlistentry>
94
95       <varlistentry>
96         <term>comments</term>
97
98         <listitem>
99           <para>string</para>
100         </listitem>
101       </varlistentry>
102     </variablelist>
103   </refsection>
104
105   <refsection>
106     <title>Description</title>
107
108     <para>Black's diagram (Nichols'chart) for a linear system ( see: <link linkend="syslin">syslin</link>). <literal>sl</literal> can be a continuous-time or
109     discrete-time SIMO system. In case of
110     multi-output the outputs are plotted with different colors.</para>
111
112     <para>The frequencies are given by the bounds
113     <literal>fmin</literal>,<literal>fmax</literal> (in Hz) or by a row-vector
114     (or a matrix for multi-output) <literal>frq</literal>.</para>
115
116     <para><literal>step</literal> is the ( logarithmic ) discretization step.
117     (see <link linkend="calfrq">calfrq</link> for the choice of default value).</para>
118
119     <para><literal>comments</literal> is a vector of character strings
120     (captions).</para>
121
122     <para><literal>db,phi</literal> are the matrices of modulus (in Db) and
123     phases (in degrees). (One row for each response).</para>
124
125     <para><literal>repf</literal> matrix of complex numbers. One row for each
126     response.</para>
127
128     <para>To plot the grid of iso-gain and iso-phase of
129     <literal>y/(1+y)</literal> use <link
130     linkend="nicholschart">nicolschart()</link>.</para>
131
132     <para>Default values for <literal>fmin</literal> and
133     <literal>fmax</literal> are <literal>1.d-3</literal>,
134     <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
135     <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
136     if <literal>sl</literal> is discrete-time.</para>
137   </refsection>
138
139   <refsection>
140     <title>Examples</title>
141
142     <programlisting role="exemple"><![CDATA[
143     //Black diagram
144     s=poly(0,'s');
145     sl=syslin('c',5*(1+s)/(.1*s^4+s^3+15*s^2+3*s+1))
146     clf();black(sl,0.01,10);
147     ]]></programlisting>
148     <para>
149       <inlinemediaobject>
150         <imageobject>
151           <imagedata fileref="../images/black1.svg"/>
152         </imageobject>
153       </inlinemediaobject>
154     </para>
155     <programlisting role="example"><![CDATA[
156     //Black diagram with Nichols chart as a grid
157     s=poly(0,'s');
158     Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
159     //two degree of freedom PID
160     tau=0.2;xsi=1.2;
161     PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau^2*s^2));
162     clf();
163     black([Plant;Plant*PID ],0.01,100,["Plant";"Plant and PID corrector"]);
164     //move the caption in the lower rigth corner
165     ax=gca();Leg=ax.children(1);
166     Leg.legend_location="in_lower_right";
167     nicholschart(colors=color('light gray')*[1 1])
168
169     ]]></programlisting>
170     <para>
171       <inlinemediaobject>
172         <imageobject>
173           <imagedata fileref="../images/black2.svg"/>
174         </imageobject>
175       </inlinemediaobject>
176     </para>
177   </refsection>
178
179   <refsection>
180     <title>See Also</title>
181
182     <simplelist type="inline">
183       <member><link linkend="nicholschart">nicholschart</link></member>
184       <member><link linkend="bode">bode</link></member>
185       <member><link linkend="nyquist">nyquist</link></member>
186
187       <member><link linkend="syslin">syslin</link></member>
188       <member><link linkend="calfrq">calfrq</link></member>
189       <member><link linkend="datatips">datatips</link></member>
190     </simplelist>
191   </refsection>
192 </refentry>