* Bug #11669 fixed - Help page of kalm and srkf functions had no example. 28/10828/2
Charlotte HECQUET [Thu, 14 Mar 2013 15:14:18 +0000 (16:14 +0100)]
Change-Id: Iff105a921e27efadfdefd2b65275ba6c61764b62

scilab/CHANGES_5.4.X
scilab/modules/helptools/images/kalm_en_US_1.png [new file with mode: 0644]
scilab/modules/helptools/images/kalm_fr_FR_1.png [new file with mode: 0644]
scilab/modules/helptools/images/kalm_pt_BR_1.png [new file with mode: 0644]
scilab/modules/helptools/images/kalm_ru_RU_1.png [new file with mode: 0644]
scilab/modules/signal_processing/help/en_US/filters/kalm.xml
scilab/modules/signal_processing/help/en_US/filters/srkf.xml

index 3944a86..1f69bda 100644 (file)
@@ -316,6 +316,8 @@ Bug fixes
 
 * Bug #11639 fixed - Uninstall removed all scilab registry information.
 
+* Bug #11669 fixed - Help page of kalm and srkf functions had no example.
+
 * Bug #11711 fixed - xclick and xgetmouse did not work under Mac OS X.
 
 * Bug #11778 fixed - Bad color_map dims did not return an error.
diff --git a/scilab/modules/helptools/images/kalm_en_US_1.png b/scilab/modules/helptools/images/kalm_en_US_1.png
new file mode 100644 (file)
index 0000000..b01ce5a
Binary files /dev/null and b/scilab/modules/helptools/images/kalm_en_US_1.png differ
diff --git a/scilab/modules/helptools/images/kalm_fr_FR_1.png b/scilab/modules/helptools/images/kalm_fr_FR_1.png
new file mode 100644 (file)
index 0000000..b01ce5a
Binary files /dev/null and b/scilab/modules/helptools/images/kalm_fr_FR_1.png differ
diff --git a/scilab/modules/helptools/images/kalm_pt_BR_1.png b/scilab/modules/helptools/images/kalm_pt_BR_1.png
new file mode 100644 (file)
index 0000000..b01ce5a
Binary files /dev/null and b/scilab/modules/helptools/images/kalm_pt_BR_1.png differ
diff --git a/scilab/modules/helptools/images/kalm_ru_RU_1.png b/scilab/modules/helptools/images/kalm_ru_RU_1.png
new file mode 100644 (file)
index 0000000..b01ce5a
Binary files /dev/null and b/scilab/modules/helptools/images/kalm_ru_RU_1.png differ
index 9f32302..0c2a188 100644 (file)
@@ -32,7 +32,7 @@
             <varlistentry>
                 <term>y</term>
                 <listitem>
-                    <para>current observation Output from the function is:</para>
+                    <para>current observation Output</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
@@ -42,7 +42,7 @@
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x</term>
+                <term>x,p</term>
                 <listitem>
                     <para>updated estimate and error covariance at t=0  based on data up to t=0</para>
                 </listitem>
     <refsection>
         <title>Description</title>
         <para>
-            function which gives the Kalman update and error variance
+            This function gives the Kalman update and error covariance. To do this, we have to enter <varname>f</varname>, 
+            <varname>g</varname>, <varname>h</varname> which are based on the state space model:
         </para>
+        <para> 
+            <literal>x(k+1)=<varname>f</varname>*x(k)+<varname>g</varname>*u(k)+v(k)</literal>
+        </para>
+        <para>
+            <literal>y(k)=<varname>h</varname>*x(k)+w(k)</literal>
+        </para>
+        <para>
+            with <literal>v(k)</literal> (resp. <literal>w(k)</literal>) is the process noise (resp. the observation noise) 
+            supposed to be drawn from a zero mean Gaussian white noise with the covariance <varname>q</varname> (resp. <varname>r</varname>).
+        </para>
+        <para>
+            Precisely, Kalman filter is a recursive estimator which gives the estimate of the current state and the error covariance. 
+            Its advantage is the fact that it only needs the estimated state from the previous step and the current measurement.
+        </para>
+        <para>
+            Algorithm:
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    Innovation (output error): <literal>E=<varname>y</varname>-<varname>h</varname>*<varname>x0</varname></literal>
+                </para>
+            </listitem>    
+            <listitem>
+                <para>
+                    Output Error covariance: <literal>S=<varname>h</varname>*<varname>p0</varname>*<varname>h</varname>'+<varname>r</varname></literal>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Kalman gain: <literal>K=<varname>p0</varname>*<varname>h</varname>'*S^-1</literal>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Correction of state estimation: <literal><varname>x</varname>=<varname>x0</varname>+K*E</literal>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Correction of estimation of error covariance: <literal><varname>p</varname>=<varname>p0</varname>-K*<varname>h</varname>*<varname>p0</varname></literal>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    State prediction: <literal><varname>x1</varname>=<varname>f</varname>*<varname>x</varname></literal>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Error covariance prediction: <literal><varname>p1</varname>=<varname>f</varname>*<varname>p</varname>*<varname>f</varname>'+<varname>g</varname>*<varname>q</varname>*<varname>g</varname>'</literal>
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example: Extraction of a sinusoid from noise with Kalman filter</title>
+        <programlisting role="Example"><![CDATA[
+// Construction of the sinusoid
+w=%pi/4; // angular frequency
+T=0.1; // period
+t=0:T:500
+signal=cos(w*t);
+// Sinusoid with noise
+v=rand(t,"normal");
+y=signal+v;
+// Plot the sinusoid with noise
+subplot(2,1,1);
+plot(t,y);
+xtitle("sinusoid with noise","t");
+// System
+n=2; // system order
+f=[cos(w*T) -sin(w*T); sin(w*T) cos(w*T)];
+g=0;
+h=[1 0];
+p0=[1000 0; 0 0];
+R=1;
+Q=0;
+x0=zeros(n,1);
+// Initialize for loop
+x1=x0;
+p1=p0;
+// Kalman filter
+for i=1:length(t)-1
+    [x1(:,i+1),p1,x,p]=kalm(y(i),x1(:,i),p1,f,g,h,Q,R);
+end
+// Plot the results (in red) to compare with the sinusoid (in green)
+subplot(2,1,2);
+plot(t,signal,"color","green");
+plot(t,x1(1,:),"color","red");
+xtitle("Comparison between sinusoid (green) and extraction with Kalman filter (red)","t");
+]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="srkf">srkf</link>
+            </member>
+            <member> 
+                <link linkend="sskf">sskf</link>
+            </member>
+        </simplelist>
     </refsection>
 </refentry>
index 5400c93..5bcefd3 100644 (file)
@@ -32,7 +32,7 @@
             <varlistentry>
                 <term>y</term>
                 <listitem>
-                    <para>current observation Output from the function is</para>
+                    <para>current observation Output</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            square root Kalman filter algorithm
+            This function is the square root form of Kalman filter. It is more efficient than the simple Kalman filter in term of numerical stability,
+            especially if dynamic noise covariance <varname>q</varname> is small. In effect, that can provock an indefinite numerical representation
+            of the state covariance matrix <literal>p</literal>, whereas <literal>p</literal> is positive definite. So, the goal of <function>srkf</function>
+            is to propagate <literal>p</literal> using a Cholesky factorization algorithm. These factors can be updated at each step of the algorithm, which
+            allows to keep <literal>p</literal> in its basic form.
         </para>
     </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example"><![CDATA[
+f=[0 0 1; 0 1 0; 2 3 4]; //State matrix
+g=[1;-1;1]; //Input matrix
+h=[1 1 0; 0 1 0; 0 0 0]; //Output matrix
+Q=[3 2 1; 2 2 1; 1 1 1]; //Covariance matrix of dynamic noise
+R=[2 1 1; 1 1 1; 1 1 2]; //Covariance matrix of observation noise
+// Initialisation
+p0=[6 3 2; 3 5 2; 2 2 4];
+x0=[1;1;1];
+y=[2 8 7]'; // Current observation output matrix
+[x1,p1]=srkf(y,x0,p0,f,h,Q,R)
+]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="kalm">kalm</link>
+            </member>
+            <member>
+                <link linkend="sskf">sskf</link>
+            </member>
+        </simplelist>
+    </refsection>
 </refentry>