<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * ...
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dasrt" xml:lang="pt">
    <refnamediv>
        <refname>dasrt</refname>
        <refpurpose>Solucionador de equações diferenciais algébricas com
            cruzamento de zeros
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>[r,nn,[,hd]] = dasrt(x0,t0,t [,atol,[rtol]],res [,jac],ng, surf [,info] [,hd])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>x0</term>
                <listitem>
                    <para>
                        pode ser tanto <literal>y0</literal> (<literal>ydot0</literal>
                        é estimado por <literal>dassl</literal> com a primeira estimativa
                        sendo 0) ou a matriz <literal>[y0 ydot0]</literal>.
                        <literal>g(t,y0,ydot0)</literal> deve ser igual a zero. Se você
                        conhece apenas uma estimativa de <literal>ydot0</literal> faça
                        <literal>info(7)=1</literal>
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>y0</term>
                            <listitem>
                                <para>vetor coluna de reais de condições iniciais</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>ydot0</term>
                            <listitem>
                                <para>vetor coluna de reais da derivada do tempo de
                                    <literal>y</literal> em <literal>t0</literal> (pode ser uma
                                    estimativa).
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>t0</term>
                <listitem>
                    <para>número real, é o instante inicial</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>t</term>
                <listitem>
                    <para>escalar real ou vetor. Fornece instantes para os quais você
                        deseja uma solução. Note que você pode obter soluções para cada
                        ponto de passo de dassl fazendo <literal>info(2)=1</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nn</term>
                <listitem>
                    <para>
                        um vetor com duas entradas <literal>[times num]</literal>
                        <literal>times</literal> é o valor do tempo no qual a superfície é
                        cruzada, <literal>num</literal> é o número da superfície
                        cruzada
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>atol, rtol</term>
                <listitem>
                    <para>escalares reais ou vetores colunas com o mesmo tamanho que
                        <literal>y</literal>. <literal>atol, rtol</literal> fornecem
                        respectivamente as tolerâncias de erros absolutos e relativos da
                        solução. Se forem vetores, as tolerâncias são especificadas para
                        cada elemento de <literal>y</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>res</term>
                <listitem>
                    <para>função, lista ou string externos. Computa o valor de
                        <literal>g(t,y,ydot)</literal>. Pode ser :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>Uma função do Scilab</para>
                            <para>Sua seqüência de chamamento pode ser
                                <literal>[r,ires]=res(t,y,ydot)</literal> e
                                <literal>res</literal> e deve retornar o resíduo
                                <literal>r=g(t,y,ydot)</literal> e o indicador de erro
                                <literal>ires</literal>. <literal>ires = 0</literal> se
                                <literal>res</literal> obtiver sucesso ao computar
                                <literal>r</literal>, <literal>=-1</literal> se o resíduo é
                                indefinido localmente para <literal>(t,y,ydot)</literal>,
                                <literal>=-2</literal> se os parâmetros estão fora do intervalo
                                admissível.
                            </para>
                        </listitem>
                        <listitem>
                            <para>Uma lista</para>
                            <para>Esta forma permite passar outros parâmetros além de
                                t,y,ydot à função. Deve ser como segue:
                            </para>
                            <screen><![CDATA[
list(res,x1,x2,...)
]]></screen>
                            <para>Onde a seqüência de chamamento da função
                                <literal>res</literal> é agora
                            </para>
                            <screen><![CDATA[
r=res(t,y,ydot,x1,x2,...)
]]></screen>
                            <para>
                                <literal>res</literal> ainda retorna
                                <literal>r=g(t,y,ydot)</literal> como função de
                                <literal>(t,y,ydot,x1,x2,...)</literal>.
                            </para>
                            <para>Warning: this form must not be used if there is no extra
                                argument to pass to <literal>the function.</literal>
                            </para>
                        </listitem>
                        <listitem>
                            <para>Um string</para>
                            <para>Deve se referir ao nome subrotina C ou Fortran ligada ao
                                Scilab.
                            </para>
                            <para>Em C a seqüência de chamamento:</para>
                            <screen><![CDATA[
void res(double *t, double y[], double yd[], double r[],
         int *ires, double rpar[], int ipar[])
]]></screen>
                            <para>Em Fortran deve ser:</para>
                            <screen><![CDATA[
subroutine res(t,y,yd,r,ires,rpar,ipar)
double precision t, y(*),yd(*),r(*),rpar(*)
integer ires,ipar(*)
]]></screen>
                            <para>
                                Os arrays <literal>rpar</literal> e <literal>ipar</literal> devem estar presentes, mas não podem
                                ser utilizados.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>jac</term>
                <listitem>
                    <para>função, lista ou string externos. Computa o valor de
                        <literal>dg/dy+cj*dg/dydot</literal> para um dado valor do parâmetro
                        <literal>cj</literal>
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>Uma função do Scilab</para>
                            <para>Sua seqüência de chamamento deve ser
                                <literal>r=jac(t,y,ydot,cj)</literal> e a função
                                <literal>jac</literal> deve retornar
                                <literal>r=dg(t,y,ydot)/dy+cj*dg(t,y,ydot)/dydot</literal> onde
                                <literal>cj</literal> é um escalar real.
                            </para>
                        </listitem>
                        <listitem>
                            <para>Uma lista</para>
                            <para>Deve ser como segue</para>
                            <screen><![CDATA[
list(jac,x1,x2,...)
]]></screen>
                            <para>Onde a seqüência de chamamento da função
                                <literal>jac</literal> é agora
                            </para>
                            <screen><![CDATA[
r = jac(t,y,ydot,cj,x1,x2,...)
]]></screen>
                            <para>
                                <literal>jac</literal> ainda retorna
                                <literal>dg/dy+cj*dg/dydot</literal> como uma função de
                                <literal>(t,y,ydot,cj,x1,x2,...)</literal>.
                            </para>
                        </listitem>
                        <listitem>
                            <para>Um string</para>
                            <para>Deve se referir ao nome de uma subrotina C ou Fortran
                                ligada ao Scilab
                            </para>
                            <para>Em C, a seqüência de chamamento deve ser</para>
                            <screen><![CDATA[
void jac(double *t, double y[], double yd[],
         double pd[], double *cj, double rpar[], int ipar[])
]]></screen>
                            <para>Em Fortran deve ser</para>
                            <screen><![CDATA[
subroutine jac(t,y,yd,pd,cj,rpar,ipar)
double precision t, y(*),yd(*),pd(*),cj,rpar(*)
integer ipar(*)
]]></screen>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>surf</term>
                <listitem>
                    <para>função, lista ou string externo. Computa o valor do vetor
                        coluna <literal>surf(t,y)</literal> com componentes
                        <literal>ng</literal>. Cada componente define uma superfície. Pode
                        ser definido por:
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>Uma função Scilab</para>
                            <para>Sua seqüência de chamamento deve ser
                                <literal>surf(t,y)</literal>
                            </para>
                        </listitem>
                        <listitem>
                            <para>Uma lista</para>
                            <para>Deve ser como segue:</para>
                            <screen><![CDATA[
list(surf,x1,x2,...)
]]></screen>
                            <para>
                                onde a seqüência de chamamento <literal>surf</literal> é
                                agora
                            </para>
                            <screen><![CDATA[
r=surf(t,y,x1,x2,...)
]]></screen>
                        </listitem>
                        <listitem>
                            <para>Um string</para>
                            <para>Deve se referir ao nome de uma subrotina C ou Fortran
                                ligada ao Scilab
                            </para>
                            <para>Em C a seqüência de chamamento deve ser:</para>
                            <screen><![CDATA[
void surf(int *ny, double *t, double y[], int *ng, double gout[])
]]></screen>
                            <para>Em Fortran deve ser</para>
                            <screen><![CDATA[
subroutine surf(ny,t,y,ng,gout)
double precision t, y(*),gout(*)
integer ny,ng
]]></screen>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>info</term>
                <listitem>
                    <para>
                        lista que contém <literal>7</literal> elementos, o valor
                        padrão é list([],0,[],[],[],0,0)
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>info(1)</term>
                            <listitem>
                                <para>escalar real que fornece o tempo máximo para o qual se
                                    permite avaliar <literal>g</literal>, ou uma matriz vazia
                                    <literal>[]</literal> se não houver limites impostos sobre o
                                    tempo.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(2)</term>
                            <listitem>
                                <para>
                                    indica se <literal>dassl</literal> retorna seus valores
                                    intermediários computados (<literal>flag=1</literal>) ou
                                    apenas os valores de pontos tempo especificados pelo usuário
                                    (<literal>flag=0</literal>).
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(3)</term>
                            <listitem>
                                <para>vetor de dois componentes que fornece a definição
                                    <literal>[ml,mu]</literal> de matriz de bandas computada por
                                    <literal>jac</literal>; <literal>r(i - j + ml + mu + 1,j) =
                                        "dg(i)/dy(j)+cj*dg(i)/dydot(j)"
                                    </literal>
                                    .Se
                                    <literal>jac</literal> retorna uma matriz cheia, faça
                                    <literal>info(3)=[]</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(4)</term>
                            <listitem>
                                <para>escalar real que fornece o tamanho de passo máximo. Faça
                                    <literal>info(4)=[]</literal> se não houver limitação.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(5)</term>
                            <listitem>
                                <para>escalar real que fornece o passo inicial. Faça
                                    <literal>info(5)=[]</literal> se não for especificado.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(6)</term>
                            <listitem>
                                <para>
                                    faça <literal>info(6)=1</literal> caso se saiba que a
                                    soulução não é negativa, em outro caso, ajuste.
                                    <literal>info(6)=0</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info(7)</term>
                            <listitem>
                                <para>
                                    faça <literal>info(7)=1</literal> se
                                    <literal>ydot0</literal> é apenas uma estimativa,
                                    <literal>info(7)=0</literal> se
                                    <literal>g(t0,y0,ydot0)=0</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>hd</term>
                <listitem>
                    <para>vetor de reais que permite armazenar o contexto de
                        <literal>dassl</literal> e retomar integração
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r</term>
                <listitem>
                    <para>
                        matriz de reais . Cada coluna é o vetor <literal>[t;x(t);xdot(t)]</literal> onde
                        <literal>t</literal> é o índice do tempo para o qual a solução foi computada
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>Solução da equação diferencial implícita</para>
        <screen><![CDATA[
g(t,y,ydot) = 0
y(t0) = y0  e   ydot(t0) = ydot0
]]></screen>
        <para>Retorna os instantes de cruzamento da superfície e o número da
            superfície alcançada em <literal>nn</literal>.
        </para>
        <para>Exemplos detalhados podem ser encontrados em
            SCIDIR/tests/unit_tests/dassldasrt.tst
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
//dy/dt = ((2*log(y)+8)/t -5)*y,  y(1) = 1,  1&lt;=t&lt;=6
//g1 = ((2*log(y)+8)/t - 5)*y
//g2 = log(y) - 2.2491
y0 = 1; t = 2:6; t0 = 1; y0d = 3;
atol = 1.d-6; rtol = 0; ng = 2;

deff('[delta,ires] = res1(t,y,ydot)', 'ires=0; delta=ydot-((2*log(y)+8)/t-5)*y')
deff('rts = gr1(t,y)', 'rts = [((2*log(y)+8)/t-5)*y;log(y)-2.2491]')

[yy, nn] = dasrt([y0,y0d], t0, t, atol, rtol, res1, ng, gr1);
//(Deveria retornar nn=[2.4698972 2])
     ]]></programlisting>
    </refsection>
    <refsection>
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="ode">ode</link>
            </member>
            <member>
                <link linkend="dassl">dassl</link>
            </member>
            <member>
                <link linkend="impl">impl</link>
            </member>
            <member>
                <link linkend="call">call</link>
            </member>
            <member>
                <link linkend="link">link</link>
            </member>
            <member>
                <link linkend="external">external</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
