460c82c75615fa1ef8a2fa80695d37e13c3d5c96
[scilab.git] / scilab / modules / differential_equations / help / en_US / daskr.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) 2013 - Scilab Enterprises - Paul Bignier
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="daskr" xml:lang="en">
17     <refnamediv>
18         <refname>daskr</refname>
19         <refpurpose>DAE solver with zero crossing</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>[r, nn [, hd]] = daskr(x0, t0, t [, atol [, rtol]], res [, jac], ng, surf [, info [, psol] [, pjac]] [, hd])</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>x0</term>
30                 <listitem>
31                     <para>
32                         is either <literal>y0</literal> (<literal>ydot0</literal> is
33                         estimated by <literal>daskr</literal> with zero as first estimate)
34                         or the matrix <literal>[y0 ydot0]</literal>.
35                         <literal>g(t, y0, ydot0)</literal> must be equal to zero.
36                         If you only know an estimate of <literal>ydot0</literal>, set
37                         <literal>info(7)=1</literal>.
38                     </para>
39                     <variablelist>
40                         <varlistentry>
41                             <term>y0</term>
42                             <listitem>
43                                 <para>a real column vector of initial conditions.</para>
44                             </listitem>
45                         </varlistentry>
46                         <varlistentry>
47                             <term>ydot0</term>
48                             <listitem>
49                                 <para>a real column vector of the time derivative of
50                                     <literal>y</literal> at <literal>t0</literal> (may be an estimate).
51                                 </para>
52                             </listitem>
53                         </varlistentry>
54                     </variablelist>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>t0</term>
59                 <listitem>
60                     <para>a real number, it is the initial instant.</para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>t</term>
65                 <listitem>
66                     <para>a real scalar or vector. Gives instants for which you want the
67                         solution. Note that you can get solution at each daskr's step point
68                         by setting <literal>info(2)=1</literal>.
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>atol, rtol</term>
74                 <listitem>
75                     <para>real scalars or column vectors of same size as
76                         <literal>y</literal> or both of size 1. <literal>atol</literal> and <literal>rtol</literal> give respectively
77                         absolute and relative error tolerances of solution. If vectors, the
78                         tolerances are specified for each component of
79                         <literal>y</literal>.
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>res</term>
85                 <listitem>
86                     <para>
87                         <link linkend="external">external</link> (function, list or string). Computes the value of
88                         <literal>g(t, y, ydot)</literal>. It may be :
89                     </para>
90                     <itemizedlist>
91                         <listitem>
92                             <para>A Scilab function.</para>
93                             <para>Its syntax must be
94                                 <literal>[r, ires] = res(t, y, ydot)</literal> and must return the residual
95                                 <literal>r = g(t, y, ydot)</literal> and error flag
96                                 <literal>ires</literal>. <literal>ires = 0</literal> if
97                                 <literal>res</literal> succeeds to compute <literal>r</literal>,
98                                 <literal>ires = -1</literal> if residual is locally not defined for
99                                 <literal>(t, y, ydot)</literal>, <literal>ires = -2</literal> if
100                                 parameters are out of admissible range.
101                             </para>
102                         </listitem>
103                         <listitem>
104                             <para>A list.</para>
105                             <para>This form allows to pass parameters other than t, y, ydot to the function.
106                                 It must be as follows:
107                             </para>
108                             <programlisting role="no-scilab-exec"><![CDATA[
109 list(res, x1, x2, ...)
110  ]]></programlisting>
111                             <para>where the syntax of the function
112                                 <literal>res</literal> is now
113                             </para>
114                             <programlisting role="no-scilab-exec"><![CDATA[
115 r = res(t, y, ydot, x1, x2, ...)
116  ]]></programlisting>
117                             <para>
118                                 <literal>res</literal> still returns
119                                 <literal>r = g(t, y, ydot)</literal> as a function of
120                                 <literal>(t, y, ydot, x1, x2, ...)</literal>.
121                             </para>
122                             <para>Warning: this form must not be used if there is no extra
123                                 argument to pass to the function.
124                             </para>
125                         </listitem>
126                         <listitem>
127                             <para>A string.</para>
128                             <para>It must refer to the name of a C function or a Fortran subroutine
129                                 linked with Scilab.
130                             </para>
131                             <para>In C, the syntax must be:</para>
132                             <programlisting role="no-scilab-exec"><![CDATA[
133 void res(double *t, double y[], double yd[], double r[],
134          int *ires, double rpar[], int ipar[])
135  ]]></programlisting>
136                             <para>In Fortran, it must be:</para>
137                             <programlisting role="no-scilab-exec"><![CDATA[
138 subroutine res(t, y, yd, r, ires, rpar, ipar)
139 double precision t, y(*), yd(*),r(*),rpar(*)
140 integer ires, ipar(*)
141  ]]></programlisting>
142                             <para>
143                                 The <literal>rpar</literal> and <literal>ipar</literal>
144                                 arrays must be present but cannot be used.
145                             </para>
146                         </listitem>
147                     </itemizedlist>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term>jac</term>
152                 <listitem>
153                     <para>
154                         <link linkend="external">external</link> (function, list or string).
155                         Computes the value of <literal>dg/dy + cj*dg/dydot</literal> for a given value of parameter
156                         <literal>cj</literal>.
157                     </para>
158                     <itemizedlist>
159                         <listitem>
160                             <para>A Scilab function.</para>
161                             <para>Its syntax must be
162                                 <literal>r = jac(t, y, ydot, cj)</literal> and must return
163                                 <literal>r = dg(t, y, ydot)/dy + cj*dg(t, y, ydot)/dydot</literal> where
164                                 <literal>cj</literal> is a real scalar.
165                             </para>
166                         </listitem>
167                         <listitem>
168                             <para>A list.</para>
169                             <para>It must be as follows</para>
170                             <programlisting role="no-scilab-exec"><![CDATA[
171 list(jac, x1, x2, ...)
172  ]]></programlisting>
173                             <para>where the syntax of the function
174                                 <literal>jac</literal> is now
175                             </para>
176                             <programlisting role="no-scilab-exec"><![CDATA[
177 r=jac(t, y, ydot, cj, x1, x2,...)
178  ]]></programlisting>
179                             <para>
180                                 <literal>jac</literal> still returns
181                                 <literal>dg/dy + cj*dg/dydot</literal> as a function of
182                                 <literal>(t, y, ydot, cj, x1, x2, ...)</literal>.
183                             </para>
184                         </listitem>
185                         <listitem>
186                             <para>A character string.</para>
187                             <para>It must refer to the name of a C function or a Fortran subroutine linked with Scilab
188                             </para>
189                             <para>In C, the syntax must be:</para>
190                             <programlisting role="no-scilab-exec"><![CDATA[
191 void jac(double *t, double y[], double yd[], double pd[],
192          double *cj, double rpar[], int ipar[])
193  ]]></programlisting>
194                             <para>In Fortran, it must be:</para>
195                             <programlisting role="no-scilab-exec"><![CDATA[
196 subroutine jac(t, y, yd, pd, cj, rpar, ipar)
197 double precision t, y(*), yd(*), pd(*), cj, rpar(*)
198 integer ipar(*)
199  ]]></programlisting>
200                         </listitem>
201                     </itemizedlist>
202                 </listitem>
203             </varlistentry>
204             <varlistentry>
205                 <term>surf</term>
206                 <listitem>
207                     <para>
208                         <link linkend="external">external</link> (function, list or string).
209                         Computes the value of the column vector <literal>surf(t, y)</literal> with
210                         <literal>ng</literal> components. Each component defines a surface.
211                         It may be defined by:
212                     </para>
213                     <itemizedlist>
214                         <listitem>
215                             <para>A Scilab function.</para>
216                             <para>Its syntax must be
217                                 <literal>surf(t, y)</literal>
218                             </para>
219                         </listitem>
220                         <listitem>
221                             <para>A list.</para>
222                             <para>It must be as follows</para>
223                             <programlisting role="no-scilab-exec"><![CDATA[
224 list(surf, x1, x2, ...)
225  ]]></programlisting>
226                             <para>where the syntax of the function
227                                 <literal>surf</literal> is now
228                             </para>
229                             <programlisting role="no-scilab-exec"><![CDATA[
230 r = surf(t, y, x1, x2, ...)
231  ]]></programlisting>
232                         </listitem>
233                         <listitem>
234                             <para>A character string.</para>
235                             <para>It must refer to the name of a C function or a Fortran subroutine linked with Scilab.
236                             </para>
237                             <para>In C, the syntax must be:</para>
238                             <programlisting role="no-scilab-exec"><![CDATA[
239 void surf(int *ny, double *t, double y[], int *ng, double gout[])
240  ]]></programlisting>
241                             <para>In Fortran, it must be:</para>
242                             <programlisting role="no-scilab-exec"><![CDATA[
243 subroutine surf(ny, t, y, ng, gout)
244 double precision t, y(*), gout(*)
245 integer ny, ng
246  ]]></programlisting>
247                         </listitem>
248                     </itemizedlist>
249                 </listitem>
250             </varlistentry>
251             <varlistentry>
252                 <term>info</term>
253                 <listitem>
254                     <para>
255                         list which contains <literal>14</literal> elements. Default value is
256                         <literal>list([], 0, [], [], [], 0, [], 0, [], 0, 0, [], [], 1)</literal>.
257                     </para>
258                     <variablelist>
259                         <varlistentry>
260                             <term>info(1)</term>
261                             <listitem>
262                                 <para>real scalar which gives the maximum time for which
263                                     <literal>g</literal> is allowed to be evaluated or an empty matrix
264                                     <literal>[]</literal> if no limits imposed for time.
265                                 </para>
266                             </listitem>
267                         </varlistentry>
268                         <varlistentry>
269                             <term>info(2)</term>
270                             <listitem>
271                                 <para>
272                                     flag which indicates if <literal>daskr</literal> returns
273                                     its intermediate computed values (<literal>= 1</literal>)
274                                     or only the user specified time point values
275                                     (<literal>= 0</literal>).
276                                 </para>
277                             </listitem>
278                         </varlistentry>
279                         <varlistentry>
280                             <term>info(3)</term>
281                             <listitem>
282                                 <para>
283                                     <literal>2</literal> components vector which give the
284                                     definition <literal>[ml,mu]</literal> of band matrix computed
285                                     by <literal>jac</literal>; <literal>r(i - j + ml + mu + 1,j) = "dg(i)/dy(j)+cj*dg(i)/dydot(j)"</literal>.
286                                     If <literal>jac</literal> returns a full matrix set
287                                     <literal>info(3)=[]</literal>.
288                                     Treat as dummy if
289                                     <literal>info(8)=1</literal>.
290                                 </para>
291                             </listitem>
292                         </varlistentry>
293                         <varlistentry>
294                             <term>info(4)</term>
295                             <listitem>
296                                 <para>real scalar which gives the maximum step size. Set
297                                     <literal>info(4)=[]</literal> if no limitation.
298                                 </para>
299                             </listitem>
300                         </varlistentry>
301                         <varlistentry>
302                             <term>info(5)</term>
303                             <listitem>
304                                 <para>real scalar which gives the initial step size. Set
305                                     <literal>info(5)=[]</literal> if not specified.
306                                 </para>
307                             </listitem>
308                         </varlistentry>
309                         <varlistentry>
310                             <term>info(6)</term>
311                             <listitem>
312                                 <para>
313                                     set <literal>info(6)=1</literal> if the solution is
314                                     known to be non negative, else set
315                                     <literal>info(6)=0</literal>.
316                                 </para>
317                             </listitem>
318                         </varlistentry>
319                         <varlistentry>
320                             <term>info(7)</term>
321                             <listitem>
322                                 <para>
323                                     if ydot0 is set so that
324                                     <literal>g(t0, y0, ydot0) = 0</literal> then set
325                                     <literal>info(7)=[]</literal>. Otherwise, set
326                                     <literal>info(7)=[+-1, ..., +-1]</literal>, with
327                                     <literal>info(7)(i) = 1</literal> if y(i) is a differential variable and
328                                     <literal>info(7)(i) = -1</literal> if y(i) is an algebraic variable
329                                     (if its derivatives do not appear explicitly in the function g(t, y, ydot)).
330                                 </para>
331                             </listitem>
332                         </varlistentry>
333                         <varlistentry>
334                             <term>info(8)</term>
335                             <listitem>
336                                 <para>
337                                     direct / Krylov method. Set <literal>info(8)=1</literal> and provide a routine in <literal>psol</literal>
338                                     if you want the solver to use Krylov iterations, else (daskr's direct method) set
339                                     <literal>info(8)=0</literal>.
340                                 </para>
341                             </listitem>
342                         </varlistentry>
343                         <varlistentry>
344                             <term>info(9)</term>
345                             <listitem>
346                                 <para>
347                                     Krylov parameters. Treat as dummy argument if you have set
348                                     <literal>info(8)=0</literal>. Otherwise, set
349                                     <literal>info(9)=[]</literal> or
350                                     <literal>info(9)=[maxl kmp nrmax epli]</literal>, where:
351                                 </para>
352                                 <para>
353                                     - maxl = maximum number of iterations in the GMRes algorithm (default
354                                     <literal>min(5, neq)</literal>),
355                                 </para>
356                                 <para>
357                                     - kmp = number of vectors on which orthogonalization is done in the GMRes algorithm
358                                     (default maxl),
359                                 </para>
360                                 <para>
361                                     - nrmax = maximum number of restarts of the GMRes algorithm per nonlinear iteration
362                                     (default <literal>5</literal>),
363                                 </para>
364                                 <para>
365                                     - epli = convergence test constant in GMRes algorithm (default <literal>0.05</literal>).
366                                 </para>
367                             </listitem>
368                         </varlistentry>
369                         <varlistentry>
370                             <term>info(10)</term>
371                             <listitem>
372                                 <para>
373                                     initial conditions. Treat as dummy argument if
374                                     <literal>info(7)=[]</literal>. Set
375                                     <literal>info(10)=1</literal> if the solver should stop right after
376                                     computation of the initial conditions, else set
377                                     <literal>info(10)=0</literal>.
378                                 </para>
379                             </listitem>
380                         </varlistentry>
381                         <varlistentry>
382                             <term>info(11)</term>
383                             <listitem>
384                                 <para>
385                                     preconditioner computation and LU-factorization routine for <literal>psol</literal>.
386                                     Treat as dummy argument if <literal>info(8)=0</literal>. Set
387                                     <literal>info(11)=1</literal> and provide a <literal>pjac</literal> routine if the
388                                     <link linkend="external">external</link> <literal>psol</literal> should use a specific routine, else set
389                                     <literal>info(11)=0</literal>.
390                                 </para>
391                             </listitem>
392                         </varlistentry>
393                         <varlistentry>
394                             <term>info(12)</term>
395                             <listitem>
396                                 <para>
397                                     if you wish to control errors locally on all the variables then set
398                                     <literal>info(12)=[]</literal>. Otherwise, set
399                                     <literal>info(12)=[+-1, ..., +-1]</literal>, with
400                                     <literal>info(12)(i) = 1</literal> if y(i) is a differential variable and
401                                     <literal>info(12)(i) = -1</literal> if y(i) is an algebraic variable
402                                     (if its derivatives do not appear explicitly in the function g(t, y, ydot)).
403                                 </para>
404                             </listitem>
405                         </varlistentry>
406                         <varlistentry>
407                             <term>info(13)</term>
408                             <listitem>
409                                 <para>
410                                     heuristic parameters. Treat as dummy argument if
411                                     <literal>info(7)=[]</literal>. Otherwise, set
412                                     <literal>info(13)=[]</literal> or
413                                     <literal>info(13)=[mxnit mxnj mxnh lsoff stptol epinit]</literal>, where:
414                                 </para>
415                                 <para>
416                                     - mxnit = maximum number of Newton iterations per Jacobian or preconditioner evaluation (default
417                                     <literal>5</literal> if <literal>info(8)=0</literal>, <literal>15</literal> otherwise),
418                                 </para>
419                                 <para>
420                                     - mxnj = maximum number of Jacobian or preconditioner evaluations (default
421                                     <literal>6</literal> if <literal>info(8)=0</literal>, <literal>2</literal> otherwise),
422                                 </para>
423                                 <para>
424                                     - mxnh = maximum number of values of the artificial stepsize
425                                        parameter <literal>h</literal> to be tried if info(7) ≠ []
426                                        (default <literal>5</literal>),
427                                 </para>
428                                 <para>
429                                     - lsoff = flag to turn off the linesearch algorithm (lsoff = 0 means linesearch is on, lsoff = 1 means it is turned off)
430                                     (default <literal>0</literal>),
431                                 </para>
432                                 <para>
433                                     - stptol = minimum scaled step in linesearch algorithm (default <literal>(unit roundoff)^(2/3)</literal>),
434                                 </para>
435                                 <para>
436                                     - epinit = swing factor in the Newton iteration convergence test (default <literal>0.01</literal>).
437                                 </para>
438                             </listitem>
439                         </varlistentry>
440                         <varlistentry>
441                             <term>info(14)</term>
442                             <listitem>
443                                 <para>
444                                     verbosity. Set <literal>info(14)=1</literal> for minimal extra printing,
445                                     <literal>info(14)=2</literal> for full printing, else set
446                                     <literal>info(14)=0</literal>.
447                                 </para>
448                             </listitem>
449                         </varlistentry>
450                     </variablelist>
451                 </listitem>
452             </varlistentry>
453             <varlistentry>
454                 <term>psol</term>
455                 <listitem>
456                     <para>
457                         <link linkend="external">external</link> (function, list or string). Solves a linear system
458                         <literal>P*x = b</literal>, with P being the factored preconditioner that routine <literal>pjac</literal>
459                         computed beforehand and stored in <literal>wp</literal> and <literal>iwp</literal>.
460                     </para>
461                     <itemizedlist>
462                         <listitem>
463                             <para>A Scilab function.</para>
464                             <para>Its syntax must be
465                                 <literal>[r, ier] = psol(wp, iwp, b)</literal> and must return the solution of the system in
466                                 <literal>r</literal> and an error flag <literal>ier</literal>.
467                             </para>
468                         </listitem>
469                         <listitem>
470                             <para>A list.</para>
471                             <para>It must be as follows:</para>
472                             <programlisting role="no-scilab-exec"><![CDATA[
473 list(psol, x1, x2, ...)
474  ]]></programlisting>
475                             <para>
476                                 where the syntax of <literal>psol</literal> is now
477                             </para>
478                             <programlisting role="no-scilab-exec"><![CDATA[
479 psol(wp, iwp, b, x1, x2, ...)
480  ]]></programlisting>
481                             <para>
482                                 <literal>psol</literal> still returns the solution in <literal>r</literal>.
483                             </para>
484                         </listitem>
485                         <listitem>
486                             <para>A character string.</para>
487                             <para>It must refer to the name of a C function or a Fortran subroutine linked with Scilab
488                             </para>
489                             <para>In C, the syntax must be:</para>
490                             <programlisting role="no-scilab-exec"><![CDATA[
491 void psol (int*neq, double*t, double*y, double*ydot, double*savr,
492   double*wk, double*cj, double*wght, double*wp, int*iwp, double*b, double*eplin, int*ier, double*rpar, int*ipar)
493  ]]></programlisting>
494                             where the arrays <literal>wp</literal> and <literal>iwp</literal> contain matrix elements of LU-factored preconditioner
495                             <literal>P</literal>, <literal>wp</literal> being the values and
496                             <literal>iwp</literal> the pivots used in the factorization.
497                             <para>In Fortran, it must be:</para>
498                             <programlisting role="no-scilab-exec"><![CDATA[
499 subroutine psol (neq, t, y, ydot, savr, wk, cj, wght,
500   wp, iwp, b, eplin, ier, rpar, ipar)
501 double precision t,y(*), ydot(*), savr(*), wk(*), cj, wght(*), wp(*),
502   b(*), eplin, rpar(*)
503 integer neq, iwp(*), ier, ipar(*)
504  ]]></programlisting>
505                         </listitem>
506                     </itemizedlist>
507                 </listitem>
508             </varlistentry>
509             <varlistentry>
510                 <term>pjac</term>
511                 <listitem>
512                     <para>
513                         <link linkend="external">external</link> (function, list or string). Computes the value of
514                         <literal>dg/dy + cj*dg/dydot</literal> for a given value of parameter
515                         <literal>cj</literal> and LU-factorizes it in two arrays, real and integer.
516                     </para>
517                     <itemizedlist>
518                         <listitem>
519                             <para>A Scilab function.</para>
520                             <para>Its syntax must be
521                                 <literal>[wp, iwp, ires] = pjac(neq, t, y, ydot, h, cj, rewt, savr)</literal> and in return,
522                                 the arrays <literal>wp</literal> and <literal>iwp</literal> must contain all factored preconditioner information.
523                             </para>
524                         </listitem>
525                         <listitem>
526                             <para>A list.</para>
527                             <para>It must be as follows</para>
528                             <programlisting role="no-scilab-exec"><![CDATA[
529 list(pjac, x1, x2, ...)
530  ]]></programlisting>
531                             <para>
532                                 where the syntax of <literal>pjac</literal> is
533                             </para>
534                             <programlisting role="no-scilab-exec"><![CDATA[
535 pjac(neq, t, y, ydot, h, cj, rewt, savr, x1, x2,...)
536  ]]></programlisting>
537                             <para>
538                                 <literal>pjac</literal> still returns factorized
539                                 <literal>dg/dy + cj*dg/dydot</literal> as a function of
540                                 <literal>(neq, t, y, ydot, h, cj, rewt, savr, x1, x2, ...)</literal>.
541                             </para>
542                         </listitem>
543                         <listitem>
544                             <para>A character string.</para>
545                             <para>It must refer to the name of a C function or a Fortran subroutine linked with Scilab
546                             </para>
547                             <para>In C, the syntax must be:</para>
548                             <programlisting role="no-scilab-exec"><![CDATA[
549 void pjac (double*res, int*ires, int*neq, double*t, double*y, double*ydot, double*rewt, double*savr,
550 double*wk, double*h, double*cj, double*wp, int*iwp, int*ier, double*rpar, int*ipar)
551  ]]></programlisting>
552                             <para>In Fortran, it must be:</para>
553                             <programlisting role="no-scilab-exec"><![CDATA[
554 subroutine pjac (res, ires, neq, t, y, ydot, rewt, savr,
555   wk, h, cj, wp, iwp, ier, rpar, ipar)
556 double precision res(*), t, y(*), ydot(*), rewt(*), savr(*),
557   wk(*), h, cj, wp(*), rpar(*)
558 integer ires, neq, iwp(*), ier, ipar(*)
559  ]]></programlisting>
560                         </listitem>
561                     </itemizedlist>
562                 </listitem>
563             </varlistentry>
564             <varlistentry>
565                 <term>hd</term>
566                 <listitem>
567                     <para>
568                         real vector which allows to store the <literal>daskr</literal>
569                         context and to resume integration.
570                     </para>
571                 </listitem>
572             </varlistentry>
573             <varlistentry>
574                 <term>r</term>
575                 <listitem>
576                     <para>
577                         real matrix. Each column is the vector <literal>[t; x(t); xdot(t)]</literal> where
578                         <literal>t</literal> is the time index for which the solution has been computed,
579                         <literal>x(t)</literal> is the value of the computed solution,
580                         <literal>xdot(t)</literal> is the derivative of the computed solution.
581                     </para>
582                 </listitem>
583             </varlistentry>
584             <varlistentry>
585                 <term>nn</term>
586                 <listitem>
587                     <para>
588                         a vector with two entries <literal>[times num]</literal>,
589                         <literal>times</literal> is the value of the time at which the surface is crossed,
590                         <literal>num</literal> is the number of the crossed surface.
591                     </para>
592                 </listitem>
593             </varlistentry>
594         </variablelist>
595     </refsection>
596     <refsection>
597         <title>Description</title>
598         <para>Solution of the implicit differential equation:</para>
599         <programlisting role="no-scilab-exec"><![CDATA[
600 g(t, y, ydot) = 0
601 y(t0) = y0  and  ydot(t0) = ydot0
602  ]]></programlisting>
603         <para>Returns the surface crossing instants and the number of the surface
604             reached in <literal>nn</literal>.
605         </para>
606         <para>Detailed examples can be found in SCI/modules/differential_equations/tests/unit_tests/daskr.tst</para>
607     </refsection>
608     <refsection>
609         <title>Examples</title>
610         <programlisting role="example"><![CDATA[
611 // dy/dt = ((2*log(y)+8)/t-5)*y,  y(1) = 1,  1 <= t <= 6
612 // g1 = ((2*log(y)+8)/t-5)*y
613 // g2 = log(y) - 2.2491
614 y0 = 1; t = 2:6; t0 = 1; y0d = 3;
615 atol = 1.d-6; rtol = 0; ng = 2;
616
617 deff('[delta, ires] = res1(t, y, ydot)', 'ires = 0; delta = ydot-((2*log(y)+8)/t-5)*y')
618 deff('[rts] = gr1(t, y)', 'rts = [((2*log(y)+8)/t-5)*y; log(y)-2.2491]')
619
620 [yy, nn] = daskr([y0, y0d], t0, t, atol, rtol, res1, ng, gr1);
621 nn
622
623 // Should return nn = [2.4698972 2]
624  ]]></programlisting>
625     </refsection>
626     <refsection role="see also">
627         <title>See also</title>
628         <simplelist type="inline">
629             <member>
630                 <link linkend="ode">ode</link>
631             </member>
632             <member>
633                 <link linkend="dasrt">dasrt</link>
634             </member>
635             <member>
636                 <link linkend="dassl">dassl</link>
637             </member>
638             <member>
639                 <link linkend="impl">impl</link>
640             </member>
641             <member>
642                 <link linkend="call">call</link>
643             </member>
644             <member>
645                 <link linkend="link">link</link>
646             </member>
647             <member>
648                 <link linkend="external">external</link>
649             </member>
650         </simplelist>
651     </refsection>
652     <refsection>
653         <title>History</title>
654         <revhistory>
655             <revision>
656                 <revnumber>5.5.0</revnumber>
657                 <revdescription>daskr solver added</revdescription>
658             </revision>
659         </revhistory>
660     </refsection>
661 </refentry>