aff2ab
======

linear (affine) function to A,b conversion



Calling Sequence
~~~~~~~~~~~~~~~~


::

    [A,b]=aff2ab(afunction,dimX,D [,flag])




Arguments
~~~~~~~~~

:afunction a scilab function `Y =fct(X,D)` where `X, D, Y` are `list`
  of matrices
: :dimX a p x 2 integer matrix ( `p` is the number of matrices in `X`)
: :D a `list` of real matrices (or any other valid Scilab object).
: :flag optional parameter ( `flag='f'` or `flag='sp'`)
: :A a real matrix
: :b a real vector having same row dimension as `A`
:



Description
~~~~~~~~~~~

`aff2ab` returns the matrix representation of an affine function (in
the canonical basis).

`afunction` is a function with imposed syntax: `Y=afunction(X,D)`
where `X=list(X1,X2,...,Xp)` is a list of p real matrices, and
`Y=list(Y1,...,Yq)` is a list of q real real matrices which depend
linearly of the `Xi`'s. The (optional) input `D` contains parameters
needed to compute Y as a function of X. (It is generally a list of
matrices).

`dimX` is a p x 2 matrix: `dimX(i)=[nri,nci]` is the actual number of
rows and columns of matrix `Xi`. These dimensions determine `na`, the
column dimension of the resulting matrix `A`: `na=nr1*nc1 +...+
nrp*ncp`.

If the optional parameter `flag='sp'` the resulting `A` matrix is
returned as a sparse matrix.

This function is useful to solve a system of linear equations where
the unknown variables are matrices.



Examples
~~~~~~~~


::

    // Lyapunov equation solver (one unknown variable, one constraint)
    `deff`_('Y=lyapunov(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q)')
    A=`rand`_(3,3);Q=`rand`_(3,3);Q=Q+Q';D=`list`_(A,Q);dimX=[3,3];
    [Aly,bly]=aff2ab(lyapunov,dimX,D);
    [Xl,kerA]=`linsolve`_(Aly,bly); Xv=`vec2list`_(Xl,dimX); lyapunov(Xv,D)
    Xm=Xv(:); A'*Xm+Xm*A-Q
    
    // Lyapunov equation solver with redundant constraint X=X'
    // (one variable, two constraints) D is global variable
    `deff`_('Y=ly2(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q,Xm''-Xm)')
    A=`rand`_(3,3);Q=`rand`_(3,3);Q=Q+Q';D=`list`_(A,Q);dimX=[3,3];
    [Aly,bly]=aff2ab(ly2,dimX,D);
    [Xl,kerA]=`linsolve`_(Aly,bly); Xv=`vec2list`_(Xl,dimX); ly2(Xv,D)
    
    // Francis equations
    // Find matrices X1 and X2 such that:
    // A1*X1 - X1*A2 + B*X2 -A3 = 0
    // D1*X1 -D2 = 0 
    `deff`_('Y=bruce(X,D)','[A1,A2,A3,B,D1,D2]=D(:),...
    [X1,X2]=X(:);Y=list(A1*X1-X1*A2+B*X2-A3,D1*X1-D2)')
    A1=[-4,10;-1,2];A3=[1;2];B=[0;1];A2=1;D1=[0,1];D2=1;
    D=`list`_(A1,A2,A3,B,D1,D2);
    [n1,m1]=`size`_(A1);[n2,m2]=`size`_(A2);[n3,m3]=`size`_(B);
    dimX=[[m1,n2];[m3,m2]];
    [Af,bf]=aff2ab(bruce,dimX,D);
    [Xf,KerAf]=`linsolve`_(Af,bf);Xsol=`vec2list`_(Xf,dimX)
    bruce(Xsol,D)
    
    // Find all X which commute with A
    `deff`_('y=f(X,D)','y=list(D(:)*X(:)-X(:)*D(:))')
    A=`rand`_(3,3);dimX=[3,3];[Af,bf]=aff2ab(f,dimX,`list`_(A));
    [Xf,KerAf]=`linsolve`_(Af,bf);[p,q]=`size`_(KerAf);
    Xsol=`vec2list`_(Xf+KerAf*`rand`_(q,1),dimX);
    C=Xsol(:); A*C-C*A




See Also
~~~~~~~~


+ `linsolve`_ linear equation solver


.. _linsolve: linsolve.html