%2345678901234567890123456789012345678901234567890123456789012345678901234567890
\chapter{Inter$\Psi$}
\label{intersci}
\index{inter$\Psi$}

\newcommand{\version}{Version 2.1}
\newcommand{\ISCI}{Inter$\Psi$}
\newcommand{\SCI}{$\Psi$Lab}
\newcommand{\T}[1]{{\tt #1}}
\newcommand{\M}[1]{$<${\em #1}$>$}
\newcommand{\ie}{\mbox{i.e.}}

%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%%%%%%%%%%%%%%%%%%%%%%
\ISCI\ is a program which permits to interface automatically FORTRAN 
subroutines or C functions to \SCI.

With \ISCI, a user can group all his FORTRAN or C code into a same set,
called an interface, and use them in \SCI\ as \SCI\ functions. The interfacing
is made by creating a FORTRAN subroutine which has to be linked to \SCI\ together
with the user code. This complex FORTRAN subroutine is automatically generated
by \ISCI\ from a description file of the interface.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Adding a new interface in \SCI}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%
\section{Using \ISCI}
%%%%%%%%%%%%%%%%%%%%%
In the following, we will only speak of FORTRAN subroutine interfacing. The
process is nearly the same for C functions (see \ref{C}).

\smallskip

To use \ISCI\ execute the UNIX command:\\
\T{intercsi }\M{interface name}\T{\ }\M{interface number}\\
where \M{interface name}\T{.desc} is the file describing the interface.

Then the files \M{interface name}\T{.f} and \T{fundef.}\M{interface name}
are created.

\smallskip

The file \M{interface name}\T{.desc} is a sequence of descriptions of 
pairs formed by the \SCI\ function and the corresponding FORTRAN subroutine
(see table \ref{t-pair}).

\begin{table}
\begin{center}
\begin{tabular}{|l|}
\hline
\M{\SCI\ function name} \M{function arguments}\\
\M{\SCI\ variable} \M{\SCI\ type} \M{possible arguments}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$
  \qquad\qquad$\vdots$\\
\M{FORTRAN subroutine name} \M{subroutine arguments}\\
\M{FORTRAN argument} \M{FORTRAN type}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\\
out \M{type} \M{formal output names}\\
\M{formal output name} \M{variable}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\\
*******************************\\
\hline
\end{tabular}
\end{center}
\caption{Description of a pair of \SCI\ function and FORTRAN subroutine}
\label{t-pair}
\end{table}

Each description is made of three parts: description of \SCI\ function and its
arguments, description of FORTRAN subroutine and its arguments, and finally
description of the output of \SCI\ function with possible type conversions.

\subsection{Description of \SCI\ function}
%%%%%%%%%%%
\label{scilab}

The first line of the description is composed by the name of the \SCI\
function followed by its input arguments in calling order.

The next lines describe \SCI\ variables: the input arguments and the
outputs of the \SCI\ function, together with the arguments of the FORTRAN
subprogram with type \T{work} (for which memory must be allocated).
It is an error not to describe such arguments.

The description of a \SCI\ variable begins by its name, then its type followed
by possible informations depending on the type.

Types of \SCI\ variables are:
\begin{description}
  \item[any] any type: only used for an input argument of \SCI\ function.
  \item[column] column vector: must be followed by its dimension.
  \item[list] list: must be followed by the name of the list,
\M{list name}. This name must correspond to a file \M{list name}\T{.list}
which describes the structure of the list (see \ref{list}).
  \item[matrix] matrix: must be followed by its two dimensions.
  \item[polynom] polynomial: must be followed by its dimension (size) and the
name of the unknown.
  \item[row] row vector: must be followed by its dimension (length).
  \item[scalar] scalar.
  \item[string] character string: must be followed by its dimension (length).
  \item[vector] row or column vector: must be followed by its dimension.
  \item[work] working array: must be followed by its dimension. It must not
correspond to an input argument or to the output of the \SCI\ function.
\end{description}

The way dimensions are specified is described in 
\ref{dimensions}.
\smallskip

A blank line and only one ends this description.

\subsubsection{Optional input arguments}

\subsection{Description of FORTRAN subroutine}
%%%%%%%%%%%
\label{fortran}

The first line of the description is composed by the name of the 
FORTRAN subroutine
followed by its arguments in calling order.

The next lines describe FORTRAN variables: the arguments of the FORTRAN
subroutine. 
It is an error not to describe such arguments.

The description of a FORTRAN variable is made of its name and its type.
Most FORTRAN variables correspond to \SCI\ variables (except for
dimensions, see \ref{dimensions}) and must have the same name as the
corresponding \SCI\ variable. It is the reason why possible FORTRAN variable
dimensions are not given here because defined with the \SCI\ variable
dimension.

\smallskip

Types of FORTRAN variables are:
\begin{description}
  \item[char] character array.
  \item[double] double precision variable.
  \item[int] integer variable.
  \item[real] real variable.
\end{description}

External types also exist, see \ref{external}.

\smallskip

A blank line and only one ends this description.

\subsection{Description of the output of \SCI\ function}
%%%%%%%%%%%
\label{output}

The first line of this description must begin by the word \T{out} followed
by the type of \SCI\ output.

\smallskip

Types of output are:
\begin{description}
  \item[empty] the \SCI\ function returns nothing.
  \item[list] a \SCI\ list: must be followed by the names of \SCI\ variables
elements of the list.
  \item[sequence] a \SCI\ sequence: must be followed by the names of \SCI\
variables elements of the sequence.
\end{description}

This first line must be followed by other lines corresponding to output type
conversion. This is the case when an output variable is also an input variable
with different \SCI\ type: for instance an input column vector becomes an
output row vector. The line which describes this conversion begins by the name
of \SCI\ output variable followed by the name of the corresponding \SCI\ input
variable. See \ref{ex3} as an example.
\medskip

A line beginning with a star ``\T{*}'' ends the description of a pair of
\SCI\ function and FORTRAN subroutine. This line is compulsory even if it is
the end of the file. Do not forget to end the file by a carriage return.

\subsection{Dimensions of non scalar variables}
%%%%%%%%%%%
\label{dimensions}

When defining non scalar \SCI\ variables (vectors, matrices, polynomials and
character strings) dimensions must be given. There are a few ways to do that:

\begin{itemize}
  \item It is possible to give the dimension as an integer (see \ref{ex1}).
  \item The dimension can be the dimension of an input argument of \SCI\
function. This dimension is then denoted by a formal name which is not the
name of a \SCI\ variable (see \ref{ex2}). This is an usual case.
  \item The dimension can be defined as an output of the FORTRAN subroutine.
This means that the memory for the corresponding variable is allocated by the
FORTRAN subroutine. The corresponding FORTRAN variable must necessary have an
external type (see \ref{external} and \ref{ex3}).
\end{itemize}

\ISCI\ is not able to treat the case where the dimension is an algebraic
expression of other dimensions. A \SCI\ variable corresponding to this value
must defined.

The dimension must not be an input of \SCI\ function.

\subsection{FORTRAN variables with external type}
%%%%%%%%%%%
\label{external}

When describing the FORTRAN subroutine, a FORTRAN variable can have a type
different than the ones described in \ref{fortran}.

External types are used when the dimension of the FORTRAN variable is
unknown when calling the FORTRAN subroutine and when its memory size is
allocated in this subroutine. This dimension must be an output of the FORTRAN
subroutine. In fact, this will typically happen when we want to interface a C
function in which memory is dynamically allocated.

\smallskip

Existing external types:
\begin{description}
 \item[cchar] character string allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[ccharf] the same as \T{cchar} but the C character string is freed after
the copy.
 \item[cdouble] C double array allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[cdoublef] the same as \T{cdouble} but the C double array is freed after
the copy.
 \item[cint] C integer array allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[cintf] the same as \T{cint} but the C integer array is freed after
the copy.
\end{description}

\medskip

In fact, the name of an external type corresponds to the name of a C function.
This C function has three arguments: the dimension of the variable, an input
pointer and an output pointer.

For instance, below is the code for external type \T{cintf}:
\begin{verbatim}
#include "../machine.h"   

/* ip is a pointer to a FORTRAN variable coming from SCILAB
which is itself a pointer to an array of n integers typically
coming from a C function
   cintf converts this integer array into a double array in op 
   moreover, pointer ip is freed */

void C2F(cintf)(n,ip,op)
int *n;
int *ip[];
double *op;
{
  int i;
  for (i = 0; i < *n; i++)
    op[i]=(double)(*ip)[i];
  free((char *)(*ip));
}
\end{verbatim}

For the meaning of \verb|#include "../machine.h"| and \T{C2F} see \ref{C}.

\smallskip

Then, the user can create its own external types by creating its own C
functions with the same arguments. \ISCI\ will generate the good call of the
function. 

\subsection{Using lists as input \SCI\ variables}
%%%%%%%%%%%
\label{list}

An input argument of the \SCI\ function can be a \SCI\ list.
If \M{list name} is the name of this variable, a file called 
\M{list name}\T{.graph}
must describe the structure of the list. This file permits to associate
a \SCI\ variable to each element of the list by defining
its name and its \SCI\ type. The variables are described in order into the
file as described by table \ref{t-list}.

Then, such a variable element of the list is referred in the file 
\M{interface name}\T{.desc} by its
name followed by the name of the corresponding list in parenthesis. For
instance, \T{la1(g)} denotes the variable named \T{la1} element of the list
named \T{g}.

\begin{table}
\begin{center}
\begin{tabular}{|l|}
\hline
\M{comment on the variable element of the list}\\
\M{name of the variable element of list} \M{type} \M{possible arguments}\\
*******************************\\
\hline
\end{tabular}
\end{center}
\caption{Description of a variable element of a list}
\label{t-list}
\end{table}

An example is shown in \ref{ex4}.

\subsection{Limitations}
%%%%%%%%%%%
\label{limit}

\ISCI\ does not permit to interface FORTRAN functions.

The FORTRAN subroutines we want to interface must not use \T{COMMON} to pass
arguments. All the arguments must be in the calling list of the subroutine.

\ISCI\ is not able to deal with constants, complexes, matrices of strings and
matrices of polynomials as \SCI\ variables.

See also \ref{dimensions} for limitations on dimensions.

\subsection{C functions interfacing}
%%%%%%%%%%%
\label{C}

To interface C functions instead of FORTRAN subroutines is easy.

The C function must be considered as a procedure \ie\
its type must be \T{void} or the value returned must not be used.

The arguments of the C function must be considered as FORTRAN arguments \ie\
they must be only pointers.

Moreover, the name of the C function must be recognized by FORTRAN. This
depends upon the machines. For instance, on SUN and DEC machines the name of C
functions must end by a \T{\_} to be recognized by FORTRAN, but on RS6000
(IBM) machines the name must be the same. So, the include file \T{machine.h}
situated in the
directory \M{\SCI\ directory}\T{/routines} can be included in C functions and
the macros \T{C2F} and \T{F2C} can be used.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Writing compatible code to \SCI}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{compat}

\subsection{Input and output}
%%%%%%%%%%%

\subsection{Error exit}
%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%
\section{Examples}
%%%%%%%%%%%%%%%%%%

\subsection{Example 1}
%%%%%%%%%%%
\label{ex1}

The name of the \SCI\ function is \T{calc}. Its input is a string and its
output is a scalar.

The name of the corresponding FORTRAN subroutine is \T{calc} and its arguments
are a string (used as input) and an integer (used as output).

We reserve a fixed dimension of 10 for the string.

The description file is the following:
\begin{verbatim}
calc    str
str     string  10
a       scalar

fcalc   str     a
str     char
a       integer

out     a
***********************
\end{verbatim}

\subsection{Example 2}
%%%%%%%%%%%
\label{ex2}

The name of the \SCI\ function is \T{som}. Its inputs are two row vectors and
its  output is a column vector.

The name of the corresponding FORTRAN subroutine is \T{fsom} and its arguments
are a real array and its dimension (used as input), another 
real array and its dimension (used as input) and a real array (used as output).
These dimensions \T{m} and \T{n} are determined at the calling of the \SCI\
function and do not need to appear as \SCI\ variables.

\ISCI\ will do the job to make the necessary conversions to transform the
double precision (default in \SCI) row vector \T{a} into a real array and to
transform the real array \T{c} into a double precision row vector.

The description file is the following:
\begin{verbatim}
som     a       b
a       row     m
b       row     n
c       column  n

fsom    a       n       b       m       c
str     char
a       real
n       integer
b       real
m       integer
c       real

out     sequence        c
***********************
\end{verbatim}

\subsection{Example 3}
%%%%%%%%%%%
\label{ex3}

The name of the \SCI\ function is \T{ext}. Its input is a matrix and its
outputs are a matrix and a column vector.

The name of the corresponding FORTRAN subroutine is \T{fext} and its arguments
are an integer array (used as input and output), its dimensions (used as
input) and another integer array and its dimension (used as outputs).

The dimension \T{p} of the output \T{b} is computed by the FORTRAN subroutine
and the memory for this variable is also allocated by the FORTRAN subroutine
(perhaps by to a call to another C function). So the type of the variable is
external and we choose \T{cintf}.

Moreover, the output \T{a} of the \SCI\ function is the same as the input
but its type changes from a $m \times n$ matrix to a $n \times m$ matrix. This
conversion is made my introducing the \SCI\ variable \T{o}

The description file is the following:
\begin{verbatim}
ext     a
a       matrix  m       n
b       column  p
o       matrix  n       m

fext    a       m       n       b       p
a       integer
m       integer
n       integer
b       cintf
p       integer

out     sequence        o       b
o       a
***************************
\end{verbatim}

\subsection{Example 4}
%%%%%%%%%%%
\label{ex4}

The name of the \SCI\ function is \T{contr}. Its input is a list representing
a linear system given by its state representation and a tolerance. Its return
is a scalar (for instance the dimension of the controllable subspace).

The name of the corresponding FORTRAN subroutine is \T{contr} and its
arguments are the dimension of the state of the system (used as input), the
number of inputs of the system (used as input), 
the state matrix of the system (used as input),
the input matrix of the system (used as input),
an integer giving the dimension of the controllable subspace (used as output),
and the tolerance (used as input).

The description file is the following:
\begin{verbatim}
contr   sys     tol
tol     scalar
sys     list    lss
icontr  scalar

contr   nstate(sys)	nin(sys)     a(sys)  b(sys)  icontr  tol
a(sys)  double
b(sys)  double
tol     double
nstate(sys)     integer
nin(sys)        integer
icontr  integer

out     sequence        icontr
******************************
\end{verbatim}

The type of the list is \T{lss} and a file describing the list \T{lss.list} is
needed. It is shown below:

\begin{verbatim}
1 type
type    string  3
******************************
2 state matrix
a       matrix  nstate  nstate
******************************
3 input matrix
b       matrix  nstate  nin
******************************
4 output matrix
c       matrix  nout    nstate
******************************
5 direct tranfer matrix
d       matrix  nout    nin
******************************
6 initial state
x0      column  nstate
******************************
7 time domain
t       any
******************************
\end{verbatim}

The number of the elements is not compulsory in the comment describing the
elements of the list but is useful.

