Helptools: refactor the HTML code generation
[scilab.git] / scilab / modules / differential_equations / help / pt_BR / dae.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:ns3="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="dae" xml:lang="en">
15     <refnamediv>
16         <refname>dae</refname>
17         <refpurpose>Solucionador de equações diferenciais algébricas</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Seqüência de Chamamento</title>
21         <synopsis> y=dae(initial,t0,t,res) 
22             [y [,hd]]=dae(initial,t0,t [,rtol, [atol]],res [,jac] [,hd])
23             [y,rd]=dae("root",initial,t0,t,res,ng,surface)
24             [y ,rd [,hd]]=dae("root",initial,t0,t [,rtol, [atol]],res [,jac], ng, surface [,hd])
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Parâmetros</title>
29         <variablelist>
30             <varlistentry>
31                 <term>initial</term>
32                 <listitem>
33                     <para>
34                         um vetor coluna. Pode ser igual a <literal>x0 </literal>or
35                         <literal>[x0;xdot0]</literal>, onde <literal>x0</literal> é o valor
36                         de estado no tempo inicial <literal>t0</literal> e
37                         <literal>ydot0</literal> é o valor da derivada do estado inicial ou
38                         uma estimativa dela (ver abaixo).
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>t0</term>
44                 <listitem>
45                     <para>número real, o tempo inicial</para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>t</term>
50                 <listitem>
51                     <para>escalar real ou vetor. Fornece instantes para os quais você
52                         deseja uma solução. Note que você pode obter soluções para cada
53                         ponto de passo de dae fazendo 
54                         <literal>
55                             <link linkend="daeoptions">%DAEOPTIONS</link>(2)=1
56                         </literal>
57                         .
58                     </para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>rtol</term>
63                 <listitem>
64                     <para>escalar real ou vetor coluna com o mesmo tamanho que
65                         <literal>x0</literal>. A tolerância do erro relativo da solução. Se
66                         <literal>rtol</literal> for um vetor, as tolerâncias são
67                         especificadas para cada componente do
68                         estado.<literal/>
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>atol</term>
74                 <listitem>
75                     <para>escalar real ou vetor coluna com o mesmo tamanho que
76                         <literal>x0</literal>. A tolerância do erro absoluto da solução. Se
77                         <literal>atol</literal> for um vetor, as tolerâncias são
78                         especificadas para cada componente do estado.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>res</term>
84                 <listitem>
85                     <para>
86                         uma função externa (<link linkend="external" role="" version="">external</link>). Computa o valor de
87                         <literal>g(t,y,ydot)</literal>. Pode ser
88                     </para>
89                     <variablelist>
90                         <varlistentry>
91                             <term>Uma função do Scilab</term>
92                             <listitem>
93                                 <para>Neste caso, a sua seqüência de chamamento pode ser
94                                     <literal>[r,ires]=res(t,x,xdot)</literal> e
95                                     <literal>res</literal> deve retornar o resíduo
96                                     <literal>r=g(t,x,xdot)</literal> e o indicador de erro
97                                     <literal>ires</literal>. <literal>ires = 0</literal> se
98                                     <literal>res</literal> obtiver sucesso ao computar
99                                     <literal>r</literal>, <literal>=-1</literal> se o resíduo é
100                                     indefinido localmente para <literal>(t,x,xdot)</literal>,
101                                     <literal>=-2</literal> se os parâmetros estão fora do
102                                     intervalo admissível.
103                                 </para>
104                             </listitem>
105                         </varlistentry>
106                         <varlistentry>
107                             <term>Uma lista</term>
108                             <listitem>
109                                 <para>Esta forma é utilizada para passar parâmetros à função.
110                                     Deve ser como segue:
111                                 </para>
112                                 <programlisting role=""><![CDATA[ 
113 list(res,p1,p2,...)
114  ]]></programlisting>
115                                 <para>Onde a seqüência de chamamento da função
116                                     <literal>res</literal> é agora
117                                 </para>
118                                 <programlisting role=""><![CDATA[ 
119 r=res(t,y,ydot,p1,p2,...)
120  ]]></programlisting>
121                                 <para>
122                                     <literal>res</literal> ainda retorna o valor residual
123                                     como uma função de <literal>(t,x,xdot,x1,x2,...)</literal>, e
124                                     p1,p2,... são parâmetros da função.
125                                 </para>
126                             </listitem>
127                         </varlistentry>
128                         <varlistentry>
129                             <term>Um string</term>
130                             <listitem>
131                                 <para>Deve se referir ao nome subrotina C ou Fortran. Supondo
132                                     que &lt;r_name&gt; ié o nome dado.
133                                 </para>
134                                 <itemizedlist>
135                                     <listitem>
136                                         <para>
137                                             <literal>A seqüência de chamamento em Fortran deve
138                                                 ser
139                                             </literal>
140                                         </para>
141                                         <para>
142                                             <literal>&lt;r_name&gt;(t,x,xdot,res,ires,rpar,ipar)</literal>
143                                         </para>
144                                         <para>
145                                             <literal>double precision
146                                                 t,x(*),xdot(*),res(*),rpar(*)
147                                             </literal>
148                                         </para>
149                                         <para>
150                                             <literal>integer ires,ipar(*)</literal>
151                                         </para>
152                                     </listitem>
153                                     <listitem>
154                                         <para>A seqüência de chamamento em C deve ser</para>
155                                         <para>C2F(&lt;r_name&gt;)(double *t, double *x, double
156                                             *xdot, double *res, integer *ires, double *rpar, integer
157                                             *ipar)
158                                         </para>
159                                     </listitem>
160                                 </itemizedlist>
161                                 <para>onde</para>
162                                 <itemizedlist>
163                                     <listitem>
164                                         <para>
165                                             <literal>t</literal> é o valor de tempo
166                                             corrente
167                                         </para>
168                                     </listitem>
169                                     <listitem>
170                                         <para>
171                                             <literal>x</literal> é o array de estados
172                                         </para>
173                                     </listitem>
174                                     <listitem>
175                                         <para>
176                                             <literal>xdot</literal> é o array das derivadas dos
177                                             estados
178                                         </para>
179                                     </listitem>
180                                     <listitem>
181                                         <para>res é o array de resíduos</para>
182                                     </listitem>
183                                     <listitem>
184                                         <para>
185                                             <literal>ires</literal> é o indicador de
186                                             execução
187                                         </para>
188                                     </listitem>
189                                     <listitem>
190                                         <para>
191                                             <literal>rpar</literal> é o array de valores de
192                                             parâmetros em ponto flutuante, necessário, mas não pode
193                                             ser definido pela função <literal>dae</literal> 
194                                         </para>
195                                     </listitem>
196                                     <listitem>
197                                         <para>
198                                             <literal>ipar</literal> é o array de valores de
199                                             parâmetros inteiros, necessário, mas não pode ser definido
200                                             pela função <literal>dae</literal> 
201                                         </para>
202                                     </listitem>
203                                 </itemizedlist>
204                             </listitem>
205                         </varlistentry>
206                     </variablelist>
207                 </listitem>
208             </varlistentry>
209             <varlistentry>
210                 <term>jac</term>
211                 <listitem>
212                     <para>
213                         uma função externa (<link linkend="external" role="" version="">external</link>). Computa o valor de
214                         <literal>dg/dx+cj*dg/dxdot</literal> para um dado valor do parâmetro
215                         <literal>cj. Pode ser</literal>
216                     </para>
217                     <variablelist>
218                         <varlistentry>
219                             <term>Uma função do Scilab</term>
220                             <listitem>
221                                 <para>Sua seqüência de chamamento deve ser
222                                     <literal>r=jac(t,x,xdot,cj)</literal> e a função
223                                     <literal>jac</literal> deve retornar
224                                     <literal>r=dg(t,x,xdot)/dy+cj*dg(t,x,xdot)/dxdot</literal>
225                                     onde <literal>cj</literal> é um escalar real.
226                                 </para>
227                             </listitem>
228                         </varlistentry>
229                         <varlistentry>
230                             <term>Uma lista</term>
231                             <listitem>
232                                 <para>Esta forma é utilizada para passar parâmetros à função.
233                                     Deve ser como segue:
234                                 </para>
235                                 <programlisting role=""><![CDATA[ 
236 list(jac,p1,p2,...)
237  ]]></programlisting>
238                                 <para>Onde a seqüência de chamamento da função
239                                     <literal>jac</literal> é agora
240                                 </para>
241                                 <programlisting role=""><![CDATA[ 
242 r=jac(t,x,xdot,p1,p2,...)
243  ]]></programlisting>
244                                 <para>
245                                     <literal>jac</literal> ainda retorna
246                                     <literal>dg/dx+cj*dg/dxdot</literal> como uma função de
247                                     <literal>(t,x,xdot,cj,p1,p2,...)</literal>.
248                                 </para>
249                             </listitem>
250                         </varlistentry>
251                         <varlistentry>
252                             <term>Um string</term>
253                             <listitem>
254                                 <para>Deve se referir ao nome de uma subrotina C ou Fortran.
255                                     Supondo que &lt;j_name&gt; é o nome dado,
256                                 </para>
257                                 <itemizedlist>
258                                     <listitem>
259                                         <para>
260                                             <literal>A seqüência de chamamento em Fortran deve
261                                                 ser
262                                             </literal>
263                                         </para>
264                                         <para>
265                                             <literal>&lt;j_name&gt;(t, x, xdot, r, cj, ires,
266                                                 rpar, ipar)
267                                             </literal>
268                                         </para>
269                                         <para>
270                                             <literal>double precision t, x(*), xdot(*), r(*),
271                                                 ci, rpar(*)
272                                             </literal>
273                                         </para>
274                                         <para>
275                                             <literal>integer ires, ipar(*)</literal>
276                                         </para>
277                                     </listitem>
278                                     <listitem>
279                                         <para>A seqüência de chamamento dem C deve ser</para>
280                                         <para>C2F(&lt;j_name&gt;)(double *t, double *x, double
281                                             *xdot, double *r, double *cj,
282                                         </para>
283                                         <para>integer *ires, double *rpar, integer *ipar)</para>
284                                     </listitem>
285                                 </itemizedlist>
286                                 <para>
287                                     onde <literal>t</literal>, x, xdot, ires, rpar, ipar são
288                                     definidas semelhantemente como acima, r é o array de
289                                     resultados.
290                                 </para>
291                             </listitem>
292                         </varlistentry>
293                     </variablelist>
294                 </listitem>
295             </varlistentry>
296             <varlistentry>
297                 <term>surface</term>
298                 <listitem>
299                     <para>
300                         uma função externa (<link linkend="external" role="" version="">external</link>). Computa o valor de cada vetor coluna
301                         <literal>surface(t,x)</literal> como componentes
302                         <literal>ng</literal>. Cada componente define uma superfície.
303                     </para>
304                     <variablelist>
305                         <varlistentry>
306                             <term>Uma função do Scilab</term>
307                             <listitem>
308                                 <para>Sua seqüência de chamamento deve ser
309                                     <literal>r=surface(t,x)</literal>, esta função deve retornar
310                                     um vetor com <literal>ng</literal> elementos.
311                                 </para>
312                             </listitem>
313                         </varlistentry>
314                         <varlistentry>
315                             <term>Uma lista</term>
316                             <listitem>
317                                 <para>Esta forma é utilizada para passar parâmetros à função.
318                                     Deve ser como segue:
319                                 </para>
320                                 <programlisting role=""><![CDATA[ 
321 list(surface,p1,p2,...)
322  ]]></programlisting>
323                                 <para>Onde a seqüência de chamamento da função
324                                     <literal>surface</literal> é agora
325                                 </para>
326                                 <programlisting role=""><![CDATA[ 
327 r=surface(t,x,p1,p2,...)
328  ]]></programlisting>
329                             </listitem>
330                         </varlistentry>
331                         <varlistentry>
332                             <term>String</term>
333                             <listitem>
334                                 <para>Deve se referir ao nome de uma rotina C ou Fortran.
335                                     Supondo que &lt;s_name&gt; é o nom dado,
336                                 </para>
337                                 <itemizedlist>
338                                     <listitem>
339                                         <para>
340                                             <literal>A seqüência de chamamento em Fortran deve
341                                                 ser
342                                             </literal>
343                                         </para>
344                                         <para>
345                                             <literal>&lt;r_name&gt;(nx, t, x, ng, r, rpar,
346                                                 ipar)
347                                             </literal>
348                                         </para>
349                                         <para>
350                                             <literal>double precision t, x(*), r(*),
351                                                 rpar(*)
352                                             </literal>
353                                         </para>
354                                         <para>
355                                             <literal>integer nx, ng,ipar(*)</literal>
356                                         </para>
357                                     </listitem>
358                                     <listitem>
359                                         <para>A seqüência de chamamento em C deve ser</para>
360                                         <para>C2F(&lt;r_name&gt;)(double *t, double *x, double
361                                             *xdot, double *r, double *cj,
362                                         </para>
363                                         <para>integer *ires, double *rpar, integer *ipar)</para>
364                                     </listitem>
365                                 </itemizedlist>
366                                 <para>
367                                     onde <literal>t</literal>, x, rpar, ipar são definidas
368                                     semelhantemente como acima, <literal>ng </literal>é o número
369                                     de superfícies, <literal>nx</literal> é a dimensão do estado e
370                                     r é o array de resultados.
371                                 </para>
372                             </listitem>
373                         </varlistentry>
374                     </variablelist>
375                 </listitem>
376             </varlistentry>
377             <varlistentry>
378                 <term>rd</term>
379                 <listitem>
380                     <para>
381                         um vetor com duas entradas <literal>[times num]</literal>
382                         <literal>times</literal> é o valor do tempo no qual a superfície é
383                         cruzada, <literal>num</literal> é o número da superfície
384                         cruzada.
385                     </para>
386                 </listitem>
387             </varlistentry>
388             <varlistentry>
389                 <term>hd</term>
390                 <listitem>
391                     <para>um vetor de reais que permite armazenar o contexto de
392                         <literal>dae</literal>. Pode ser utilizado como argumento de entrada
393                         para retomar a integração (recomeço rápido).
394                     </para>
395                 </listitem>
396             </varlistentry>
397             <varlistentry>
398                 <term>y</term>
399                 <listitem>
400                     <para>
401                         matriz de reais. Se 
402                         <literal>
403                             <link linkend="daeoptions">%DAEOPTIONS</link>(2)=1
404                         </literal>
405                         ,cada coluna
406                         é o vetor <literal>[t;x(t);xdot(t)]</literal> onde
407                         <literal>t</literal> é o índice do tempo para o qual a solução foi
408                         computada. De outro modo, <literal>y</literal> é o vetor
409                         <literal>[x(t);xdot(t)]</literal>.
410                     </para>
411                 </listitem>
412             </varlistentry>
413         </variablelist>
414     </refsection>
415     <refsection>
416         <title>Descrição</title>
417         <para>
418             A função <literal>dae</literal> é uma porta construída sobre as
419             funções <link linkend="dassl">dassl</link> e <link linkend="dasrt">dasrt</link> designada para equações diferenciais
420             implícitas.
421         </para>
422         <programlisting role=""><![CDATA[ 
423 g(t,x,xdot)=0
424 x(t0)=x0  e   xdot(t0)=xdot0
425  ]]></programlisting>
426         <para>
427             Se <literal>xdot0</literal> não for fornecido no argumento<literal>
428                 initial
429             </literal>
430             ,a função dae tenta computá-lo resolvendo
431             g(t,x0,xdot0)=0,
432         </para>
433         <para>
434             Se <literal>xdot0</literal> for fornecido no argumento<literal>
435                 initial
436             </literal>
437             ,pode ser tanto uma derivada compatível satisfazendo
438             g(t,x0,xdot0)=0 ou um valor aproximado . No último caso 
439             <literal>
440                 <link linkend="daeoptions">%DAEOPTIONS</link>(7) deve ser ajustado para
441                 1.
442             </literal>
443         </para>
444         <para>Exemplos detalhados utilizando funções externas codificadas em C e
445             Fortran são dados em
446             <literal>modules/differential_equations/tests/unit_tests/dassldasrt.tst</literal>
447         </para>
448     </refsection>
449     <refsection>
450         <title>Exemplos</title>
451         <programlisting role="example"><![CDATA[ 
452 //Exemplo com um código Scilab
453 function [r,ires]=chemres(t,y,yd)
454   r(1) = -0.04*y(1) + 1d4*y(2)*y(3) - yd(1);
455   r(2) =  0.04*y(1) - 1d4*y(2)*y(3) - 3d7*y(2)*y(2) - yd(2);
456   r(3) =       y(1) +     y(2)      + y(3)-1;
457   ires =  0;
458 endfunction
459 function pd=chemjac(x,y,yd,cj)
460   pd=[-0.04-cj , 1d4*y(3)               , 1d4*y(2);
461        0.04    ,-1d4*y(3)-2*3d7*y(2)-cj ,-1d4*y(2);
462        1       , 1                      , 1       ]
463 endfunction
464
465 x0=[1; 0; 0];
466 xd0=[-0.04; 0.04; 0];
467 t=[1.d-5:0.02:.4, 0.41:.1:4, 40, 400, 4000, 40000, 4d5, 4d6, 4d7, 4d8, 4d9, 4d10];
468
469 y=dae([x0,xd0],0,t,chemres);// retorna os pontos de observação requisitados
470
471 %DAEOPTIONS=list([],1,[],[],[],0,0); // pede que a malha de dae seja retornada
472 y=dae([x0,xd0],0,4d10,chemres); // sem jacobiano
473 y=dae([x0,xd0],0,4d10,chemres,chemjac); // com jacobiano
474
475 //exemplo com um código C (requer-se um compilador C) --------------------------------------------------
476 //-1- criando os códigos C em TMPDIR - equação de Vanderpol, forma implícita
477 code=['#include &lt;math.h&gt;'
478       'void res22(double *t,double *y,double *yd,double *res,int *ires,double *rpar,int *ipar)'
479       '{res[0] = yd[0] - y[1];'
480       ' res[1] = yd[1] - (100.0*(1.0 - y[0]*y[0])*y[1] - y[0]);}'
481       ' '
482       'void jac22(double *t,double *y,double *yd,double *pd,double *cj,double *rpar,int *ipar)'
483       '{pd[0]=*cj - 0.0;'
484       ' pd[1]=    - (-200.0*y[0]*y[1] - 1.0);'
485       ' pd[2]=    - 1.0;'
486       ' pd[3]=*cj - (100.0*(1.0 - y[0]*y[0]));}'
487       ' '
488       'void gr22(int *neq, double *t, double *y, int *ng, double *groot, double *rpar, int *ipar)'
489       '{ groot[0] = y[0];}']
490 mputl(code,TMPDIR+'/t22.c') 
491
492 //-2- compilando e carregando
493 ilib_for_link(['res22' 'jac22' 'gr22'],'t22.c',[],'c',TMPDIR+'/Makefile',TMPDIR+'/t22loader.sce');
494 exec(TMPDIR+'/t22loader.sce')
495
496 //-3- executando
497 rtol=[1.d-6;1.d-6];atol=[1.d-6;1.d-4];
498 t0=0;y0=[2;0];y0d=[0;-2];t=[20:20:200];ng=1;
499
500 //simulação simples
501 t=0:0.003:300;
502 yy=dae([y0,y0d],t0,t,atol,rtol,'res22','jac22');
503 clf();plot(yy(1,:),yy(2,:))
504
505 //achando o primeiro ponto onde yy(1)=0
506 [yy,nn,hotd]=dae("root",[y0,y0d],t0,300,atol,rtol,'res22','jac22',ng,'gr22');
507 plot(yy(1,1),yy(2,1),'r+')
508 xstring(yy(1,1)+0.1,yy(2,1),string(nn(1)))
509
510 //recomeço rápido para o próximo ponto
511 t01=nn(1);[pp,qq]=size(yy);y01=yy(2:3,qq);y0d1=yy(3:4,qq);
512 [yy,nn,hotd]=dae("root",[y01,y0d1],t01,300,atol,rtol,'res22','jac22',ng,'gr22',hotd);
513 plot(yy(1,1),yy(2,1),'r+')
514 xstring(yy(1,1)+0.1,yy(2,1),string(nn(1)))
515  ]]></programlisting>
516     </refsection>
517     <refsection>
518         <title>Ver Também</title>
519         <simplelist type="inline">
520             <member>
521                 <link linkend="ode">ode</link>
522             </member>
523             <member>
524                 <link linkend="daeoptions">daeoptions</link>
525             </member>
526             <member>
527                 <link linkend="dassl">dassl</link>
528             </member>
529             <member>
530                 <link linkend="impl">impl</link>
531             </member>
532             <member>
533                 <link linkend="fort">fort</link>
534             </member>
535             <member>
536                 <link linkend="link">link</link>
537             </member>
538             <member>
539                 <link linkend="external">external</link>
540             </member>
541         </simplelist>
542     </refsection>
543 </refentry>