<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - F Delebecque
 * 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="lqg">
    <refnamediv>
        <refname>lqg</refname>
        <refpurpose>LQG compensator</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
          K = lqg(P_aug, r)
          K = lqg(P, Qxu, Qwv)
          K = lqg(P, Qxu, Qwv, Qi, #dof)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>P_aug</term>
                <listitem>
                    <para>
                        State space representation of the augmented plant (see:
                        <link linkend="lqg2stan">lqg2stan</link>)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r</term>
                <listitem>
                    <para>
                        1 by 2 row vector = (number of measurements, number of
                        inputs) (dimension of the 2,2 part of
                        <literal>P_aug</literal>)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>P</term>
                <listitem>
                    <para>
                        State-space representation of the nominal plant
                        (<literal>nu</literal> inputs, <literal>ny</literal>
                        outputs, <literal>nx</literal> states).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Qxu</term>
                <listitem>
                    <para>
                        Symmetric <literal>nx+nu</literal> by
                        <literal>nx+nu</literal> weighting matrix.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Qwv</term>
                <listitem>
                    <para>
                        Symmetric <literal>nx+ny</literal> by <literal>nx+ny</literal> covariance matrix.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Qi</term>
                <listitem>
                    <para>
                        Symmetric <literal>ny</literal> by <literal>ny</literal> weight for integral term.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>#dof</term>
                <listitem>
                    <para>
                        Scalar with value in {1,2}, the degrees of freedom of the
                        controller. The default value is 2.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>K</term>
                <listitem>
                    <para>
                        Linear LQG (H2) controller in state-space representation.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <refsect2>
            <title>Regulation around zero</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="../../../images/lqg.png"/>
                </imageobject>
            </mediaobject>
            <variablelist>
                <varlistentry>
                    <term>
                        Syntax  <literal>K=lqg(P_aug,r)</literal>
                    </term>
                    <para>
                        Computes the linear optimal LQG (H2) controller for the
                        "augmented" plant <literal>P_aug</literal> which can be
                        generated by <link linkend="lqg2stan">lqg2stan</link>
                        givent the nominal plant plant <literal>P</literal>, the
                        weighting matrix <literal>Qxu</literal> and the noise
                        covariance matrix <literal>Qwv</literal>.
                    </para>
                </varlistentry>
                <varlistentry>
                    <term>
                        Syntax  <literal>K=lqg(P,Qxu,Qwv)</literal>
                    </term>
                    <para>
                        Computes the linear optimal LQG (H2) controller for the nominal
                        plant <literal>P</literal>, the weighting matrix
                        <literal>Qxu</literal> and the noise covariance matrix
                        <literal>Qwv</literal>
                    </para>
                </varlistentry>
            </variablelist>
        </refsect2>
        <refsect2>
            <title>
                Regulation around a reference signal, Syntax <literal>K=lqg(P,Qxu,Qwv,Qi [,#dof])</literal>
            </title>
            <para>
                <mediaobject>
                    <imageobject>
                        <imagedata align="center" contentwidth="360" contentdepth="100"  fileref="../../../images/lqgi.png"/>
                    </imageobject>
                </mediaobject>
            </para>
            <para>
                Computes the linear optimal LQG (H2) reference tracking controller for the
                plant <literal>P</literal>, the weighting matrix
                <literal>Qxu</literal> and the noise covariance matrix
                <literal>Qwv</literal>
            </para>
        </refsect2>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            Assume the dynamical system formed by two masses connected by a spring and a damper:
        </para>
        <para>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="../../../images/twoMasses.png"/>
                </imageobject>
            </mediaobject>
        </para>
        <para>
            A force <latex> u=\bar{u}+e</latex> (where <emphasis>e</emphasis> is a noise) is
            applied to M, the deviations <emphasis>dy<subscript>1</subscript></emphasis> and
            <emphasis>dy<subscript>2</subscript></emphasis> from equilibrium positions of the
            masses are measured. These measures are subject to an additional
            noise <emphasis>v</emphasis>.
        </para>
        <para>
            A continuous time state space representation of this system is:
            <latex style="display"
             align="left"><![CDATA[\left\lbrace\begin{array}{l}
             \dot{x}=\left[\begin{array}{llll}0&1&0&0\\ -k/M&-b/M&k/M&b/M\\
             0&0&0&1\\ k/m&b/m&-k/m&-b/m \end{array}\right] x
             +\left[\begin{array}{l}0\\ 1/M\\ 0\\ 0 \end{array}\right]
             (\bar{u}+e)\\ \left[\begin{array}{l}dy_1\\
             dy_2\end{array}\right]=\left[\begin{array}{llll}1&0&0&0\\
             0&0&1&0 \end{array}\right] x +v \end{array}\right.]]></latex>
            <latex style="display" align="left">\text{Where }x=\left[\begin{array}{l}dy_1\\ \dot{dy_1}\\ dy_2\\
                \dot{dy_2}\end{array}\right]
            </latex>
        </para>
        <para>
            The instructions below can be used to compute a LQG compensator of the discretized
            version of this dynamical system. <emphasis>e</emphasis> and <emphasis>v</emphasis>
            are discrete time white noises such as <latex style="display"
      align="left">\mathbb{E}(e e')=Q_e \text{ , }\mathbb{E}(v
                v')=R_vv \text{ and }\mathbb{E}(e v')=S_{ev}
            </latex>
        </para>
        <para>
            The LQ cost is defined by <latex style="display"
      align="left"><![CDATA[\sum_0^\infty\left[\begin{array}{ll}x'&u'\end{array}\right]\left[\begin{array}{ll}Q_{xx}&0\\0&R_{uu}\end{array}\right]\left[\begin{array}{l}x\\u\end{array}\right]
      dt]]></latex>
        </para>
        <refsect2>
            <title>Regulation around zero</title>
            <programlisting role="example"><![CDATA[
      // Form the state space model
      M = 1; m = 0.2; k = 0.1; b = 0.004;
      A = [0     1    0    0
      -k/M  -b/M  k/M  b/M
      0     0    0    1
      k/m  b/m  -k/m  -b/m];
      B = [0; 1/M; 0; 0];
      C = [1 0 0 0  //dy1
      0 0 1 0];//dy2
      //inputs u and e; outputs dy1 and dy2
      P = syslin("c",A, B, C);
      // Discretize it
      dt=0.5;
      Pd=dscr(P, dt);

      // The noise variances
      Q_e=1; //additive input noise variance
      R_vv=0.0001*eye(2,2); //measurement noise variance
      Q_ww=Pd.B*Q_e*Pd.B'; //input noise adds to regular input u
      Qwv=blockdiag(Q_ww,R_vv);
      //The compensator weights
      Q_xx=diag([0.1 0 5 0]); //Weights on states
      R_uu   = 0.3; //Weight on input
      Qxu=blockdiag(Q_xx,R_uu);

      //----syntax [K,X]=lqg(P,Qxu,Qwv)---
      J=lqg(Pd,Qxu,Qwv);

      //----syntax [K,X]=lqg(P_aug,r)---
      // Form standard LQG model
      [Paug,r]=lqg2stan(Pd,Qxu,Qwv); // Form standard LQG model
      J1=lqg(Paug,r);

      //  Form the closed loop
      Sys=Pd/.(-J);
      // Compare real and Estimated states for initial state evolution
      t = 0:dt:30;
      // Simulate system evolution for initial state [1;0;0;0;
      y = flts(zeros(t),Sys,eye(8,1));
      clf;
      plot2d(t',y')
      e=gce();e.children.polyline_style=2;
      L=legend(["$dy_1$","$dy_2$"]);L.font_size=4;
      xlabel('Time (s)')
      ]]></programlisting>
            <scilab:image>
                // Form the state space model
                M = 1; m = 0.2; k = 0.1; b = 0.004;
                A = [0     1    0    0
                -k/M  -b/M  k/M  b/M
                0     0    0    1
                k/m  b/m  -k/m  -b/m];
                B = [0; 1/M; 0; 0];
                C = [1 0 0 0  //dy1
                0 0 1 0];//dy2
                //inputs u and e; outputs dy1 and dy2
                P = syslin("c",A, B, C);
                // Discretize it
                dt=0.5;
                Pd=dscr(P, dt);

                // The noise variances
                Q_e=1; //additive input noise variance
                R_vv=0.0001*eye(2,2); //measurement noise variance
                Q_ww=Pd.B*Q_e*Pd.B'; //input noise adds to regular input u
                Qwv=blockdiag(Q_ww,R_vv);
                //The compensator weights
                Q_xx=diag([0.1 0 5 0]); //Weights on states
                R_uu   = 0.3; //Weight on input
                Qxu=blockdiag(Q_xx,R_uu);

                //----syntax [K,X]=lqg(P,Qxu,Qwv)---
                J=lqg(Pd,Qxu,Qwv);

                //  Form the closed loop
                Sys=Pd/.(-J);
                // Compare real and Estimated states for initial state evolution
                t = 0:dt:30;
                // Simulate system evolution for initial state [1;0;0;0;
                y = flts(zeros(t),Sys,eye(8,1));
                clf;
                plot2d(t',y')
                e=gce();e.children.polyline_style=2;
                L=legend(["$dy_1$","$dy_2$"]);L.font_size=4;
                xlabel('Time (s)')
            </scilab:image>
        </refsect2>
        <refsect2>
            <title>
                Regulation around a reference signal, Syntax <literal>K=lqg(P,Qxu,Qwv,Qi [,#dof])</literal>
            </title>
            <para>
                The purpose of the controller is here to assign
                <emphasis>dy<subscript>2</subscript></emphasis> using the measure of
                <emphasis>dy<subscript>2</subscript></emphasis>.
            </para>
            <programlisting role="example"><![CDATA[
      M = 1; m = 0.2; k = 0.1; b = 0.004;
      A = [0     1    0    0
      -k/M  -b/M  k/M  b/M
      0     0    0    1
      k/m  b/m  -k/m  -b/m];
      B = [0; 1/M; 0; 0];
      C = [1 0 0 0  //dy1
      0 0 1 0];//dy2
      //inputs u and e; outputs dy1 and dy2
      P = syslin("c",A, B, C);
      // Discretize it
      dt=0.1;
      Pd=dscr(P, dt);

      // The noise variances
      Q_e=1; //additive input noise variance
      R_vv=0.0001; //measurement noise variance
      Q_ww=Pd.B*Q_e*Pd.B'; //input noise adds to regular input u
      Qwv=blockdiag(Q_ww,R_vv);
      //The compensator weights
      Q_xx=diag([0.1 0 1 0]); //Weights on states
      R_uu   = 0.1; //Weight on input
      Qxu=blockdiag(Q_xx,R_uu);

      //Control of the second mass position (y2)
      Qi=50;
      J=lqg(Pd(2,:),Qxu,Qwv,Qi);
      H=lft([1;1]*Pd(2,:)*(-J),1);
      //step response
      t=0:dt:15;
      r=ones(t);
      dy2=flts(r,H);
      clf;
      subplot(211);plot(t',dy2');xlabel("Time");ylabel("dy2")
      u=flts([r;dy2],J);
      subplot(212);plot(t',u');xlabel("Time");ylabel("u")
      ]]>
            </programlisting>
            <scilab:image>
                M = 1; m = 0.2; k = 0.1; b = 0.004;
                A = [0     1    0    0
                -k/M  -b/M  k/M  b/M
                0     0    0    1
                k/m  b/m  -k/m  -b/m];
                B = [0; 1/M; 0; 0];
                C = [1 0 0 0  //dy1
                0 0 1 0];//dy2
                //inputs u and e; outputs dy1 and dy2
                P = syslin("c",A, B, C);
                // Discretize it
                dt=0.1;
                Pd=dscr(P, dt);

                // The noise variances
                Q_e=1; //additive input noise variance
                R_vv=0.0001; //measurement noise variance
                Q_ww=Pd.B*Q_e*Pd.B'; //input noise adds to regular input u
                Qwv=blockdiag(Q_ww,R_vv);
                //The compensator weights
                Q_xx=diag([0.1 0 1 0]); //Weights on states
                R_uu   = 0.1; //Weight on input
                Qxu=blockdiag(Q_xx,R_uu);

                //Control of the second mass position (y2)
                Qi=50;
                J=lqg(Pd(2,:),Qxu,Qwv,Qi);
                H=lft([1;1]*Pd(2,:)*J,1);
                //step response
                t=0:dt:15;
                r=ones(t);
                dy2=flts(r,H);
                clf;
                subplot(211);plot(t',dy2');xlabel("Time");ylabel("dy2")
                u=flts([r;dy2],J);
                subplot(212);plot(t',u');xlabel("Time");ylabel("u")
            </scilab:image>
        </refsect2>
    </refsection>
    <refsection>
        <title>Reference</title>
        <para>
            <ulink url="http://www.springer.com/us/book/9780817640095"> Engineering and Scientific Computing with Scilab</ulink>, Claude Gomez and al.,Springer Science+Business Media, LLC,1999, ISNB:978-1-4612-7204-5
        </para>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="lqg2stan">lqg2stan</link>
            </member>
            <member>
                <link linkend="lqr">lqr</link>
            </member>
            <member>
                <link linkend="lqe">lqe</link>
            </member>
            <member>
                <link linkend="h_inf">h_inf</link>
            </member>
            <member>
                <link linkend="obscont">obscont</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
      <title>History</title>
      <revhistory>
        <revision>
          <revnumber>6.0</revnumber>
          <revdescription>
             lqg(P,Qxu,Qwv) and lqg(P,Qxu,Qwv,Qi,#dof) syntaxes added.
          </revdescription>
        </revision>
      </revhistory>
    </refsection>
</refentry>
