gschur() was declared obsolete in Scilab 4, now removed
[scilab.git] / scilab / modules / functions / help / en_US / built_in / external.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <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">
3     <refnamediv>
4         <refname>external</refname>
5         <refpurpose>Scilab Object, external function or routine</refpurpose>
6     </refnamediv>
7     <refsection role="description">
8         <title>Description</title>
9         <para>
10             External function or routine for use with specific commands.
11         </para>
12         <para>
13             An "external" is a function or routine which is used as an argument
14             of some high-level primitives (such as <literal>ode</literal>, <literal>optim</literal>, <literal>schur</literal>...).
15         </para>
16         <para>
17             The syntax of the external (function or routine) is imposed by
18             the high-level primitive which sets the arguments of the external.
19         </para>
20         <para>
21             For example the external function <literal>costfunc</literal> is an argument of the <literal>optim</literal> 
22             primitive. Its syntax must be: <literal>[f,g,ind]=costfunc(x,ind)</literal> and 
23             <literal>optim</literal> (the high-level optimization primitive) is invoked as follows:
24         </para>
25         <programlisting role="no-scilab-exec"><![CDATA[ 
26 optim(costfunc,...)
27  ]]></programlisting>
28         <para>
29             Here <literal>costfunc</literal> (the cost function to be minimized by the primitive <literal>optim</literal>)
30             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).
31         </para>
32         <para>
33             If other values are needed by the external function these variables
34             can be defined in its environment. Also, they can be put in a list.
35             For example, the external function
36         </para>
37         <programlisting role="no-scilab-exec"><![CDATA[ 
38 [f,g,ind]=costfunc(x,ind,a,b,c) 
39  ]]></programlisting>
40         <para>
41             is valid for <literal>optim</literal> if the external is <literal>list(costfunc,a,b,c)</literal> and
42             the call to <literal>optim</literal> is then:
43         </para>
44         <programlisting role="no-scilab-exec"><![CDATA[ 
45 optim(list(costfunc,a1,b1,c1),....
46  ]]></programlisting>
47         <para>
48             An external can also be a Fortran or C routine : this is convenient to speed up 
49             the computations.
50         </para>
51         <para>
52             The name of the routine is given to the high-level primitive
53             as a character string. The syntax of the routine 
54             is also imposed.  
55         </para>
56         <para>
57             External Fortran or C routines can also be dynamically linked (see <literal>link</literal>).
58         </para>
59     </refsection>
60     <refsection role="see also">
61         <title>See Also</title>
62         <simplelist type="inline">
63             <member>
64                 <link linkend="ode">ode</link>
65             </member>
66             <member>
67                 <link linkend="optim">optim</link>
68             </member>
69             <member>
70                 <link linkend="impl">impl</link>
71             </member>
72             <member>
73                 <link linkend="dassl">dassl</link>
74             </member>
75             <member>
76                 <link linkend="intg">intg</link>
77             </member>
78             <member>
79                 <link linkend="schur">schur</link>
80             </member>
81         </simplelist>
82     </refsection>
83 </refentry>