Add sparse unitary test about matrix insertion
[scilab.git] / scilab / modules / xcos / help / en_US / solvers / 0-LSodar.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) Scilab Enterprises - 2012 - Paul Bignier
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.
9  * The terms are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  -->
12 <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_US" xml:id="LSodar">
13     <refnamediv>
14         <refname>LSodar</refname>
15         <refpurpose>
16             <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.
17         </refpurpose>
18     </refnamediv>
19     <refsection>
20         <title>Description</title>
21         <para>
22             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 :
23         </para>
24         <para>
25             <latex>
26                 \begin{eqnarray}
27                 \dot{y} = f(t,y), \hspace{3 mm} y(t_0) = y_0, \hspace{3 mm} y \in R^N
28                 \end{eqnarray}
29             </latex>
30         </para>
31         <para>
32             LSodar is similar to <emphasis>CVode</emphasis> in many ways :
33             <itemizedlist>
34                 <listitem>
35                     It uses variable-size steps,
36                 </listitem>
37                 <listitem>
38                     It can potentially use <emphasis>BDF</emphasis> and <emphasis>Adams</emphasis> integration, methods,
39                 </listitem>
40                 <listitem>
41                     <emphasis>BDF</emphasis> and <emphasis>Adams</emphasis> being implicit stable methods, <emphasis>LSodar</emphasis> is suitable for stiff and nonstiff problems,
42                 </listitem>
43                 <listitem>
44                     They both look for roots over the integration interval.
45                 </listitem>
46             </itemizedlist>
47         </para>
48         <para>
49             The main difference though is that <emphasis>LSodar</emphasis> is <emphasis role="bold">fully automated</emphasis>, and chooses between <emphasis>BDF</emphasis> and <emphasis>Adams</emphasis> itself, by checking for stiffness at every step.
50         </para>
51         <para>
52             If the step is considered stiff, then <emphasis>BDF</emphasis> (with max order set to 5) is used and the Modified Newton method <emphasis>'Chord'</emphasis> iteration is selected.
53         </para>
54         <para>
55             Otherwise, the program uses <emphasis>Adams</emphasis> integration (with max order set to 12) and <emphasis>Functional</emphasis> iterations.
56         </para>
57         <para>
58             The stiffness detection is done by step size attempts with both methods.
59         </para>
60         <para>
61             First, if we are in <emphasis>Adams</emphasis> mode and the order is greater than 5, then we assume the problem is nonstiff and proceed with <emphasis>Adams</emphasis>.
62         </para>
63         <para>
64             The first twenty steps use <emphasis>Adams / Functional</emphasis> method.
65             Then <emphasis>LSodar</emphasis> computes the ideal step size of both methods. If the step size advantage is at least <emphasis>ratio = 5</emphasis>, then the current method switches (<emphasis>Adams / Functional</emphasis> to <emphasis>BDF / Chord Newton</emphasis> or vice versa).
66         </para>
67         <para>
68             After every switch, <emphasis>LSodar</emphasis> takes twenty steps, then starts comparing the step sizes at every step.
69         </para>
70         <para>
71             Such strategy induces a minor overhead computational cost if the problem stiffness is known, but is very effective on problems that require differentiate precision. For instance, discontinuities-sensitive problems.
72         </para>
73         <para>
74             Concerning precision, the two integration/iteration methods being close to <emphasis>CVode</emphasis>'s, the results are very similar.
75         </para>
76     </refsection>
77     <refsection>
78         <title>Examples</title>
79         <para>
80             <link type="scilab" linkend="scilab.xcos/xcos/examples/solvers/ODE_Example.xcos">
81                 <inlinemediaobject>
82                     <imageobject>
83                         <imagedata align="center" fileref="../../../examples/solvers/ODE_Example.xcos" valign="middle"/>
84                     </imageobject>
85                 </inlinemediaobject>
86             </link>
87             <scilab:image><![CDATA[
88 loadScicos();
89 loadXcosLibs();
90 importXcosDiagram(SCI + "/modules/xcos/examples/solvers/ODE_Example.xcos");
91 scs_m.props.tol(6) = 0;
92 try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
93 ]]></scilab:image>
94         </para>
95         <para>
96             The integral block returns its continuous state, we can evaluate it with LSodar by running the example :
97         </para>
98         <para>
99             <programlisting language="example"><![CDATA[
100       // Import the diagram and set the ending time
101       loadScicos();
102       loadXcosLibs();
103       importXcosDiagram("SCI/modules/xcos/examples/solvers/ODE_Example.xcos");
104       scs_m.props.tf = 10000;
105
106       // Select the LSodar solver
107       scs_m.props.tol(6) = 0;
108
109       // Start the timer, launch the simulation and display time
110       tic();
111       try xcos_simulate(scs_m, 4); catch disp(lasterror()); end;
112       t = toc();
113       disp(t, "Time for LSodar :");
114       ]]></programlisting>
115         </para>
116         <para>
117             The Scilab console displays :
118             <screen><![CDATA[
119 Time for LSodar :
120  30.584
121             ]]></screen>
122         </para>
123         <para>
124             Now, in the following script, we compare the time difference between the methods by running the example with the five solvers in turn :
125             <link type="scilab" linkend ="scilab.scinotes/xcos/examples/solvers/integLSodar.sce">
126                 Open the script
127             </link>
128         </para>
129         <para>
130             <screen><![CDATA[
131 Time for LSodar :
132  5.001
133
134 Time for BDF / Newton :
135  12.943
136
137 Time for BDF / Functional :
138  12.415
139
140 Time for Adams / Newton :
141  8.651
142
143 Time for Adams / Functional :
144  7.962
145             ]]></screen>
146         </para>
147         <para>
148             These results show that on a nonstiff problem, for the same precision required, LSodar is significantly faster. Other tests prove the proximity of the results. Indeed, we find that the solution difference order between LSodar and CVode is close to the order of the highest tolerance ( 
149             <emphasis>
150                 y<subscript>lsodar</subscript> - y<subscript>cvode</subscript>
151             </emphasis>
152             &#8776; <emphasis>max(reltol, abstol)</emphasis> ).
153         </para>
154         <para>
155             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.
156         </para>
157     </refsection>
158     <refsection>
159         <title>See Also</title>
160         <simplelist type="inline">
161             <member>
162                 <link linkend="CVode">CVode</link>
163             </member>
164             <member>
165                 <link linkend="IDA">IDA</link>
166             </member>
167             <member>
168                 <link linkend="RK">Runge-Kutta 4(5)</link>
169             </member>
170             <member>
171                 <link linkend="DoPri">Dormand-Price 4(5)</link>
172             </member>
173             <member>
174                 <link linkend="ode">ode</link>
175             </member>
176             <member>
177                 <link linkend="ode_discrete">ode_discrete</link>
178             </member>
179             <member>
180                 <link linkend="ode_root">ode_root</link>
181             </member>
182             <member>
183                 <link linkend="odedc">odedc</link>
184             </member>
185             <member>
186                 <link linkend="impl">impl</link>
187             </member>
188         </simplelist>
189     </refsection>
190     <refsection>
191         <title>Bibliography</title>
192         <para>
193             ACM SIGNUM Newsletter, Volume 15, Issue 4, December 1980, Pages 10-11 <ulink url="http://dl.acm.org/citation.cfm?id=1218052.1218054&amp;coll=DL&amp;dl=GUIDE&amp;CFID=213153447&amp;CFTOKEN=26634355">LSode - LSodi</ulink>
194         </para>
195         <para>
196             <ulink url="https://computation.llnl.gov/casc/sundials/documentation/documentation.html">Sundials Documentation</ulink>
197         </para>
198     </refsection>
199     <refsection>
200         <title>History</title>
201         <revhistory>
202             <revision>
203                 <revnumber>5.4.1</revnumber>
204                 <revdescription>LSodar solver added</revdescription>
205             </revision>
206         </revhistory>
207     </refsection>
208 </refentry>