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>