<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 1996 - 2016 - INRIA - Serge Steer <serge.steer@inria.fr>
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org"  xml:id="black" xml:lang="en">
    <refnamediv>
        <refname>black</refname>
        <refpurpose>Black-Nichols diagram of a linear dynamical system</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            black(sl)
            black(sl, fmin, fmax)
            black(sl, fmin, fmax, step)
            black(sl, frq)
            black(frq, db, phi)
            black(frq, repf)
            black(.., comments)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>sl</term>
                <listitem>
                    <para>
                        A siso or simo linear dynamical system, in state
                        space, transfer function or zpk representations,
                        in continuous or discrete time.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fmin,fmax</term>
                <listitem>
                    <para>real scalars (frequency bounds)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>frq</term>
                <listitem>
                    <para>row vector or matrix (frequencies)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>db, phi</term>
                <listitem>
                    <para>
                        row vectors or matrices of modulus (in dB) and phases (in degrees).
                        One row for each response.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>repf</term>
                <listitem>
                    <para>
                        row or matrix of complex frequency response(s). One row for each response.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>step</term>
                <listitem>
                    <para>
                        real: (logarithmic) discretization step.
                        See <link linkend="calfrq">calfrq</link> for the choice of default value.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>comments</term>
                <listitem>
                    <para>vector of character strings: captions.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Black's diagram (Nichols'chart) for a linear dynamical system .
        </para>

        <para>
            <literal>sl</literal> can be a continuous-time or
            discrete-time SIMO system given by its state space,
            rational transfer function (see <link
            linkend="syslin">syslin</link>) or <link
            linkend="zpk">zpk</link> representation. In case of
            multi-output the outputs are plotted with different
            colors.
        </para>

        <para>
            The frequencies are given by the bounds
            <literal>fmin</literal>,<literal>fmax</literal> (in Hz) or
            by a row-vector (or a matrix for multi-output)
            <literal>frq</literal>.
        </para>
        <para>To plot the grid of iso-gain and iso-phase of
            <literal>y/(1+y)</literal> use <link linkend="nicholschart">nicolschart()</link>.
        </para>
        <para>
            Default values for <literal>fmin</literal> and
            <literal>fmax</literal> are <literal>1.d-3</literal>,
            <literal>1.d+3</literal> if <literal>sl</literal> is continuous-time or
            <literal>1.d-3</literal>, <literal>0.5</literal>/sl.dt (nyquist frequency)
            if <literal>sl</literal> is discrete-time.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
    //Black diagram
    s=poly(0,'s');
    sl=syslin('c',5*(1+s)/(.1*s.^4+s.^3+15*s.^2+3*s+1))
    clf();black(sl,0.01,10);
    ]]></programlisting>
        <para>
            <scilab:image localized="true">
                s=poly(0,'s');
                sl=syslin('c',5*(1+s)/(.1*s.^4+s.^3+15*s.^2+3*s+1))
                black(sl,0.01,10);
            </scilab:image>
        </para>
        <programlisting role="example"><![CDATA[
    //Black diagram with Nichols chart as a grid
    s=poly(0,'s');
    Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
    //two degree of freedom PID
    tau=0.2;xsi=1.2;
    PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau.^2*s.^2));
    clf();
    black([Plant;Plant*PID ],0.01,100,["Plant";"Plant and PID corrector"]);
    //move the caption in the lower right corner
    ax=gca();Leg=ax.children(1);
    Leg.legend_location="in_lower_right";
    nicholschart(colors=color('light gray')*[1 1])

    ]]></programlisting>
        <para>
            <scilab:image localized="true">
                s=poly(0,'s');
                Plant=syslin('c',16000/((s+1)*(s+10)*(s+100)));
                tau=0.2;xsi=1.2;
                PID=syslin('c',(1/(2*xsi*tau*s))*(1+2*xsi*tau*s+tau.^2*s.^2));
                black([Plant;Plant*PID ],0.01,100,["Plant";"Plant and PID corrector"]);
                ax=gca();Leg=ax.children(1);
                Leg.legend_location="in_lower_right";
                nicholschart(colors=color('light gray')*[1 1])
            </scilab:image>
        </para>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="nicholschart">nicholschart</link>
            </member>
            <member>
                <link linkend="bode">bode</link>
            </member>
            <member>
                <link linkend="nyquist">nyquist</link>
            </member>
            <member>
                <link linkend="syslin">syslin</link>
            </member>
            <member>
                <link linkend="calfrq">calfrq</link>
            </member>
            <member>
                <link linkend="datatips">datatips</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <para>handling zpk representation</para>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
