<?xml version="1.0" encoding="UTF-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="external">
    <refnamediv>
        <refname>external</refname>
        <refpurpose>Scilab Object, external function or routine</refpurpose>
    </refnamediv>
    <refsection role="description">
        <title>Description</title>
        <para>
            External function or routine for use with specific commands.
        </para>
        <para>
            An "external" is a function or routine which is used as an argument
            of some high-level primitives (such as <literal>ode</literal>, <literal>optim</literal>, <literal>schur</literal>...).
        </para>
        <para>
            The syntax of the external (function or routine) is imposed by
            the high-level primitive which sets the arguments of the external.
        </para>
        <para>
            For example the external function <literal>costfunc</literal> is an argument of the <literal>optim</literal>
            primitive. Its syntax must be: <literal>[f,g,ind]=costfunc(x,ind)</literal> and
            <literal>optim</literal> (the high-level optimization primitive) is invoked as follows:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
optim(costfunc,...)
 ]]></programlisting>
        <para>
            Here <literal>costfunc</literal> (the cost function to be minimized by the primitive <literal>optim</literal>)
            evaluates <literal>f=f(x)</literal> and <literal>g=</literal> gradient of <literal>f</literal> at <literal>x</literal> (<literal>ind</literal> is an integer. Its use is precised in the <literal>optim</literal> help).
        </para>
        <para>
            If other values are needed by the external function these variables
            can be defined in its environment. Also, they can be put in a list.
            For example, the external function
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
[f,g,ind]=costfunc(x,ind,a,b,c)
 ]]></programlisting>
        <para>
            is valid for <literal>optim</literal> if the external is <literal>list(costfunc,a,b,c)</literal> and
            the call to <literal>optim</literal> is then:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
optim(list(costfunc,a1,b1,c1),....
 ]]></programlisting>
        <para>
            An external can also be a Fortran or C routine : this is convenient to speed up
            the computations.
        </para>
        <para>
            The name of the routine is given to the high-level primitive
            as a character string. The syntax of the routine
            is also imposed.
        </para>
        <para>
            External Fortran or C routines can also be dynamically linked (see <literal>link</literal>).
        </para>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="ode">ode</link>
            </member>
            <member>
                <link linkend="optim">optim</link>
            </member>
            <member>
                <link linkend="impl">impl</link>
            </member>
            <member>
                <link linkend="dae">dae</link>
            </member>
            <member>
                <link linkend="intg">intg</link>
            </member>
            <member>
                <link linkend="schur">schur</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
