<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Serge STEER
 * Copyright (C) 2008 - INRIA - Francois 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: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="bloc2ss" xml:lang="en">
    <refnamediv>
        <refname>bloc2ss</refname>
        <refpurpose>block-diagram to state-space conversion</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>sl = bloc2ss(blocd)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>blocd</term>
                <listitem>
                    <para>list</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>sl</term>
                <listitem>
                    <para>list</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>Given a block-diagram representation of a linear system
            <literal>bloc2ss</literal> converts this representation to a state-space
            linear system. The first element of the list <literal>blocd</literal> must
            be the string <literal>'blocd'</literal>. Each other element of this list
            is itself a list of one the following types :
        </para>
        <programlisting><![CDATA[
list('transfer','name_of_linear_system')
 ]]></programlisting>
        <programlisting><![CDATA[
list('link','name_of_link',
             [number_of_upstream_box,upstream_box_port],
             [downstream_box_1,downstream_box_1_portnumber],
             [downstream_box_2,downstream_box_2_portnumber],
             ...)
 ]]></programlisting>
        <para>
            The strings <literal>'transfer'</literal> and
            <literal>'link'</literal> are keywords which indicate the type of element
            in the block diagram.
        </para>
        <para>Case 1 : the second parameter of the list is a character string
            which may refer (for a possible further evaluation) to the Scilab name of
            a linear system given in state-space representation
            (<literal>syslin</literal> list) or in transfer form (matrix of
            rationals).
        </para>
        <para>To each transfer block is associated an integer. To each input and
            output of a transfer block is also associated its number, an integer (see
            examples)
        </para>
        <para>Case 2 : the second kind of element in a block-diagram
            representation is a link. A link links one output of a block represented
            by the pair <literal>[number_of_upstream_box,upstream_box_port]</literal>,
            to different inputs of other blocks. Each such input is represented by the
            pair
            <literal>[downstream_box_i,downstream_box_i_portnumber]</literal>.
        </para>
        <para>The different elements of a block-diagram can be defined in an
            arbitrary order.
        </para>
        <para>For example</para>
        <para>
            [1] <literal>S1*S2</literal> with unit feedback.
        </para>
        <para>
            There are 3 transfers <literal>S1</literal> (number
            <literal>n_s1=2</literal>) , <literal>S2</literal> (number
            <literal>n_s2=3</literal>) and an adder (number
            <literal>n_add=4</literal>) with symbolic transfer function
            <literal>['1','1']</literal>.
        </para>
        <para>
            There are 4 links:
            <itemizedlist>
              <listitem>
                The first one (named <literal>'U'</literal>) links the input
                (port 0 of fictitious block -1, omitted) to port 1 of the adder.
              </listitem>
              <listitem>
                The second one links the (output)port 1 of the adder to the (input)port 1 of system
                <literal>S1</literal>.
              </listitem>
              <listitem>
                The third one links the (output)port 1 of <literal>S1</literal> to
                the (input)port 1 of <literal>S2</literal>.
              </listitem>
              <listitem>
                The fourth link (named <literal>'Y'</literal>) links (output)port 1 of
                <literal>S2</literal> to the output (port 0 of fictitious block -1,
                omitted) and to (input)port 2 of the adder.
              </listitem>
          </itemizedlist>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//Initialization
syst=list('blocd'); l=1;

//Systems
l=l+1;
n_s1=l;
syst(l)=list('transfer','S1');  //System 1
l=l+1;
n_s2=l;
syst(l)=list('transfer','S2');  //System 2
l=l+1;
n_adder=l;
syst(l)=list('transfer',['1','1']);  //adder

//Links
// Inputs  -1 --> input 1
l=l+1;
syst(l)=list('link','U1',[-1],[n_adder,1]);

// Internal
l=l+1;
syst(l)=list('link',' ',[n_adder,1],[n_s1,1]);
l=l+1;
syst(l)=list('link',' ',[n_s1,1],[n_s2,1]);

// Outputs // -1 -> output 1
l=l+1;
syst(l)=list('link','Y',[n_s2,1],[-1],[n_adder,2]);
 ]]></programlisting>
        <para>
            With <literal>s=poly(0,'s'); S1=1/(s+1);S2=1/s;</literal> the result
            of the evaluation call <literal>sl=bloc2ss(syst);</literal> is a
            state-space representation for <literal>1/(s^2+s-1)</literal>.
        </para>
        <para>[2] Example of LFT (Linear Fractional Transformation):</para>
        <programlisting role="example"><![CDATA[
//Initialization
syst=list('blocd');
l=1;

//System (2x2 blocks plant)
l=l+1;
n_s=l;
syst(l)=list('transfer',['P11','P12';'P21','P22']);

//Controller
l=l+1;
n_k=l;
syst(l)=list('transfer','k');

//Links
l=l+1;
syst(l)=list('link','w',[-1],[n_s,1]);
l=l+1;
syst(l)=list('link','z',[n_s,1],[-1]);
l=l+1;
syst(l)=list('link','u',[n_k,1],[n_s,2]);
l=l+1;
syst(l)=list('link','y',[n_s,2],[n_k,1]);
 ]]></programlisting>
        <para>With</para>
        <programlisting role="example"><![CDATA[
A=[0,1;0,0];
B=[1;1];
C=[1,1];
D=poly(0,'s');
P=syslin('c',A,B,C,D);
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="poly">poly</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
