792d0072d5eed06e1831bc58ba76887d4ae3e90f
[scilab.git] / scilab / modules / xcos / help / en_US / solvers / 6-IDA.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.1-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="IDA">
13     <refnamediv>
14         <refname>IDA</refname>
15         <refpurpose>
16             <emphasis>IDA</emphasis> (short for Implicit Differential Algebraic equations system solver) is a numerical solver providing an efficient and stable method to solve Differential Algebraic Equations system (DAEs) Initial Value Problems.
17         </refpurpose>
18     </refnamediv>
19     <refsection>
20         <title>Description</title>
21         <para>
22             Called by <link linkend="xcos">xcos</link>, <emphasis>IDA</emphasis> (short for Implicit Differential Algebraic equations system solver) is a numerical solver providing an efficient and stable method to solve Initial Value Problems of the form:
23         </para>
24         <para>
25             <latex>
26                 \begin{eqnarray}
27                 F(t,y,\dot{y}) = 0, \hspace{2 mm} y(t_0)=y_0, \hspace{2 mm} \dot{y}(t_0)=\dot{y}_0, \hspace{3 mm} y, \hspace{1.5 mm} \dot{y}  \hspace{1.5 mm} and \hspace{1.5 mm} F \in R^N \hspace{10 mm} (1)
28                 \end{eqnarray}
29             </latex>
30         </para>
31         <para>
32         </para>
33         Before solving the problem, <emphasis>IDA</emphasis> runs an internal routine to find consistent values for
34         <emphasis>
35             y<subscript>0</subscript>
36         </emphasis>
37         and
38         <emphasis>
39             yPrime<subscript>0</subscript>
40         </emphasis>
41         .
42         <para>
43             Starting then with those
44             <emphasis>
45                 y<subscript>0</subscript>
46             </emphasis>
47             and
48             <emphasis>
49                 yPrime<subscript>0</subscript>
50             </emphasis>
51             , <emphasis>IDA</emphasis> approximates
52             <emphasis>
53                 y<subscript>n+1</subscript>
54             </emphasis>
55             with the <emphasis>BDF</emphasis> formula:
56         </para>
57         <para>
58             <latex>
59                 \begin{eqnarray}
60                 \sum_{i=0}^{q} \alpha_{n,i} y_{n-i} = h_n\dot{y}_{n}
61                 \end{eqnarray}
62             </latex>
63             <para>
64                 &#160; with, like in <link linkend="CVode">CVode</link>,
65                 <emphasis>
66                     y<subscript>n</subscript>
67                 </emphasis>
68                 the approximation of
69                 <emphasis>
70                     y(t<subscript>n</subscript>)
71                 </emphasis>
72                 ,
73                 <emphasis>
74                     h<subscript>n</subscript>
75                 </emphasis>
76                 =
77                 <emphasis>
78                     t<subscript>n</subscript> - t<subscript>n-1</subscript>
79                 </emphasis>
80                 the step size, and the coefficients are fixed, uniquely determined by the method type, its order <emphasis>q</emphasis> ranging from 1 to 5 and the history of the step sizes.
81             </para>
82         </para>
83         <para>
84             Injecting this formula in <emphasis>(1)</emphasis> yields the system:
85         </para>
86         <para>
87             <latex>
88                 G(y_n) \equiv F \left( t_n, \hspace{1.5mm} y_n, \hspace{1.5mm} h_n^{-1}\sum_{i=0}^{q} \alpha_{n,i} y_{n-i} \right) = 0
89             </latex>
90         </para>
91         <para>
92             To apply <emphasis>Newton</emphasis> iterations to it, we rewrite it into:
93         </para>
94         <para>
95             <latex>
96                 J \left[y_{n(m+1)}-y_{n(m)} \right] = -G(y_{n(m)})
97             </latex>
98         </para>
99         <para>
100             &#160; with <emphasis>J</emphasis> an approximation of the Jacobian:
101         </para>
102         <para>
103             &#160; <latex>
104                 J = \frac{\partial{G}}{\partial{y}} = \frac{\partial{F}}{\partial{y}}+\alpha\frac{\partial{F}}{\partial{\dot{y}}}, \hspace{4 mm} \alpha = \frac{\alpha_{n,0}}{h_n},
105             </latex>
106         </para>
107         <para>
108             &#160; <emphasis>&#x3B1;</emphasis> changes whenever the step size or the method order varies.
109         </para>
110         <para>
111             An implemented direct dense solver is used and we go on to the next step.
112         </para>
113         <para>
114             <emphasis>IDA</emphasis> uses the history array to control the local error
115             <emphasis>
116                 y<subscript>n(m)</subscript> - y<subscript>n(0)</subscript>
117             </emphasis>
118             and recomputes
119             <emphasis>
120                 h<subscript>n</subscript>
121             </emphasis>
122             if that error is not satisfying.
123         </para>
124         <para>
125             The function is called in between activations, because a discrete activation may change the system.
126         </para>
127         <para>
128             Following the criticality of the event (its effect on the continuous problem), we either relaunch the solver with different start and final times as if nothing happened, or, if the system has been modified, we need to "cold-restart" the problem by reinitializing it anew and relaunching the solver.
129         </para>
130         <para>
131             Averagely, <emphasis>IDA</emphasis> accepts tolerances up to 10<superscript>-11</superscript>. Beyond that, it returns a <emphasis>Too much accuracy</emphasis> requested error.
132         </para>
133     </refsection>
134     <refsection id="Example_IDA">
135         <title>Example</title>
136         <para>
137             The 'Modelica Generic' block returns its continuous states, we can evaluate them with <emphasis>IDA</emphasis> by running the example:
138         </para>
139         <para>
140             <link type="scilab" linkend="scilab.xcos/xcos/examples/solvers/DAE_Example.zcos">
141                 <inlinemediaobject>
142                     <imageobject>
143                         <imagedata align="center" fileref="../../../examples/solvers/DAE_Example.zcos" valign="middle"/>
144                     </imageobject>
145                 </inlinemediaobject>
146             </link>
147             <scilab:image localized="true"><![CDATA[
148 loadScicos();
149 loadXcosLibs();
150 importXcosDiagram(SCI + "/modules/xcos/examples/solvers/DAE_Example.zcos");
151 // Redefining messagebox() to avoid popup
152 function messagebox(msg, Title)
153  disp(Title);
154  disp(msg);
155 endfunction
156 try xcos_simulate(scs_m, 4); catch disp(lasterror()); end
157 ]]></scilab:image>
158         </para>
159     </refsection>
160     <refsection>
161         <title>See Also</title>
162         <simplelist type="inline">
163             <member>
164                 <link linkend="LSodar">LSodar</link>
165             </member>
166             <member>
167                 <link linkend="CVode">CVode</link>
168             </member>
169             <member>
170                 <link linkend="RK">Runge-Kutta 4(5)</link>
171             </member>
172             <member>
173                 <link linkend="DoPri">Dormand-Prince 4(5)</link>
174             </member>
175             <member>
176                 <link linkend="ImpRK">Implicit Runge-Kutta 4(5)</link>
177             </member>
178             <member>
179                 <link linkend="DDaskr">DDaskr</link>
180             </member>
181             <member>
182                 <link linkend="Comparisons">Comparisons</link>
183             </member>
184             <member>
185                 <link linkend="ode">ode</link>
186             </member>
187             <member>
188                 <link linkend="ode_discrete">ode_discrete</link>
189             </member>
190             <member>
191                 <link linkend="ode_root">ode_root</link>
192             </member>
193             <member>
194                 <link linkend="odedc">odedc</link>
195             </member>
196             <member>
197                 <link linkend="impl">impl</link>
198             </member>
199         </simplelist>
200     </refsection>
201     <refsection>
202         <title>Bibliography</title>
203         <para>
204             <ulink url="https://computation.llnl.gov/casc/sundials/documentation/documentation.html">Sundials Documentation</ulink>
205         </para>
206     </refsection>
207 </refentry>