13
13
<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" version="5.0-subset Scilab" xml:lang="en" xml:id="sci_files">
15
<refname>sci_files</refname>
16
<refpurpose>How to write conversion functions</refpurpose>
19
<title>Description</title>
21
To convert calls to Matlab functions, <literal>mfile2sci</literal> uses a function called
22
<literal>sci_<Matlab_function_name></literal>. All these functions are defined in <literal>sci_files</literal>
23
in directory SCI/modules/m2sci/macros/sci_files/. The set of <literal>sci_files</literal> given in Scilab
24
distribution does not allow to convert calls to all Matlab functions yet.
25
However, a Scilab user can add <literal>sci_files</literal> (for Matlab functions or for user defined functions)
26
to Scilab using the following tips.
29
In M2SCI, a function call is considered as a "tree" (it is also the case for the instructions
30
of the file to convert), represented in Scilab by a <literal>tlist</literal> with following fields:
38
<para>Matlab function name</para>
44
<para>number of Matlab function output parameters</para>
50
<para>list of Matlab function output parameters</para>
56
<para>list of Matlab function input parameters</para>
63
A <literal>sci_function</literal> has one input called <literal>tree</literal> which is also the output of the function.
64
A <literal>sci_function</literal> has to convert this incoming "tree" so that it is compatible with Scilab
65
by changing name, lhsnb, lhs and/or rhs. The other task that has to be done by this function
66
is inference. Incoming tree contains inference data in its lhs that have to be updated with what
67
can be infered for the outputs of this function.
70
Some useful functions have been written to help to create M2SCI tlists while writing this conversion function:
78
<para>create a tree representing a function call</para>
82
<term>Operation</term>
84
<para>create a tree representing an operation</para>
90
<para>create a tree representing a variable</para>
96
<para>create a tree representing a constante value</para>
102
<para>create a tree representing inference data</para>
108
<para>create a tree representing type for inference</para>
114
<para>create a tree representing an instruction</para>
121
Some other functions have been designed to get properties of operands/inputs. Considering A is tlist used in macro tree, you can use the following functions:
123
<informaltable border="1">
127
returns <literal>%T</literal> if...
132
<literal>is_empty(A)</literal>
134
<td>all dimensions of A are 0</td>
138
<literal>not_empty(A)</literal>
140
<td>all dimensions of A are known and at least one dimension of A is not 0</td>
144
<literal>is_a_scalar(A)</literal>
146
<td>all dimensions of A are 1</td>
150
<literal>not_a_scalar(A)</literal>
152
<td>all dimensions of A are known and at least one dimension of A is not 1</td>
156
<literal>is_a_vector(A)</literal>
158
<td>all dimensions of A are known and all dimensions of A but one are equal to 1</td>
162
<literal>not_a_vector(A)</literal>
164
<td>all dimensions of A are known and at least two dimensions of A are greater than one</td>
168
<literal>is_real(A)</literal>
174
<literal>is_complex(A)</literal>
176
<td>A is complex</td>
180
<literal>isdefinedvar(A)</literal>
182
<td>A is a variable already created in M-file currently converted</td>
186
<literal>allunknown(A)</literal>
188
<td>all dimensions of A are unknown</td>
192
Some other functions have been written for specific needs while writing conversion files:
198
<term>first_non_singleton</term>
201
is an equivalent to <link linkend="firstnonsingleton">firstnonsingleton</link> for an M2SCI tlist. Calling sequence: <literal>dim = first_non_singleton(A)</literal>
206
<term>gettempvar</term>
209
generates a temporary variable having a name which does not already exist. Calling sequence:<literal> v = gettempvar()</literal>
217
allows to insert instructions. Calling sequence:<literal> insert(Equal(...),opt)</literal> with <literal>opt~=1</literal> to insert before current instruction and <literal> opt=1</literal> to insert after it.
222
<term>getoperands</term>
225
can be used to get each operand as a variable. Calling sequence: <literal>[A,B] = getoperands(operation_tlist)</literal>
233
can be used to get each parameter as a variable. Calling sequence: <literal>[A,...] = getrhs(funcall_tlist)</literal>
238
<term>convert2double</term>
241
change type of input when this type is not implemented for a particular function is Scilab. Calling sequence:<literal> A = convert2double(A)</literal>
249
To have more information about how to write such files, refer to directory
250
SCI/modules/m2sci/macros/sci_files/ which gives many examples from very simple ones
251
(e.g. sci_abs.sci) to very complex ones (e.g. sci_zeros.sci).
254
<refsection role="see also">
255
<title>See Also</title>
256
<simplelist type="inline">
258
<link linkend="m2scideclare">m2scideclare</link>
261
<link linkend="Funcall">Funcall</link>
264
<link linkend="Operation">Operation</link>
267
<link linkend="Variable">Variable</link>
270
<link linkend="Cste">Cste</link>
273
<link linkend="Infer">Infer</link>
276
<link linkend="Type">Type</link>
279
<link linkend="Equal">Equal</link>
15
<refname>sci_files</refname>
16
<refpurpose>How to write conversion functions</refpurpose>
19
<title>Description</title>
21
To convert calls to Matlab functions, <literal>mfile2sci</literal> uses a function called
22
<literal>sci_<Matlab_function_name></literal>. All these functions are defined in <literal>sci_files</literal>
23
in directory SCI/modules/m2sci/macros/sci_files/. The set of <literal>sci_files</literal> given in Scilab
24
distribution does not allow to convert calls to all Matlab functions yet.
25
However, a Scilab user can add <literal>sci_files</literal> (for Matlab functions or for user defined functions)
26
to Scilab using the following tips.
29
In M2SCI, a function call is considered as a "tree" (it is also the case for the instructions
30
of the file to convert), represented in Scilab by a <literal>tlist</literal> with following fields:
38
<para>Matlab function name</para>
44
<para>number of Matlab function output parameters</para>
50
<para>list of Matlab function output parameters</para>
56
<para>list of Matlab function input parameters</para>
63
A <literal>sci_function</literal> has one input called <literal>tree</literal> which is also the output of the function.
64
A <literal>sci_function</literal> has to convert this incoming "tree" so that it is compatible with Scilab
65
by changing name, lhsnb, lhs and/or rhs. The other task that has to be done by this function
66
is inference. Incoming tree contains inference data in its lhs that have to be updated with what
67
can be infered for the outputs of this function.
70
Some useful functions have been written to help to create M2SCI tlists while writing this conversion function:
78
<para>create a tree representing a function call</para>
82
<term>Operation</term>
84
<para>create a tree representing an operation</para>
90
<para>create a tree representing a variable</para>
96
<para>create a tree representing a constante value</para>
102
<para>create a tree representing inference data</para>
108
<para>create a tree representing type for inference</para>
114
<para>create a tree representing an instruction</para>
121
Some other functions have been designed to get properties of operands/inputs. Considering A is tlist used in macro tree, you can use the following functions:
123
<informaltable border="1">
127
returns <literal>%T</literal> if...
132
<literal>is_empty(A)</literal>
134
<td>all dimensions of A are 0</td>
138
<literal>not_empty(A)</literal>
140
<td>all dimensions of A are known and at least one dimension of A is not 0</td>
144
<literal>is_a_scalar(A)</literal>
146
<td>all dimensions of A are 1</td>
150
<literal>not_a_scalar(A)</literal>
152
<td>all dimensions of A are known and at least one dimension of A is not 1</td>
156
<literal>is_a_vector(A)</literal>
158
<td>all dimensions of A are known and all dimensions of A but one are equal to 1</td>
162
<literal>not_a_vector(A)</literal>
164
<td>all dimensions of A are known and at least two dimensions of A are greater than one</td>
168
<literal>is_real(A)</literal>
174
<literal>is_complex(A)</literal>
176
<td>A is complex</td>
180
<literal>isdefinedvar(A)</literal>
182
<td>A is a variable already created in M-file currently converted</td>
186
<literal>allunknown(A)</literal>
188
<td>all dimensions of A are unknown</td>
192
Some other functions have been written for specific needs while writing conversion files:
198
<term>first_non_singleton</term>
201
is an equivalent to <link linkend="firstnonsingleton">firstnonsingleton</link> for an M2SCI tlist. Calling sequence: <literal>dim = first_non_singleton(A)</literal>
206
<term>gettempvar</term>
209
generates a temporary variable having a name which does not already exist. Calling sequence:<literal> v = gettempvar()</literal>
217
allows to insert instructions. Calling sequence:<literal> insert(Equal(...),opt)</literal> with <literal>opt~=1</literal> to insert before current instruction and <literal> opt=1</literal> to insert after it.
222
<term>getoperands</term>
225
can be used to get each operand as a variable. Calling sequence: <literal>[A,B] = getoperands(operation_tlist)</literal>
233
can be used to get each parameter as a variable. Calling sequence: <literal>[A,...] = getrhs(funcall_tlist)</literal>
238
<term>convert2double</term>
241
change type of input when this type is not implemented for a particular function is Scilab. Calling sequence:<literal> A = convert2double(A)</literal>
249
To have more information about how to write such files, refer to directory
250
SCI/modules/m2sci/macros/sci_files/ which gives many examples from very simple ones
251
(e.g. sci_abs.sci) to very complex ones (e.g. sci_zeros.sci).
254
<refsection role="see also">
255
<title>See Also</title>
256
<simplelist type="inline">
258
<link linkend="m2scideclare">m2scideclare</link>
261
<link linkend="Funcall">Funcall</link>
264
<link linkend="Operation">Operation</link>
267
<link linkend="Variable">Variable</link>
270
<link linkend="Cste">Cste</link>
273
<link linkend="Infer">Infer</link>
276
<link linkend="Type">Type</link>
279
<link linkend="Equal">Equal</link>
added
removed
modules/m2sci/help/en_US/sci_files.xml
