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>