graphics: bug 9270 fixed - The contour function was broken.
[scilab.git] / scilab_doc / scicos / scicos.tex
1
2 \documentclass{article}
3 \usepackage{epsfig,times,amsmath,amssymb}
4
5
6 \def\Figdir{}
7
8 \def\Scilab{{\sc Scilab}}
9
10 \newcommand{\computational}{{\em Computational }}
11 \newcommand{\interfacing}{{\em Interfacing }}
12
13
14 %\makeatletter
15
16 \title{SCICOS - A Dynamic System Builder and Simulator\\ User's Guide \thanks{Scicos is a Scilab
17 toolbox. This version of Scicos is included in Scilab-2.4. For more information on Scilab see:
18 {\tt http://www-rocq.inria.fr/scilab/}}}
19 \author{R. Nikoukhah \and S. Steer}
20 \date{}
21
22 \begin{document}
23 \maketitle
24 \input demo22.tex
25 \dessin{A typical Scicos diagram}{}
26 \section{Introduction}
27 \label{scicos}
28 Scicos (Scilab Connected Object Simulator) is a Scilab package for
29 modeling and simulation of dynamical systems including
30 both continuous and discrete sub-systems.
31 Scicos includes a graphical editor for constructing 
32 models by interconnecting blocks (representing predefined basic
33 functions or user defined functions). 
34
35 Associated with each signal, in Scicos, is a set of time indices, called activation times,
36 on which the signal can evolve. Outside their activation times, Scicos signals remain constant (see
37 Figure~\ref{ghuio}). The activation time set is a union of time intervals and isolated
38 points called events.
39 \begin{figure}
40 \begin{center}
41 \input jadid20.pstex_t
42 \end{center}
43 \caption{A signal in Scicos  and its activation time set.}
44 \label{ghuio}
45 \end{figure}
46
47 Signals in Scicos are generated by blocks driven by activation signals. An activation
48 signal causes the block to evaluate its output as a function of its input and internal state. 
49 The output signal, which inherits its activation time set from the generating block, can be
50 used to drive other blocks. 
51
52 Blocks are activated by activation signals which are received on activation input
53 ports placed on top of blocks. A block with no input activation port is 
54 permanently active (called time dependent) otherwise it inherits its activation
55 times from the union of activations times of its input signals.
56
57 Ports placed at the bottom of blocks are output activation ports. The outgoing
58 signals are activation signals generated by the block. For example,
59 the {\tt Clock} block generates an activation signal composed of a train of
60 regularly spaced events in time. If this output is connected to the input
61 activation port of a scope block (such as the {\tt MScope} block), it specifies
62 at what times the value of the inputs of the scope must be displayed.
63
64 \section{Scicos editor}
65 \label{scasm}
66 \label{ch2}
67 In Scicos, systems are modeled by interconnecting blocks and subsystems (Super blocks);
68 blocks can be found in various palettes or be defined by user. Scicos has an easy to use
69 graphical user interface for editing diagrams. To start the editor, in Scilab, type {\tt scicos();}.
70 This opens up Scicos' main window.
71
72 Construction of Scicos model typically consists of
73 \begin{itemize}
74 \item opening one or more palettes (using {\tt Palettes} button in the {\tt Edit} menu),
75 \item copying blocks from palettes into Scicos' main window; this can be done by
76 selecting the {\tt copy} button in the {\tt Edit} menu, then clicking on the block to
77 be copied, and finally in the Scicos' main window, where the block is to be placed. 
78 \item connecting the input and output ports of the blocks
79 by selecting first the {\tt link} button in the {\tt Edit} menu, then clicking  on the 
80 output port and then on the input port (or intermediary points
81 before that).
82 \end{itemize}
83 Note that to make a
84 link originate  from another link (to split a link), user should first click
85 on the {\tt Link} button and then on an existing link, where split is
86 to be placed, and finally on an input port (or intermediary points
87 before that). The process of link creation can be stopped and current link deleted
88 by clicking on the right mouse button.
89
90 Note also that at least one  scope or a ``write to file'' block should be placed in any Scicos 
91 diagram to visualize or save the result of the simulation. See Scicos demos for
92 examples. 
93
94 \subsection{Parameter adaptation}
95 Block parameters can be modified by opening the block dialogs. This can be
96 done using the {\tt Open/set} button. Most blocks have dialog menus which can be
97 used to set or modify block parameters. These parameters can be defined using
98 valid Scilab expressions. Scilab variables can be used in the definition of these
99 expressions if they are already defined in the context of diagram. These
100 expressions are memorized symbolically, and
101 then evaluated. 
102
103 The context of the diagram can be edited by selecting the {\tt Context} button.
104 The context is evaluated by the {\tt Eval} button. This is necessary only if the
105 context modification includes a change in the value of a variable previously used in the
106 definition of a block parameter.
107
108 \subsection{Simulation}
109 A completed diagram can be simulated using {\tt Run} in the
110 {\tt Simulate} menu. Selecting this button results in a compilation
111 of the diagram (if not already compiled) and simulation.
112 The simulation can be stopped by clicking on the {\tt stop} button on
113 top of the Scicos main window. 
114
115
116 A compiled Scicos diagram, saved as a {\tt *.cos} file, 
117 does not need compilation the next time it is loaded; the saved file contains, the
118 result of the compilation. It is also possible to 
119 extract just the data needed to do simulation, and do the simulation
120 without having to enter the Scicos environment. This can be done
121 using the {\tt scicosim} function.
122
123
124 \subsection{Other functionalities}
125 The editor provides many other functionalities such as
126 \begin{itemize}
127 \item saving and loading diagrams in various formats
128 \item zooming and changing the point of view
129 \item changing block aspects and colors
130 \item changing diagram's background and forground colors
131 \item placing text in the diagram
132 \item printing and exporting Scicos diagrams
133 \item and many other standard GUI functions.
134 \end{itemize}
135 The {\tt Help} button can be used to obtain help on various aspects of Scicos.
136 Selecting {\tt Help} and then clicking on a block displays the manual page of the block.
137 Selecting {\tt Help} and then selecting another button, displays the manual page of the button.
138
139
140 Finally, an important feature in Scicos is the possibility of creating sub-systems (Super Blocks).
141 Clearly, it would not be desirable to fit a complex system with hundreds of
142 components in one Scicos diagram. For that, Scicos provides the possibility
143 of grouping blocks together and defining sub-diagrams called Super Blocks.
144 These blocks behave like any other block but can contain
145 an unlimited number of blocks, and even other Super Blocks. 
146
147
148
149
150 \section{Basic Blocks}
151 There are three types of Basic Blocks in Scicos: Regular Basic Blocks,
152 Zero Crossing Basic Blocks and Synchro Basic Blocks. These blocks have can have two types of
153 inputs and two types of outputs ports: regular inputs, activation inputs,
154 regular 
155 outputs and activation outputs ports. Regular inputs and outputs are
156 interconnected by regular links, and activation inputs and outputs, by
157 activation links. Note that activation input ports are placed on top and activation output
158 ports at the bottom of the blocks. 
159
160 \subsection{Regular Basic Block}
161 Regular Basic Blocks (RBB) can have a {\em continuous state} $x$ and a 
162 {\em discrete state} $z$. If it does have an $x$ and if $u$ denotes its regular input, then,
163 when the block is active over an interval of time, $x$ evolves continuously according to
164 \begin{equation}
165 \dot{x} = f(t,x,z,u,p,n_{e}) \label{e1}
166 \end{equation}
167 where $f$ is a vector function, $p$ is a vector of
168 constant parameters and $n_{e}$ is the {\em activation
169 code} which is an integer designating the port(s)  through which the block is
170 activated. In particular, if activating input ports are
171 $i_1,i_2,\dots,i_n$, then
172 \[
173 n_{e}=\sum_{j=1}^n 2^{i_j-1}.
174 \]
175
176 On the other hand, activated by an event, the states $x$ and $z$ jump
177 instantaneously according to the following equations:
178 \begin{eqnarray}
179 x(t_e) &=& g_c(t_e,x(t_e^-),z(t_e^-),u(t_e),p,n_{e}) \label{e11}\\
180 z(t_e) &=& g_d(t_e,x(t_e^-),z(t_e^-),u(t_e),p,n_{e}) \label{e12}
181 \end{eqnarray}
182 where $t_e$ denotes the event time. The discrete state $z$ remains constant 
183 between any two successive events so $z(t_e^-)$ can be interpreted as the previous value of $z$.
184
185 During activation times, the regular output of the block is defined by
186 \begin{equation}
187 y(t)=h(t,x(t^-),z(t^-),u(t),p,n_{e}) \label{e2}
188 \end{equation}
189 and is constant when the block is not active.
190
191 Finally, RBB's can generate activation signals of event type.
192 If it is activated by an event at time $t_e$, the time 
193 of each output event is given by
194 \begin{equation}
195 t_{evo} = k(t_e,z(t_e),u(t_e),p,n_{e})  \label{e20}
196 \end{equation}
197 where $t_{evo}$ is a vector of time, each entry of which corresponds to one activation output port. 
198 The absence of event corresponds to a time smaller than the current time. 
199 Event generations can also be pre-scheduled. Pre-scheduling of events
200 can  be done by setting the "initial  firing variables of blocks 
201 with event output ports.  
202
203
204 \subsection{Zero Crossing Basic Block} 
205 Zero Crossing Basic Block (ZBB)  can generate event outputs only if at least
206 one of the regular inputs crosses zero (changes sign). In such a case, the
207 generation of the event, and its timing, can depend on the combination of
208 the inputs which have crossed zero and the signs of the inputs just
209 before the crossing occurs. 
210
211 A few examples of ZBB's can be found in the {\tt Threshold} palette. 
212
213
214 \subsection{Synchro Basic Block}
215 \label{syn}
216 Synchro Basic Blocks (SBB) generate output activation signals that are
217 synchronized with their input activation signals. These blocks have a
218 unique activation input port; they route their input activation signals
219 to one of their activation outputs. The choice of this output depends
220 on the value of the regular input. Examples are
221 the {\tt event select} block and
222 the {\tt If-then-else} block in the {\tt Branching} palette.
223
224
225
226 \section{Time dependence and inheritance}
227 To avoid explicitly drawing all the activation
228 signals in a Scicos diagram, a feature called inheritance is
229 provided in Scicos. In particular, if a block has no activation input port, it inherits its
230 activation signal from its regular input signals. And for blocks which are active 
231 permanently, they can be declared as such (``time dependent'') and they do not
232 need input activation ports. Note that time dependent blocks do not inherit.
233
234
235
236 \section{Block construction}
237 A new block can be constructed as a Super Block (by interconnection of basic
238 blocks) and compiled. As for a new basic block, it can be 
239 defined by a pair of functions: 
240 \begin{itemize}
241 \item an \interfacing function for handling the user-interface
242 \item a \computational function for specifying its dynamic behavior.
243 \end{itemize}
244 The \interfacing function is always written as a  Scilab function. See 
245 Scilab functions in {\tt <SCIDIR>/macros/scicos\_blocks}
246 for examples. The \computational function can be written in 
247 C or Fortran. See {\tt <SCIDIR>/routines/scicos} for examples.
248 But it can also be written in Scilab language. C and Fortran routines dynamically linked or
249 permanently interfaced with Scilab give the better results as far as  
250 simulation performance is concerned. 
251
252 The {\tt Scifunc}, {\tt GENERIC}, {\tt C\_block} and {\tt Fortran\_block} blocks provide
253 generic \interfacing functions, very useful for rapid prototyping and testing user-developed
254 \computational functions.
255
256
257 \subsection{\interfacing function}
258 The \interfacing function determines the geometry, color, number
259 of ports and their sizes, icon, etc..., in addition to the initial states,
260 parameters. This function also handles the block's user dialog.
261
262 What the interfacing function should do and should
263 return depends on an input flag {\tt job}. The syntax is as follows:
264
265 \subsubsection{Syntax}
266 \begin{verbatim}
267  [x,y,typ]=block(job,arg1,arg2)
268 \end{verbatim}
269
270 \paragraph{Parameters}
271 \begin{itemize}
272 \item job=='plot': the function draws the block. 
273   \begin{itemize}
274   \item {\tt arg1} is the data structure of the block.
275   \item {\tt arg2} is not used.
276   \item {\tt x,y,typ} are not used.
277   \end{itemize}
278 In general, we can use {\tt standard\_draw} \label{stdd} function
279 which  draws a rectangular block, and the input and output ports. It
280 also handles the size, icon, and color aspects of the block.
281
282 \item job=='getinputs': the function returns position and type of
283   input ports (regular or activation). 
284   \begin{itemize}
285   \item  {\tt arg1} is the data structure of the block.
286   \item  {\tt arg2} is not used.
287   \item {\tt x} is the vector of x coordinates of input ports.
288   \item {\tt y} is the vector of y coordinates of input ports.
289   \item {\tt typ} is the vector of input ports types (1 for regular
290 and 2 for activation). 
291   \end{itemize}
292   In general, we can use the {\tt standard\_input} function.
293 \item job=='getoutputs': returns position and type of output ports
294 (regular and activation). 
295   \begin{itemize}
296   \item  {\tt arg1} is the data structure of the block. 
297   \item  {\tt arg2} is not used.
298   \item {\tt x} is the vector of x coordinates of output ports.
299   \item {\tt y} is the vector of y coordinates of output ports.
300   \item {\tt typ} is the vector of output ports types .
301   \end{itemize}
302 In general, we can use the {\tt standard\_output} function.
303 \item job=='getorigin': returns coordinates of the lower
304   left point of the rectangle containing the block's silhouette.
305   \begin{itemize}
306   \item  {\tt arg1} is the data structure of the block. 
307   \item  {\tt arg2} is not used.
308   \item {\tt x} is the x coordinate of the lower left point of the block.
309   \item {\tt y} is the y coordinate of the lower left point of the block.
310   \item {\tt typ} is not used.
311   \end{itemize}
312 In general, we can use the {\tt standard\_origin} function.
313 \item job=='set': opens up a dialogue for block parameter acquisition
314 (if any).
315   \begin{itemize}
316   \item  {\tt arg1} is the data structure of the block. 
317   \item  {\tt arg2} is not used.
318   \item {\tt x} is the new data structure of the block.
319   \item {\tt y} is not used.
320   \item {\tt typ} is not used.
321   \end{itemize}
322 \item  job=='define': initialization of block's data
323   structure (name of corresponding \computational function, type, 
324   number and sizes of inputs and outputs, etc...).
325   \begin{itemize}
326   \item  {\tt arg1, arg2} are not used.
327   \item {\tt x} is the data structure of the block.
328   \item {\tt y} is not used.
329   \item {\tt typ} is not used.
330   \end{itemize}
331 \end{itemize}
332
333 \subsubsection{Block data-structure definition}
334 \label{bds}
335 Each Scicos block is defined by a Scilab data structure as
336 follows:
337
338 \begin{verbatim}
339  list('Block',graphics,model,unused,GUI_function)
340 \end{verbatim}
341 where {\tt GUI\_function} is a string containing the name of the
342 corresponding \interfacing function and
343 {\tt graphics} is the structure containing the graphical data:
344 \begin{verbatim}
345 graphics=..
346   list([xo,yo],[l,h],orient,dlg,pin,pout,pcin,pcout,gr_i)
347 \end{verbatim}
348 \begin{itemize}
349 \item \textbf{xo}: x coordinate of block origin
350 \item \textbf{yo}: y coordinate of block origin
351 \item \textbf{l}: block's width
352 \item \textbf{h}: block's height
353 \item \textbf{orient}:  boolean, specifies if block is flipped or not (regular
354 inputs are on the left or right).
355 \item \textbf{dlg}: \label{dlg2} vector of character strings, contains block's
356 symbolic parameters.
357 \item \textbf{pin}: vector, {\tt pin(i)} is  the number  of the link
358 connected to {\tt i}th regular input port, or 0 if this port is not
359 connected. 
360 \item \textbf{pout}: vector, {\tt pout(i)} is  the number  of the link
361   connected to {\tt i}th regular output port, or 0 if this port is not
362   connected.
363 \item \textbf{pcin}: vector, {\tt pcin(i)} is  the number  of the link
364   connected to {\tt i}th activation input port, or 0 if this port is not
365   connected.
366 \item \textbf{pcout}: vector, {\tt pcout(i)} is  the number  of the link
367   connected to {\tt i}th activation output port, or 0 if this port is not
368   connected.
369 \item \textbf{gr\_i}: character string vector, Scilab instructions used to draw
370   the icon.
371 \end{itemize}
372 The data structure containing simulation information is {\tt model}:
373 \label{model}
374 \begin{verbatim}
375 model=list(eqns,#input,#output,#clk_input,#clk_output,..
376       state,dstate,rpar,ipar,typ,firing,deps,label,unused)
377 \end{verbatim}
378 \begin{itemize}
379 \item \textbf{eqns}: \label{eqns} list containing two elements. First element
380 is a string containing 
381 the name of the \computational function (fortran, C, or Scilab
382 function). Second element 
383 is an integer specifying the type of the \computational function. The
384 type of a \computational function specifies essentially its calling
385 sequence; more on that later. 
386 \item \textbf{\#input}: vector of size equal to the number of block's regular
387 input ports. Each entry specifies the size of the corresponding input
388 port. A negative integer stands for  ``to be determined by the
389 compiler''. Specifying the same negative integer on 
390 more than one input or output port tells the compiler that these ports have
391 equal sizes. 
392 \item \textbf{\#output}: vector of size equal to the number of block's regular
393 output ports. Each entry specifies the size of the corresponding
394 output port. Specifying the same negative integer on 
395 more than one input or output port tells the compiler that these ports have
396 equal sizes. 
397 \item \textbf{\#clk\_input}: vector of size equal to the number 
398 of activation input ports. All entries
399 must be equal to $1$. Scicos does not support vectorized activation links.
400
401 \item \textbf{\#clk\_output}: vector of size equal to the 
402 number of activation output ports. All entries
403 must be equal to $1$. Scicos does not support vectorized activation links.
404
405 \item \textbf{state}: column vector of initial continuous state.
406 \item \textbf{dstate}: column vector of initial discrete state.
407 \item \textbf{rpar}: column vector of real parameters passed on to the corresponding
408 \computational function.
409 \item \textbf{ipar}: column vector of integer parameters passed on to the
410 corresponding \computational function.
411 \item \textbf{typ}: string. Basic block type: {\tt 'z'} if ZBB, 
412 {\tt 'l'} if
413 SBB and anything else for except {\tt 's'} for RBB.
414 \item \textbf{firing}: column vector of initial firing times of size  equal to
415 the number of activation output ports of the block. It includes
416 preprogrammed event firing times ($<$0 if no firing). 
417
418 \item \textbf{deps}: [{\tt udep} {\tt timedep}] 
419   \begin{itemize}
420   \item \textbf{udep}: boolean. True if system has direct feed-through, i.e., at least
421 one of the outputs depends explicitly on one of the inputs.
422   \item \textbf{timedep}: boolean. True if block is time dependent.
423   \end{itemize}
424 \item \textbf{label}: character string, used as block identifier. This field
425   may be set by the {\tt label} button in {\tt Block} menu.
426 \end{itemize}
427
428
429 \subsection{\computational function}
430 The \computational function  evaluates outputs, new states,
431 continuous state derivative and the output events timing vector
432 depending on the type of the block and the way it is called by the
433 simulator. 
434
435 \subsubsection{Behavior}
436 \label{tasks}
437 Simulator calls the \computational function for performing 
438 different tasks:
439
440 \begin{itemize}
441 \item \textbf{Initialization} The simulator calls the \computational function once
442 at the start for state and output initialization (inputs
443 are not available then).  Other tasks such as file opening, graphical window
444 initialization, etc..., can also be performed at this point.
445
446 \item \textbf{Re-initialization} The simulator can call the block a number of times for 
447 re-initialization. This is another opportunity to initialize
448 states and outputs. But this time, the inputs are
449 available. 
450
451 \item \textbf{Outputs update} The simulator calls for the value of
452 the outputs. Thus the \computational function should evaluate
453 (\ref{e2}).
454
455 \item \textbf{States update} One or more events have arrived and  the
456 simulator calls the \computational function to update the
457 states $x$ and $z$  according to (\ref{e11}) and
458 (\ref{e12}). 
459
460 \item \textbf{State derivative computation}
461 The simulator is in a continuous phase; the
462 solver requires $\dot{x}$. This means that the \computational function 
463 must evaluate (\ref{e1}).
464
465 \item \textbf{Output events timing} The simulator calls the \computational
466 function  about the timing of its output events. The
467 \computational function should evaluate (\ref{e20}).
468
469 \item \textbf{Ending} The simulator calls
470 the \computational function once at the end (useful for closing files, free allocated 
471 memory, etc...).
472
473 \end{itemize}
474
475 The simulator uses a flag to specify which task should be performed
476 (see Table~\ref{tab2}).
477
478 \begin{table}[ht]
479 \begin{center}
480 \begin{tabular}{|c|l|}
481 \hline
482 Flag & Task \\
483 \hline
484 0 & State derivative computation \\
485 1 & Outputs update \\
486 2 & States update \\
487 3 & Output events timing \\
488 4 & Initialization \\
489 5 & Ending \\
490 6 & Re-initialization \\
491 \hline
492 \end{tabular}
493 \caption{Tasks of \computational function and their corresponding flags}
494 \label{tab2}
495 \end{center}
496 \end{table}
497
498
499
500 \subsubsection{Types of \computational functions}
501 In Scicos, \computational functions can be of different types
502 and co-exist in the same diagram. Currently defined types are
503 listed in Table~\ref{tab1}. The type of the \computational function
504 is stored in the second field of {\tt eqns} (see Section~\ref{eqns}). 
505
506 \begin{table}[ht]
507 \begin{center}
508 \begin{tabular}{|c|c|c|c|l|} \hline
509 Function type& Scilab & Fortran & C & Comments \\ \hline
510 0 & yes & yes & yes & Fixed calling sequence \\
511 1 & no &  yes & yes & Varying calling sequence   \\
512 2 & no &  no  & yes & Fixed calling sequence  \\
513 3 & yes& no  &  no  & Inputs/outputs are Scilab lists\\ \hline
514 \end{tabular}
515 \caption{Different types of the \computational functions. 
516 Type $0$ is obsolete.}
517 \label{tab1}
518 \end{center}
519 \end{table}
520
521 \paragraph{\computational function: type 0}
522 In blocks of type 0, the simulator constructs a unique input vector by
523 stacking up all the input vectors, and expects the outputs, stacked up
524 in a unique vector as well. This type is supported for backward only.
525
526 The calling sequence is identical to that of \computational functions of type 1
527 with one regular input and one regular output.
528
529 \paragraph{\computational function: type 1}
530 The simplest way of illustrating this type is by considering
531 an example:
532 for a block with two regular input vectors and four regular output
533 vectors, the \computational function has the following synopsis.
534
535 \paragraph{Fortran case}
536 \begin{verbatim}
537       subroutine myfun(flag,nevprt,t,xd,x,nx,z,nz,tvec,
538      &   ntvec,rpar,nrpar,ipar,nipar,u1,nu1,u2,nu2,
539      &   y1,ny1,y2,ny2,y3,ny3,y4,ny4)
540 c
541       double precision t,xd(*),x(*),z(*),tvec(*),rpar(*)
542       double precision u1(*),u2(*),y1(*),y2(*),y3(*),y4(*)
543       integer flag,nevprt,nx,nz,ntvec,nrpar,ipar(*)
544       integer nipar,nu1,nu2,ny1,ny2,ny3,ny4
545 \end{verbatim}
546
547
548 See Tables~\ref{tab11} for a description of the arguments.
549 \begin{table}[ht]
550 \begin{center}
551 \begin{tabular}{|c|c|l|} \hline
552 I/O&Args.&Description \\ \hline
553 I&  {\tt flag}& 0,1,2,3,4,5 or 6,  (see Table~\ref{tab2})\\
554 I& {\tt nevprt}& activation code  \\
555 I& {\tt t}& time\\
556 O& {\tt xdot}& derivative of the continuous state \\
557 I/O& {\tt x}& continuous state\\
558 I& {\tt nx}& size of {\tt x}\\
559 I/O& {\tt z}& discrete state\\
560 I& {\tt nz}& size of {\tt z}\\
561 O& {\tt tvec}& times of output events (for {\tt flag}$=$3) \\
562 I& {\tt ntvec}& number of activation output ports\\
563 I& {\tt rpar}& parameter\\
564 I& {\tt nrpar}& size of {\tt rpar}\\
565 I& {\tt ipar}& parameter\\
566 I& {\tt nipar}& size of {\tt ipar}\\
567 I& {\tt ui}& {\tt i}th input (regular), {\tt i}=1,2,\ldots\\
568 I& {\tt nui} & size of {\tt i}th input \\
569 O& {\tt yj}& {\tt j}th output (regular), {\tt j}=1,2,\ldots\\
570 I& {\tt nyj}& size of {\tt j}th output \\ \hline
571 \end{tabular}
572 \caption{Arguments of \computational functions of type 1. I: input, O:
573 output.}
574 \label{tab11}
575 \end{center}
576 \end{table}
577
578 \paragraph{C case}
579 Type 1 \computational functions can also be written in C language,
580 the same way. Note that, arguments must be passed as pointers.
581
582
583 The best way to learn how to write these functions is to examine the
584 routines in the Scilab directory 
585 {\tt SCIDIR/routines/scicos} where \computational functions of all Scicos blocks are available.
586 Most of them are fortran type~0 and~1.
587
588 \paragraph{\computational function type 2}
589 This \computational function type is specific to programming in C. The
590 synopsis is:
591
592 \begin{verbatim}
593 #include "<SCIDIR>/routines/machine.h"
594 void selector(flag,nevprt,t,xd,x,nx,z,nz,tvec,ntvec,
595    rpar,nrpar,ipar,nipar,inptr,insz,nin,outptr,outsz,nout)
596
597 integer *flag,*nevprt,*nx,*nz,*ntvec,*nrpar;
598 integer ipar[],*nipar,insz[],*nin,outsz[],*nout;
599
600 double x[],xd[],z[],tvec[],rpar[];
601 double *inptr[],*outptr[],*t;
602 \end{verbatim}
603
604 See Table~\ref{tab20} for a description of arguments.
605 \begin{table}[ht]
606 \begin{center}
607 \begin{tabular}{|c|c|l|} \hline
608 I/O&Args.&description \\ \hline
609 I& {\tt  *flag}& 0,1,2,3,4,5 or 6,  (see Table~\ref{tab2})\\
610 I& {\tt  *nevprt}& activation code \\
611 I& {\tt  *t}& time\\
612 O& {\tt  xd}& derivative of the continuous
613        state ({\tt flag}$=0$) \\
614 I/O& {\tt  x}& continuous state\\
615 I& {\tt  *nx}& size of {\tt x}\\
616 I/O& {\tt  z}& discrete state\\
617 I& {\tt  *nz}& size of {\tt z}\\
618 O& {\tt  tvec} & times of output events ({\tt flag}$=$3)\\
619 I& {\tt  *ntvec}& number of activation output ports\\
620 I& {\tt  rpar}& parameter\\
621 I& {\tt  *nrpar}& size of {\tt rpar}\\
622 I& {\tt  ipar}& parameter\\
623 I& {\tt  *nipar}& size of {\tt ipar}\\
624 I& {\tt  inptr}& {\tt inptr[i]} is  pointer to
625          beginning of  {\tt i}th  input\\
626 I& {\tt  insz}& {\tt insz[i]} is the size of the
627         {\tt i}th   input \\
628 I& {\tt  *nin}& number of  input ports\\
629 I& {\tt  outptr}& {\tt outptr[j]} is pointer to 
630        beginning of {\tt j}th  output \\
631 I& {\tt  outsz}& {\tt outsz[j]} is the size of the
632           {\tt j}th   output \\
633 I& {\tt  *nout}& number of  output ports \\ \hline
634 \end{tabular}
635 \caption{Arguments of \computational functions of type 2. I: input, O: output.}
636 \label{tab20}
637 \end{center}
638 \end{table}
639
640
641 \paragraph{\computational function type 3}
642 This \computational function type is specific to programming in
643 Scilab. The calling sequence is as follow:
644 \begin{verbatim}
645 [y,x,z,tvec,xd]=test(flag,nevprt,t,x,z,rpar,ipar,u)
646 \end{verbatim}  
647 See table~\ref{tab30} for a description of arguments.
648 \begin{table}[ht]
649 \begin{center}
650 \begin{tabular}{|c|c|l|} \hline
651 I/O&Args.&description \\ \hline
652 I &  {\tt flag} & 0,1,2,3,4,5 or 6  (see Table~\ref{tab2}) \\
653 I &  {\tt nevprt} & activation code (scalar)\\
654 I &  {\tt t} & time (scalar)\\
655 I &  {\tt x} & continuous state (vector)\\
656 I &  {\tt z} & discrete state (vector)\\
657 I &  {\tt rpar}  &parameter (any type of scilabtt variable)\\
658 I &  {\tt ipar} & parameter (vector)\\
659 I &  {\tt u} & {\tt u(i)} is the vector of {\tt i} th regular input (list) \\
660 O &  {\tt y}& {\tt y(j)} is the vector of {\tt j} th regular output (list)\\
661 O &  {\tt x} & new x if {\tt flag}$=$2, 4, 5 or 6 \\
662 O &  {\tt z} & new z if {\tt flag}$=$2, 4, 5 or 6 \\
663 O &  {\tt xd} & derivative of x if {\tt flag}$=0$ (vector), [ ] otherwise\\
664 O &  {\tt tvec} & times of output events if {\tt flag}$=$3 (vector), [ ] otherwise \\ \hline
665 \end{tabular}
666 \caption{Arguments of \computational functions of type 3. I: input, O: output.}
667 \label{tab30}
668 \end{center}
669 \end{table}
670  
671
672
673 \paragraph{Example}
674 The following is the \computational function associated with a block
675 that displays in a Scilab window, every time it receives an event, the
676 number of events it has received up to the current time, and the values
677 of its two inputs.
678 \begin{verbatim}
679 function [y,x,z,tvec,xd]=test(flag,nevprt,t,x,z,rpar,ipar,u)
680 y=list();tvec=[];xd=[]
681 if flag==4 then
682     z=0
683 elseif flag==2 then
684     z=z+1
685     write(%io(2),'Number of calls:'+string(z))
686     [u1,u2]=u(1:2)
687     write(%io(2),'first input');disp(u1)
688     write(%io(2),'second input');disp(u2)
689 end
690 \end{verbatim}
691
692 \paragraph{Example}
693 The advantage of coding inputs and outputs as lists is that
694 the number of inputs and outputs need not be specified
695 explicitly. In this example, the output is the element-wise
696 product of all the input vectors, regardless of the number
697 of inputs.
698
699 \begin{verbatim}
700 function [y,x,z,tvec,xd]=elemprod(flag,nevprt,t,x,z,rpar,ipar,u)
701 tvec=[];xd=[]
702 y=u(1)
703 for i=2:length(u)
704    y=y.*u(i)
705 end
706 y=list(y)
707 \end{verbatim}
708
709 \section{Conclusion}
710 This document gives only a brief description of Scicos and its
711 usage. More information can be found in the manual pages of Scicos
712 functions (Scilab help under Scicos library). Scicos demos provided with
713 Scilab constitute also an interesting source of information. Often,
714 it is advantageous to start off from and edit a Scicos demo rather than
715 starting with an empty diagram.
716
717 \newpage 
718
719 \tableofcontents
720
721 \end{document}