<?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="arl2">
    <refnamediv>
        <refname>arl2</refname>
        <refpurpose>SISO model realization by L2 transfer approximation</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            h = arl2(y, den0, n)
            h = arl2(y, den0, n, imp)
            h = arl2(y, den0, n, imp, 'all')
            h = arl2(y, den0, n, 'all')
            [den, num, err] = arl2(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        real vector or polynomial in <literal>z^-1</literal>, it contains the
                        coefficients of the Fourier's series of the rational system to approximate
                        (the impulse response)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>den0</term>
                <listitem>
                    <para>
                        a polynomial which gives an initial guess of the solution, it may be <literal>poly(1,'z','c')</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n</term>
                <listitem>
                    <para>integer, the degree of approximating transfer function (degree of den)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>imp</term>
                <listitem>
                    <para>
                        integer in <literal>(0,1,2)</literal> (verbose mode)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>
                        transfer function <literal>num/den</literal> or transfer matrix (column vector) when flag <literal>'all'</literal> is given.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>den</term>
                <listitem>
                    <para>polynomial or vector of polynomials, contains the denominator(s) of the solution(s)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>num</term>
                <listitem>
                    <para>polynomial or vector of polynomials, contains the numerator(s) of the solution(s)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>err</term>
                <listitem>
                    <para>real constant or vector , the l2-error achieved for each solutions</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            <literal>[den,num,err]=arl2(y,den0,n [,imp]) </literal> finds a pair of polynomials
            <literal>num</literal> and <literal>den</literal> such that the transfer function <literal>num/den</literal>
            is stable and its impulse response approximates (with a minimal l2
            norm) the vector <literal>y</literal> assumed to be completed by an infinite number
            of zeros.
        </para>
        <para>
            If <literal>y(z)  =  y(1)(1/z)+y(2)(1/z^2)+ ...+ y(ny)(1/z^ny)</literal>
        </para>
        <para>
            then l2-norm of <literal>num/den - y(z)</literal> is <literal>err</literal>.
        </para>
        <para>
            <literal>n</literal> is the degree of the polynomial <literal>den</literal>.
        </para>
        <para>
            The <literal>num/den</literal>  transfer function is a L2 approximant of the
            Fourier's series of the rational system.
        </para>
        <para>
            Various intermediate results are printed according to <literal>imp</literal>.
        </para>
        <para>
            <literal>[den,num,err]=arl2(y,den0,n [,imp],'all') </literal>  returns in the
            vectors of polynomials <literal>num</literal> and <literal>den</literal>  a set of local
            optimums for the problem. The solutions are sorted with increasing
            errors <literal>err</literal>. In this case <literal>den0</literal> is already assumed to be
            <literal>poly(1,'z','c')</literal>
        </para>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
v = ones(1,20);
clf();
plot2d([], [v';zeros(80,1)], 2, '051',' ',[1,-0.5,100,1.5])

[d,n,e] = arl2(v, poly(1,'z','c'),1)
plot2d([], ldiv(n,d,100), 2, '000')
[d,n,e] = arl2(v,d,3)
plot2d([], ldiv(n,d,100), 3, '000')
[d,n,e] = arl2(v,d,8)
plot2d([], ldiv(n,d,100), 5, '000')

[d,n,e] = arl2(v,poly(1,'z','c'),4,'all')
plot2d([], ldiv(n(1),d(1),100), 10, '000')
 ]]></programlisting>
        <scilab:image>
            v = ones(1,20);
            plot2d([], [v';zeros(80,1)], 2, '051',' ',[1,-0.5,100,1.5])

            [d,n,e] = arl2(v, poly(1,'z','c'),1)
            plot2d([], ldiv(n,d,100), 2, '000')
            [d,n,e] = arl2(v,d,3)
            plot2d([], ldiv(n,d,100), 3, '000')
            [d,n,e] = arl2(v,d,8)
            plot2d([], ldiv(n,d,100), 5, '000')

            [d,n,e] = arl2(v,poly(1,'z','c'),4,'all')
            plot2d([], ldiv(n(1),d(1),100), 10, '000')
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="ldiv">ldiv</link>
            </member>
            <member>
                <link linkend="imrep2ss">imrep2ss</link>
            </member>
            <member>
                <link linkend="time_id">time_id</link>
            </member>
            <member>
                <link linkend="armax">armax</link>
            </member>
            <member>
                <link linkend="frep2tf">frep2tf</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
