Xcos help : sorting the solvers and bringing minor corrections 92/9992/9
Paul BIGNIER [Tue, 11 Dec 2012 13:36:11 +0000 (14:36 +0100)]
Renamed files to sort the pages and corrected typos

Change-Id: Ied7b7b1b2f10e69491157ad9ede7c48bee54b6c7

scilab/modules/xcos/help/en_US/solvers/0-LSodar.xml [moved from scilab/modules/xcos/help/en_US/solvers/LSodar.xml with 92% similarity]
scilab/modules/xcos/help/en_US/solvers/1-CVode.xml [moved from scilab/modules/xcos/help/en_US/solvers/CVode.xml with 94% similarity]
scilab/modules/xcos/help/en_US/solvers/2-Runge-Kutta.xml [moved from scilab/modules/xcos/help/en_US/solvers/Runge-Kutta.xml with 96% similarity]
scilab/modules/xcos/help/en_US/solvers/3-Dormand-Price.xml [moved from scilab/modules/xcos/help/en_US/solvers/Dormand-Price.xml with 90% similarity]
scilab/modules/xcos/help/en_US/solvers/7-IDA.xml [moved from scilab/modules/xcos/help/en_US/solvers/IDA.xml with 94% similarity]

     <refnamediv>
         <refname>LSodar</refname>
         <refpurpose>
-            LSODAR (short for Livermore Solver for Ordinary Differential equations, with Automatic method switching for stiff and nonstiff problems, and with Root-finding) is a numerical solver providing an efficient and stable method to solve Ordinary Differential Equations (ODEs) Initial Value Problems. Called by <link linkend="xcos">xcos</link>.
+            <emphasis>LSodar</emphasis> (short for Livermore Solver for Ordinary Differential equations, with Automatic method switching for stiff and nonstiff problems, and with Root-finding) is a numerical solver providing an efficient and stable method to solve Ordinary Differential Equations (ODEs) Initial Value Problems.
         </refpurpose>
     </refnamediv>
     <refsection>
         <title>Description</title>
         <para>
-            LSODAR (short for Livermore Solver for Ordinary Differential equations, with Automatic method switching for stiff and nonstiff problems, and with Root-finding) is a numerical solver providing an efficient and stable variable-size step method to solve Initial Value Problems of the form :
+            Called by <link linkend="xcos">xcos</link>, <emphasis>LSodar</emphasis> (short for Livermore Solver for Ordinary Differential equations, with Automatic method switching for stiff and nonstiff problems, and with Root-finding) is a numerical solver providing an efficient and stable variable-size step method to solve Initial Value Problems of the form :
         </para>
         <para>
             <latex>
@@ -137,10 +137,10 @@ Time for BDF / Newton :
 Time for BDF / Functional :
  12.415
 
-Time for Adams / Functional :
+Time for Adams / Newton :
  8.651
 
-Time for Adams / Newton :
+Time for Adams / Functional :
  7.962
             ]]></screen>
         </para>
     <refnamediv>
         <refname>CVode</refname>
         <refpurpose>
-            <emphasis>CVode</emphasis> is a numerical solver providing an efficient and stable method to solve Ordinary Differential Equations (ODEs) Initial Value Problems. Called by <link linkend="xcos">xcos</link>, it uses either <emphasis>BDF</emphasis> or <emphasis>Adams</emphasis> as implicit integration method, and <emphasis>Newton</emphasis> or <emphasis>Functional</emphasis> iterations
+            <emphasis>CVode</emphasis> (short for C-language Variable-coefficients ODE solver) is a numerical solver providing an efficient and stable method to solve Ordinary Differential Equations (ODEs) Initial Value Problems. It uses either <emphasis>BDF</emphasis> or <emphasis>Adams</emphasis> as implicit integration method, and <emphasis>Newton</emphasis> or <emphasis>Functional</emphasis> iterations
         </refpurpose>
     </refnamediv>
     <refsection>
         <title>Description</title>
         <para>
-            <emphasis>CVode</emphasis> is a numerical solver providing an efficient and stable method to solve Initial Value Problems of the form :
+            Called by <link linkend="xcos">xcos</link>, <emphasis>CVode</emphasis> (short for C-language Variable-coefficients ODE solver) is a numerical solver providing an efficient and stable method to solve Initial Value Problems of the form :
         </para>
         <para>
             <latex>
@@ -225,7 +225,7 @@ Time for BDF / Newton :
         </para>
         <para>
             Now, in the following script, we compare the time difference between the methods by running the example with the four solvers in turn :
-            <link type="scilab" linkend ="scilab.scinotes/xcos/examples/solvers/integ.sce">
+            <link type="scilab" linkend ="scilab.scinotes/xcos/examples/solvers/integSundials.sce">
                 Open the script
             </link>
         </para>
@@ -253,10 +253,10 @@ Time for Adams / Functional :
         <title>See Also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="IDA">IDA</link>
+                <link linkend="LSodar">LSodar</link>
             </member>
             <member>
-                <link linkend="LSodar">LSodar</link>
+                <link linkend="IDA">IDA</link>
             </member>
             <member>
                 <link linkend="RK">Runge-Kutta 4(5)</link>
     <refnamediv>
         <refname>Runge-Kutta 4(5)</refname>
         <refpurpose>
-            Runge-Kutta is a numerical solver providing an efficient explicit method to solve Ordinary Differential Equations (ODEs) Initial Value Problems. Called by <link linkend="xcos">xcos</link>.
+            <emphasis>Runge-Kutta</emphasis> is a numerical solver providing an efficient explicit method to solve Ordinary Differential Equations (ODEs) Initial Value Problems.
         </refpurpose>
     </refnamediv>
     <refsection>
         <title>Description</title>
         <para>
-            Runge-Kutta is a numerical solver providing an efficient fixed-size step method to solve Initial Value Problems of the form :
+            Called by <link linkend="xcos">xcos</link>, <emphasis>Runge-Kutta</emphasis> is a numerical solver providing an efficient fixed-size step method to solve Initial Value Problems of the form :
         </para>
         <para>
             <latex>
@@ -195,12 +195,12 @@ Time for BDF / Newton :
 Time for BDF / Functional :
  24.893
 
-Time for Adams / Functional :
- 20.049
-
 Time for Adams / Newton :
  20.469
 
+Time for Adams / Functional :
+ 20.049
+
 Time for Runge-Kutta :
  18.254
             ]]></screen>
@@ -216,13 +216,13 @@ Time for Runge-Kutta :
         <title>See Also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="CVode">CVode</link>
+                <link linkend="LSodar">LSodar</link>
             </member>
             <member>
-                <link linkend="IDA">IDA</link>
+                <link linkend="CVode">CVode</link>
             </member>
             <member>
-                <link linkend="LSodar">LSodar</link>
+                <link linkend="IDA">IDA</link>
             </member>
             <member>
                 <link linkend="DoPri">Dormand-Price 4(5)</link>
@@ -32,7 +32,7 @@
             <emphasis>CVode</emphasis> and <emphasis>IDA</emphasis> use variable-size steps for the integration.
         </para>
         <para>
-            A drawback of that is the unpredictable computation time. With DoPri, we do not adapt to the complexity of the problem, but we guarantee a stable computation time.
+            A drawback of that is the unpredictable computation time. With Dormand-Price, we do not adapt to the complexity of the problem, but we guarantee a stable computation time.
         </para>
         <para>
             As of now, this method is explicit, so it is not concerned with Newton or Functional iterations, and not advised for stiff problems.
@@ -48,7 +48,7 @@
             By convention, to use fixed-size steps, the program first computes a fitting <emphasis>h</emphasis> that approaches the simulation parameter <link linkend="Simulatemenu_Menu_entries">max step size</link>.
         </para>
         <para>
-            An important difference of DoPri with the previous methods is that it computes up to the seventh derivative of <emphasis>y</emphasis>, while the others only use linear combinations of <emphasis>y</emphasis> and <emphasis>y'</emphasis>.
+            An important difference of Dormand-Price with the previous methods is that it computes up to the seventh derivative of <emphasis>y</emphasis>, while the others only use linear combinations of <emphasis>y</emphasis> and <emphasis>y'</emphasis>.
         </para>
         <para>
             Here, the next value is determined by the present value 
@@ -95,7 +95,7 @@
             .
         </para>
         <para>
-            That error analysis baptized the method <emphasis>Dopri 4(5)</emphasis> : 
+            That error analysis baptized the method <emphasis>Dormand-Price 4(5)</emphasis> : 
             <emphasis>
                 O(h<superscript>5</superscript>)
             </emphasis>
@@ -137,7 +137,7 @@ try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
 ]]></scilab:image>
         </para>
         <para>
-            The integral block returns its continuous state, we can evaluate it with DoPri by running the example :
+            The integral block returns its continuous state, we can evaluate it with Dormand-Price by running the example :
         </para>
         <para>
             <programlisting language="example"><![CDATA[
@@ -145,9 +145,9 @@ try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
       loadScicos();
       loadXcosLibs();
       importXcosDiagram("SCI/modules/xcos/examples/solvers/ODE_Example.xcos");
-      scs_m.props.tf = 10000;
+      scs_m.props.tf = 5000;
 
-      // Select the DoPri solver and set the precision
+      // Select the Dormand-Price solver and set the precision
       scs_m.props.tol(6) = 5;
       scs_m.props.tol(7) = 10^-2;
 
@@ -155,18 +155,18 @@ try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
       tic();
       try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
       t = toc();
-      disp(t, "Time for DoPri :");
+      disp(t, "Time for Dormand-Price :");
       ]]></programlisting>
         </para>
         <para>
             The Scilab console displays :
             <screen><![CDATA[
-Time for DoPri :
- 31.501
+Time for Dormand-Price :
+ 17.126
             ]]></screen>
         </para>
         <para>
-            Now, in the following script, we compare the time difference between DoPri and Sundials by running the example with the five solvers in turn :
+            Now, in the following script, we compare the time difference between Dormand-Price and Sundials by running the example with the five solvers in turn :
             <link type="scilab" linkend ="scilab.scinotes/xcos/examples/solvers/integDoPri.sce">
                 Open the script
             </link>
@@ -174,23 +174,23 @@ Time for DoPri :
         <para>
             <screen><![CDATA[
 Time for BDF / Newton :
- 37.882
+ 12.852
 
 Time for BDF / Functional :
- 32.815
+ 12.343
 
 Time for Adams / Newton :
- 30.108
+ 8.75
 
 Time for Adams / Functional :
- 29.242
+ 7.789
 
 Time for DoPri :
- 31.501
+ 7.606
             ]]></screen>
         </para>
         <para>
-            These results show that on a nonstiff problem, for relatively same precision required and forcing the same step size, DoPri's computational overhead is significant. Its error to the solution is althought much smaller than the regular Runge-Kutta 4(5), for a small overhead in time.
+            These results show that on a nonstiff problem, for relatively same precision required and forcing the same step size, Dormand-Price's computational overhead (compared to Runge-Kutta) is significant and is close to <emphasis>Adams/Functional</emphasis>. Its error to the solution is althought much smaller than the regular Runge-Kutta 4(5), for a small overhead in time.
         </para>
         <para>
             Variable step-size ODE solvers are not appropriate for deterministic real-time applications because the computational overhead of taking a time step varies over the course of an application.
     <refnamediv>
         <refname>IDA</refname>
         <refpurpose>
-            <emphasis>IDA</emphasis> (Implicit Differential Algebraic) is a numerical solver providing an efficient and stable method to solve Differential Algebraic Equations (DAEs) Initial Value Problems. Called by <link linkend="xcos">xcos</link>.
+            <emphasis>IDA</emphasis> (short for Implicit Differential Algebraic solver) is a numerical solver providing an efficient and stable method to solve Differential Algebraic Equations (DAEs) Initial Value Problems.
         </refpurpose>
     </refnamediv>
     <refsection>
         <title>Description</title>
         <para>
-            <emphasis>IDA</emphasis> is a numerical solver providing an efficient and stable method to solve Initial Value Problems of the form :
+            Called by <link linkend="xcos">xcos</link>, <emphasis>IDA</emphasis> (short for Implicit Differential Algebraic solver) is a numerical solver providing an efficient and stable method to solve Initial Value Problems of the form :
         </para>
         <para>
             <latex>
@@ -161,10 +161,10 @@ try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
         <title>See Also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="CVode">CVode</link>
+                <link linkend="LSodar">LSodar</link>
             </member>
             <member>
-                <link linkend="LSodar">LSodar</link>
+                <link linkend="CVode">CVode</link>
             </member>
             <member>
                 <link linkend="RK">Runge-Kutta 4(5)</link>