<?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 - Scilab Enterprises - Adeline CARNIS
 * ...
 *
 * 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="ode_root" xml:lang="en">
    <refnamediv>
        <refname>ode_root</refname>
        <refpurpose>ordinary differential equation solver with roots
            finding
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>[y, rd, w, iw] = ode("root", y0, t0, t [,rtol [,atol]], f [,jac], ng, g [,w,iw])</synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>y0</term>
                <listitem>
                    <para>a real vector or matrix (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>f</term>
                <listitem>
                    <para>an external i.e. function or character string or list.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rtol, atol</term>
                <listitem>
                    <para>a real constants or real vectors of the same size as
                        <literal>y</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>jac</term>
                <listitem>
                    <para>an external i.e. function or character string or list.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ng</term>
                <listitem>
                    <para>an integer.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>g</term>
                <listitem>
                    <para>an external i.e. function or character string or list.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>a real vector or matrix. The solution.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rd</term>
                <listitem>
                    <para>a real vector.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>w, iw</term>
                <listitem>
                    <para>vectors of real numbers.
                        See <link linkend="ode_optional_output">ode() optional output</link>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            With this syntax (first argument equal to <literal>"root"</literal>)
            <literal>ode</literal> computes the solution of the differential equation
            <literal>dy/dt=f(t,y)</literal> until the state <literal>y(t)</literal>
            crosses the surface <literal>g(t,y)=0</literal>.
        </para>
        <para>
            <literal>g</literal> should give the equation of the surface. It is
            an external i.e. a function with specified syntax, or the name of a
            Fortran subroutine or a C function (character string) with specified
            syntax or a list.
        </para>
        <para>
            If <literal>g</literal> is a function the syntax should be as
            follows:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
z = g(t,y)
 ]]></programlisting>
        <para>
            where <literal>t</literal> is a real scalar (time) and
            <literal>y</literal> a real vector (state). It returns a vector of size
            <literal>ng</literal> which corresponds to the <literal>ng</literal>
            constraints. If <literal>g</literal> is a character string it refers to
            the name of a Fortran subroutine or a C function, with the following
            calling sequence: <literal>g(n,t,y,ng,gout)</literal> where
            <literal>ng</literal> is the number of constraints and
            <literal>gout</literal> is the value of <literal>g</literal> (output of
            the program). If <literal>g</literal> is a list the same conventions as
            for <literal>f</literal> apply (see <link linkend="ode">ode</link> help).
        </para>
        <para>
            Output <literal>rd</literal> is a <literal>1 x k</literal> vector.
            The first entry contains the stopping time. Other entries indicate which
            components of <literal>g</literal> have changed sign. <literal>k</literal>
            larger than 2 indicates that more than one surface
            (<literal>(k-1)</literal> surfaces) have been simultaneously
            traversed.
        </para>
        <para>Other arguments and other options are the same as for
            <literal>ode</literal>, see the <link linkend="ode">ode</link> help.
        </para>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// Integration of the differential equation
// dy/dt=y , y(0)=1, and finds the minimum time t such that y(t)=2
deff("[ydot]=f(t,y)","ydot=y")
deff("[z]=g(t,y)","z=y-2")
y0=1;ng=1;
[y,rd]=ode("root",y0,0,2,f,ng,g)

deff("[z]=g(t,y)","z=y-[2;2;33]")
[y,rd]=ode("root",1,0,2,f,3,g)
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="ode">ode</link>
            </member>
            <member>
                <link linkend="ode_optional_output">ode_optional_output</link>
            </member>
            <member>
                <link linkend="ode_discrete">ode_discrete</link>
            </member>
            <member>
                <link linkend="dasrt">dasrt</link>
            </member>
            <member>
                <link linkend="daskr">daskr</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
