<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://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="impl" xml:lang="en">
    <refnamediv>
        <refname>impl</refname>
        <refpurpose>differential algebraic equation</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>y = impl([type,] y0, ydot0, t0, t [,atol [,rtol]], res, adda [,jac])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>y0, ydot0</term>
                <listitem>
                    <para>real vectors or matrices (initial conditions)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>t0</term>
                <listitem>
                    <para>a real scalar (initial time)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>t</term>
                <listitem>
                    <para>a real vector (times at which the solution is computed)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>res, adda</term>
                <listitem>
                    <para>externals (function or character string or list)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>type</term>
                <listitem>
                    <para>
                        string <literal>'adams'</literal> or  <literal>'stiff'</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>atol, rtol</term>
                <listitem>
                    <para>
                        real scalars or real vectors of the same size as  <literal>y</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>jac</term>
                <listitem>
                    <para>external (function or character string or list).</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>Solution of the linear implicit differential equation</para>
        <para>A(t,y) dy/dt=g(t,y), y(t0)=y0</para>
        <para>
            <literal>t0</literal> is the initial instant, <literal>y0</literal>
            is the vector of initial conditions. Vector <literal>ydot0</literal> of the
            time derivative of <literal>y</literal> at <literal>t0</literal> must also
            be given. The input <literal>res</literal> is an <link linkend="external">external</link> i.e. a
            function with specified syntax, or the name a Fortran subroutine or a C
            function (character string) with specified syntax or a
            list.
        </para>
        <para>
            If <literal>res</literal> is a function, its syntax must be as
            follows:
        </para>
        <screen><![CDATA[
r = res(t,y,ydot)
]]></screen>
        <para>
            where <literal>t</literal> is a real scalar (time) and
            <literal>y</literal> and <literal>ydot</literal> are real vector (state
            and derivative of the state). This function must return
            <literal>r=g(t,y)-A(t,y)*ydot</literal>.
        </para>
        <para>
            If <literal>res</literal> is a character string, it refers to the
            name of a Fortran subroutine or a C function. See
            <literal>SCI/modules/differential_equations/sci_gateway/fortran/Ex-impl.f</literal> for an example to do
            that.
        </para>
        <para>
            <literal>res</literal> can also be a list: see the help of <link linkend="ode">ode</link>.
        </para>
        <para>
            The input <literal>adda</literal> is also an external.
        </para>
        <para>
            If <literal>adda</literal> is a function, its syntax must be as
            follows:
        </para>
        <screen><![CDATA[
r = adda(t,y,p)
]]></screen>
        <para>
            and it must return <literal>r=A(t,y)+p</literal> where
            <literal>p</literal> is a matrix to be added to
            <literal>A(t,y)</literal>.
        </para>
        <para>
            If <literal>adda</literal> is a character string, it refers to the
            name of a Fortran subroutine or a C function. See
            <literal>SCI/modules/differential_equations/sci_gateway/fortran/Ex-impl.f</literal> for an example to do
            that.
        </para>
        <para>
            <literal>adda</literal> can also be a list: see the help of <link linkend="ode">ode</link>.
        </para>
        <para>
            The input <literal>jac</literal> is also an external.
        </para>
        <para>
            If <literal>jac</literal> is a function, its syntax must be as
            follows:
        </para>
        <screen><![CDATA[
j = jac(t,y,ydot)
]]></screen>
        <para>and it must return the Jacobian of
            <literal>r=g(t,y)-A(t,y)*ydot</literal> with respect to
            <literal>y</literal>.
        </para>
        <para>
            If <literal>jac</literal> is a character string, it refers to the
            name of a Fortran subroutine or a C function. See
            <literal>SCI/modules/differential_equations/sci_gateway/fortran/Ex-impl.f</literal> for an example to do
            that.
        </para>
        <para>
            <literal>jac</literal> can also be a list: see the help of <link linkend="ode">ode</link>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
y = impl([1;0;0], [-0.04;0.04;0], 0, 0.4, 'resid', 'aplusp');
// Using hot restart
//[x1,w,iw] = impl([1;0;0], [-0.04;0.04;0], 0, 0.2, 'resid', 'aplusp');
// hot start from previous call
//x1 = impl([1;0;0],[-0.04;0.04;0], 0.2, 0.4, 'resid', 'aplusp', w, iw);
//max(abs(x1-x))
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="dae">dae</link>
            </member>
            <member>
                <link linkend="ode">ode</link>
            </member>
            <member>
                <link linkend="external">external</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
