Revision of English help pages for different functions (nothing serious).
[scilab.git] / scilab / modules / differential_equations / help / en_US / dasrt.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) 2008 - INRIA
5  * ...
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dasrt" xml:lang="en">
15     <refnamediv>
16         <refname>dasrt</refname>
17         <refpurpose>DAE solver with zero crossing</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[r,nn,[,hd]]=dasrt(x0,t0,t [,atol,[rtol]],res [,jac],ng, surf [,info] [,hd])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>x0</term>
28                 <listitem>
29                     <para>
30                         is either <literal>y0</literal> (<literal>ydot0</literal> is
31                         estimated by <literal>dassl</literal> with zero as first estimate)
32                         or the matrix <literal>[y0 ydot0]</literal>.
33                         <literal>g(t,y0,ydot0)</literal> must be equal to zero. If you only
34                         know an estimate of <literal>ydot0</literal> set
35                         <literal>info(7)=1</literal>.
36                     </para>
37                     <variablelist>
38                         <varlistentry>
39                             <term>y0</term>
40                             <listitem>
41                                 <para>a real column vector of initial conditions.</para>
42                             </listitem>
43                         </varlistentry>
44                         <varlistentry>
45                             <term>ydot0</term>
46                             <listitem>
47                                 <para>a real column vector of the time derivative of
48                                     <literal>y</literal> at <literal>t0</literal> (may be an
49                                     estimate).
50                                 </para>
51                             </listitem>
52                         </varlistentry>
53                     </variablelist>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>t0</term>
58                 <listitem>
59                     <para>a real number, it is the initial instant.</para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>t</term>
64                 <listitem>
65                     <para>a real scalar or vector. Gives instants for which you want the
66                         solution. Note that you can get solution at each dassl's step point
67                         by setting <literal>info(2)=1</literal>.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>nn</term>
73                 <listitem>
74                     <para>
75                         a vector with two entries <literal>[times num]</literal>
76                         <literal>times</literal> is the value of the time at which the
77                         surface is crossed, <literal>num</literal> is the number of the
78                         crossed surface.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>atol, rtol</term>
84                 <listitem>
85                     <para>real scalars or column vectors of same size as
86                         <literal>y</literal>. <literal>atol, rtol</literal> give respectively
87                         absolute and relative error tolerances of solution. If vectors the
88                         tolerances are specified for each component of
89                         <literal>y</literal>.
90                     </para>
91                 </listitem>
92             </varlistentry>
93             <varlistentry>
94                 <term>res</term>
95                 <listitem>
96                     <para>
97                         <link linkend="external">external</link> (function or list or string). Computes the value of
98                         <literal>g(t,y,ydot)</literal>. It may be :
99                     </para>
100                     <itemizedlist>
101                         <listitem>
102                             <para>A Scilab function.</para>
103                             <para>Its calling sequence must be
104                                 <literal>[r,ires]=res(t,y,ydot)</literal> and
105                                 <literal>res</literal> must return the residue
106                                 <literal>r=g(t,y,ydot)</literal> and error flag
107                                 <literal>ires</literal>. <literal>ires = 0</literal> if
108                                 <literal>res</literal> succeeds to compute <literal>r</literal>,
109                                 <literal>=-1</literal> if residue is locally not defined for
110                                 <literal>(t,y,ydot)</literal>, <literal>=-2</literal> if
111                                 parameters are out of admissible range.
112                             </para>
113                         </listitem>
114                         <listitem>
115                             <para>A list.</para>
116                             <para>This form allows to pass parameters other than t,y,ydot to
117                                 the function. It must be as follows:
118                             </para>
119                             <programlisting role="no-scilab-exec"><![CDATA[ 
120 list(res,x1,x2,...)
121  ]]></programlisting>
122                             <para>where the calling sequence of the function
123                                 <literal>res</literal> is now
124                             </para>
125                             <programlisting role="no-scilab-exec"><![CDATA[
126 r=res(t,y,ydot,x1,x2,...)
127  ]]></programlisting>
128                             <para>
129                                 <literal>res</literal> still returns
130                                 <literal>r=g(t,y,ydot)</literal> as a function of
131                                 <literal>(t,y,ydot,x1,x2,...)</literal>.
132                             </para>
133                             <para>
134                                 <warning>
135                                     Warning: this form must not be used if there is no extra
136                                     argument to pass to the function.
137                                 </warning>
138                             </para>
139                         </listitem>
140                         <listitem>
141                             <para>A string.</para>
142                             <para>It must refer to the name of a C or Fortran subroutine
143                                 linked with Scilab.
144                             </para>
145                             <para>In C The calling sequence must be:</para>
146                             <programlisting role="no-scilab-exec"><![CDATA[
147 void res(double *t, double y[], double yd[], double r[],
148          int *ires, double rpar[], int ipar[]) 
149  ]]></programlisting>
150                             <para>In Fortran it must be:</para>
151                             <programlisting role="no-scilab-exec"><![CDATA[
152 subroutine res(t,y,yd,r,ires,rpar,ipar)
153 double precision t, y(*),yd(*),r(*),rpar(*)
154 integer ires,ipar(*)
155  ]]></programlisting>
156                             <para>
157                                 The <literal>rpar</literal> and <literal>ipar</literal> arrays must be present but cannot be
158                                 used.
159                             </para>
160                         </listitem>
161                     </itemizedlist>
162                 </listitem>
163             </varlistentry>
164             <varlistentry>
165                 <term>jac</term>
166                 <listitem>
167                     <para>
168                         <link linkend="external">external</link> (function or list or string). Computes the value of
169                         <literal>dg/dy + cj*dg/dydot</literal> for a given value of parameter
170                         <literal>cj</literal>.
171                     </para>
172                     <itemizedlist>
173                         <listitem>
174                             <para>A Scilab function.</para>
175                             <para>Its calling sequence must be
176                                 <literal>r=jac(t,y,ydot,cj)</literal> and the
177                                 <literal>jac</literal> function must return
178                                 <literal>r=dg(t,y,ydot)/dy+cj*dg(t,y,ydot)/dydot</literal> where
179                                 <literal>cj</literal> is a real scalar.
180                             </para>
181                         </listitem>
182                         <listitem>
183                             <para>A list.</para>
184                             <para>It must be as follows</para>
185                             <programlisting role="no-scilab-exec"><![CDATA[
186 list(jac,x1,x2,...)
187  ]]></programlisting>
188                             <para>where the calling sequence of the function
189                                 <literal>jac</literal> is now
190                             </para>
191                             <programlisting role="no-scilab-exec"><![CDATA[
192 r=jac(t,y,ydot,cj,x1,x2,...)
193  ]]></programlisting>
194                             <para>
195                                 <literal>jac</literal> still returns
196                                 <literal>dg/dy + cj*dg/dydot</literal> as a function of
197                                 <literal>(t,y,ydot,cj,x1,x2,...)</literal>.
198                             </para>
199                         </listitem>
200                         <listitem>
201                             <para>A character string.</para>
202                             <para>It must refer to the name of a Fortran subroutine linked
203                                 with scilab
204                             </para>
205                             <para>In C The calling sequence must be:</para>
206                             <programlisting role="no-scilab-exec"><![CDATA[
207 void jac(double *t, double y[], double yd[], double pd[],
208          double *cj, double rpar[], int ipar[])
209  ]]></programlisting>
210                             <para>In Fortran it must be:</para>
211                             <programlisting role="no-scilab-exec"><![CDATA[
212 subroutine jac(t,y,yd,pd,cj,rpar,ipar)
213 double precision t, y(*),yd(*),pd(*),cj,rpar(*)
214 integer ipar(*)
215  ]]></programlisting>
216                         </listitem>
217                     </itemizedlist>
218                 </listitem>
219             </varlistentry>
220             <varlistentry>
221                 <term>surf</term>
222                 <listitem>
223                     <para>
224                         <link linkend="external">external</link> (function or list or string). Computes the value of
225                         the column vector <literal>surf(t,y)</literal> with
226                         <literal>ng</literal> components. Each component defines a surface.
227                         It may be defined by:
228                     </para>
229                     <itemizedlist>
230                         <listitem>
231                             <para>A Scilab function.</para>
232                             <para>Its calling sequence must be
233                                 <literal>surf(t,y)</literal>
234                             </para>
235                         </listitem>
236                         <listitem>
237                             <para>A list.</para>
238                             <para>It must be as follows</para>
239                             <programlisting role="no-scilab-exec"><![CDATA[
240 list(surf,x1,x2,...)
241  ]]></programlisting>
242                             <para>where the calling sequence of the function
243                                 <literal>surf</literal> is now
244                             </para>
245                             <programlisting role="no-scilab-exec"><![CDATA[
246 r=surf(t,y,x1,x2,...)
247  ]]></programlisting>
248                         </listitem>
249                         <listitem>
250                             <para>A character string.</para>
251                             <para>It must refer to the name of a Fortran subroutine linked
252                                 with scilab.
253                             </para>
254                             <para>In C the calling sequence must be:</para>
255                             <programlisting role="no-scilab-exec"><![CDATA[
256 void surf(int *ny, double *t, double y[], int *ng, double gout[])
257  ]]></programlisting>
258                             <para>In Fortran it must be:</para>
259                             <programlisting role="no-scilab-exec"><![CDATA[
260 subroutine surf(ny,t,y,ng,gout)
261 double precision t, y(*),gout(*)
262 integer ny,ng
263  ]]></programlisting>
264                         </listitem>
265                     </itemizedlist>
266                 </listitem>
267             </varlistentry>
268             <varlistentry>
269                 <term>info</term>
270                 <listitem>
271                     <para>
272                         list which contains <literal>7</literal> elements. Default
273                         value is <literal>list([],0,[],[],[],0,0)</literal>.
274                     </para>
275                     <variablelist>
276                         <varlistentry>
277                             <term>info(1)</term>
278                             <listitem>
279                                 <para>real scalar which gives the maximum time for which
280                                     <literal>g</literal> is allowed to be evaluated or an empty
281                                     matrix <literal>[]</literal> if no limits imposed for
282                                     time.
283                                 </para>
284                             </listitem>
285                         </varlistentry>
286                         <varlistentry>
287                             <term>info(2)</term>
288                             <listitem>
289                                 <para>
290                                     flag which indicates if <literal>dassl</literal> returns
291                                     its intermediate computed values (<literal>flag=1</literal>)
292                                     or only the user specified time point values
293                                     (<literal>flag=0</literal>).
294                                 </para>
295                             </listitem>
296                         </varlistentry>
297                         <varlistentry>
298                             <term>info(3)</term>
299                             <listitem>
300                                 <para>
301                                     <literal>2</literal> components vector which give the
302                                     definition <literal>[ml,mu]</literal> of band matrix computed
303                                     by <literal>jac</literal>; <literal>r(i - j + ml + mu + 1,j) =
304                                         "dg(i)/dy(j)+cj*dg(i)/dydot(j)"
305                                     </literal>
306                                     .If <literal>jac</literal> returns a full matrix set
307                                     <literal>info(3)=[]</literal>.
308                                 </para>
309                             </listitem>
310                         </varlistentry>
311                         <varlistentry>
312                             <term>info(4)</term>
313                             <listitem>
314                                 <para>real scalar which gives the maximum step size. Set
315                                     <literal>info(4)=[]</literal> if no limitation.
316                                 </para>
317                             </listitem>
318                         </varlistentry>
319                         <varlistentry>
320                             <term>info(5)</term>
321                             <listitem>
322                                 <para>real scalar which gives the initial step size. Set
323                                     <literal>info(5)=[]</literal> if not specified.
324                                 </para>
325                             </listitem>
326                         </varlistentry>
327                         <varlistentry>
328                             <term>info(6)</term>
329                             <listitem>
330                                 <para>
331                                     set <literal>info(6)=1</literal> if the solution is
332                                     known to be non negative, else set
333                                     <literal>info(6)=0</literal>.
334                                 </para>
335                             </listitem>
336                         </varlistentry>
337                         <varlistentry>
338                             <term>info(7)</term>
339                             <listitem>
340                                 <para>
341                                     set <literal>info(7)=1</literal> if
342                                     <literal>ydot0</literal> is just an estimation,
343                                     <literal>info(7)=0</literal> if
344                                     <literal>g(t0,y0,ydot0)=0</literal>.
345                                 </para>
346                             </listitem>
347                         </varlistentry>
348                     </variablelist>
349                 </listitem>
350             </varlistentry>
351             <varlistentry>
352                 <term>hd</term>
353                 <listitem>
354                     <para>
355                         real vector which allows to store the <literal>dassl</literal>
356                         context and to resume integration.
357                     </para>
358                 </listitem>
359             </varlistentry>
360             <varlistentry>
361                 <term>r</term>
362                 <listitem>
363                     <para>
364                         real matrix . Each column is the vector <literal>[t;x(t);xdot(t)]</literal> where
365                         <literal>t</literal> is time index for which the solution had been computed.
366                     </para>
367                 </listitem>
368             </varlistentry>
369         </variablelist>
370     </refsection>
371     <refsection>
372         <title>Description</title>
373         <para>Solution of the implicit differential equation.</para>
374         <programlisting role="no-scilab-exec"><![CDATA[
375 g(t,y,ydot)=0
376 y(t0)=y0  and   ydot(t0)=ydot0
377  ]]></programlisting>
378         <para>Returns the surface crossing instants and the number of the surface
379             reached in <literal>nn</literal>.
380         </para>
381         <para>Detailed examples can be found in SCIDIR/tests/unit_tests/dassldasrt.tst</para>
382     </refsection>
383     <refsection>
384         <title>Examples</title>
385         <programlisting role="example"><![CDATA[ 
386 //dy/dt = ((2*log(y)+8)/t -5)*y,  y(1) = 1,  1<=t<=6
387 //g1 = ((2*log(y)+8)/t - 5)*y 
388 //g2 = log(y) - 2.2491 
389 y0=1;t=2:6;t0=1;y0d=3;
390 atol=1.d-6;rtol=0;ng=2;
391
392 deff('[delta,ires]=res1(t,y,ydot)','ires=0;delta=ydot-((2*log(y)+8)/t-5)*y')
393 deff('[rts]=gr1(t,y)','rts=[((2*log(y)+8)/t-5)*y;log(y)-2.2491]')
394
395 [yy,nn]=dasrt([y0,y0d],t0,t,atol,rtol,res1,ng,gr1);
396 //(Should return nn=[2.4698972 2])
397  ]]></programlisting>
398     </refsection>
399     <refsection role="see also">
400         <title>See Also</title>
401         <simplelist type="inline">
402             <member>
403                 <link linkend="ode">ode</link>
404             </member>
405             <member>
406                 <link linkend="dassl">dassl</link>
407             </member>
408             <member>
409                 <link linkend="daskr">daskr</link>
410             </member>
411             <member>
412                 <link linkend="impl">impl</link>
413             </member>
414             <member>
415                 <link linkend="fort">fort</link>
416             </member>
417             <member>
418                 <link linkend="link">link</link>
419             </member>
420             <member>
421                 <link linkend="external">external</link>
422             </member>
423         </simplelist>
424     </refsection>
425 </refentry>