new
[scilab.git] / scilab_doc / intro / chap1.tex
1 % Copyright INRIA
2
3 \chapter{Introduction}
4
5 \section{What is Scilab}
6
7 Developed at INRIA and ENPC, Scilab has been developed for engineering 
8 applications. It is freely distributed (see the copyright file) and the source
9 code is available.
10
11 Scilab is made of three distinct parts: an interpreter, 
12 a set of libraries of Fortran and C routines linked with Scilab
13 and a number of toolboxes written in Scilab language.
14 The numerical librairies (which, strictly speaking, do not belong to Scilab but
15 are interactively called by the interpreter) are of 
16 independent interest and most of them are available through the Web. 
17  
18 A key feature of the Scilab syntax is its ability to handle matrices: 
19 basic matrix manipulations such as concatenation, 
20 extraction or transpose are immediately performed as well as basic operations
21 such as addition or multiplication. The syntax for manipulating
22 matrices is mostly compatible with Matlab. 
23 Scilab also aims at handling more complex
24 objects than numerical matrices. This is
25 done in Scilab by manipulating structures which allows a 
26 natural symbolic representation of complicated
27 objects such as transfer functions, linear systems or graphs
28 (see Section~\ref{s2.5}).
29
30  Mathematical objects such as polynomials, polynomials matrices 
31 and rational polynomial matrices are also defined and the syntax 
32 used for manipulating these matrices is identical to that used for 
33 manipulating numerical vectors and matrices.
34
35         Scilab provides a variety of powerful primitives for
36 the analysis of non-linear systems.  
37 Integration of explicit and implicit dynamic systems can be accomplished 
38 numerically.  The {\tt scicos} toolbox allows the graphic definition
39 and simulation of complex interconnected hybrid systems. Documentation
40 about {\tt scicos} can be found at its the Web page 
41 \href{http://www.scicos.org}{scicos.org}.
42
43  There exist numerical optimization facilities for non linear 
44 optimization (including non differentiable optimization), quadratic 
45 optimization and linear optimization (see also the contribution 
46 directory on the Scilab Web page).
47
48   Scilab has an open programming environment where the
49 creation of functions and libraries of functions is completely in the
50 hands of the user (see Chapter~\ref{ch4}).    
51 Functions are recognized as data objects in Scilab and, thus, can be 
52 manipulated or created as other data objects.  For example, functions
53 can be defined inside Scilab and passed as input or output 
54 arguments of other functions.
55
56 In addition Scilab supports a character string data type 
57 which, in particular, allows the on-line creation of functions.
58 Matrices of character strings are also manipulated with the same
59 syntax as ordinary matrices.
60
61         Finally, Scilab is easily interfaced with Fortran or C 
62 subprograms.  This allows use of standardized 
63 packages and libraries in the interpreted environment of Scilab.
64
65         The general philosophy of Scilab is to provide the following
66 sort of computing environment:
67 \begin{itemize}
68    \item To have data types which are varied and flexible with 
69 a syntax which is natural and easy to use.
70    \item To provide a reasonable set of primitives which serve
71            as a basis for a wide variety of calculations.
72    \item To have an open programming environment where new
73            primitives are easily added. 
74    \item To support library development through ``toolboxes'' of
75          functions devoted to specific
76            applications (linear control, signal processing, 
77            network analysis, non-linear control, etc.)
78 \end{itemize}
79
80         The objective of this introduction manual is to give the user 
81 an idea of what Scilab can do. On line documentation about all
82 functions is available ({\tt help} command).
83
84
85 \section{Software Organization}
86
87 Scilab is divided into a set of directories. The main directory
88 \verb!SCIDIR! contains the following files: {\tt scilab.star} (startup file), the
89 copyright file {\tt notice.tex}, and the \verb!configure! files
90 (see(\ref{install})).
91 The main subdirectories are the following:
92 \begin{itemize}
93
94 \item{{\tt bin} is the directory of the executable files.
95 The starting script {\tt scilab} on Unix/Linux systems and {\tt runscilab.exe} on Windows.
96 The executable code of Scilab: {\tt scilex} on Unix/Linux systems and {\tt scilex.exe} on 
97 Windows are there. 
98 This directory also contains Shell scripts 
99 for managing or printing Postscript/\LaTeX\  files produced by Scilab.}
100
101 \item{{\tt demos} is the directory of demos. 
102 This directory contains the codes corresponding
103 to various demos. They are often useful for inspiring new users.
104 The file 
105 {\tt alldems.dem} is used by the  ``Demos'' button. 
106 Most of plot commands are illustrated by simple demo examples. 
107 Note that running a graphic function without input parameter
108 provides an example of use for this function (for instance {\tt
109 plot2d()} displays an example for using {\tt plot2d}  function). }
110
111 \item{{\tt examples} contains examples of specific topics. It is shown
112 in appropriate subdirectories how to add new C or Fortran program
113 to Scilab (see \verb!addinter-tutorial!). More complex examples are given
114 in \verb!addinter-examples!. The directory \verb!mex-examples!
115 contains examples of interfaces realized by emulating the Matlab
116 mexfiles. The directory \verb!link-examples! illustrates the use of
117 the \verb!call! function which allows to call external function within
118 Scilab.}
119
120 \item{{\tt macros} contains the libraries of functions
121 which are available on-line. New libraries can easily be added 
122 (see the Makefile). This directory is divided into a number of subdirectories
123 which contain ``Toolboxes'' for control, signal processing, etc... Strictly
124 speaking Scilab is not organized in toolboxes : functions of a specific
125 subdirectory can call functions of other directories; so, for example, the 
126 subdirectory {\tt signal} is not self-contained but all the functions there 
127 are devoted to signal processing.}
128
129 \item{{\tt man} is the directory containing the manual divided 
130 into submanuals, corresponding to the on-line help.}
131
132 To get information about an item, one should enter 
133 {\tt help item}\index{help@{\tt help}} 
134 in Scilab or use the help window facility obtained with help button.
135 To get information corresponding to a key-word, one should  enter 
136 {\tt apropos key-word} or use 
137 {\tt apropos}\index{apropos@{\tt apropos}} in the help window. 
138 All the {\tt item}s and {\tt key-words} known by the {\tt help} and 
139 {\tt apropos} commands are in {\tt .html} and {\tt whatis} files 
140 located in the {\tt man} subdirectories.
141
142 To add new items to the {\verb!help!} and {\tt apropos} commands 
143 the user can extend the list of directories available to the help 
144 browser by adapting the variable \verb!%helps!. 
145
146 \item{{\tt routines} is a directory which contains the source code of all
147 the numerical routines. The subdirectory {\tt default} is important
148 since it contains the
149 source code of routines which are necessary to customize Scilab.
150 In particular user's C or Fortran routines for ODE/DAE simulation 
151 or optimization can be included here (they can be also dynamically
152 linked)}
153
154 \item{{\tt tests} : this directory contains evaluation programs for testing 
155 Scilab's installation on a machine. The file ``demos.tst'' tests all the 
156 demos.}
157
158 \item{{\tt intersci} contains a program which can be used to build
159 interface programs for adding new Fortran or C 
160 primitives to Scilab. This program is executed by the {\tt intersci}
161 script in the {\tt bin/intersci} directory.}
162
163 \end{itemize}
164
165 \section{Installing Scilab. System Requirements}
166 \label{install}
167 Scilab is distributed in source code format; binaries for Windows98/NT/XP
168 systems and several popular Unix/Linux-XWindow systems are also
169 available. See the Scilab Web page and the contributions for specific
170 ports. All of these binaries versions include tk/tcl interface.
171
172 The installation requirements are the following :
173
174 - for the source version: Scilab requires approximately 130Mb of disk
175 storage to unpack and install (all sources included).  You a C 
176 compiler and a Fortran compiler.
177   
178 - for the binary version: the minimum for running Scilab (without
179 sources) is about 40 Mb when decompressed.
180
181 \label{stks}
182 Scilab uses a large internal stack for its calculations. This size
183 of this stack can be reduced or enlarged by the 
184 {\tt stacksize}\index{stacksize@{\tt stacksize}}.
185 command. The default dimension of the internal stack can be adapted
186 by modifying the variable {\tt newstacksize} in the {\tt scilab.star}
187 script.
188
189 - For more information on the installation, please look at the README files.
190
191 \section{Documentation}
192
193 The documentation is made of this User's guide (Introduction to
194 Scilab) and the Scilab on-line manual. There are also
195 reports devoted to specific toolboxes: Scicos (graphic system builder
196 and simulator), Signal (Signal processing toolbox), Lmitool (interface for 
197 LMI problems), Metanet (graph and network toolbox). An FAQ is
198 available at Scilab home page:\\
199 (\verb!http://www.scilab.org!)\index{home page}.
200
201 Several documents are available in French, German, Spanish, Chinese etc. 
202 See the Scilab Web page.
203
204 \section{Scilab at a Glance. A Tutorial}
205
206 \subsection{Getting Started}
207
208 After starting Scilab, you get:
209
210 \bigskip
211
212 \begin{verbatim}
213                            ===========
214                            S c i l a b
215                            ===========
216  
217  
218                           Scilab-x.y.z
219                   Copyright (C) 1989-xx INRIA/ENPC 
220  
221  
222 Startup execution:
223   loading initial environment
224    
225  -->
226
227 \end{verbatim}
228
229
230 A first contact with Scilab can be made by clicking 
231 on {\tt Demos} with the left mouse button and clicking then on 
232 {\tt Introduction to SCILAB }: the 
233 execution of the session is then done by entering empty lines and can be
234 stopped with the buttons {\tt Stop} and {\tt Abort}.
235
236   Several libraries
237 (see the {\tt SCIDIR/scilab.star} file) are automatically loaded.
238         
239 To give the user an idea of some of the capabilities of Scilab
240 we will give later a sample session in Scilab.\\
241
242 \subsection{Editing a command line}
243
244 Before the sample session, we briefly present how to edit a command line.
245 You can enter a command line by typing after the prompt or clicking with the 
246 mouse on a part on a window and copy it at the prompt in the Scilab
247 window. 
248 The pointer may be moved using the directionnal arrows
249 ($\leftarrow^\uparrow_\downarrow \rightarrow$). For Emacs customers,
250 the usual Emacs commands are at your 
251 disposal for modifying a command (Ctrl-$<$chr$>$  means hold the CONTROL key 
252 while typing the character $<$chr$>$), for example:
253
254 \bigskip
255
256
257 %
258 \begin{itemize}
259 \item Ctrl-p    recall previous line
260 \item Ctrl-n    recall next line
261 \item Ctrl-b    move backward one character
262 \item Ctrl-f    move forward one character
263 \item Delete    delete previous character
264 \item Ctrl-h    delete previous character
265 \item Ctrl-d    delete one character (at cursor)
266 \item Ctrl-a    move to beginning of line
267 \item Ctrl-e    move to end of line
268 \item Ctrl-k    delete to the end of the line
269 \item Ctrl-u    cancel current line
270 \item Ctrl-y    yank the text previously deleted
271 \item !{\tt prev}     recall the last command line which begins by {\tt prev}
272 \item Ctrl-c    interrupt Scilab and pause after carriage return. 
273 Clicking on the Control/stop button enters a Ctrl-c.
274 \end{itemize}
275 %
276
277 As said before you can also cut and paste using the mouse. This way will be
278 useful if you type your commands in an editor. Another way to 
279 ``load'' files containing Scilab statements
280 is available with the {\tt File/File Operations} button.
281
282 \subsection{Sample Session for Beginners}
283
284 We present now some simple commands. At the carriage return all the 
285 commands typed since the last prompt are interpreted. 
286
287 \noindent\dotfill
288
289 \input{diary/d1p1.dia}
290
291 Give the values of 1 and 2 to the variables {\tt a} and { \tt A} .  The 
292 semi-colon at the end of the command suppresses the display of the result.
293 Note that Scilab is case-sensitive.
294 Then two commands are processed and the second result is displayed because
295 it is not followed by a semi-colon. The last command shows how to write a
296 command on several lines by using ``{\tt ...}''. This sign is only needed
297 in the on-line typing for avoiding the effect of the carriage return.
298  The chain of characters which follow the {\tt //} is not interpreted 
299 (it is a comment line).
300
301 \noindent\dotfill
302
303 \input{diary/d1p2.dia}
304
305 We get the list of previously defined variables {\tt a b c A}  together
306 with the initial environment composed of the different libraries and
307 some specific ``permanent'' variables.
308
309 Below is an example of an expression which mixes constants with existing
310 variables.  The result is retained in the standard default variable 
311 {\tt ans}\index{ans@{\tt ans}}.
312
313 \noindent\dotfill
314
315 \input{diary/d1p2bis.dia}
316
317 Defining {\tt I}, a vector of indices, {\tt W} a random 2 x 4 matrix,
318 and extracting submatrices from {\tt W}. The \verb!$! symbol stands
319 for the last row or last column index of a matrix or vector. The colon
320 symbol stands for ``all rows'' or ``all columns''.
321
322 \noindent\dotfill
323
324 \input{diary/d1p3.dia}
325
326 Calling a function (or primitive) with a vector argument.  The response
327 is a complex vector.
328
329 \noindent\dotfill
330
331 \input{diary/d1p4.dia}
332
333 A  more complicated command which creates a polynomial. 
334
335 \noindent\dotfill
336
337 \input{diary/d1p41.dia}
338
339 Definition of a structure variable. 
340
341 \noindent\dotfill
342
343 \input{diary/d1p5.dia}
344
345 Definition of a polynomial matrix. The syntax for polynomial matrices
346 is the same as for numerical matrices. Calculation of the
347 determinant of the polynomial matrix by the {\tt det} function. 
348
349
350 \noindent\dotfill
351
352 \input{diary/d1p6.dia}
353
354 Definition of a matrix of rational polynomials. (The internal representation
355 of {\tt F} is a typed list of the form {\tt tlist('the type',num,den)}
356 where {\tt num} and {\tt den} are two matrix polynomials). Retrieving
357 the numerator and denominator matrices of {\tt F} by extraction operations in a
358 typed list. Last command is the direct extraction of entry {\tt 1,2} 
359 of the numerator matrix {\tt F.num}.
360
361 \noindent\dotfill
362
363 \input{diary/d1p7.dia}
364
365
366 Here we move into a new environment using the command 
367 {\tt pause}\index{pause@{\tt pause}}
368 and we obtain the new prompt {\tt -1->} which indicates the level
369 of the new environment (level 1).  All variables that are available
370 in the first environment are also available in the new environment.  Variables
371 created in the new environment can be returned to the original environment
372 by using {\tt return}\index{return@{\tt return}}.  
373 Use of {\tt return} without an argument 
374 destroys all the variables created in the new environment before returning
375 to the old environment. The {\tt pause} facility is very useful 
376 for debugging purposes.
377
378 \noindent\dotfill
379
380 \input{diary/d1p8.dia}
381
382 Definition of a rational polynomial by extraction of an entry
383 of the matrix {\tt F} defined above.  This is followed by the evaluation
384 of the rational polynomial at the vector of complex frequency values defined
385 by {\tt frequencies}.  The evaluation of the rational polynomial is done by
386 the primitive {\tt freq}. {\tt F12.num} is the numerator
387 polynomial and {\tt F12.den} is the denominator polynomial of the
388 rational polynomial {\tt F12}. Note that
389 the polynomial {\tt F12.num} can be also obtained by extraction
390 from the matrix {\tt F} using the syntax {\tt F.num(1,2)}.
391 The  visualization of the resulting evaluation
392 is made by using the basic plot command {\tt plot2d} (see Figure~\ref{f1.1}).
393
394 \noindent\dotfill
395
396 \input{diary/d1p9.dia}
397
398 The function {\tt horner} performs a (possibly symbolic) change of 
399 variables for a polynomial (for example, here, to
400 perform the bilinear transformation f(w(s))).
401
402 \noindent\dotfill
403
404 \input{diary/d1p10.dia}
405
406 Definition of a linear system in state-space representation.
407 The function {\tt syslin} defines here the continuous time ({\tt 'c'}) system
408 {\tt Sl} with state-space matrices ({\tt A,B,C}). The function
409 {\tt ss2tf} transforms {\tt Sl} into transfer matrix representation.
410
411 \noindent\dotfill
412
413 \input{diary/d1p11.dia}
414
415 Definition of the rational matrix {\tt R}. {\tt Sl} is the
416 continuous-time linear system with (improper) transfer matrix
417 {\tt R}. {\tt tf2ss} puts {\tt Sl} in state-space representation with a
418 polynomial {\tt D} matrix. Note that linear systems are represented
419 by specific typed lists (with 7 entries).
420
421 \noindent\dotfill
422
423 \input{diary/d1p12.dia}
424
425 {\tt sl1} is the linear system in transfer matrix representation
426 obtained by the parallel inter-connection of {\tt Sl} and {\tt 2*Sl +eye()}.
427 The same syntax is valid with {\tt Sl} in state-space representation.
428
429 \noindent\dotfill
430
431 \input{diary/d1p13.dia}
432
433 On-line definition of a function, called {\tt compen} which calculates the 
434 state space representation
435 ({\tt Cl}) of a linear system ({\tt Sl}) controlled by an observer
436 with gain {\tt Ko}
437 and a controller with gain {\tt Kr}.  Note that matrices are constructed
438 in block form using other matrices.
439
440 \noindent\dotfill
441
442 \input{diary/d1p14.dia}
443
444 Call to the function {\tt compen} defined above where the gains were
445 calculated by a call to the primitive {\tt ppol} which performs pole
446 placement.
447 The resulting {\tt Aclosed} matrix is displayed and the placement
448 of its poles is checked using the primitive {\tt spec} which calculates
449 the eigenvalues of a matrix. (The function {\tt compen} is defined here
450 on-line by  as an example of function which receive a linear system 
451 ({\tt Sl}) as input and returns a linear system ({\tt Cl}) as output.
452 In general Scilab functions are defined in files and loaded in Scilab
453 by {\tt exec} or by {\tt getf} ).
454
455 \noindent\dotfill
456
457 \input{diary/d1p15.dia}
458
459 Relation with the host environment.
460
461 \noindent\dotfill
462
463 \input{diary/d1p16.dia}
464
465 Definition of a column vector of character strings used for defining a C
466 function file. The routine is compiled (needs a compiler), 
467 and a shared library is done. The libary is dynamically 
468 linked to Scilab by the {\tt link} command, and interactively called
469 by the function {\tt myplus}. {\tt myplus} passes variables from Scilab
470 to C and conversely.
471
472 \noindent\dotfill
473
474 \input{diary/d1p17.dia}
475
476 Definition of a function which calculates a first order vector differential
477 {\tt f(t,y)}.  This is followed by the definition of the constant {\tt a}
478 used in the function.  The primitive {\tt ode}
479 then integrates the differential equation defined by the Scilab
480 function {\tt f(t,y)}
481 for {\tt y0=[1;0]} at {\tt t=0} and where the solution is given
482 at the time values $t=0,.02,.04,\ldots,20$. (Function {\tt f} can
483 be defined as a C or Fortran program). The result is plotted in
484 Figure~\ref{f1.2} where the first element of the integrated vector is 
485 plotted against the second element of this vector.
486
487 \noindent\dotfill
488
489 \input{diary/d1p18.dia}
490
491 Definition of a matrix containing character strings. By default, the 
492 operation of symbolic multiplication of two matrices of character
493 strings is not defined in Scilab.  However, the (on-line)
494 function definition for {\tt \%cmc} defines the multiplication of 
495 matrices of character strings.
496 The {\tt \%} which begins the function definition for {\tt \%cmc}
497 allows the definition of an operation which did not previously 
498 exist in Scilab, and the name {\tt cmc} means ``chain multiply chain''.
499 This example is not very useful: it is simply given to show
500 how {\em operations} such as \verb!*! can be defined on complex data 
501 structures by mean of scpecific Scilab functions.
502
503 \noindent\dotfill
504
505 \input{diary/d1p19.dia}
506
507 A simple example which illustrates the passing of a function as an argument
508 to another function. Scilab functions are objects which may be defined, loaded,
509 or manipulated as other objects such as matrices or lists.
510
511 \noindent\dotfill
512
513 \begin{verbatim}
514 -->quit
515 \end{verbatim}
516
517 Exit from Scilab.
518
519 \noindent\dotfill
520
521 \input{figures/d1-7.tex}
522 \caption{\label{f1.1}A Simple Response}
523 \end{figure}
524
525 \input{figures/d1-14.tex}
526 \caption{\label{f1.2}Phase Plot}
527 \end{figure}
528