<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA -
 * 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:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:lang="en" xml:id="lqi">
    <refnamediv>
        <refname>lqi</refname>
        <refpurpose>Linear quadratic integral compensator (full state)</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
          [K, X] = lqi(P, Q, R)
          [K, X] = lqi(P, Q, R, S)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>P</term>
                <listitem>
                    <para>
                        The plant  state space representation
                        (see <link linkend="syslin">syslin</link>) with nx states, nu inputs and ny outputs.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Q</term>
                <listitem>
                    <para>
                        Real nx+ny by nx+ny symmetric matrix,
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>R</term>
                <listitem>
                    <para>
                        full rank nu by nu real symmetric matrix
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>
                        real nx+ny by nu  matrix, the default value is zeros(nx+ny,nu)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>K</term>
                <listitem>
                    <para>a real matrix, the optimal gain</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>X</term>
                <listitem>
                    <para>a real symmetric matrix, the stabilizing solution of the Riccati equation</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function computes the linear quadratic integral full-state gain K for the plant P.
            The associated system block diagram is:
        </para>
        <para>
            <inlinemediaobject>
                <imageobject>
                    <imagedata fileref="../../../images/lqi.png"/>
                </imageobject>
            </inlinemediaobject>
        </para>
        <para>
            The plant P is given by its state space representation
            <latex style="display">\text{P}=\left\lbrace \begin{array}{l}\dot{x}=A x+B u\\y=C x+D u \end{array}\right. \text{ in continuous time or } \text{P}=\left\lbrace \begin{array}{l}\overset{+}{x}=A x+B_2 u\\y=C x+D u \end{array}\right. \text{ in discrete time.}</latex>
            The cost function in l2-norm is:
            <latex style="display">\int_{t=0}^\infty{z(t)' Q z(t)+u(t)' R u(t)+2 z(t) S u(t) dt}\text{ in continuous time } </latex>
            <latex style="display">\sum_{k=0}^\infty{z(k)' Q z(k)+u(k)' R u(k)+2 z(k) S u(k)}\text{ in discrete time.}</latex>
            where <latex>z=\left[\begin{array}{l}x\\x_i \end{array}\right]</latex> and <emphasis>x<subscript>i</subscript></emphasis> is the integrator(s) state(s);
        </para>
        <warning>
            It is assumed that matrix <emphasis>R</emphasis> is non singular.
        </warning>
        <note>
            If the full state of the system is not available, an estimator  of the plant state
            can be built using the <link linkend="lqe">lqe()</link> function.
        </note>
    </refsection>
    <refsection>
        <title>Algorithm</title>
        <para>
            The lqi function solves the <link linkend="lqr">lqr</link> problem for the augmented plant
            <latex style="display"><![CDATA[\left\lbrace \begin{array}{l}\left[\begin{array}{l}\dot{x}\\ \dot{x_i} \end{array}\right]=\left[\begin{array}{ll}A&0\\-C&0 \end{array}\right]\left[\begin{array}{l}x\\x_i \end{array}\right]+\left[\begin{array}{l}B\\-G \end{array}\right] u \end{array}\right. \text{ in continuous time }]]></latex>
            <latex style="display"><![CDATA[\text{P}=\left\lbrace\begin{array}{l}\left[\begin{array}{l}\overset{+}{x}\\ \overset{+}{x_i} \end{array}\right]=\left[\begin{array}{ll}A&0\\-C dt&I \end{array}\right]\left[\begin{array}{l}x\\x_i \end{array}\right]+\left[\begin{array}{l}B\\-G dt \end{array}\right] u \end{array} \right.\text{ in discrete time }]]>
            </latex>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            Linear quadratic integral controller of a simplified disk drive using state observer.
        </para>
        <para>
            <inlinemediaobject>
                <imageobject>
                    <imagedata fileref="../../../images/lqifull.png"/>
                </imageobject>
            </inlinemediaobject>
        </para>
        <programlisting role="example"><![CDATA[
    //Disk drive model
    G=syslin("c",[0,32;-31.25,-0.4],[0;2.236068],[0.0698771,0]);
    t=linspace(0,20,2000);
    y=csim("step",t,G);

    //State estimator
    Wy=1;
    Wu=1;
    S=0;
    Q=G.B*Wu*G.B';
    R=Wy+G.D*S + S'*G.D+G.D*Wu*G.D';
    S=G.B*Wu*G.D'+S;

    //State estimator
    [Kf,X]=lqe(G,Q,R,S);
    Gx=observer(G,Kf);

    //LQI compensator

    wy=100;
    Q= wy*blockdiag(G.C'*G.C,1);
    R=1/wy;
    Kc=lqi(G,Q,R);
    //full controller
    K=lft([1;1]*(-Kc(1:2)*Gx(:,[2 1])+Kc(3)*[1/%s 0]),1);//e-->u

    //Full system
    H=(-K*G)/.(1);// full system transfer function

    y=csim("step",t,H);
    clf;plot(t,y)
    ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="observer">observer</link>
            </member>

            <member>
                <link linkend="lqr">lqr</link>
            </member>
            <member>
                <link linkend="lqg">lqg</link>
            </member>
            <member>
                <link linkend="lft">lft</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
      <title>History</title>
      <revhistory>
        <revision>
          <revnumber>6.0</revnumber>
          <revdescription>
             lqi() function introduced.
          </revdescription>
        </revision>
      </revhistory>
    </refsection>
</refentry>
