example of aff2ab help page updated.
[scilab.git] / scilab / modules / linear_algebra / help / en_US / linear / aff2ab.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="aff2ab">
17     <refnamediv>
18         <refname>aff2ab</refname>
19         <refpurpose>linear (affine) function to A,b conversion</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>[A,b]=aff2ab(afunction,dimX,D [,flag])</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>afunction</term>
30                 <listitem>
31                     <para>
32                         a scilab function <literal> Y =fct(X,D) </literal> where <literal>X, D, Y</literal> are <literal>list</literal> of matrices
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>dimX</term>
38                 <listitem>
39                     <para>
40                         a p x 2 integer matrix (<literal>p</literal> is the number of matrices in <literal>X</literal>)
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>D</term>
46                 <listitem>
47                     <para>
48                         a <literal>list</literal> of real matrices (or any other valid Scilab object).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>flag</term>
54                 <listitem>
55                     <para>
56                         optional parameter (<literal>flag='f'</literal> or <literal>flag='sp'</literal>)
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>A</term>
62                 <listitem>
63                     <para>a real matrix</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>b</term>
68                 <listitem>
69                     <para>
70                         a real vector having same row dimension as <literal>A</literal>
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75     </refsection>
76     <refsection>
77         <title>Description</title>
78         <para>
79             <literal>aff2ab</literal>  returns the matrix representation of an affine
80             function (in the canonical basis).
81         </para>
82         <para>
83             <literal>afunction</literal> is a function with imposed syntax:
84             <literal> Y=afunction(X,D) </literal> where <literal> X=list(X1,X2,...,Xp) </literal> is
85             a list of p real matrices, and <literal> Y=list(Y1,...,Yq) </literal> is
86             a list of q real real matrices which depend linearly of
87             the <literal> Xi</literal>'s. The (optional) input <literal> D</literal> contains
88             parameters needed to compute Y as a function of X.
89             (It is generally a list of matrices).
90         </para>
91         <para>
92             <literal> dimX</literal> is a p x 2 matrix: <literal>dimX(i)=[nri,nci]</literal>
93             is the actual number of rows and columns of matrix <literal>Xi</literal>.
94             These dimensions determine <literal>na</literal>, the column dimension of
95             the resulting matrix <literal>A</literal>: <literal>na=nr1*nc1 +...+ nrp*ncp</literal>.
96         </para>
97         <para>
98             If the optional parameter <literal>flag='sp'</literal> the resulting <literal>A</literal>
99             matrix is returned as a sparse matrix.
100         </para>
101         <para>
102             This function is useful to solve a system of linear equations
103             where the unknown variables are matrices.
104         </para>
105     </refsection>
106     <refsection>
107         <title>Examples</title>
108         <programlisting role="example"><![CDATA[
109 // Lyapunov equation solver (one unknown variable, one constraint)
110 deff('Y=lyapunov(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q)')
111 A=rand(3,3);Q=rand(3,3);Q=Q+Q';D=list(A,Q);dimX=[3,3];
112 [Aly,bly]=aff2ab(lyapunov,dimX,D);
113 [Xl,kerA]=linsolve(Aly,bly); Xv=vec2list(Xl,dimX); lyapunov(Xv,D)
114 Xm=Xv(:); A'*Xm+Xm*A-Q
115
116 // Lyapunov equation solver with redundant constraint X=X'
117 // (one variable, two constraints) D is global variable
118 deff('Y=ly2(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q,Xm''-Xm)')
119 A=rand(3,3);Q=rand(3,3);Q=Q+Q';D=list(A,Q);dimX=[3,3];
120 [Aly,bly]=aff2ab(ly2,dimX,D);
121 [Xl,kerA]=linsolve(Aly,bly); Xv=vec2list(Xl,dimX); ly2(Xv,D)
122
123 // Francis equations
124 // Find matrices X1 and X2 such that:
125 // A1*X1 - X1*A2 + B*X2 -A3 = 0
126 // D1*X1 -D2 = 0
127 deff('Y=bruce(X,D)','[A1,A2,A3,B,D1,D2]=D(:);'+...
128 '[X1,X2]=X(:);Y=list(A1*X1-X1*A2+B*X2-A3,D1*X1-D2)')
129 A1=[-4,10;-1,2];A3=[1;2];B=[0;1];A2=1;D1=[0,1];D2=1;
130 D=list(A1,A2,A3,B,D1,D2);
131 [n1,m1]=size(A1);[n2,m2]=size(A2);[n3,m3]=size(B);
132 dimX=[[m1,n2];[m3,m2]];
133 [Af,bf]=aff2ab(bruce,dimX,D);
134 [Xf,KerAf]=linsolve(Af,bf);Xsol=vec2list(Xf,dimX)
135 bruce(Xsol,D)
136
137 // Find all X which commute with A
138 deff('y=f(X,D)','y=list(D(:)*X(:)-X(:)*D(:))')
139 A=rand(3,3);dimX=[3,3];[Af,bf]=aff2ab(f,dimX,list(A));
140 [Xf,KerAf]=linsolve(Af,bf);[p,q]=size(KerAf);
141 Xsol=vec2list(Xf+KerAf*rand(q,1),dimX);
142 C=Xsol(:); A*C-C*A
143  ]]></programlisting>
144     </refsection>
145     <refsection role="see also">
146         <title>See also</title>
147         <simplelist type="inline">
148             <member>
149                 <link linkend="linsolve">linsolve</link>
150             </member>
151         </simplelist>
152     </refsection>
153 </refentry>