bug 6394 fix + datatips custimization + revision of help pages
[scilab.git] / scilab / modules / cacsd / help / en_US / hallchart.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 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" xml:id="hallchart">
14   <info>
15     <pubdate>$LastChangedDate: 2008-06-19 18:44:44 +0200 (jeu, 19 jun 2008) $</pubdate>
16   </info>
17   <refnamediv>
18     <refname>hallchart</refname>
19     <refpurpose>Draws the Hall chart</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>hallchart([ modules [,args [,colors]]])</synopsis>
24    <synopsis></synopsis>
25   </refsynopsisdiv>
26   <refsection>
27     <title>Parameters</title>
28     <variablelist>
29       <varlistentry>
30         <term>modules</term>
31         <listitem>
32           <para>real vector ( modules (in dB))</para>
33         </listitem>
34       </varlistentry>
35       <varlistentry>
36         <term>args</term>
37         <listitem>
38           <para>real vector (phases (in degree))</para>
39         </listitem>
40       </varlistentry>
41       <varlistentry>
42         <term>colors</term>
43         <listitem>
44           <para>a scalar or a vector, the color indices for isogain and iso phase curves</para>
45         </listitem>
46       </varlistentry>
47     </variablelist>
48   </refsection>
49   <refsection>
50     <title>Description</title>
51     <para> plot the Hall'chart: iso-module and iso-argument contours of
52     <literal>y/(1+y)</literal> in the <literal>real(y)</literal>, <literal>imag(y)</literal> plane</para>
53     <para><literal>hallchart</literal> may be used in cunjunction with
54     <link linkend="nyquist">nyquist</link>. </para>
55     <para>The default values for <literal>modules</literal> and
56     <literal>args</literal> are respectively :</para>
57     <para>
58       <literal>[-20 -10 -6 -4 -2 2 4 6 10 20]</literal>
59     </para>
60     <para><literal>[-90 -60 -45 -30 -15 15 30 45 60 90]</literal></para>
61     <para>This function superseeds the <link linkend="m_circle">m_circle</link> function</para>
62
63   </refsection>
64   <refsection>
65     <title>Graphics entities organization</title>
66     <para>The <literal>hallchart</literal> function create a single
67     compound object which is generaly the last child of the current
68     axes. This compound object contains a set of compound objects, one
69     for each grid curve. The first ones are the iso module curves and
70     the last one the iso-argument contours. Each of these compound
71     objects contains a Polyline object (the curve) and a Text object
72     (the label). The following piece of code can be used to change the color of the ith iso module curve:
73     </para>
74     <programlisting role="customizing"><![CDATA[
75     clf();hallchart()
76     ax=gca();//handle on current axes
77     c=ax.children($).children;// the handles on the chart grid curves
78     i=4; //the index of the -4dB curve
79     ci=c(i); //the handle on the -4dB curve
80     ci.children(1).foreground=color('red'); //draw it in red
81
82     j=3; // the index of the -45° curve
83     cj=c(10+j); //the handle on the -45° curve
84     cj.children(1).thickness=3;//draw it thicker
85      ]]></programlisting>
86   </refsection>
87   <refsection>
88     <title>Examples</title>
89     <programlisting role="example"><![CDATA[
90     //Hall chart
91     clf();hallchart()
92     ]]></programlisting>
93    <para>
94       <inlinemediaobject>
95         <imageobject>
96           <imagedata fileref="../images/hallchart.svg"/>
97         </imageobject>
98       </inlinemediaobject>
99     </para>
100     <programlisting role="example"><![CDATA[
101     //Hall chart as a grid for nyquist
102     s=poly(0,'s');
103     Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
104     //two degree of freedom PID
105     tau=0.2;xsi=1.2;
106     PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau^2*s^2));
107     clf();
108     nyquist([Plant;Plant*PID],0.5,100,["Plant";"Plant and PID corrector"]);
109     hallchart(colors=color('light gray')*[1 1])
110     //move the caption in the lower rigth corner
111     ax=gca();Leg=ax.children(1);
112     Leg.legend_location="in_lower_right";
113     ]]></programlisting>
114    <para>
115       <inlinemediaobject>
116         <imageobject>
117           <imagedata fileref="../images/nyquist2.svg"/>
118         </imageobject>
119       </inlinemediaobject>
120     </para>
121   </refsection>
122   <refsection>
123     <title>See Also</title>
124     <simplelist type="inline">
125       <member><link linkend="nyquist">nyquist</link></member>
126       <member><link linkend="nicholschart">nicholschart</link></member>
127     </simplelist>
128   </refsection>
129 </refentry>