new
[scilab.git] / scilab_doc / intro / chap4.tex
1 \chapter{Basic Primitives}
2 \label{ch5}
3 This chapter briefly describes some basic primitives of Scilab.
4 More detailed information is given in the ``manual'' document.
5
6 \section{The Environment and Input/Output}
7         In this chapter we describe the most important aspects
8 of the environment of Scilab: how to automatically
9 perform certain operations when entering Scilab,
10 and how to read and write data
11 from and to the Scilab environment.
12
13 \subsection{The Environment}
14 \label{s5.1}
15 \index{environment}
16
17  Scilab is loaded with a number of variables and primitives.
18 The command {\tt who}\index{who@{\tt who}} lists the variables 
19 which are available. {\tt whos()}\index{whos@{\tt whos}} lists the variables 
20 which are available in a more detailled fashion.  
21
22 The {\tt who} command also indicates how many elements and variables
23 are available for use.  The user can obtain on-line help on any of 
24 the functions listed by typing {\tt help <function-name>}\index{help@{\tt help}}.
25
26 Variables can be saved in an external binary
27 file using {\tt save}\index{save@{\tt save}}.  
28 Similarly, variables previously saved can be
29 reloaded into Scilab using {\tt load}\index{load@{\tt load}}.
30
31 Note that after the command {\tt clear x y}\index{clear@{\tt clear}} 
32  the variables {\tt x} and
33 {\tt y} no longer exist in the environment.  
34 The command {\tt save} without any variable arguments saves the entire 
35 Scilab environment.  Similarly,
36 the command {\tt clear} used
37 without any arguments clears all of the variables, functions, and libraries
38 in the environment.
39
40 Libraries of functions are loaded
41 using {\tt lib}\index{lib@{\tt lib}}\index{libraries}.  
42
43 The list of functions available in the library can be obtained by using {\tt disp}.
44
45 \subsection{Startup Commands by the User}
46 \label{s5.2}
47 \index{startup by user}
48 \index{startup@{\tt startup}}
49
50         When Scilab is called the user can automatically load
51 into the environment functions, libraries, variables, and perform
52 commands using the the file {\tt .scilab} in his home directory.  
53 This is particularly useful when the user wants to run Scilab programs
54 in the background (such as in batch mode).  Another useful aspect
55 of the {\tt .scilab} file is when some functions or libraries
56 are often used.  In this case the commands {\tt getf} {\tt exec} or
57 {\tt load} can be used
58 in the {\tt .scilab} file to automatically load the desired 
59 functions and libraries whenever Scilab is invoked.
60
61 \subsection{Input and Output}
62 \label{s5.3}
63 \index{input}
64 \index{output}
65
66         Although the commands {\tt save} and {\tt load} are
67 convenient, one has much more control over the transfer of
68 data between files and Scilab by using the Fortran like functions 
69 {\tt read}\index{read@{\tt read}}
70 and {\tt write}\index{write@{\tt write}}.  
71 These two functions work similarly to the
72 read and write commands found in Fortran.  The syntax of these
73 two commands is as follows.  
74 \begin{verbatim}
75  
76 --> x=[1 2 %pi;%e 3 4]
77  x         =
78  
79 !   1.           2.    3.1415927 !
80 !   2.7182818    3.    4.        !
81  
82 --> write('x.dat',x)
83  
84 --> clear x
85  
86 --> xnew=read('x.dat',2,3)
87  xnew      =
88  
89 !   1.           2.    3.1415927 !
90 !   2.7182818    3.    4.        !
91 \end{verbatim}
92 Notice that {\tt read} specifies the number of rows and columns
93 of the matrix {\tt x}. Complicated formats can be specified. 
94
95 The C like function {\tt mfscanf} \index{mfscanf@{\tt mfscanf}} and {\tt
96 mfprintf}\index{mfprintf@{\tt mfprintf}}  can be also used
97 \begin{verbatim}
98  
99 --> x=[1 2 %pi;%e 3 4]
100  x         =
101  
102 !   1.           2.    3.1415927 !
103 !   2.7182818    3.    4.        !
104  
105 --> fd=mopen('x_c.dat','w')
106
107 --> mfprintf(fd,'%f %f %f\n',x)
108
109 --> mclose(fd)
110  
111 --> clear x
112  
113 --> fd=mopen('x_c.dat','r')
114
115 --> xnew(1,1:3)=mfscanf(fd,'%f %f %f\n') ;
116
117 --> xnew(2,1:3)=mfscanf(fd,'%f %f %f\n')
118
119  xnew  =
120  
121 !   1.          2.    3.141593 !
122 !   2.718282    3.    4.       !
123 --> mclose(fd)
124 \end{verbatim}
125
126 Here is a table of useful input-output functions:
127
128 \begin{center}
129 \begin{tabular}{|c|c|}
130 \hline
131 \verb!mprintf! & print in standard output\\ \hline
132
133 \verb!mfprintf! & print in a file\\ \hline
134
135 \verb!msprintf! & print in a string matrix \\ \hline
136
137 \verb!mscanf! & read in standard input \\ \hline
138
139 \verb!mfscanf! & read in a file \\ \hline
140
141 \verb!msscanf! & read in a string matrix \\ \hline
142
143 \verb!fprintfMat! & formated write a matrix into a file  \\ \hline
144
145 \verb!fscanfMat! & formated read of a matrix in a file \\ \hline
146
147 \verb!mgetl! & read a file as a Scilab string matrix  \\ \hline
148
149 \verb!mputl! & write a string matrix \\ \hline
150
151 \verb!mopen! & open a file \\ \hline
152
153 \verb!mclose! & close a file\\ \hline
154 \end{tabular}
155 \end{center}
156
157 To manipulate binary files, the following functions are available:
158 \begin{center}
159 \begin{tabular}{|c|c|}
160 \hline
161 \verb!mget! & read binary data\\ \hline
162
163 \verb!mput! & write binary data\\ \hline
164
165 \verb!mgetstr! & print in a string matrix \\ \hline
166
167 \verb!mputstr! & write a string matrix \\ \hline
168
169 \verb!mgetstr! & read in a file \\ \hline
170
171 \verb!mtell! & current position in a file\\ \hline
172
173 \verb!mseek! & move current position  \\ \hline
174
175 \verb!meof! & end of file test \\ \hline
176 \end{tabular}
177 \end{center}
178
179 \section{Help}
180 On-line help is available either by clicking on the 
181 {\tt help}\index{help@{\tt help}}
182 button or by entering {\tt help item} (where {\tt item} is usually the 
183 name of a function or primitive). {\tt apropos
184 keyword}\index{apropos@{\tt apropos}} looks 
185 for {\tt keyword} in a {\tt whatis} file. 
186
187  To add a new item or keyword is easy.
188 Just create a {\tt .cat} ASCII file describing the item and a 
189 {\tt whatis}\index{whatis@{\tt whatis}} file in your directory. 
190 Then add your directory path
191 (and a title) in the variable \verb!%helps! (see also the README file
192 there). You can use the standard format of the scilab manual\index{manual}
193 (see the {\tt SCIDIR/man/subdirectories} 
194 and {\tt SCIDIR/examples/man-examples}).
195 The Scilab \LaTeX\   manual is automatically obtained from the
196 manual items by a {\tt Makefile}. 
197 See the directory {\tt SCIDIR/man/Latex-doc}. 
198
199 \section{Useful functions}
200
201 We give here a short list of useful functions and keywords that can be used
202 as entry points in the Scilab manual. All the functions available 
203 can be obtained by entering {\tt help}. For each manual entry the
204 {\tt SEE ALSO} line refers to related functions.
205
206 \begin{itemize}
207 \item{Elementary functions: {\tt sum, prod, sqrt, diag, cos, max, round, sign, fft}}
208 \item{Sorting: {\tt sort, gsort, find}}
209 \item{Specific Matrices: {\tt zeros, eye, ones, matrix}}
210 \item{Linear Algebra: {\tt det, inv, qr, svd, bdiag, spec, schur}}
211 \item{Polynomials}: {\tt poly, roots, coeff, horner, clean, freq}
212 \item{Buttons, dialog: \verb!x_choose, x_dialog, x_mdialog, getvalue, addmenu!}
213 \item{GUI (Tcl-tk): \verb!TK_EvalStr, TK_GetVar, TK_SetVar, TK_EvalFile!}
214 \item{Linear systems: {\tt syslin}}
215 \item{Random numbers: {\tt rand}, {\tt grand}}
216 \item{Programming: {\tt function, deff, argn, for, if, end, while, 
217 select, warning, error, break, return}}
218 \item{Comparison symbols: {\tt ==}, {\tt >=}, {\tt >}, {\tt ~=}, {\verb!&!}
219 ({\tt and}),{\tt |} ({\tt or})}
220 \item{Execution of a file: {\tt exec}}
221 \item{Debugging: {\tt pause, return, abort}}
222 \item{Spline functions, interpolation: {\tt splin2d, interp2d, smooth, splin3d}}
223 \item{Character strings: {\tt string, part, evstr, execstr, grep}}
224 \item{Graphics: {\tt plot2d, set, get, xgrid, locate, plot3d, Graphics}}
225 \item{Ode solvers: {\tt ode, dassl, dassrt, odedc}}
226 \item{Optimization: {\tt optim, quapro, linpro, lmitool, lsqrsolve}}
227 \item{Interconnected dynamic systems: {\tt scicos}}
228 \item{Adding a C or Fortran routine: {\verb!link, call, addinter, ilib_for_link, ilib_build!}}
229 \item{Graphs, networks: {\verb! edit_graph, metanet!}}
230 \end{itemize}
231
232
233 \section{Nonlinear Calculation}
234 \label{ch6}
235 \index{non-linear calculation}
236
237         Scilab has several powerful non-linear primitives for simulation
238 or optimization.
239 \index{simulation}
240 \index{optimization}
241 \subsection{Nonlinear Primitives}
242 Scilab provides several facilities for nonlinear calculations.
243
244 Numerical simulation of systems of differential equations is
245 made by the {\tt ode} primitive. Many solvers are available,
246 mostly from {\tt odepack}, for solving stiff or non-stiff systems.
247 Implicit systems can be solved by {\tt dassl}. It is also
248 possible to solve systems with stopping time: integration
249 is performed until the state is crossing a given surface.
250 See {\tt ode} and {\tt dassrt} commands. There is a number
251 of optional arguments available for solving ode's (tolerance
252 parameters, jacobian, order of approximation, time steps etc).
253 For {\t ode} solvers, these parameters are set by the global 
254 variable {\tt \%ODEOPTIONS}.
255
256 Minimizing non linear functions is done the {\tt optim} function. 
257 Several algorithms (including non differentiable optimization)
258 are available. Codes are from INRIA's {\tt modulopt} library.
259 Enter {\tt help optim} for more a more detailed description.
260
261 \subsection{Argument functions}
262 \label{refexternals}
263 \index{external}
264 \index{argument function}
265 Specific Scilab functions or C or Fortran routines can be used as an argument
266 of some high-level primitives (such as {\tt ode}, {\tt optim}, {\tt dassl}...).
267 These fonctions are called argument functions or externals.
268 The calling sequence of this function or routine is imposed by
269 the high-level primitive which sets the argument of this function or
270 routine.
271
272 For example the function {\tt costfunc} is an argument of 
273 the {\tt optim} primitive. Its calling sequence must be: 
274 {\tt [f,g,ind]=costfunc(x,ind)} as imposed by the {\tt optim} primitive.
275 The following non-linear primitives in Scilab need argument functions
276 or subroutines: 
277 {\tt ode}, {\tt optim}, {\tt impl}, {\tt dassl}, {\tt intg}, 
278 {\tt odedc}, {\tt fsolve}.
279 For problems where computation time is important, it is recommended
280 to use C or Fortran subroutines. Examples of such
281 subroutines are given in the directory {\tt SCIDIR/routines/default}.
282 See the README file there for more details.
283
284 When such a subroutine is written it must be linked to Scilab.
285 This link operation can be done dynamically by the {\tt link}
286 command. It is also possible to introduce the code in a more 
287 permanent manner by inserting it in a specific interface in 
288 {\tt SCIDIR/routines/default} and rebuild a new Scilab by a 
289 {\tt make all} command in the Scilab directory.
290
291 \section{XWindow Dialog}
292 It may be convenient to open a specific XWindow window for entering
293 interactively parameters inside a function or for a demo.
294 This facility is possible thanks to e.g. the functions \verb!x_dialog!,
295 \verb!x_choose!, \verb!x_mdialog!, \verb!x_matrix! and \verb!x_message!.
296 The demos which can be executed by clicking on the {\tt demo} button
297 provide simple examples of the use of these functions.
298
299 \section{Tk-Tcl Dialog}
300 An interface between Scilab and Tk-Tcl exists. 
301 A Graphic User Interface object can be created by the function
302 \verb!uicontrol!. Basic primitives are \verb!TK_EvalFile!,
303 \verb!TK_EvalStr! and \verb! TK_GetVar, TK_Setvar!. Examples
304 are given by invoking the help of these functions.
305
306 Let us give a simple dialog. We pass a script to TK as a Scilab
307 string matrix, TK opens a dialog box, and the result is returned
308 to Scilab as a string, using \verb!TK_GetVar!.
309 \begin{verbatim}
310 -->TK_script=["toplevel .dialog";
311               "label .dialog.1 -text ""Enter your input\n here""";
312               "pack .dialog.1";
313               "entry .dialog.e -textvariable scivar";
314               "set scivar """"";
315               "pack .dialog.e"];
316 -->TK_EvalStr(TK_script);
317 -->text=TK_GetVar(scivar);
318 \end{verbatim}
319