Add examples for armax, armax1 & initstate
[scilab.git] / scilab / modules / cacsd / help / en_US / armax.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) ENPC - JPC
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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="armax">
14     <refnamediv>
15         <refname>armax</refname>
16         <refpurpose>armax identification</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[arc,la,lb,sig,resid]=armax(r,s,y,u,[b0f,prf])</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>y</term>
27                 <listitem>
28                     <para>output process  y(ny,n); ( ny: dimension of y , n : sample size)</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>u</term>
33                 <listitem>
34                     <para>input process   u(nu,n); ( nu: dimension of u , n : sample size)</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>r and s</term>
39                 <listitem>
40                     <para>auto-regression orders r &gt;=0 et s &gt;=-1</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>b0f</term>
45                 <listitem>
46                     <para>optional parameter. Its default value is 0 and it means that the coefficient b0 must be identified. if bof=1 the b0 is supposed to be zero and is not identified</para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>prf</term>
51                 <listitem>
52                     <para>optional parameter for display control. If prf =1, the default value,  a display of the identified Arma is given.</para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>arc</term>
57                 <listitem>
58                     <para>a Scilab arma object (see armac)</para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>la</term>
63                 <listitem>
64                     <para>is the list(a,a+eta,a-eta) ( la = a in dimension 1) ; where eta is the estimated standard deviation.  , a=[Id,a1,a2,...,ar] where each ai is a matrix of size (ny,ny)</para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>lb</term>
69                 <listitem>
70                     <para>is the list(b,b+etb,b-etb) (lb =b in dimension 1) ; where etb is the estimated standard deviation. b=[b0,.....,b_s] where each bi is a matrix of size (nu,nu)</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>sig</term>
75                 <listitem>
76                     <para>is the estimated standard deviation of the noise and resid=[ sig*e(t0),....] (</para>
77                 </listitem>
78             </varlistentry>
79         </variablelist>
80     </refsection>
81     <refsection>
82         <title>Description</title>
83         <para>
84             armax is used to identify the coefficients of a n-dimensional 
85             ARX process
86         </para>
87         <programlisting role=""><![CDATA[ 
88 A(z^-1)y= B(z^-1)u + sig*e(t)
89  ]]></programlisting>
90         <para>
91             where e(t) is a n-dimensional white noise with variance I.
92             sig  an nxn matrix and A(z) and B(z):
93         </para>
94         <programlisting role=""><![CDATA[ 
95 A(z) = 1+a1*z+...+a_r*z^r; ( r=0 => A(z)=1)
96 B(z) = b0+b1*z+...+b_s z^s ( s=-1 => B(z)=0)
97  ]]></programlisting>
98         <para>
99             for the method see Eykhoff in trends and progress in system identification, page 96.
100             with  
101             <literal>z(t)=[y(t-1),..,y(t-r),u(t),...,u(t-s)]</literal>
102             and
103             <literal>coef= [-a1,..,-ar,b0,...,b_s] </literal>
104             we can write 
105             <literal>y(t)= coef* z(t) + sig*e(t) </literal> and the algorithm minimises 
106             <literal>sum_{t=1}^N ( [y(t)- coef'z(t)]^2)</literal>
107             where t0=max(max(r,s)+1,1))).
108         </para>
109     </refsection>
110     <refsection>
111         <title>Examples</title>
112         <programlisting role="example"><![CDATA[ 
113 //-Ex1- Arma model : y(t) = 0.2*u(t-1)+0.01*e(t-1)
114 ny=1,nu=1,sig=0.01;
115 Arma=armac(1,[0,0.2],[0,1],ny,nu,sig)  //defining the above arma model
116 u=rand(1,1000,'normal');     //a random input sequence u
117 y=arsimul(Arma,u); //simulation of a y output sequence associated with u.
118 Armaest=armax(0,1,y,u);   //Identified model given u and y.
119 Acoeff=Armaest('a');    //Coefficients of the polynomial A(x)
120 Bcoeff=Armaest('b')     //Coefficients of the polynomial B(x)
121 Dcoeff=Armaest('d');    //Coefficients of the polynomial D(x)
122 [Ax,Bx,Dx]=arma2p(Armaest)   //Results in polynomial form. 
123  ]]></programlisting>
124         <programlisting role="example"><![CDATA[ 
125 //-Ex2- Arma1: y_t -0.8*y_{t-1} + 0.2*y_{t-2} =  sig*e(t)
126 ny=1,nu=1;sig=0.001;
127 // First step: simulation the Arma1 model, for that we define
128 // Arma2: y_t -0.8*y_{t-1} + 0.2*y_{t-2} = sig*u(t)
129 // with normal deviates for u(t).  
130 Arma2=armac([1,-0.8,0.2],sig,0,ny,nu,0);
131 //Definition of the Arma2 arma model (a model with B=sig and without noise!)
132 u=rand(1,10000,'normal');  // An input sequence for Arma2
133 y=arsimul(Arma2,u); // y = output of Arma2 with input u 
134 //                     can be seen as output of Arma1.
135 // Second step: identification. We look for an Arma model
136 // y(t) + a1*y(t-1) + a2 *y(t-2) =  sig*e(t)
137 Arma1est=armax(2,-1,y,[]);
138 [A,B,D]=arma2p(Arma1est)
139  ]]></programlisting>
140         <programlisting role="example"><![CDATA[ 
141 a = [1, -2.851, 2.717, -0.865];
142 b = [0, 1, 1, 1];
143 d = [1, 0.7, 0.2];
144 ar = armac(a, b, d, 1, 1, 1);
145 disp(_("Simulation of an ARMAX process:"));
146 disp(ar);
147 // The input
148 n = 300;
149 u = -prbs_a(n, 1, int([2.5,5,10,17.5,20,22,27,35]*100/12));
150 // simulation
151 zd = narsimul(ar, u);
152
153 // visualization
154 plot2d(1:n,[zd',1000*u'],style=[1,3]);curves = gce();
155 legend(["Simulated output";"Input [scaled]"])
156  ]]></programlisting>
157         <scilab:image>
158             a = [1, -2.851, 2.717, -0.865];
159             b = [0, 1, 1, 1];
160             d = [1, 0.7, 0.2];
161             ar = armac(a, b, d, 1, 1, 1);
162             n = 300;
163             u = -prbs_a(n, 1, int([2.5,5,10,17.5,20,22,27,35]*100/12));
164             zd = narsimul(ar, u);
165             plot2d(1:n,[zd',1000*u'],style=[1,3]);curves = gce();
166             legend(["Simulated output";"Input [scaled]"]);
167         </scilab:image>
168     </refsection>
169     <refsection role="see also">
170         <title>See Also</title>
171         <simplelist type="inline">
172             <member>
173                 <link linkend="imrep2ss">imrep2ss</link>
174             </member>
175             <member>
176                 <link linkend="time_id">time_id</link>
177             </member>
178             <member>
179                 <link linkend="arl2">arl2</link>
180             </member>
181             <member>
182                 <link linkend="armax">armax</link>
183             </member>
184             <member>
185                 <link linkend="frep2tf">frep2tf</link>
186             </member>
187         </simplelist>
188     </refsection>
189 </refentry>