new
[scilab.git] / scilab_doc / intro / chap3.tex
1 % Copyright INRIA
2
3 \chapter{Programming}
4 \label{ch4}
5 \index{programming}
6
7         One of the most useful features of Scilab is its ability
8 to create and use functions.  This allows the development of specialized
9 programs which can be integrated into the Scilab package in a simple and
10 modular way through, for example, the use of libraries.  In this chapter we 
11 treat the following subjects:
12 \begin{itemize}
13         \item Programming Tools
14         \item Defining and Using Functions
15         \item Definition of Operators for New Data Types
16         \item{Debbuging}
17 \end{itemize}   
18 Creation of libraries is discussed in a later chapter.
19
20 \section{Programming Tools}
21
22         Scilab supports a full list of programming tools
23 including loops, conditionals, case selection,
24 and creation of new environments.  Most programming tasks
25 should be accomplished in the environment of a function.
26 Here we explain what programming tools are available.
27
28 \subsection{Comparison Operators}\index{programming!comparison operators}
29 There exist five methods for making comparisons between the
30 values of data objects in Scilab. These comparisons are listed
31 in the following table.
32
33 \begin{center}
34 \begin{tabular}{|c|c|}
35 \hline
36 {\tt == }  & equal to \\ \hline
37 {\tt < } & smaller than \\ \hline
38 {\tt > } &  greater than \\ \hline
39 {\tt <= } & smaller or equal to \\ \hline
40 {\tt >= } & greater or equal to \\ \hline
41 {\tt <> } or {\verb!~=!} & not equal to \\ \hline
42 \end{tabular}
43 \end{center}
44
45 These comparison operators are used for evaluation of conditionals.
46
47 \subsection{Loops}\index{programming!loops}
48 Two types of loops exist in Scilab: the 
49 {\tt for}\index{for@{\tt for}} loop
50 and the 
51 {\tt while}\index{while@{\tt while}} loop.  The {\tt for} loop
52 steps through a vector of indices performing each time the
53 commands delimited by {\tt end}.  
54 \begin{verbatim}
55  
56 --> x=1;for k=1:4,x=x*k,end
57  x         =
58  
59     1.  
60  x         =
61  
62     2.  
63  x         =
64  
65     6.  
66  x         =
67  
68     24.  
69 \end{verbatim}
70 The {\tt for} loop can iterate on any vector or matrix taking for values
71 the elements of the vector or the columns of the matrix.
72 \begin{verbatim}
73  
74 --> x=1;for k=[-1 3 0],x=x+k,end
75  x         =
76  
77     0.  
78  x         =
79  
80     3.  
81  x         =
82  
83     3.  
84 \end{verbatim}
85 The {\tt for} loop can also iterate on lists. The syntax is the same as for
86 matrices. The index takes as values the entries of the list.
87
88 \begin{verbatim}
89 -->l=list(1,[1,2;3,4],'str')
90
91 -->for k=l, disp(k),end
92  
93     1.  
94  
95 !   1.    2. !
96 !   3.    4. !
97  
98  str
99 \end{verbatim}
100
101         The {\tt while} loop repeatedly performs a sequence of commands 
102 until a condition is satisfied.
103 \begin{verbatim}
104 --> x=1; while x<14,x=2*x,end
105  x         =
106  
107     2.  
108  x         =
109  
110     4.  
111  x         =
112  
113     8.  
114  x         =
115  
116     16.  
117
118 \end{verbatim}
119
120  A {\tt for} or {\tt while} loop can be ended by the command {\tt break} :
121 \begin{verbatim}
122
123 -->a=0;for i=1:5:100,a=a+1;if i > 10  then  break,end; end
124  
125 -->a
126  a  =
127  
128     3.  
129
130 \end{verbatim}
131 In nested loops, {\tt break} exits from the innermost loop.
132
133 \begin{verbatim}
134 -->for k=1:3; for j=1:4; if k+j>4 then break;else disp(k);end;end;end
135  
136     1.  
137  
138     1.  
139  
140     1.  
141  
142     2.  
143  
144     2.  
145  
146     3. 
147 \end{verbatim}
148 \subsection{Conditionals}\index{programming!conditionals}
149 Two types of conditionals exist in Scilab: the 
150 {\tt if}-{\tt then}-{\tt else}\index{if-then-else@{\tt if-then-else}}
151 conditional and the 
152 {\tt select}-{\tt case}\index{select-case@{\tt select}-{\tt case}} 
153 conditional.  The 
154 {\tt if}-{\tt then}-{\tt else} conditional
155 evaluates an expression and if true executes the
156 instructions between the {\tt then} statement and the {\tt else} statement
157 (or {\tt end} statement).
158 If false the statements between the {\tt else} and the {\tt end}
159 statement are executed.  The {\tt else} is not required. The {\tt elseif}
160 has the usual meaning and is a also a keyword recognized by the interpreter.
161 \begin{verbatim}
162  
163 --> x=1
164  x         =
165  
166     1.  
167  
168 --> if x>0 then,y=-x,else,y=x,end
169  y         =
170  
171   - 1.  
172  
173 --> x=-1
174  x         =
175  
176   - 1.  
177  
178 --> if x>0 then,y=-x,else,y=x,end
179  y         =
180  
181   - 1.  
182 \end{verbatim}
183
184
185         The {\tt select}-{\tt case} conditional
186 compares an expression to several possible expressions and performs the
187 instructions following the first case which equals the initial expression.
188 \begin{verbatim}
189  
190 --> x=-1
191  x         =
192  
193   - 1.  
194  
195 --> select x,case 1,y=x+5,case -1,y=sqrt(x),end
196  y         =
197  
198     i    
199 \end{verbatim}
200 It is possible to include an {\tt else} statement for the condition
201 where none of the cases are satisfied.
202
203 \section{Defining and Using Functions}
204 \label{s4.2}
205 \index{programming!functions}
206 \index{functions}
207 \index{functions!definition}
208
209         It is possible to define a function directly in
210 the Scilab environment, however, the most convenient way
211 is to create a file containing the function
212 with a text editor.  In this section we describe the
213 structure of a function and several Scilab commands which are
214 used almost exclusively in a function environment.
215
216 \subsection{Function Structure}
217 Function structure must obey the following format
218 \begin{verbatim}
219 function [y1,...,yn]=foo(x1,...,xm)
220    .
221    .
222    .
223 \end{verbatim}
224 where {\tt foo} is the function name, the {\tt xi} are the $m$ input arguments
225 of the function,  the {\tt yj} are the $n$ output arguments from the function, and
226 the three vertical dots represent the list of instructions performed by
227 the function.  An example of a function
228 which calculates $k!$ is as follows\index{functions!{\tt exec}}\index{exec@{\tt exec}}
229 \begin{verbatim}
230 function [x]=fact(k)
231   k=int(k)
232   if k<1 then k=1,end
233   x=1;
234   for j=1:k,x=x*j;end
235 endfunction
236 \end{verbatim}
237 If this function is contained in a file called {\tt fact.sci} the function
238 must be ``loaded'' into  Scilab by the {\tt exec} or {\tt getf} command and before
239 it can be used:
240 \begin{verbatim}
241 --> exists('fact')
242  ans       =
243  
244     0.  
245  
246 --> exec('../macros/fact.sci',-1);
247  
248 --> exists('fact')
249  ans       =
250  
251     1.  
252  
253 --> x=fact(5)
254  x         =
255  
256     120.  
257 \end{verbatim}
258 In the above Scilab session, the command 
259 {\tt exists}\index{functions!{\tt exists}}\index{exists@{\tt exists}} 
260 indicates that
261 {\tt fact} is not in the environment (by the $0$ answer to {\tt exist}).  The
262 function is loaded into the environment using {\tt exec} and now {\tt exists}
263 indicates that the function is there (the $1$ answer).  The example 
264 calculates $5!$. 
265
266 \subsection{Loading Functions}
267 Functions are usually defined in files. A file which contains a function
268 must obey the following format
269 \begin{verbatim}
270 function [y1,...,yn]=foo(x1,...,xm)
271    .
272    .
273    .
274 \end{verbatim}
275 where {\tt foo} is the function name. The {\tt xi}'s  are the input 
276 parameters and the the {\tt yj}'s  are the  output parameters, and
277 the three vertical dots represent the set of instructions performed by
278 the function to evaluate the {\tt yj}'s, given the {\tt xi}'s.
279 Inputs and ouputs parameters can be {\it any} Scilab object
280 (including functions themeselves).
281
282 Functions are Scilab objects and should not be considered as files. To
283 be used in Scilab, functions defined in files  {\em must} be loaded by 
284 the command {\tt getf(filename)} or {\tt exec(filename,-1) ;}  . If the file {\tt filename} contains the
285 function {\tt foo}, the function {\tt foo} can be executed only if
286 it has been previously loaded by the command {\tt getf(filename)}.
287 A file may contain {\em several} functions. Functions can also be defined ``on line''
288 by the command using the {\tt function/endfunction} syntax or by using
289 the function {\tt deff}. This is useful if one wants to define
290 a function as the output parameter of a other function. 
291
292 Collections of functions can be organized as libraries (see {\tt lib}
293 command). Standard Scilab librairies (linear algebra, control,\ldots) 
294 are defined in the subdirectories of {\tt SCIDIR/macros/}.
295
296 \subsection{Global and Local Variables}
297 If a variable in a function is not defined (and is not among the input
298 parameters) then it takes the value of a variable having the same name in the
299 calling environment. This variable however remains local in the sense that
300 modifying it within the function does not alter the variable in the calling
301 environment unless {\tt resume} is used (see below). Functions
302 can be invoked with less input or output parameters. Here is an example:
303 \begin{verbatim}
304 function [y1,y2]=f(x1,x2)
305   y1=x1+x2
306   y2=x1-x2
307 endfunction
308 \end{verbatim}
309 \begin{verbatim}
310 -->[y1,y2]=f(1,1)
311  y2  =
312     0.  
313  y1  =
314     2.  
315
316 -->f(1,1)
317  ans  =
318     2.
319
320 -->f(1)
321 y1=x1+x2;
322         !--error     4 
323 undefined variable : x2                      
324 at line       2 of function f
325
326 -->x2=1;
327
328 -->[y1,y2]=f(1)
329  y2  =
330     0.  
331  y1  =
332     2.  
333  
334 -->f(1)
335  ans  =
336  
337     2. 
338
339 \end{verbatim}
340
341 Note that it is not possible to call a function if one of the
342 parameter of the calling sequence is not defined:
343
344 \begin{verbatim}
345 function [y]=f(x1,x2)
346   if x1<0 then y=x1, else y=x2;end
347 endfunction
348 \end{verbatim}
349 \begin{verbatim}
350
351 -->f(-1)
352  ans  =
353  
354   - 1.  
355  
356 -->f(-1,x2)
357        !--error     4 
358 undefined variable : x2  
359
360 -->f(1)
361  undefined variable : x2                      
362 at line       2 of function    f     called by :  
363 f(1)
364
365 -->x2=3;f(1)
366
367 -->f(1)
368  ans  =
369  
370     3
371                     
372 \end{verbatim}
373
374 Global variable are defined by the \verb!global! command. They can
375 be read and modified inside functions. Enter {\tt help global} for
376 details. 
377
378 \subsection{Special Function Commands}
379 Scilab has several special commands which are used almost exclusively
380 in functions.  These are the commands 
381
382 \begin{itemize}
383         \item {\tt argn}\index{argn@{\tt argn}}: returns the number of input
384 and output arguments for the function
385         \item {\tt error}\index{error@{\tt error}}: used to suspend the 
386 operation of a function, to print an error message, and to return to the
387 previous level of environment when an error is detected.  
388         \item {\tt warning}\index{warning@{\tt warning}}, 
389         \item {\tt pause}\index{pause@{\tt pause}}: temporarily suspends the 
390 operation of a function.
391         \item {\tt break}\index{break@{\tt break}}: forces the end of a loop 
392         \item {\tt return}\index{return@{\tt return}} or {\tt resume} : used 
393 to return to the calling environment and to pass local
394 variables from the function environment to the calling environment.  
395 \end{itemize}
396
397 The following example runs the following {\tt foo} function which
398 illustrates these commands.
399 \begin{itemize}
400 \item The function definition
401 \begin{verbatim}
402 function [z]=foo(x,y)
403 [out,in]=argn(0);
404 if x==0 then,
405      error('division by zero');
406 end,
407 slope=y/x;
408 pause,
409 z=sqrt(slope);
410 s=resume(slope);
411 endfunction
412 \end{verbatim}
413 \item The function use
414 \begin{verbatim} 
415 --> z=foo(0,1)
416 error('division by zero');
417                           !--error 10000 
418 division by zero                                                                
419 at line       4 of function    foo      called by :  
420  z=foo(0,1)
421  
422  
423 --> z=foo(2,1)
424  
425 -1-> resume
426  z         =
427  
428     0.7071068  
429  
430 --> s
431  s         =
432  
433     0.5  
434  
435 \end{verbatim}
436 \end{itemize}
437
438 In the example, the first call to {\tt foo} passes an argument which cannot
439 be used in the calculation of the function.  The function discontinues
440 operation and indicates the nature of the error to the user.  The second call
441 to the function suspends operation after the calculation of {\tt slope}.
442 Here the user can examine values calculated inside of the function,
443 perform plots, and, in fact perform any operations 
444 allowed in Scilab.  The {\tt -1->} prompt indicates that the current
445 environment created by the {\tt pause} command is the environment 
446 of the function and not that of the calling environment.  Control is 
447 returned to the function by the command {\tt return}.  Operation of the
448 function can be stopped by the command {\tt quit} or {\tt abort}.
449 Finally the function terminates its calculation returning the
450 value of {\tt z}.  Also available in the environment is the variable
451 {\tt s} which is a local variable from the function which is passed to
452 the global environment.
453
454 \section{Definition of Operations on New Data Types}
455 \label{s4.3}
456 \index{operations!for new data types}
457
458         It is possible to transparently define fundamental operations 
459 for new data types in Scilab (enter {\tt help overloading} for 
460 a full description of this feature).
461 That is, the user can give a sense to multiplication, division, addition, etc.
462 on any two data types which exist in Scilab.  As an example, two linear
463 systems (represented by lists)
464 can be added together to represent their parallel inter-connection
465 or can be multiplied together to represent their series inter-connection.
466 Scilab performs these user defined operations by searching for functions
467 (written by the user) which follow a special naming convention described
468 below.
469
470         The naming convention Scilab uses to recognize operators 
471 defined by the user is determined by the following conventions.  The name
472 of the user defined function is composed of four (or possibly three)
473 fields.  The first field is always the symbol {\tt \%}.  
474 The third field is one of the characters in the following table
475 which represents the type of operation to be performed between the
476 two data types.
477
478 \begin{center}
479 \begin{tabular}{|c|c|}
480 \hline 
481 \multicolumn{2}{|c|}{Third field}
482 \\ \hline \hline
483 SYMBOL & OPERATION 
484 \\ \hline \hline
485 \verb!a! & \verb!+!  \\ \hline
486
487 \verb!b! & \verb!:!  (range generator)\\ \hline
488
489 \verb!c! & \verb![a,b]! column concatenation  \\ \hline
490
491 \verb!d! & \verb!./!  \\ \hline
492
493 \verb!e! & \verb!()! extraction: \verb!m=a(k)!  \\ \hline
494
495 \verb!f! & \verb![a;b]! row concatenation  \\ \hline
496
497 \verb!g! & \verb!|! logical or  \\ \hline
498
499 \verb!h! & \verb!&! logical and  \\ \hline
500
501 \verb!i! & \verb!()! insertion:  \verb!a(k)=m!  \\ \hline
502
503 \verb!j! & \verb!.^! element wise exponent  \\ \hline
504
505 \verb!k! & \verb!.*.!  \\ \hline
506
507 \verb!l! & \verb!\!  left division \\ \hline
508
509 \verb!m! & \verb!*!  \\ \hline
510
511 \verb!n! & \verb!<>! inequality comparison \\ \hline
512
513 \verb!o! & \verb!==! equality comparison \\ \hline
514
515 \verb!p! & \verb!^!  exponent \\ \hline
516
517 \verb!q! & \verb!.\!  \\ \hline
518
519 \verb!r! & \verb!/!  right division \\ \hline
520
521 \verb!s! & \verb!-!  \\ \hline
522
523 \verb!t! & \verb!'!  (transpose) \\ \hline
524
525 \verb!u! & \verb!*.!  \\ \hline
526
527 \verb!v! & \verb!/.!  \\ \hline
528
529 \verb!w! & \verb!\.!  \\ \hline
530
531 \verb!x! & \verb!.*!  \\ \hline
532
533 \verb!y! & \verb!./.!  \\ \hline
534
535 \verb!z! & \verb!.\.!  \\ \hline
536
537 \verb!0! & \verb!.'!  \\ \hline
538
539 \verb!1! & \verb!<!  \\ \hline
540
541 \verb!2! & \verb!>!  \\ \hline
542
543 \verb!3! & \verb!<=!  \\ \hline
544
545 \verb!4! & \verb!>=!  \\ \hline
546
547 \verb!5! & \verb!~!  (not)\\ \hline
548
549 \end{tabular}
550 \end{center}
551
552 The second
553 and fourth fields represent the type of the first and second data objects,
554 respectively, 
555 to be treated by the function and are represented by the symbols given
556 in the following table.
557
558 \begin{center}
559 \begin{tabular}{|c|c|}
560 \hline  
561 \multicolumn{2}{|c|}{Second and Fourth fields}
562 \\ \hline \hline
563 SYMBOL & VARIABLE TYPE
564 \\ \hline \hline
565
566 \verb!s! & scalar  \\ \hline
567
568 \verb!p! & polynomial \\ \hline
569
570 \verb!l! & list (untyped)  \\ \hline
571
572 \verb!c! & character string   \\ \hline
573
574 \verb!b! & boolean   \\ \hline
575
576 \verb!sp! & sparse  \\ \hline
577
578 \verb!spb! & boolean sparse   \\ \hline
579
580 \verb!m! & function \\ \hline
581
582 \verb!xxx! & list (typed)  \\ \hline 
583 \end{tabular}
584 \end{center}
585
586 A typed list is one in which the first
587 entry of the list is a character string where the first
588 characters of the string are represented by the 
589 {\tt xxx} in the above table.  For example a typed list
590 representing a linear system has the form: \\
591
592 {\tt tlist(['lss','A','B','C','D','X0','dt'],a,b,c,d,x0,'c')}.\\
593  and, thus, the {\tt xxx}
594 above is {\tt lss}.
595
596         An example of the function name which multiplies two
597 linear systems together (to represent their series inter-connection)
598 is {\tt \%lss\_m\_lss}.  Here the first field is \%, the second field is 
599 {\tt lss} (linear state-space), the third field is {\tt m} ``multiply''
600 and the fourth one is {\tt lss}. A possible user function which performs
601 this multiplication is as follows
602 \begin{verbatim}
603 function [s]=%lss_m_lss(s1,s2)
604 [A1,B1,C1,D1,x1,dom1]=s1(2:7),
605 [A2,B2,C2,D2,x2]=s2(2:6),
606 B1C2=B1*C2,
607 s=lsslist([A1,B1C2;0*B1C2' ,A2],...
608        [B1*D2;B2],[C1,D1*C2],D1*D2,[x1;x2],dom1),
609 endfunction
610 \end{verbatim}
611 An example of the use of this function after having loaded it into
612 Scilab (using for example {\tt getf} or inserting it in a library) 
613 is illustrated in the following Scilab session
614 \begin{verbatim}
615  
616 -->A1=[1 2;3 4];B1=[1;1];C1=[0 1;1 0];
617  
618 -->A2=[1 -1;0 1];B2=[1 0;2 1];C2=[1 1];D2=[1,1];
619  
620 -->s1=syslin('c',A1,B1,C1);
621  
622 -->s2=syslin('c',A2,B2,C2,D2);
623  
624 -->ssprint(s1)
625  
626 .   | 1  2 |    | 1 |    
627 x = | 3  4 |x + | 1 |u   
628  
629     | 0  1 |    
630 y = | 1  0 |x   
631  
632 -->ssprint(s2)
633  
634 .   | 1 -1 |    | 1  0 |    
635 x = | 0  1 |x + | 2  1 |u   
636  
637 y = | 1  1 |x + | 1  1 |u   
638  
639 -->s12=s1*s2;   //This is equivalent to s12=%lss_m_lss(s1,s2)
640  
641 -->ssprint(s12)
642  
643     | 1  2  1  1 |    | 1  1 |    
644 .   | 3  4  1  1 |    | 1  1 |    
645 x = | 0  0  1 -1 |x + | 1  0 |u   
646     | 0  0  0  1 |    | 2  1 |    
647  
648     | 0  1  0  0 |    
649 y = | 1  0  0  0 |x   
650 \end{verbatim}
651 Notice that the use of {\tt \%lss\_m\_lss} is totally transparent in
652 that the multiplication of the two lists {\tt s1} and {\tt s2}
653 is performed using the usual multiplication operator {\tt *}.
654
655 The directory {\tt SCIDIR/macros/percent} contains all the functions
656 (a very large number...) which perform operations on linear systems
657 and transfer matrices. Conversions are automatically performed.
658 For example the code for the function {\tt \%lss\_m\_lss} is there (note
659 that it is much more complicated that the code given here!).
660 \section{Debbuging}
661 The simplest way to debug a Scilab function is to introduce
662 a {\tt pause} command in the function.
663 When executed the function stops at this point and prompts {\tt -1->} which 
664 indicates a different ``level''; another {\tt pause} gives {\tt -2->} ...
665 At the level 1 the Scilab commands are analog to a different session but
666 the user can display all the current variables present in Scilab,
667 which are inside or outside the function i.e. local in the function
668 or belonging to the calling environment. The execution of the function
669 is resumed by the command {\tt return} or {\tt resume} (the variables used
670 at the upper level are cleaned).
671 The execution of the function can be interrupted by {\tt abort}.
672 %and the current loop is terminated by {\tt break}.
673
674 It is also possible to insert breakpoints in functions. See the commands
675 {\tt setbpt}, {\tt delbpt}, {\tt disbpt}.
676 Finally, note that it is also possible to trap errors during the 
677 execution of a function: 
678 see the commands {\tt errclear} and {\tt errcatch}.
679 Finally the experts in  Scilab  can use the 
680 function {\tt debug(i)} where i=0,..,4 denotes a debugging level.