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+'/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>