Scilab

Reference
Manual
On-line Documentation

Scilab Group
SCILAB
REFERENCE
MANUAL

Scilab Group
INRIA Meta2 Project/ENPC Cergrene

INRIA - Unite de recherche de Rocquencourt - Projet Meta2

Domaine de Voluceau - Rocquencourt - BP 105 - 78153 Le Chesnay Cedex (France)
Email: [email protected]
Chapter 1

Programming

5
argn Scilab Function
1.0.1 addinter new functions interface incremental linking at run
time
CALLING SEQUENCE :
addinter(files,spname,fcts)

PARAMETERS :
files : a character string or a vector of character string contain object les used to dene the
new Scilab interface routine (interface code, user routines or libraries, system libraries).
spname : a character string. Name of interface routine entry point
fcts : vector of character strings. The name of new Scilab function inplemented in the new
interface (in fin the order ).
DESCRIPTION :
addinter performs incremental linking of a compiled C or Fortran new Scilab interface routine
(see intersci documentation) and dene corresponding scilab functions.
See link for more precision on use.
See Also : link, intersci, newfun, clearfun
1.0.2 and logical and
CALLING SEQUENCE :
[b]=and(A)

DESCRIPTION :
and(A) is the logical AND of elements of the boolean matrix A. and(A) returns %T ("true") i
all entries of A are %T.
See Also : & | ~
1.0.3 ans answer
DESCRIPTION :
ans means "answer". Variable ans is created automatically when expressions are not assigned.
ans contains the last unassigned evaluated expression.

1.0.4 apropos searches keywords in Scilab help

CALLING SEQUENCE :
apropos word
apropos 'string'

DESCRIPTION :
Looks for keywords in Unix whatis les.
EXAMPLE :
apropos '+'
apropos ode
apropos 'list of'

See Also : help , directory man/.. , makewhatis script files.

Scilab Group April 1993 6

brackets Scilab Function
1.0.5 argn number of arguments in a function call
CALLING SEQUENCE :
[lhs [,rhs] ]=argn(0)

DESCRIPTION :
This function is used inside a function denition. It gives the number of actual inputs rhs and
output lhs parameters passed to the function when the function is called. It is usually used in
function denitions to deal with optional arguments.
See Also : function
1.0.6 n left matrix division backslash
CALLING SEQUENCE :
x=A\\b

DESCRIPTION :
Backslash denotes left matrix division. x=Anb is a solution to A*x=b.
If A is nonsingular x=Anb (uniquely dened) is equivalent to x=inv(A)*b.
If A is singular, x is a least square solution. i.e. norm(A*x-b) is minimal. If A is full column
rank, the least square solution, x=Anb, is uniquely dened (there is a unique x which minimizes
norm(A*x-b)). If A is not full column rank, then the least square solution is not unique, and x=Anb,
in general, is not the solution with minimum norm (the minimum norm solution is x=pinv(A)*b).
A.nB is the matrix with (i,j) entry A(i,j)nB(i,j). If A (or B) is a scalar A.nB is equivalent to
A*ones(B).nB (or A.n(B*ones(A))
EXAMPLE :
A=rand(3,2);b=[1;1;1]; x=A\\b; y=pinv(A)*b; x-y
A=rand(2,3);b=[1;1]; x=A\\b; y=pinv(A)*b; x-y, A*x-b, A*y-b
A=rand(3,1)*rand(1,2); b=[1;1;1]; x=A\\b; y=pinv(A)*b; A*x-b, A*y-b
A=rand(2,1)*rand(1,3); b=[1;1]; x=A\\b; y=pinv(A)*b; A*x-b, A*y-b

See Also : slash , inv , pinv , percent

1.0.7 Scilab object: boolean boolean variables and operators & ~ j

DESCRIPTION :
A boolean variable is %T (for "true") or %F (for "false"). These variables can be used to dene
matrices of booleans, with the usual syntax. Boolean matrices are manipulated as ordinary matrices
with usual operations and usual meaning (+, *, -, etc)
~b : is the negation of boolean b (matrix).
b1&b2 : is the logical and of b1 and b2 (matrices).
b1jb2 : is the logical or of b1 and b2 (matrices).
Boolean variables can be used for indexing matrices or vectors. For instance a([%T,%F,%T],:)
returns the submatrix made of rows 1 and 3 of a.
EXAMPLE :
[1,2]==[1,3]
[1,2]==1
a=1:5; a(a>2)

See Also : matrices , | , & , ~, or , and.

Scilab Group April 1993 7

ceil Scilab Function
1.0.8 [,] left and right brackets
CALLING SEQUENCE :
[a11,a12,...;a21,a22,...;...]
[s1,s2,...]=func(...)

PARAMETERS :
a11,a12,... : any matrix (real, polynomial, rational,syslin list ...) with appropriate dimen-
sions
s1,s2,... : any possible variable name
DESCRIPTION :
Left and right brackets are used to note vector and matrix concatenation. These symbols are also
used to denote a multiple left-hand-side for a function call
Inside concatenation brackets, blank or comma characters mean "column concatenation", semicol-
umn and carriage-return mean "row concatenation".
Note : to avoid confusions it is safer to use commas instead of blank to separate columns.
Within multiple lhs brackets variable names must be separated by comma.
EXAMPLES :
[6.9,9.64; sqrt(-1) 0]
[1 +%i 2 -%i 3]
[]
['this is';'a string';'vector']
s=poly(0,'s');[1/s,2/s]
[tf2ss(1/s),tf2ss(2/s)]

[u,s]=schur(rand(3,3))

See Also : comma , semicolumn

1.0.9 break keyword to interrupt loops

DESCRIPTION :
Inside a for or while loop, the command break forces the end of the loop.
EXAMPLE :
k=0; while 1==1, k=k+1; if k > 100 then break,end; end

See Also : while , ifthenelse , for , abort , return

1.0.10 case keyword used in select

DESCRIPTION :
Keyword used in select ... case Use it in the following way:
select expr0,
case expr1 then instructions1,
case expr2 then instructions2,
...
case exprn then instructionsn,
[else instructions],
end

See Also : select , while , end , for

Scilab Group April 1993 8

coe Scilab Function
1.0.11 ceil rounding up
CALLING SEQUENCE :
[y]=ceil(x)

PARAMETERS :
x : a real matrix
y : integer matrix
DESCRIPTION :
returns an integer matrix made of rounded up elements
ceil(x)
See Also : round, floor, int
1.0.12 clear kills variables
CALLING SEQUENCE :
clear a

DESCRIPTION :
This command kills variables which are not protected. It removes the named variables from the
environment. By itself clear kills all the variables except the variables protected by predef. Thus
the two commands predef(0) and clear remove all the variables.
Normally, protected variables are standard libraries and variables with the percent prex.
Note the particular syntax clear a and not clear(a). Note also that a=[] does not kill a but
sets a to an empty matrix.
See Also : predef, who
1.0.13 clearfun remove primitive.
CALLING SEQUENCE :
clearfun('name')

DESCRIPTION :
clearfun('name') removes the primitive 'name' from the set of primitives (built-in func-
tions) . This function allows to rename a primitive : a Scilab primitive can be replaced by a
user-dened function. For experts...
See Also : newfun, funptr
1.0.14 code2str returns character string associated with Scilab
integer codes.
CALLING SEQUENCE :
str=code2str(c)

PARAMETERS :
str : a character string
c : vector of character integer codes
DESCRIPTION :
Returns character string associated with Scilab integer codes.str is such that c(i) is the Scilab
integer code of part(str,i))
EXAMPLE :
code2str([-28 12 18 21 10 11])

See Also : str2code

Scilab Group April 1993 9

comp Scilab Function
1.0.15 coe coecients of matrix polynomial
CALLING SEQUENCE :
[C]=coeff(Mp [,v])

PARAMETERS :
Mp : polynomial matrix
v : integer (row or column) vector of selected degrees
C : big matrix of the coecients
DESCRIPTION :
C=coeff(Mp) returns in a big matrix C the coecients of the polynomial matrix Mp . C is parti-
tioned as C=[C0,C1,...,Ck] where the Ci are arranged in increasing order k = maxi(degree(Mp))
C=coeff(Mp,v) returns the matrix of coecients with degree in v . (v is a row or column vector).
See Also : poly , degree

1.0.16 : colon operator

DESCRIPTION :
: : Colon. Used in subscripts and loops.

j:k is the vector [j, j+1, ..., k] (empty if J>K).

j:d:k is the vector [j, j+d, ..., j+m*d]
The colon notation can also be used to pick out selected rows, columns and elements of vectors
and matrices.
A(:) is the vector of all the elements of A regarded as a single column.
A(:,j) is the j-th column of A
A(j:k) is [A(j),A(j+1),...,A(k)]
A(:,j:k) is [A(:,j),A(:,j+1),...,A(:,k)]
A(:)=w lls the matrix A with entries of w (taken column by column if w is a matrix).

See Also : matrix

1.0.17 , comma
DESCRIPTION :
Commas are used to separate parameters in functions or to separate entries of row vectors.
Blanks can also be used to separate entries in a row vector but use preferably commas.
Also used to separate Scilab instructions. (Use ; to have the result not displayed on the screen).
EXAMPLES :
a=[1,2,3;4,5,6];
a=1,b=1;c=2

1.0.18 comments comments

DESCRIPTION :
Command lines whch begin by // are not interpreted by Scilab.
Comments must not begin with //end !
Scilab Group April 1993 10
delbpt Scilab Function
1.0.19 comp function compilation
CALLING SEQUENCE :
comp(function-name)

DESCRIPTION :
comp(function-name) compiles the function function-name. Compiled and interpreted func-
tions are equivalent but usually compiled functions are much faster. The functions provided in the
standard libraries are compiled. Un-compiled versions exist (entering a library-name returns the
names of the un-compiled corresponding functions)
The command: getf('filename','c') loads the functions in le 'filename' and compiles
them.
REMARKS :
commands who, help, what cannot be compiled.
See Also : deff, getf, whereis, macr2lst, lib

1.0.20 de on-line denition of function

CALLING SEQUENCE :
deff('[s1,s2,...]=newmacro(e1,e2,....)',text)

PARAMETERS :
e1,e2,..., : input variables.
s1,s2,..., : output variables.
text : matrix of character strings
DESCRIPTION :
On-line denition of macro (user dened function): the name of the created function is newmacro.
text is a sequence of instructions usually set as a vector of character strings.
This command can be used inside a function and the new function can be an input or output of
any other function.
Usually, functions are dened in a le and loaded into Scilab by getf
EXAMPLES :
deff('[x]=myplus(y,z)','x=y+z')

deff('[x]=mymacro(y,z)',['instruc11,instruc12'; 'instruc21,x=instruc22'])

See Also : getf , comp, exec , function

1.0.21 degree degree of polynomial matrix

CALLING SEQUENCE :
[D]=degree(M)

PARAMETERS :
M : polynomial matrix
D : integer matrix
DESCRIPTION :
returns the matrix of highest degrees of M.
See Also : poly, coeff, clean

Scilab Group April 1993 11

matrices Scilab Function
1.0.22 delbpt delete breakpoint
CALLING SEQUENCE :
delbpt('macroname' [,linenumb])

DESCRIPTION :
deletes the breakpoint at line linenumb in the function macroname. If linenumb is omitted all
the breakpoints in the function are deleted.
EXAMPLE :
setbpt('foo',1),setbpt('foo',10),delbpt('foo',10),dispbpt()

See Also : setbpt , ,

dispbpt pause , resume

1.0.23 diary diary of session

CALLING SEQUENCE :
diary('file-name')

DESCRIPTION :
diary creates a le which contains a copy of the current Scilab session. diary(0) interrupts the
diary.
See Also : exec , unix

1.0.24 disp displays variables

CALLING SEQUENCE :
disp(x1,[x2,...xn])

DESCRIPTION :
displays xi with the current format. xi's are arbitrary objects (matrices of constants, strings,
functions, lists, ...)
See Also : write, read, print, string
1.0.25 dispbpt display breakpoints
CALLING SEQUENCE :
dispbpt()

DESCRIPTION :
dispbpt() displays all active breakpoints actually inserted in functions.
See Also : setbpt, delbpt, pause, resume
1.0.26 else keyword in if-then-else
DESCRIPTION :
Used with if . See ifthenelse .
1.0.27 elseif keyword in if-then-else
DESCRIPTION :
See if,then,else .
Scilab Group April 1993 12
errcatch Scilab Function
1.0.28 [] empty matrix
DESCRIPTION :
[] denotes the empty matrix. It is uniquely dened and has 0 row and 0 column, i.e. size([])
=[0,0] . The following convenient conventions are made:
[] * A = A * [] = []
[] + A = A + [] = A
[ [], A] = [A, []] = A
inv([]) =[]
det([])=cond([])=rcond([])=1, rank([])=0
Matrix functions return or an error message when there is no obvious answer. Empty linear
[]
systems (
syslin lists) may have several rows or columns.
EXAMPLE :
s=poly(0,'s'); A = [s, s+1];
A+[], A*[]
A=rand(2,2); AA=A([],1), size(AA)
svd([])
w=ssrand(2,2,2); wr=[]*w; size(wr), w1=ss2tf(wr), size(w1)

See Also : matrices , poly , string , boolean , ,

rational syslin.

1.0.29 end end keyword

DESCRIPTION :
Used at end of loops or conditionals. for, while, if, select must be terminated by end .
Comments must not begin by //end .
1.0.30 = equal sign
DESCRIPTION :
Equal sign is used to denote a value aectation to a variable.
== denote equality comparison between two expressions and returns a boolean matrix.
EXAMPLES :
a=sin(3.2)
[u,s]=schur(rand(3,3))
[1:10]==4
1~=2

See Also : less , boolean

1.0.31 errcatch error trapping

CALLING SEQUENCE :
errcatch(n [,'action'] [,'option'])

PARAMETERS :
n : integer
action, option : strings
DESCRIPTION :
errcatch gives an "action" (error-handler) to be performed when an error of type n occurs.
meaning of n :
n>0 is the error number to trap
if n<0 all errors are to be trapped
action is one of the following character strings :

Scilab Group April 1993 13

exec Scilab Function
"pause" : a pause is executed when trapping the error
"continue" : next instruction is executed, current instruction is ignored
"kill" : default mode.
"stop" : interrupts the current Scilab session (useful when Scilab is called from an external
program).
option is the character string 'nomessage' for killing error message.
See Also : errclear
1.0.32 errclear error clearing
CALLING SEQUENCE :
errclear([n])

DESCRIPTION :
clears the action (error-handler) connected to error of type n.
If n is positive, it is the number of the cleared error ; otherwise all errors are cleared (default case)
See Also : errcatch

1.0.33 error error messages

CALLING SEQUENCE :
error('string' [,n])
error(m)

DESCRIPTION :
prints the character string 'string' in an error message and stops the current instruction.
If n is given, it is associated to the number of the error. n should be larger than 10000 (default
value).
error(m) prints the message associated with the error number m.
See Also : warning
1.0.34 evstr evaluation of expressions
CALLING SEQUENCE :
[H]=evstr(Z)

PARAMETERS :
Z : matrix of character strings or list
H : matrix
DESCRIPTION :
returns the evaluation of the matrix of character strings Z.
EXAMPLES :
a=1; b=2; Z=['a','b'] ; evstr(Z)

returns the matrix [1,2]

This function can also be used for a list.
a=1; b=2; Z =list(['%(1)','%(1)-%(2)'],['a+1','b+1']);
evstr(Z)

Scilab Group April 1993 14

external Scilab Function
returns [2,-1]
Here, Z is a list with two elements; the second element of Z is a vector V of character strings;
evstr returns the evaluation of the rst element of Z. In this rst element %(i) stands for the ith
element of V consequently evstr returns [a+1,(a+1)-(b+1)]=[2,-1].
evstr('a=1') is not valid (use execstr ).
See Also : execstr
1.0.35 exec script le execution
CALLING SEQUENCE :
exec('file-name' [,mode])

DESCRIPTION :
executes the content of the le 'file-name' with an optional execution mode mode .
The dierent cases for mode are :
0 : the default value
-1 : nothing is printed
1 : echo of each command line
2 : prompt --> is printed
3 : echoes + prompts
4 : stops before each prompt
7 : stops + prompts + echoes : useful mode for demos.
See Also : getf , comp, mode

1.0.36 exists checks variable existence

CALLING SEQUENCE :
exists('variable-name')

DESCRIPTION :
returns 1 if the variable 'variable-name' exists and 0 otherwise. Caveats: a function which
uses exists may return a result which depends on the environment!
See Also : isdef, whereis, type, typeof, macrovar
1.0.37 exit Scilab quit
DESCRIPTION :
Ends the current Scilab session. Same as quit .
See Also : quit, abort, break, return, resume.

1.0.38 external Scilab Object, external function or routine

DESCRIPTION :
External function or routine for use with specic commands.
An "external" is a function or routine which is used as an argument of some high-level primitives
(such as ode, optim, schur...).
The calling sequence of the external (function or routine) is imposed by the high-level primitive
which sets the arguments of the external.
For example the external function costfunc is an argument of the optim primitive. Its calling se-
quence must be: [f,g,ind]=costfunc(x,ind) and optim (the high-level optimization primitive)
is invoked as follows:
Scilab Group April 1993 15
feval Scilab Function
optim(costfunc,...)

Here costfunc (the cost function to be minimized by the primitive optim) evaluates f=f(x) and
g= gradient of f at x (ind is an integer which is not useful here).
If other values are needed by the external function these variables can be dened in the environment.
Also, they can be put in a list. For example,the external function
[f,g,ind]=costfunc(x,ind,a,b,c)

is valid for optim if the external is list(costfunc,a,b,c) and the call to optim is then:
optim(list(costfunc,a1,b1,c1),....

An external can also be a Fortran routine : this is convenient to speed up the computations.
The name of the routine is given to the high-level primitive as a character string. The calling
sequence of the routine is also imposed. Examples are given in the default directory (see e.g.
routines fydot.f or foptim.f)
External Fortran routines can also be dynamically linked. The calling sequence should be as given
by dyncall (see e.g. source code of fydot.f)
See Also : ode, optim, impl, dassl, intg, schur, gschur
1.0.39 eye identity matrix
CALLING SEQUENCE :
[X]=eye(m,n)
[X]=eye(A)

PARAMETERS :
A,X : matrices or syslin lists
m,n : integers
DESCRIPTION :
according to its arguments denes an mxn matrix with 1 along the main diagonal or an identity
matrix of the same dimension as A .
Caution: eye(10) is interpreted as eye(A) with A=10 i.e. 1. (It is NOT a ten by ten identity
matrix!).
If A is a linear system represented by a syslin list, eye(A) returns an eye matrix of appropriate
dimension: (number of outputs x number of inputs).
EXAMPLES :
eye(2,3)
A=rand(2,3);eye(A)
s=poly(0,'s');A=[s,1;s,s+1];eye(A)
A=[1/s,1;s,2];eye(A);
A=ssrand(2,2,3);eye(A)

See Also : ones , zeros

1.0.40 feval multiple evaluation

CALLING SEQUENCE :
[z]=feval(x,y,f)
[z]=feval(x,f)

PARAMETERS :
Scilab Group April 1993 16
le Scilab Function
x,y : two vectors
f : function or character string (for Fortan call)
DESCRIPTION :
Multiple evaluation of a function for one or two arguments of vector type :
z=feval(x,f) returns the vector z dened by z(i)=f(x(i))
z=feval(x,y,f) returns the matrix z, z(i,j)=f(x(i),y(j))

f is an external (function or routine) depending on one or two arguments which are supposed to
be real. The result returned by f can be real or complex. In case of a Fortran call, the function
'f' must be dened in the subroutine ffeval.f (in directory SCIDIR/routines/default)
EXAMPLE :
deff('[z]=f(x,y)','z=x^2+y^2');
feval(1:10,1:5,f)
deff('[z]=f(x,y)','z=x+%i*y');
feval(1:10,1:5,f)
feval(1:10,1:5,'parab') //See ffeval.f file
feval(1:10,'parab')
// For dynamic link (see example ftest in ffeval.f)
// you can use the link command (the parameters depend on the machine):
// unix('make ftest.o');link('ftest.o','ftest); feval(1:10,1:5,'ftest')

See Also : evstr , horner , execstr , external , link

1.0.41 le le management
CALLING SEQUENCE :
[unit]=file('open', file-name, [status], [access], [format], [recl])

PARAMETERS :
open : string
file-name : string
status : string
access : string
format : string
recl : integer
DESCRIPTION :
selects a logical unit unit and manages the le file-name. 'open' can be replaced by the
parameter 'action' for managing the le (see below).
The status of the le is given by the parameter status :
"new" : new le (default)
"old" : le already exists.
"unknown" : unknown status
"scratch" : le is to be deleted at end of session
The type of access to the le is given by access
"sequential" : sequential access (default)
"direct" : direct access.
The other informations are the format
Scilab Group April 1993 17
 oor Scilab Function
"formatted" : for a formatted le (default)
"unformatted" : binary record.
and recl is the size of records when access="direct"
A particular call is file([action],unit) : it modies the state or the position inside a le with
the following choices :
action is one of the following strings:

"close" : closes the le

"rewind" : puts the pointer at beginning of le
"backspace" : puts the pointer at beginning of last record.
"last" : puts the pointer after last record.

and the logical unit is unit.

See Also : save, load, write, read
1.0.42 nd nd indices of boolean vector or matrix true elements
CALLING SEQUENCE :
[ii]=find(x)
[ir,ic]=find(x)

PARAMETERS :
x : a boolean vector or a boolean matrix
ii, ir, ic : integer vectors of indices or empty matrices
DESCRIPTION :
If is a boolean matrix,
x
ii=find(x) returns the vector of indices i for which x(i) is "true". If no true element found
nd returns an empty matrix.
[ir,ic]=find(x) returns two vectors of indices ir (for rows) and ic (for columns) such that
x(il(n),ic(n)) is "true". If no true element found nd returns empty matrices in ir and ic.
EXAMPLE :
A=rand(1,20);
w=find(A<0.5);
A(w)

returns the vector made of entries of A which are < 0.5

w=find(A>100);

See Also : boolean

1.0.43 x rounding towards zero

CALLING SEQUENCE :
[y]=fix(x)

PARAMETERS :
x : a real matrix
y : integer matrix
DESCRIPTION :
fix(x) returns an integer matrix made of nearest rounded integers toward zero,i.e, y=sign(x).*floor(abs(x)).
Same as int.
See Also : round, floor, ceil
Scilab Group April 1993 18
fort Scilab Function
1.0.44 oor rounding down
CALLING SEQUENCE :
[y]=floor(x)

PARAMETERS :
x : a real matrix
y : integer matrix
DESCRIPTION :
floor(x) returns an integer matrix made of nearest rounded down integers.
See Also : round, fix, ceil
1.0.45 for language keyword for loops
DESCRIPTION :
Used to dene loops. Its syntax is:
for variable=expression ,instruction, ,instruction,end
If expression is a matrix or a row vector, variable takes as values the values of each column of
the matrix.
Useful example : for variable=n1:step:n2, ...,end
If expression is a list variable takes as values the successive entries of the list.
EXAMPLE :
n=5;
for i = 1:n, for j = 1:n, a(i,j) = 1/(i+j-1);end;end
for j = 2:n-1, a(j,j) = j; end; a
for e=eye(3,3),e,end
for v=a, write(6,v),end
for j=1:n,v=a(:,j), write(6,v),end
for l=list(1,2,'example'); l,end

1.0.46 format printing format

CALLING SEQUENCE :
format([type],[long])

PARAMETERS :
type : character string
long : integer ( max number of digits (default 10))
DESCRIPTION :
Sets the current printing format with the parameter type ; it is one of the following :
"v" : for a variable format (default)
"e" : for the e-format.

long denes the max number of digits (default 10). format() returns a vector for the current
format: rst component is the type of format (0 if v ; 1 if e ); second component is the number
of digits.
See Also : write
Scilab Group April 1993 19
fort Scilab Function
1.0.47 fort fortran or C user routines call
CALLING SEQUENCE :
[y1,...,yk]=fort("ident",x1,px1,"tx1",...,xn,pxn,"txn",
"out",[ny1,my1],py1,"ty1",...,[nyl,myl],pyl,"tyl")
[y1,....,yk]=fort("ident",x1,...,xn)

PARAMETERS :
"ident" : string
xi : real matrix
pxi, pyi : integers
txi, tyi : character string "d", "r" or "i"
DESCRIPTION :
Interactive call of Fortran (or C) user routine from Scilab. The routine must be previously linked
with Scilab. This link may be done:
- with Scilab "link" command (incremental "soft" linking) during the Scilab session.(see
link)
- by "hard" re-linking. Writing the routine call within Scilab routine "default/interf.f" and
then re linking all Scilab with the command make bin/scilex in main Scilab directory.
The meaning of each parameter is described now:
"ident" is the name of the subroutine called.
x1,...,xn are input variables sent to the routine,
px1,...,pxn are the respective positions of these variables in the calling sequence of the
routine and
tx1,...,txn are their fortran types ("r","i", "d", for real, integer, double precision)
(strings are treated as integers).
"out" is a keyword used to separate input variables from output variables.
[ny1, my1] are the size (# of rows and columns) of output variables and
py1, ... are the positions of output variables (possibly equal to pxi ).
"ty1", ... are the fortran types of output variables. The k rst output variables are put
in y1,..., yk.
If an output variable coincides with an input variable (i.e. pyi=pxj ) one can pass only its position
pyi . The size and type of yi are the same as those of xi .
In the case of short syntax , [y1,....,yk]=fort("ident",x1,...,xn), the txi, nyj, myj and
tyj are then given in the routine interf (see the source code in the directory SCIDIR/default).
For example the following program:
subroutine foo(a,b,c)
c=2*a+b
end

link("foo.o","foo")
a=13;b=10;
c=fort("foo",a,1,"r",b,2,"r","out",[1,1],3,"r")

returns the scalar (1x1 matrix) c=2*a+b with a=13 and b=10. a (resp. b,c ) is the rst (resp.
2nd, 3rd) argument passed to foo . If your machine is a DEC Alpha, SUN Solaris or SGI you may
have to change the previous command line link("foo.o","foo") by one of the followings:
link('foo.o -lfor -lm -lc','foo').
link('foo.o -lftn -lm -lc','foo').
link('foo.o -L/opt/SUNWspro/SC3.0/lib/lib77 -lm -lc','foo').

Scilab Group April 1993 20

printf Scilab Function
The same example coded in C:
void foo(a,b,c)
double *a,*b,*c
{
*c=2*(*a)+(*b);
}

link("foo.o","foo","c") // note the third argument

a=13;b=10;
c=fort("foo",a,1,"r",b,2,"r","out",[1,1],3,"r")

See Also : link , c_link , interf.f in SCIDIR/routines/default

1.0.48 printf,fprintf,sprintf Emulator of C language printf functions

CALLING SEQUENCE :
printf(format,value_1,..,value_n)
fprintf(file,format,value_1,..,value_n)
str=sprintf(format,value_1,..,value_n)

PARAMETERS :
format : a Scilab string. Species a character string combining literal characters with conversion
specications.
value i : Species the data to be converted according to the format parameter.
str : column vector of character strings
file : a Scilab string specifying a le name or a logical unit number (see file)

DESCRIPTION :
The printf function converts, formats, and writes its value parameters, under control of the
format parameter, to the standard output.
Thefprintf function converts, formats, and writes its value parameters, under control of
theformat parameter, to the le specied by its file parameter.
Thesprintf function converts, formats, and stores its value parameters, under control of the
format parameter.
Theformat parameter is a character string that contains two types of objects:
Literal characters : which are copied to the output stream.
Conversion specifications : each of which causes zero or more items to be fetched from the
value parameter list.

If there are not enough items for format in the value parameter list, sprintf generate an
error. If any values remain after the entire format has been processed, they are ignored.
Conversion Specications
Each conversion specication in the format parameter has the following syntax:
- A % (percent) sign.
- Zero or more options, which modify the meaning of the conversion specication. The following
list contains the option characters and their meanings:
- : Left align, within the eld, the result of the conversion.
+ : Begin the result of a signed conversion with a sign (+ or -).
"space" : Prex a space character to the result if the rst character of a signed conversion
is not a sign. If both the (space) and + options appear, the (space) option is ignored.
Scilab Group May 1994 21
printf Scilab Function
# : Convert the value to an alternate form. For c, d, i, s, and u conversions, the # option
has no eect. For o conversion, # increases the precision to force the rst digit of the
result to be a 0 (zero). For x and X conversions, a nonzero result has 0x or 0X prexed
to it. For e, E, f, g, and G conversions, the result always contains a decimal point,
even if no digits follow it. For g and G conversions, trailing zeros are not removed from
the result.
0 : Pad to the eld width, using leading zeros (following any indication of sign or base)
for d, i, o, u, x, X, e, E, f, g, and G conversions; no space padding is performed. If
the 0 and -- (dash) ags both appear, the 0 ag is ignored. For d, i, o u, x, and X
conversions, if a precision is specied, the 0 ag is also ignored.
An optional decimal digit string that species the minimum eld width. If the converted value
has fewer characters than the eld width, the eld is padded on the left to the length specied by
the eld width. If the left-adjustment option is specied, the eld is padded on the right.
An optional precision. The precision is a . (dot) followed by a decimal digit string. If no
precision is given, the parameter is treated as 0 (zero). The precision species:
-The minimum number of digits to appear for d, u, o, x, or X conversions
-The number of digits to appear after the decimal point for e, E, and f conversions
-The maximum number of signicant digits for g and G conversions
-The maximum number of characters to be printed from a string in an s conversion
- A character that indicates the type of conversion to be applied:
% : Performs no conversion. Displays %.
d,i :Accepts an integer value and converts it to signed decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as a leading character causes the eld width value to be padded
with leading zeros.
u :Accepts an integer value and converts it to unsigned decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros.
o :Accepts an integer value and converts it to unsigned octal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros. An octal value for eld width is not implied.
x, X :Accepts an integer value and converts it to unsigned hexadecimal notation. The
letters \abcdef" are used for the x conversion; the letters \ABCDEF" are used for the
X conversion. The precision species the minimum number of digits to appear. If the
value being converted can be represented in fewer digits, it is expanded with leading
zeros. The default precision is 1. The result of converting a zero value with a precision
of zero is a null string. Specifying a eld width with a zero as the leading character
causes the eld width value to be padded with leading zeros.
f : Accepts a oat or double value and converts it to decimal notation in the format
%[{]ddd.ddd. The number of digits after the decimal point is equal to the precision
specication.
- If no precision is specied, six digits are output.
- If the precision is zero, no decimal point appears and the system outputs a number
rounded to the integer nearest to value.
Scilab Group May 1994 22
scanf Scilab Function
- If a decimal point is output, at least one digit is output before it.
e, E :Accepts a real and converts it to the exponential form %[{]d.ddde+/{dd. There is
one digit before the decimal point, and the number of digits after the decimal point is
equal to the precision specication.
- If no precision is specied, , six digits are output.
- If the precision is zero, , no decimal point appears.
- The E conversion character produces a number with E instead of e before the ex-
ponent. The exponent always contains at least two digits. If the value is zero, the
exponent is zero.
g, G : Accepts a real and converts it in the style of the e, E, or f conversion characters,
with the precision specifying the number of signicant digits. Trailing zeros are removed
from the result. A decimal point appears only if it is followed by a digit. The style
used depends on the value converted. Style e (E, if G is the ag used) results only if
the exponent resulting from the conversion is less than {4, or if it is greater or equal to
the precision.
c :Accepts and displays an integer value converted to a character.
s :Accepts a string value and displays characters from the string to the end or the number
of characters indicated by the precision is reached. If no precision is specied, all
characters up to the end are displayed.
A eld width or precision can be indicated by an * (asterisk) instead of a digit string. In this
case, an integer value parameter supplies the eld width or precision. The value parameter
converted for output is not fetched until the conversion letter is reached, so the parameters
specifying eld width or precision must appear before the value to be converted (if any).
If the result of a conversion is wider than the eld width, the eld is expanded to contain
the converted result.
The representation of the plus sign depends on whether the + or (space) formatting option
is specied.
EXAMPLES :
fahr=120
sprintf('%3d Fahrenheit = %6.1f Celsius',fahr,(5/9)*(fahr-32))

printf('Result is:\nalpha=%f",0.535)

u=file('open','results','unknown') //open the result file

t=0:0.1:2*%pi;
for tk=t
fprintf(u,'time = %6.3f value = %6.3f',tk,sin(tk)) // write a line
end
file('close',u) //close the result file

See Also : ,
string print , write , format , disp , file

1.0.49 scanf, sscanf - Converts formatted input

CALLING SEQUENCE :
[v_1,...v_n]=scanf (format);
[v_1,...v_n]=fscanf (file,format)
[v_1,...v_n]=sscanf (string,format)

PARAMETERS :
format :Species the format conversion.
Scilab Group May 1994 23
functions Scilab Function
file :Species the input le name or le number.
string :Species input to be read.
DESCRIPTION :
The scanf,fscanf, and sscanf functions read character data, interpret it according to a format, and
returns the converted results.
These functions read their input from the following sources:
scanf :Reads from standard input
fscanf :Reads from the le dened by the le parameter.
sscanf :Reads from the character string specied by the string parameter.
The formatparameter contains conversion specications used to interpret the input.
The format parameter can contain white-space characters (blanks, tabs, newline, or formfeed)
that, except in the following two cases, read the input up to the next nonwhite-space character.
Unless there is a match in the control string, trailing white space (including a newline character)
is not read.
- Any character except % (percent sign), which must match the next character of the input
stream.
- A conversion specication that directs the conversion of the next input eld.
CONVERSION SPECIFICATIONS :
Each conversion specication in the format parameter contains the following elements:
+ The character % (percent sign)
+ The optional assignment suppression character *
+ An optional numeric maximum eld width
+ A conversion code

The conversion specication has the following syntax:

[*][width][size]convcode.
The results from the conversion are placed in v i arguments unless you specify assignment
suppression with * (asterisk). Assignment suppression provides a way to describe an input eld
that is to be skipped. The input eld is a string of nonwhite-space characters. It extends to the
next inappropriate character or until the eld width, if specied, is exhausted.
The conversion code indicates how to interpret the input eld. You should not specify the v i
parameter for a suppressed eld. You can use the following conversion codes:
% :Accepts a single % (percent sign) input at this point; no assignment is done.
d, i :Accepts a decimal integer;
u :Accepts an unsigned decimal integer;
o :Accepts an octal integer;
x :Accepts a hexadecimal integer;
e,f,g :Accepts a oating-point number. The next eld is converted accordingly and stored
through the corresponding parameter, which should be a pointer to a oat. The input format
for oating-point numbers is a string of digits, with the following optional characteristics:
+ It can be a signed value.
+ It can be an exponential value, containing a decimal point followed by an exponent eld,
which consists of an E or an e followed by an (optionally signed) integer.
+ It can be one of the special values INF, NaN,
s :Accepts a string of characters.
c :character value is expected. The normal skip over white space is suppressed.

See Also : printf , read

Scilab Group April 1993 24

getf Scilab Function
1.0.50 Scilab object : function Scilab procedure
DESCRIPTION :
Functions are Scilab procedures ("macro", "function" and "procedure" have the save meaning).
Usually, they are dened in les with an editor and loaded into Scilab by getf or through a library.
They can also be dened on-line (see deff). A le which contains a function must begin as follows:
function [y1,...,yn]=foo(x1,...,xm)

The yi are output variables calculated as functions of input variables and variables existing in
Scilab when the function is executed. A function can be compiled for faster execution. Collections
of functions can be collected in libraries. Functions which begin with % sign (e.g. %foo) and whose
arguments are lists are used to perform specic operations: for example, z=%rmr(x,y) is equivalent
to z=x*y when x and z are rationals (i.e. x=list('r',n,d,[]) with n and d polynomials).
For example if the le myfct.sci contains:
function [x,y]=myfct(a,b)
x=a+b
y=a-b

you can load and use it in the following way:

getf('pathname/myfct.sci','c')
[a,b]=myfct(1,2)

See Also : deff, getf, comp, lib.

1.0.51 funptr coding of primitives ( wizard stu )

DESCRIPTION :
Utility function (for experts only) funptr('name') returns 100*fun + fin where (fun,fin)
is the internal coding of the primitive 'name' . fun is the interface number and fin the routine
number
See Also : clearfun, newfun

1.0.52 getenv get the value of an environnement variable

CALLING SEQUENCE :
env=getenv(str)

PARAMETERS :
str : character string specifying environnement variable name
env : character string which contain the environnement variable value
DESCRIPTION :
Return the value of an environnement variable
EXAMPLE :
getenv('SCI')

Scilab Group April 1993 25

help Scilab Function
1.0.53 getf loading of function
CALLING SEQUENCE :
getf(file-name [,'c'])

PARAMETERS :
filename : Scilab string.
"c" : scilab string "c".
DESCRIPTION :
loads one or several functions which are dened in the le 'file-name'. The string 'c' means
that the functions are to be compiled when loaded. (see comp). The rst line of the le must be
as follows:
function [s1,s2,..,slhs]=macr(e1,e2,...,erhs)

ei are input variables and si are output variables.

EXAMPLE :
getf('SCI/macros/xdess/plot.sci','c')

See Also : comp , exec , edit

1.0.54 getpid get Scilab process identicator

CALLING SEQUENCE :
id=getpid()

DESCRIPTION :
Return an the scilab process identicator integer
EXAMPLE :
host('ls >/tmp/scilab.'+string(getpid()))

1.0.55 ^,exp exponentiation

CALLING SEQUENCE :
A^b

DESCRIPTION :
Exponentiation of matrices or vectors by a constant vector.
If A is a vector or a rectangular matrix the exponentiation is done element-wise, with the usual
meaning.
For square A matrices the exponentiation is done in the matrix sense.
For boolean, polynomial and rational matrices, the exponent must be an integer
EXAMPLES :
2^4
[1 2;2 4]^(1+%i)
s=poly(0,"s");
[1 2 s]^4
[s 1;1 s]^(-1)

See Also : exp , inv

Scilab Group April 1993 26

imag Scilab Function
1.0.56 help on-line help command
CALLING SEQUENCE :
help word
help 'string'

DESCRIPTION :
Scilab's manual. Needs the Unix command "man" and "xman".
See the script les SCIDIR/bin/scihelp and SCIDIR/bin/xscihelp.
See Also : apropos

1.0.57 host unix call

CALLING SEQUENCE :
host('string')

DESCRIPTION :
Same as unix : sends a command to Unix.
See Also : unix

1.0.58 if else - conditional execution

DESCRIPTION :
Conditional execution; the syntax is the following :
if boolean then instructions,
elseif expri then instructions,
....
[else instructions],
end

- The only constraint is that each then keyword must be on the same line line as its corresponding
if or elseif keyword.
- The keyword then can be replaced by a carriage return or a comma.

EXAMPLE :
i=2
for j = 1:3,
if i == j then
a(i,j) = 2;
elseif abs(i-j) == 1 then
a(i,j) = -1;
else a(i,j) = 0;
end,
end

See Also : while , select , boolean , end , then , else

Scilab Group April 1993 27

left Scilab Function
1.0.59 imag imaginary part
CALLING SEQUENCE :
[y]=imag(x)

PARAMETERS :
x : real or complex vector or matrix.
y : real vector or matrix.
DESCRIPTION :
imag(x) is the imaginary part of x. (See %i to enter complex numbers).
See Also : real, %i
1.0.60 int integer part
CALLING SEQUENCE :
[y]=int(X)

PARAMETERS :
X : real matrix
y : integer matrix
DESCRIPTION :
int(X) returns the integer part of the real matrix X. Same as fix.
See Also : round, floor, ceil

1.0.61 iserror error test

CALLING SEQUENCE :
iserror([n])

DESCRIPTION :
tests if error number n has occurred (after a call to errcatch). iserror returns 1 if the error
occurred a nd 0 otherwise
n>0 is the error number ; all errors are tested with n<0.
See Also : error, errcatch
1.0.62 keyboard keyborad commands
DESCRIPTION :
Let C- stands for the control key. The following keyboard commands are available:
C-l clears the Scilab window
C-d deletes the current character
C-p calls back the preceding command
C-n go to next command line
C-a moves the cursor to the beginning of command line.
C-b backspace, moves the cursor one caracter to the left
C-f forwards, moves the cursor one caracter to the right
C-k kills command line from cursor to the end.
C-y yank, retrieves killed line.
!beg looks for last command line which begins by beg.
C-c interrupts Scilab and pause after carriage return. (Only functions can be interrupted).
Clicking on the stop button enters a C-C.
See Also : pause, read, input
Scilab Group April 1993 28
lib Scilab Function
1.0.63 [ left bracket
CALLING SEQUENCE :
[a11,a12,...;a21,a22,...;...]
[s1,s2,...]=func(...)

PARAMETERS :
a11,a12,... : matrix of any compatibles types with compatibles dimensions s1,s2,... : any
possible variable name
DESCRIPTION :
Left and right brackets are used for vector and matrix concatenation. These symbols are also used
to denote a multiple left-hand-side for a function call
Inside concatenation brackets blank or comma characters mean "column concatenation", semicol-
umn and carriage-return mean "row concatenation".
Note : to avoid confusions it is safer to use comma instead of blank to separate columns.
Within multiple lhs brackets variable names must be separated by comma.
EXAMPLES :
[6.9,9.64; sqrt(-1) 0]
[1 +%i 2 -%i 3]
[]
['this is';'a string';'vector']

[u,s]=schur(rand(3,3))

1.0.64 length length of object

CALLING SEQUENCE :
n=length(M)

PARAMETERS :
M : matrix (usual or polynomial or character string) or list
n : integer or integer matrix
DESCRIPTION :
For usual or polynomial matrix n is the integer equal to number of rows times number of columns
of M. (Also valid for M a boolean matrix)
For matrices made of character strings (and in particular for a character string) length returns
in n the length of entries of the matrix of character strings M.
The length of a list is the number of elements in the list (also given by size).
length('123') is 3. length([1,2;3,4]) is 4.
See Also : size, syssize
1.0.65 < lower
DESCRIPTION :
logical comparison symbol
<> means "dierent" (same as ~=)
< means "lower than"
> means "larger than"
<= means lower than or equal to.
>= means larger than or equal to
See Also : if
Scilab Group April 1993 29
link Scilab Function
1.0.66 lib library denition
CALLING SEQUENCE :
[xlib]=lib('lib_path')

PARAMETERS :
lib path : character string
DESCRIPTION :
lib path is a character string dening the path of a directory containing functions . This directory
must contain the binary les names(i).bin and an additional le names (which contains the
names of the functions). After the command lib all the functions of lib path can be called
interactively by Scilab. Such a binary le, for example foo.bin can be created by Scilab using
the command save(lib path+'/foo.bin',foo).
EXAMPLE :
deff('[z]=myplus(x,y)','z=x+y')
deff('[z]=yourplus(x,y)','x=x-y')

are two functions and lib path is : lib path='/usr/mymachine/mydirectory'

This directory contains the le names including myplus (rst line of the le) and yourplus (sec-
ond line of the le).
myplus and yourplus are compiled functions respectively saved in the les
'/usr/mymachine/mydirectory/myplus.bin'
'/usr/mymachine/mydirectory/yourplus.bin'
by the command:
save(lib_path+'/myplus.bin',myplus)
save(lib_path+'/yourplus.bin',yourplus)

A library can now be created with the command:

xlib=lib(lib_path+'/')

xlib is then a Scilab variable which can be saved and loaded in a future session of Scilab or
dened on-line or put in the startup le. The functions in this library are known by Scilab which
automatically loads them when necessary.
See Also : save, functions, whereis, SCIDIR/macros subdirectories

1.0.67 lines rows and columns used for display

CALLING SEQUENCE :
[nl,nc]=lines([n,nc])

DESCRIPTION :
lines() returns the vector [# columns, # rows] currently used by Scilab for displaying the
results. lines(n) sets the number of displayed lines to n. lines(n,nc) changes also the size of
the output to nc columns.
Scilab Group April 1993 30
list Scilab Function
1.0.68 link dynamic link
CALLING SEQUENCE :
link(files, sub-name)
link(files, sub-name, flag)
names=link()

PARAMETERS :
files : a character string or a vector of character strings. ld les used to dene the new entry
point (compiled routines, user libraries, system libraries,..)
sub-name : a character string. Name of the entry point in files to be linked.
flag : character string 'f' or 'c' for Fortran (default) or C code.
names : a vector of character string. Names of dynamically linked entry points.

DESCRIPTION :
link is a dynamic link facility: this command allows to add new compiled Fortran or C routines
to scilab executable code. Linked routines can be called interactively by the function fort. Linked
routines can also be used as "external" for e.g. non linear problem solvers (ode, optim, intg,
vdassl
The command link('foo.o','foo','f') links the Fortran object le foo.o with the entry point
foo.
The command link('foo.o','foo','c') links the C object le foo.o with the entry point foo.
The command link('SCIDIR/libs/calelm.a','dcopy') links the Fortran routine dcopy in the
library calelm.a.
Note that with dld (Linux machine) you can use an empty string if you want to link a program
which is already in one of the scilab libraries (e.g. link(' ','dcopy')).
A routine can be linked several times: each link undo the previous one.
Used with no arguments, link() returns the current linked routines.
If Scilab is compiled with static link (this is the default for SystemV machines) you may have to
include the system libraries in the "link" command.
For example, if foo.o denes the object code of a routine named foo, you will use link in one
the following way:
link('foo.o','foo').
link('foo.o -lm -lc','foo','c').
link('foo.o -lfor -lm -lc','foo').
link('foo.o -lftn -lm -lc','foo').
link('foo.o -L/opt/SUNWspro/SC3.0/lib/lib77 -lm -lc','foo')

If Scilab compiled with the "shared" option, the rst example can be used even if a warning for
unresolved references is issued.
(Experienced) users may also link a new scilab interface routine to add a set of new functions.
See Intersci documentation for interface generation and addinter function.
REMARKS :
For IBM-RS6000 only one program can be dynamically linked.
When running a demo, you may have some trouble with the link due to slight dierences between
systems. In this case, you modify the demo by adding the needed libraries in the link command.
See Also : fort, c_link, addinter
1.0.69 Scilab object: list list denition
CALLING SEQUENCE :
list( a1,....an )

Scilab Group April 1993 31

matrices Scilab Function
DESCRIPTION :
Creates a list with elements ai's which are arbitrary Scilab objects (matrix, list,...). Type
of list objects is 15.
list() is the empty list (0 element).
Operations on lists:
extraction : [x,y,z...]=l(v) where v is a vector of indices; [x,y,z]=l(:) extracts all the
elements.
insertion : l(i)=a
deletion : l(i)=null() removes the i-th element of the list l.
EXAMPLE :
x=list(1,2,3);
x(4)=10;

See Also : null , tlist

1.0.70 load load saved variable

CALLING SEQUENCE :
load('file-name')

DESCRIPTION :
loads the variables saved in le 'file-name' and load('file-name',x,y,...,z) loads only
variables x,y,...,z of le 'file-name'.
See Also : save
1.0.71 Scilab object : macro Scilab procedure
DESCRIPTION :
Macros are Scilab procedures ("macro", "function" and "procedure" have the save meaning).
Usually, they are dened in les with an editor and loaded into Scilab by getf or through a
library.
They can also be dened on-line (see deff). A le which contains a macro must begin as follows:
function [y1,...,yn]=foo(x1,...,xm)

The yi are output variables calculated as functions of input variables and variables existing in
Scilab when the macro is executed. A macro can be compiled for faster execution. Collections
of macros can be collected in libraries. Macros which begin with % sign (e.g. %foo) and whose
arguments are lists are used to perform specic operations: for example, z=%rmr(x,y) is equivalent
to z=x*y when x and z are rationals (i.e. x=list('r',n,d,[]) with n and d polynomials).
See Also : deff, getf, comp, lib.
1.0.72 Scilab object: matrix matrices in Scilab
DESCRIPTION :
Matrices are basic objects dened in Scilab. They can be dened as follows:
E=[e11,e12,...,e1n;
e21,e22,...,e2n;
....
em1,em2,...,emn];

Scilab Group April 1993 32

Maximum Scilab Function
Entries eij can be real or complex numbers, polynomials, rationals, strings, booleans.
Vectors are seen as matrices with one row or one column.
syslin lists in state-space form or transfer matrices can also be dened as above.
EXAMPLES :
E=[1,2;3,4]
E=[%T,%F;1==1,1~=1]
s=poly(0,'s');E=[s,s^2;1,1+s]
E=[1/s,0;s,1/(s+1)]
E=['A11','A12';'A21','A22']

See Also : poly , string , boolean , rational , ,

syslin empty

1.0.73 matrix vector to matrix conversion

CALLING SEQUENCE :
[y]=matrix(v,n,m)

PARAMETERS :
v : vector
n,m : integers
y n : x m matrix
DESCRIPTION :
transforms the v vector into an nxm matrix by stacking columnwise the entries of x.
Old stu:
matrix('magi',n) : returns a magic square of size n .
matrix('frk',n) : returns the franck matrix :
matrix('hilb',n) : is the inverse of the nxn Hilbert matrix (Hij= 1/(i+j-1)).

See Also : matrices, ones, zeros, rand, poly, empty

1.0.74 max maximum
CALLING SEQUENCE :
[m [,k]]=max(V)
[m [,k]]=maxi(V)

PARAMETERS :
V : real vector or matrix or list.
DESCRIPTION :
For V a vector, matrix or list, max(V) is the largest element V.
For matrices, [m,k]=max(V) gives in addition the index of the maximum.
For example:
[m,[k]]=max([V1,V2,...,Vn])

returns the vector m:

m(i)=max([V1(i),....,Vn(1)])
and the vector k contains for each m(i) the number of the rst Vj(i) achieving the maximum.
[m [,k]]=max(list(v1,...,vn))
is an equivalent syntax.
Note that max and maxi are equivalent.
See Also : sort, find, mini
Scilab Group April 1993 33
mode Scilab Function
1.0.75 maxi maximum
CALLING SEQUENCE :
[m [,k]]=maxi(A)
[m [,k]]=maxi(A1,A2,...,An)
[m [,k]]=maxi(list(A1,A2,...,An))

PARAMETERS :
A : real vector or matrix.
A1,...,An : a set of real vectors or matrices, all of the same size.
DESCRIPTION :
For A, a real vector or matrix, maxi(A) is the largest element A. [m,k]=maxi(A) gives in addition
the index of the maximum.
m=maxi(A1,A2,...,An) returns a vector m of size size(m)=size(A1) such that m(i)= max(
Aj(i)), j=1,...,n. [m,k]=maxi(A1,A2,...,An) gives in addition the vector k. for a xed i,
k(i) is the number of the rst Aj(i) achieving the maximum.
[m,k]=maxi(list(A1,...,An)) is an equivalent syntax of [m,k]=maxi(A1,A2,...,An)
EXAMPLE :
[m,n]=maxi([1,3,1])
[m,n]=maxi([3,1,1],[1,3,1],[1,1,3])
[m,n]=maxi(list([3,1,1],[1,3,1],[1,1,3]))
[m,n]=maxi(list(1,3,1))

See Also : sort , find , mini

1.0.76 min minimum

DESCRIPTION :
See max. Note that min and mini are equivalent.
See Also : mini, max
1.0.77 mini minimum
See Also : min , max

1.0.78 - the minus operation

DESCRIPTION :
The minus operation - (usual meaning). For use with arbitrary matrices (constant, polynomial,
rational).
See Also : subf
1.0.79 mode select a mode in exec le
CALLING SEQUENCE :
mode(k)

DESCRIPTION :
Used inside an exec-le with the following values for k
k=0 : no echo, no prompt, no stop.
k=-1 : nothing is printed.

Scilab Group April 1993 34

or Scilab Function
k=1 : an echo is received after each command line.
k=2 : prompt --> is printed.
k=3 : there are echoes, prompts, but no stops.
k=4 : stops before each prompt and waits for a new command line
k=7 : there are stops, prompts and echoes.
See Also : exec

1.0.80 newfun add a name in the table of functions

CALLING SEQUENCE :
newfun("function-name",nameptr)

DESCRIPTION :
Utility function (for experts only). Adds the name "function-name" in the table of functions
known to the interpreter. "nameptr" is an integer 100*fun+fin where fun and fin is the inter-
nal coding of the primitive "function-name". This function is useful to associate a primitive to a
routine interfaced in "matusr.f" (fun=14). Used with funptr and clearfun one can redene a
primitive by a function with same name.
See Also : clearfun
1.0.81 null delete an element in a list
CALLING SEQUENCE :
l(i)=null()

DESCRIPTION :
Deletion of objects inside a list
EXAMPLE :
l=list(1,2,3);
l(2)=null() // get list(1,3)

See Also : list , clear

1.0.82 ones matrix made of ones

CALLING SEQUENCE :
[y]=ones(m,n)
[y]=ones(x)

DESCRIPTION :
Returns a matrix made of ones.
ones(m,n) returns a (m,n) matrix full of ones.
ones(x) returns a matrix full of ones with the same size that x.
ones(x) is also valid for x a syslin list.
Note that ones(3) is ones(a) with a=3 i.e it is NOT a 3x3 matrix!
See Also : eye, zeros
Scilab Group April 1993 35
part Scilab Function
1.0.83 or - logical or
CALLING SEQUENCE :
or(A)
A|B

DESCRIPTION :
or(A) gives the or of the elements of the boolean matrix A. or(A) is true (%t) i at least one
entry of A is %t.
AjB gives the element-wise logical or of the booleans matrices A and B .A and B must be matrices
with the same dimensions or one from them must be a single boolean.
EXAMPLES :
or([%t %t %f])
[%t %t %f]|[%f %t %t]
[%t %t %f]|%f

See Also : and , not , find

1.0.84 ( - left and right parenthesis

CALLING SEQUENCE :
(expression)
[...]=func(e1,e2,...)
x(i,j)
v(i)
[...]=l(i)

PARAMETERS :
x : matrix of any possible type
v : row or column vector of any possible type
l : list variable
func : any function or macro name
e1,e2,... : any possible type expression
DESCRIPTION :
Left and right parenthesis are used to specify evaluation order within expressions, to form right-
hand-side functions argument list and to select elements within matrices and lists.
Within multiple rhs arguments must be separated by comma.
For elements selection i, j, may be real scalar or vectors or then : symbol which stands for "all
elements".
EXAMPLE :
3^(-1)
x=poly(0,"x");
(x+10)/2
i3=eye(3,3)
a=[1 2 3;4 5 6;7 8 9],a(1,3),a([1 3],:),a(:,3)
a(:,3)=[]
w=ssrand(2,2,2); w(:,1), ss2tf(w(:,1))
l=list(1,2,3,4)
[a,b,c,d]=l(:)

See Also : colon , comma , brackets

Scilab Group April 1993 36

+ Scilab Function
1.0.85 part extraction of strings
CALLING SEQUENCE :
[c]=part(mp,v)

PARAMETERS :
mp,c : string matrices
v : integer vector.
DESCRIPTION :
Let s[k] stands for the k character of string s ( or the empty character if k >length(s)).
part returns c, a matrix of character strings, such that c(i,j) is the string "s[v(1)]...s[v(n)]"
( s=mp(i,j) ).
EXAMPLE :
c=part(['a','abc','abcd'],[1,1,2])

See Also : ,
string length

1.0.86 pause pause mode, invoke keyboard

DESCRIPTION :
Switch to the pause mode; inserted in the code of a function, pause interrupts the execution of
the function: one receives a prompt symbol which indicates the level of the pause (e.g. -1->).
The user is then in a new session in which all the lower-level variables (and in particular all the
variable of the function) are available. To return to lower session enter "return"
In this mode, [...]=return(...) returns the variables of the argument (...) to lower session
with names in the output [...]. Otherwise, the lower-level variables are protected and cannot be
modied.
The pause is extremely useful for debugging purposes.
This mode is killed by the command "abort".
See Also : return, abort, quit, whereami, where

1.0.87 % percent
DESCRIPTION :
Some predened variables begin with %, such as %i (for sqrt(-1)), %inf (for Infinity), %pi
(for 3.14...), %T (for the boolean variable "true"),...
In addition, functions whose names begin with % are special : they are used for coding (extensions
of usual) operations .
For example the function %rmr performs the multiplication (m) operation x*y for x and y rational
matrices (r). The coding conventions are given by the readme le in directory SCIDIR/macros/percent.
EXAMPLE :
x1=list('x',1,2);
x2=list('x',2,3);
deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
x1*x2

Scilab Group April 1993 37

predef Scilab Function
1.0.88 + addition
DESCRIPTION :
Addition. Usual meaning. For character strings + means concatenation.
EXAMPLE :
[1,2]+1
s=poly(0,"s");
s+2
1/s+2
"cat"+"enate"

See Also : addf

1.0.89 poly polynomial denition

CALLING SEQUENCE :
[p]=poly(a,"x", ["flag"])

PARAMETERS :
a : matrix or real number
x : symbolic variable
"flag" : string ("roots", "coe")
DESCRIPTION :
If a is a matrix, p is the characteristic polynomial i.e. determinant(x*eye-a), x being the
symbolic variable.
If v is a vector, poly(v,"x",["roots"]) is the polynomial with roots the entries of v and "x"
as formal variable. (In this case, roots and poly are inverse functions).
poly(v,"x","coeff") creates the polynomial with symbol "x" and with coecients the entries
of v. (Here poly and coeff are inverse functions).
s=poly(0,"s") is the seed for dening polynomials with symbol "s".
EXAMPLE :
s=poly(0,"s");p=1+s+2*s^2;
A=rand(2,2);poly(A,"x")

See Also : coeff , matrices, rational

1.0.90 ^ power operation

DESCRIPTION :
For square matrices A^p is calculated by successive multiplication if p is a positive integer, and
by diagonalization if not. For non-square matrices the operation is done entry by entry. Note that
Kronecker product is noted .*. (e.g. A.*.2 returns the elementwise squared A matrix).
Note that ** can be used instead of ^.
EXAMPLE :
A=rand(2,3);A^2
A=rand(5,5);X=A^(0.2);X^5-A

See Also : exp , function mpow in SCIDIR/macros/util

Scilab Group April 1993 38

printf Scilab Function
1.0.91 predef variable protection
CALLING SEQUENCE :
predef([n])

DESCRIPTION :
Utility function used for dening "predened" variables. Predened variables are protected and
cannot be killed. They are not saved by the 'save' command.
predef() sets all the current variables to predened ones.
predef(n) sets the max(n,7) last dened variables as predened.

REMARK :
A number of predened variables are set in the start-up le scilab.star. These variables are
seen by typing who when entering in Scilab.
User may in particular set its own predened variables in user's startup le home/.scilab
See Also : clear, save
1.0.92 print prints variables in a le
CALLING SEQUENCE :
print('file-name',x1,[x2,...xn])

DESCRIPTION :
prints xi on le 'file-name' with the current format, i.e. the format used by scilab to display
the variables. All types of variables may be "print"'ed
Note : xi must be a named variable, with expressions variable name part of the display is unpre-
dictable.
print(%io(2),...) prints on Scilab's window. this syntax may be used to display variables
within a macro.
EXAMPLES :
a=rand(3,3);p=poly([1,2,3],'s');l=list(1,'asdf',[1 2 3]);
print(%io(2),a,p,l)
write(%io(2),a)

See Also : write , read, format , printf , disp

1.0.93 printf,fprintf,sprintf Emulator of C language printf functions

CALLING SEQUENCE :
printf(format,value_1,..,value_n)
fprintf(file,format,value_1,..,value_n)
str=sprintf(format,value_1,..,value_n)

PARAMETERS :
format : a Scilab string. Species a character string combining literal characters with conversion
specications.
value i : Species the data to be converted according to the format parameter.
str : column vector of character strings
file : a Scilab string specifying a le name or a logical unit number (see file)

Scilab Group May 1994 39

printf Scilab Function
DESCRIPTION :
The printf function converts, formats, and writes its value parameters, under control of the
format parameter, to the standard output.
Thefprintf function converts, formats, and writes its value parameters, under control of
theformat parameter, to the le specied by its file parameter.
Thesprintf function converts, formats, and stores its value parameters, under control of the
format parameter.
Theformat parameter is a character string that contains two types of objects:
Literal characters : which are copied to the output stream.
Conversion specifications : each of which causes zero or more items to be fetched from the
value parameter list.

If there are not enough items for format in the value parameter list, sprintf generate an
error. If any values remain after the entire format has been processed, they are ignored.
Conversion Specications
Each conversion specication in the format parameter has the following syntax:
- A % (percent) sign.
- Zero or more options, which modify the meaning of the conversion specication. The following
list contains the option characters and their meanings:
- : Left align, within the eld, the result of the conversion.
+ : Begin the result of a signed conversion with a sign (+ or -).
"space" : Prex a space character to the result if the rst character of a signed conversion
is not a sign. If both the (space) and + options appear, the (space) option is ignored.
# : Convert the value to an alternate form. For c, d, i, s, and u conversions, the # option
has no eect. For o conversion, # increases the precision to force the rst digit of the
result to be a 0 (zero). For x and X conversions, a nonzero result has 0x or 0X prexed
to it. For e, E, f, g, and G conversions, the result always contains a decimal point,
even if no digits follow it. For g and G conversions, trailing zeros are not removed from
the result.
0 : Pad to the eld width, using leading zeros (following any indication of sign or base)
for d, i, o, u, x, X, e, E, f, g, and G conversions; no space padding is performed. If
the 0 and -- (dash) ags both appear, the 0 ag is ignored. For d, i, o u, x, and X
conversions, if a precision is specied, the 0 ag is also ignored.
An optional decimal digit string that species the minimum eld width. If the converted value
has fewer characters than the eld width, the eld is padded on the left to the length specied by
the eld width. If the left-adjustment option is specied, the eld is padded on the right.
An optional precision. The precision is a . (dot) followed by a decimal digit string. If no
precision is given, the parameter is treated as 0 (zero). The precision species:
-The minimum number of digits to appear for d, u, o, x, or X conversions
-The number of digits to appear after the decimal point for e, E, and f conversions
-The maximum number of signicant digits for g and G conversions
-The maximum number of characters to be printed from a string in an s conversion
- A character that indicates the type of conversion to be applied:
% : Performs no conversion. Displays %.
d,i :Accepts an integer value and converts it to signed decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as a leading character causes the eld width value to be padded
with leading zeros.
Scilab Group May 1994 40
printf Scilab Function
u :Accepts an integer value and converts it to unsigned decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros.
o :Accepts an integer value and converts it to unsigned octal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros. An octal value for eld width is not implied.
x, X :Accepts an integer value and converts it to unsigned hexadecimal notation. The
letters \abcdef" are used for the x conversion; the letters \ABCDEF" are used for the
X conversion. The precision species the minimum number of digits to appear. If the
value being converted can be represented in fewer digits, it is expanded with leading
zeros. The default precision is 1. The result of converting a zero value with a precision
of zero is a null string. Specifying a eld width with a zero as the leading character
causes the eld width value to be padded with leading zeros.
f : Accepts a oat or double value and converts it to decimal notation in the format
%[{]ddd.ddd. The number of digits after the decimal point is equal to the precision
specication.
- If no precision is specied, six digits are output.
- If the precision is zero, no decimal point appears and the system outputs a number
rounded to the integer nearest to value.
- If a decimal point is output, at least one digit is output before it.
e, E :Accepts a real and converts it to the exponential form %[{]d.ddde+/{dd. There is
one digit before the decimal point, and the number of digits after the decimal point is
equal to the precision specication.
- If no precision is specied, , six digits are output.
- If the precision is zero, , no decimal point appears.
- The E conversion character produces a number with E instead of e before the ex-
ponent. The exponent always contains at least two digits. If the value is zero, the
exponent is zero.
g, G : Accepts a real and converts it in the style of the e, E, or f conversion characters,
with the precision specifying the number of signicant digits. Trailing zeros are removed
from the result. A decimal point appears only if it is followed by a digit. The style
used depends on the value converted. Style e (E, if G is the ag used) results only if
the exponent resulting from the conversion is less than {4, or if it is greater or equal to
the precision.
c :Accepts and displays an integer value converted to a character.
s :Accepts a string value and displays characters from the string to the end or the number
of characters indicated by the precision is reached. If no precision is specied, all
characters up to the end are displayed.
A eld width or precision can be indicated by an * (asterisk) instead of a digit string. In this
case, an integer value parameter supplies the eld width or precision. The value parameter
converted for output is not fetched until the conversion letter is reached, so the parameters
specifying eld width or precision must appear before the value to be converted (if any).
If the result of a conversion is wider than the eld width, the eld is expanded to contain
the converted result.
The representation of the plus sign depends on whether the + or (space) formatting option
is specied.
Scilab Group May 1994 41
rat Scilab Function
EXAMPLES :
fahr=120
sprintf('%3d Fahrenheit = %6.1f Celsius',fahr,(5/9)*(fahr-32))

printf('Result is:\nalpha=%f",0.535)

u=file('open','results','unknown') //open the result file

t=0:0.1:2*%pi;
for tk=t
fprintf(u,'time = %6.3f value = %6.3f',tk,sin(tk)) // write a line
end
file('close',u) //close the result file

See Also : string , print , write , format , disp , file

1.0.94 quit decrease the pause level or exit

DESCRIPTION :
quit terminates Scilab or decreases the pause level.
See Also : pause, break, abort

1.0.95 ' transpose of matrix

DESCRIPTION :
quote (')is used for (Conjugate) Transpose of matrix. Quotes are also used to dene character
strings. (Character strings are dened between two quotes).

1.0.96 rand random number generator

CALLING SEQUENCE :
rand(m,n)
rand(x)
rand('key'[,n])

DESCRIPTION :
random matrix generator.
rand(m,n) is a random matrix of dimension mxn.
rand(a) is a random matrix of same size as a.
rand('uniform') is for uniform random numbers.
rand('normal') is for gaussian random numbers.
rand('seed') returns the current value of the seed.
rand('seed',n) puts the seed to n. (n=0 at rst call).
rand : with no arguments gives a scalar whose value changes each time it is referenced. By default,
random numbers are uniformly distributed in the interval (0,1). rand('normal') switches to a
normal distribution with mean 0 and variance 1. rand('uniform') switches back to the uniform
distribution.
See Also : ssrand
Scilab Group April 1993 42
read Scilab Function
1.0.97 rat Floating point rational approximation
CALLING SEQUENCE :
[N,D]=rat(x [,tol])
y=rat(x [,tol])

PARAMETERS :
x : real vector or matrix
n : integer vector or matrix
d : integer vector or matrix
y : real vector or matrix
DESCRIPTION :
[N,D] = rat(x,tol) returns two integer matrices so that N./D is close tox in the sense that
<
abs(N./D - X) = tol*abs(x) . The rational approximations are generated by truncating con-
tinued fraction expansions.
tol = 1.e-6*norm(X,1) is the default. y = rat(x,tol) return the
quotientN./D
See Also : int round
1.0.98 Scilab object : rationals rational in Scilab
DESCRIPTION :
A rational r is a quotient of two polynomials r=num/den. The internal representation of a rational
is a list. r=list('r',num,den,[]) is the same as r=num/den. A rational matrix can be dened
with the usual syntax e.g. [r11,r12;r21,r22] is a 2x2 matrix where rij are 1x1 rationals. A
rational matrix can also be dened as above as a list list('r',num,den,[]) with num and den
polynomial matrices.
EXAMPLES :
s=poly(0,'s');
W=[1/s,1/(s+1)]
W'*W
Num=[s,s+2;1,s];Den=[s*s,s;s,s*s];
list('r',Num,Den,[])
H=Num./Den
syslin('c',Num,Den)
syslin('c',H)
[Num1,Den1]=simp(Num,Den)

See Also : poly , syslin , simp

1.0.99 read matrices read

CALLING SEQUENCE :
[x]=read(file-desc,m,n,[format])
[x]=read(file-desc,m,n,k,format)

PARAMETERS :
file-desc : character string specifying the le name or integer value specifying logical unit (see
le).
m, n : integers (dimensions of the matrix x). Set m=-1 if you dont know the numbers of rows,
so the whole le is read.
Scilab Group April 1993 43
real Scilab Function
format : character string, specifies a "fortran" format. This character string must
begin with a right parenthesis and end with a left parenthesis. Formats cannot mix oating
point or character edition modes.
k : integer
DESCRIPTION :
reads row after row the mxn matrix x (n=1 for character chain) in the le file-desc (string or
integer). Each row of the matrix x begin in a new line of file-desc le. Depending on format
a given row of the x matrix may be read from more than one line of file-desc le.
The type of the result will depend on the specied form. If form is numeric (d,e,f,g) the matrix
will be a scalar matrix and if form contains the character a the matrix will be a matrix of character
strings. In this case n must be equal to 1.
Examples for format:
(1x,e10.3,5x,3(f3.0))
(10x,a20)
.LP
When format is omitted datas are read using numerical free format:
blank, comma and shash may be used as data separators, n*v may be use
to represent n occurences of value n.

.LP
A direct access file can be used if using the parameter \fVk\fR which is
is the vector of record numbers to be read (one record per row),
thus \fVm\fR must be \fVm=prod(size(k))\fR.
.LP
To read on the keyboard use \fVread(%io(1),...)\fR.
.SH EXAMPLE
.nf
unix('rm foo')
A=rand(3,5); write('foo',A);
B=read('foo',3,5)
B=read('foo',-1,5)
read(%io(1),1,1,'(a)') // waits for user's input

See Also : file , readb, write , %io , x_dialog , scanf

1.0.100 readb binary read

CALLING SEQUENCE :
[x]=readb(file-name,m,n)

PARAMETERS :
file-name : string or integer
m, n : integers (dimensions of the matrix x). Set m=-1 if you dont know the numbers of rows,
so all the le is read
DESCRIPTION :
binary read of the matrix x in the le file-name.
See Also : file, write, writeb
Scilab Group April 1993 44
scanf Scilab Function
1.0.101 real real part
CALLING SEQUENCE :
[y]=real(x)

PARAMETERS :
x : real or complex vector or matrix
y : real matrix
DESCRIPTION :
real(x) is the real part of x (See %i to enter complex numbers).
See Also : imag
1.0.102 resume return or resume
DESCRIPTION :
In a function resume stops the execution of the function. In pause mode, it allows to return to
lower levels.
resume is equivalent to return.
See Also : abort, break
1.0.103 return return or resume
DESCRIPTION :
In a function return stops the execution of the function. In pause mode, it allows to return to
lower levels.
resume is equivalent to return.
See Also : abort, break, pause
1.0.104 round rounding
CALLING SEQUENCE :
[y]=round(x)

PARAMETERS :
x : real or complex matrix
y : integer or complex (with integer real and imag) matrix
DESCRIPTION :
round(x) rounds the elements of x to the nearest integers.
See Also : int, floor, ceil

1.0.105 save saving variables

CALLING SEQUENCE :
save(file-name, [,x1,..])

DESCRIPTION :
saves all current variables on the le file-name.
save(file-name,x,y) saves only x,y.
Saved variables are loaded by the load command
See Also : load
Scilab Group May 1994 45
scanf Scilab Function
1.0.106 scanf, sscanf - Converts formatted input
CALLING SEQUENCE :
[v_1,...v_n]=scanf (format);
[v_1,...v_n]=fscanf (file,format)
[v_1,...v_n]=sscanf (string,format)

PARAMETERS :
format :Species the format conversion.
file :Species the input le name or le number.
string :Species input to be read.
DESCRIPTION :
The scanf,fscanf, and sscanf functions read character data, interpret it according to a format, and
returns the converted results.
These functions read their input from the following sources:
scanf :Reads from standard input
fscanf :Reads from the le dened by the le parameter.
sscanf :Reads from the character string specied by the string parameter.
The formatparameter contains conversion specications used to interpret the input.
The format parameter can contain white-space characters (blanks, tabs, newline, or formfeed)
that, except in the following two cases, read the input up to the next nonwhite-space character.
Unless there is a match in the control string, trailing white space (including a newline character)
is not read.
- Any character except % (percent sign), which must match the next character of the input
stream.
- A conversion specication that directs the conversion of the next input eld.
CONVERSION SPECIFICATIONS :
Each conversion specication in the format parameter contains the following elements:
+ The character % (percent sign)
+ The optional assignment suppression character *
+ An optional numeric maximum eld width
+ A conversion code

The conversion specication has the following syntax:

[*][width][size]convcode.
The results from the conversion are placed in v i arguments unless you specify assignment
suppression with * (asterisk). Assignment suppression provides a way to describe an input eld
that is to be skipped. The input eld is a string of nonwhite-space characters. It extends to the
next inappropriate character or until the eld width, if specied, is exhausted.
The conversion code indicates how to interpret the input eld. You should not specify the v i
parameter for a suppressed eld. You can use the following conversion codes:
% :Accepts a single % (percent sign) input at this point; no assignment is done.
d, i :Accepts a decimal integer;
u :Accepts an unsigned decimal integer;
o :Accepts an octal integer;
x :Accepts a hexadecimal integer;
e,f,g :Accepts a oating-point number. The next eld is converted accordingly and stored
through the corresponding parameter, which should be a pointer to a oat. The input format
for oating-point numbers is a string of digits, with the following optional characteristics:
Scilab Group May 1994 46
scilink Scilab Function
+It can be a signed value.
+It can be an exponential value, containing a decimal point followed by an exponent eld,
which consists of an E or an e followed by an (optionally signed) integer.
+ It can be one of the special values INF, NaN,

s :Accepts a string of characters.

c :character value is expected. The normal skip over white space is suppressed.
See Also : printf, read

1.0.107 scilab Major unix script to execute Scilab and miscellaneous

tools
CALLING SEQUENCE :
scilab [-ns -nw -display display]
scilab -help [ <key> ]
scilab -xhelp [-display display]
scilab -k <key>
scilab -link <objects>
scilab -macro <macro-name>

DESCRIPTION :
scilab [-ns -nw -display display] : run scilab , if -ns option is present SCI/scilab.star is
not executed. if -nw option is present then scilab is not run within an Xwindow widget
scilab -help <key> : write on-line documentation about <key> (usually automatically called
by scilab command "help <key>") Example:
scilab -help plot3d

scilab -k <key> : gives the list of Scilab commands containing the keyword <key> in their
description ( same as man -k )
scilab -link <objects-files> : Is used to produce a local scilex (executable code of
Scilab) linked with the additional les given by the user in <object-files>.
If in the list of object les some names are known scilex names (from SCIDIR/routines/default
) then the scilex default les are omitted and replaced with the given ones .
This script also produces an xscilab script, which when called will ran the new generated
scilex le.
For example:
scilab -link C/interf.o C/evol.o C/bib.a

will create a new scilex le in which the default interf.o le will be replaced by C/interf.o.
scilab -function <function-name>

write brief description of calling sequence and description of scilab function function name. (Usu-
ally automatically called by scilab to display a compiled function).
For example:
scilab -function bode

Scilab Group April 1993 47

setbpt Scilab Function
1.0.108 scilink Unix script to relink Scilab
CALLING SEQUENCE :
scilink <object-files>

DESCRIPTION :
This script is used to produce a local scilex (executable code of Scilab) linked with the additional
les given by the user in <object-files>.
If in the list of object les some names are known scilex names (from SCIDIR/routines/default
) then the scilex default les are omited and replaced with the given ones .
This script also produces an xscilab script, which when called will ran the new generated
scilex le.
For example the command
scilink C/interf.o C/evol.o C/bib.a

will create a new scilex le in which the default interf.o le will be replaced by C/interf.o.
See Also : directory SCIDIR/routines/default
1.0.109 select select keyword
DESCRIPTION :
select expr,
case expr1 then instructions1,
case expr2 then instructions2,
...
case exprn then instructionsn,
[else instructions],
end

Notes:
- The only constraint is that each "then" keyword must be on the same line line as corresponding
"case" keyword.
- The "keyword "then" can be replaced by a carriage return or a comma.
instructions1 are executed if expr1=expr, etc.

EXAMPLE :
while %t do
n=round(10*rand(1,1))
select n
case 0 then
disp(0)
case 1 then
disp(1)
else
break
end
end

See Also : if , while, for

Scilab Group April 1993 48

size Scilab Function
1.0.110 ; ending expression and row separator
DESCRIPTION :
In a le, the line separator \;" suppresses the display of the line; row separator in matrix deni-
tion.
1.0.111 setbpt setting breakpoints
CALLING SEQUENCE :
setbpt(macro-name [,line-num])

PARAMETERS :
macro-name : string
line-num : integer
DESCRIPTION :
setbpt interactively inserts a breakpoint in the line number line-num (default value is 1) of the
function macro-name
When reaching the breakpoint, Scilab evaluates the specied line , prints the number of the line
and the name of the function. If the function is not compiled ( see comp ) the line is printed on
the screen. Then Scilab goes into a pause mode in which the user can check current values. The
pause is exited with resume or abort. Redening the function does not clear the breakpoints,
the user must explicitly delete breakpoints using delbpt. The maximum number of functions with
breakpoints enabled must be less than 20 and the maximum number of breakpoints is set to 100.
See Also : delbpt, dispbpt, pause, resume
1.0.112 sign sign function
DESCRIPTION :
For non-square matrices, X=sign(A) returns the matrix made of the signs of A(i,j). For square
and Hermitian matrices X=sign(A) is matrix sign function.
EXAMPLE :
sign(rand(2,3));
A=rand(4,4);B=A+A';X=sign(B);spec(X)

See Also : function msign in SCIDIR/macros/util

1.0.113 size size of objects

CALLING SEQUENCE :
y=size(x [,sel])
[nr,nc]=size(x)

PARAMETERS :
x : matrix (including transfer matrix) or list or linear system (syslin)
:
y 1x2 integer vector or integer number
sel : a scalar or a character string
nr,nc : two integers
DESCRIPTION :
Size of a (constant, polynomial, string, boolean, rational) matrix x, y = 1x2 vector [number of
rows, number of columns].
Called with LHS=2, returns nr,nc = [number of rows, number of columns].
sel may be used to specify what dimension to get:

Scilab Group April 1993 49

printf Scilab Function
1 or 'r' : to get the number of rows
2 or 'c' : to get the number of columns
2 or '*' : to get the product of rows and column numbers
Size (length) of ordinary list (number of elements). In this case the syntax must be y=size(x)
Caution: if x is a syslin list representing a linear system, y=size(x) returns in y the (row)
vector [number of outputs, number if inputs] i.e. the dimension of the corresponding transfer
matrix. The syntax [nr,nc]=size(x) is also valid (with (nr,nc)=(y(1),y(2)).
If x is a syslin list representing a linear system in state-space form, then [nr,nc,nx]=size(x)
returns in addition the dimension nx of the A matrix of x.
EXAMPLES :
[n,m]=size(rand(3,2))
[n,m]=size(['a','b';'c','d'])
x=ssrand(3,2,4);[ny,nu]=size(x)
[ny,nu]=size(ss2tf(x))
[ny,nu,nx]=size(x)

See Also : length , syslin

1.0.114 / right division and feed back

DESCRIPTION :
Right division. x=A / b is the solution of x*A=b .
b/a = (a' nb')' .
a ./ b is the matrix with entries a(i,j)/ b(i,j). If b is scalar (1x1 matrix) this operation is
the same as a./b*ones(a). (Same convention if a is a scalar).
Backslash stands for left division.
System feed back. S=G/.K evaluates S=G*(eye+K*G)^(-1) this operator avoid simplication prob-
lem.
Comment // comments a line i.e lines which begin by // are ignored by the interpreter.
See Also : inv, percent, backslash
1.0.115 printf,fprintf,sprintf Emulator of C language printf functions
CALLING SEQUENCE :
printf(format,value_1,..,value_n)
fprintf(file,format,value_1,..,value_n)
str=sprintf(format,value_1,..,value_n)

PARAMETERS :
format : a Scilab string. Species a character string combining literal characters with conversion
specications.
value i : Species the data to be converted according to the format parameter.
str : column vector of character strings
file : a Scilab string specifying a le name or a logical unit number (see file)

DESCRIPTION :
The printf function converts, formats, and writes its value parameters, under control of the
format parameter, to the standard output.
Thefprintf function converts, formats, and writes its value parameters, under control of
theformat parameter, to the le specied by its file parameter.
Thesprintf function converts, formats, and stores its value parameters, under control of the
format parameter.
Theformat parameter is a character string that contains two types of objects:
Scilab Group May 1994 50
printf Scilab Function
Literal characters : which are copied to the output stream.
Conversion specifications : each of which causes zero or more items to be fetched from the
value parameter list.
If there are not enough items for format in the value parameter list, sprintf generate an
error. If any values remain after the entire format has been processed, they are ignored.
Conversion Specications
Each conversion specication in the format parameter has the following syntax:
- A % (percent) sign.
- Zero or more options, which modify the meaning of the conversion specication. The following
list contains the option characters and their meanings:
- : Left align, within the eld, the result of the conversion.
+ : Begin the result of a signed conversion with a sign (+ or -).
"space" : Prex a space character to the result if the rst character of a signed conversion
is not a sign. If both the (space) and + options appear, the (space) option is ignored.
# : Convert the value to an alternate form. For c, d, i, s, and u conversions, the # option
has no eect. For o conversion, # increases the precision to force the rst digit of the
result to be a 0 (zero). For x and X conversions, a nonzero result has 0x or 0X prexed
to it. For e, E, f, g, and G conversions, the result always contains a decimal point,
even if no digits follow it. For g and G conversions, trailing zeros are not removed from
the result.
0 : Pad to the eld width, using leading zeros (following any indication of sign or base)
for d, i, o, u, x, X, e, E, f, g, and G conversions; no space padding is performed. If
the 0 and -- (dash) ags both appear, the 0 ag is ignored. For d, i, o u, x, and X
conversions, if a precision is specied, the 0 ag is also ignored.
An optional decimal digit string that species the minimum eld width. If the converted value
has fewer characters than the eld width, the eld is padded on the left to the length specied by
the eld width. If the left-adjustment option is specied, the eld is padded on the right.
An optional precision. The precision is a . (dot) followed by a decimal digit string. If no
precision is given, the parameter is treated as 0 (zero). The precision species:
-The minimum number of digits to appear for d, u, o, x, or X conversions
-The number of digits to appear after the decimal point for e, E, and f conversions
-The maximum number of signicant digits for g and G conversions
-The maximum number of characters to be printed from a string in an s conversion
- A character that indicates the type of conversion to be applied:
% : Performs no conversion. Displays %.
d,i :Accepts an integer value and converts it to signed decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as a leading character causes the eld width value to be padded
with leading zeros.
u :Accepts an integer value and converts it to unsigned decimal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros.
o :Accepts an integer value and converts it to unsigned octal notation. The precision
species the minimum number of digits to appear. If the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
Scilab Group May 1994 51
printf Scilab Function
The result of converting a zero value with a precision of zero is a null string. Specifying
a eld width with a zero as the leading character causes the eld width value to be
padded with leading zeros. An octal value for eld width is not implied.
x, X :Accepts an integer value and converts it to unsigned hexadecimal notation. The
letters \abcdef" are used for the x conversion; the letters \ABCDEF" are used for the
X conversion. The precision species the minimum number of digits to appear. If the
value being converted can be represented in fewer digits, it is expanded with leading
zeros. The default precision is 1. The result of converting a zero value with a precision
of zero is a null string. Specifying a eld width with a zero as the leading character
causes the eld width value to be padded with leading zeros.
f : Accepts a oat or double value and converts it to decimal notation in the format
%[{]ddd.ddd. The number of digits after the decimal point is equal to the precision
specication.
- If no precision is specied, six digits are output.
- If the precision is zero, no decimal point appears and the system outputs a number
rounded to the integer nearest to value.
- If a decimal point is output, at least one digit is output before it.
e, E :Accepts a real and converts it to the exponential form %[{]d.ddde+/{dd. There is
one digit before the decimal point, and the number of digits after the decimal point is
equal to the precision specication.
- If no precision is specied, , six digits are output.
- If the precision is zero, , no decimal point appears.
- The E conversion character produces a number with E instead of e before the ex-
ponent. The exponent always contains at least two digits. If the value is zero, the
exponent is zero.
g, G : Accepts a real and converts it in the style of the e, E, or f conversion characters,
with the precision specifying the number of signicant digits. Trailing zeros are removed
from the result. A decimal point appears only if it is followed by a digit. The style
used depends on the value converted. Style e (E, if G is the ag used) results only if
the exponent resulting from the conversion is less than {4, or if it is greater or equal to
the precision.
c :Accepts and displays an integer value converted to a character.
s :Accepts a string value and displays characters from the string to the end or the number
of characters indicated by the precision is reached. If no precision is specied, all
characters up to the end are displayed.
A eld width or precision can be indicated by an * (asterisk) instead of a digit string. In this
case, an integer value parameter supplies the eld width or precision. The value parameter
converted for output is not fetched until the conversion letter is reached, so the parameters
specifying eld width or precision must appear before the value to be converted (if any).
If the result of a conversion is wider than the eld width, the eld is expanded to contain
the converted result.
The representation of the plus sign depends on whether the + or (space) formatting option
is specied.
EXAMPLES :
fahr=120
sprintf('%3d Fahrenheit = %6.1f Celsius',fahr,(5/9)*(fahr-32))

printf('Result is:\nalpha=%f",0.535)

u=file('open','results','unknown') //open the result file

t=0:0.1:2*%pi;

Scilab Group May 1994 52

scanf Scilab Function
for tk=t
fprintf(u,'time = %6.3f value = %6.3f',tk,sin(tk)) // write a line
end
file('close',u) //close the result file

See Also : string , print , write , format , disp , file

1.0.116 scanf, sscanf - Converts formatted input

CALLING SEQUENCE :
[v_1,...v_n]=scanf (format);
[v_1,...v_n]=fscanf (file,format)
[v_1,...v_n]=sscanf (string,format)

PARAMETERS :
format :Species the format conversion.
file :Species the input le name or le number.
string :Species input to be read.
DESCRIPTION :
The scanf,fscanf, and sscanf functions read character data, interpret it according to a format, and
returns the converted results.
These functions read their input from the following sources:
scanf :Reads from standard input
fscanf :Reads from the le dened by the le parameter.
sscanf :Reads from the character string specied by the string parameter.
The formatparameter contains conversion specications used to interpret the input.
The format parameter can contain white-space characters (blanks, tabs, newline, or formfeed)
that, except in the following two cases, read the input up to the next nonwhite-space character.
Unless there is a match in the control string, trailing white space (including a newline character)
is not read.
- Any character except % (percent sign), which must match the next character of the input
stream.
- A conversion specication that directs the conversion of the next input eld.
CONVERSION SPECIFICATIONS :
Each conversion specication in the format parameter contains the following elements:
+ The character % (percent sign)
+ The optional assignment suppression character *
+ An optional numeric maximum eld width
+ A conversion code

The conversion specication has the following syntax:

[*][width][size]convcode.
The results from the conversion are placed in v i arguments unless you specify assignment
suppression with * (asterisk). Assignment suppression provides a way to describe an input eld
that is to be skipped. The input eld is a string of nonwhite-space characters. It extends to the
next inappropriate character or until the eld width, if specied, is exhausted.
The conversion code indicates how to interpret the input eld. You should not specify the v i
parameter for a suppressed eld. You can use the following conversion codes:
% :Accepts a single % (percent sign) input at this point; no assignment is done.

Scilab Group May 1994 53

str2code Scilab Function
d, i :Accepts a decimal integer;
u :Accepts an unsigned decimal integer;
o :Accepts an octal integer;
x :Accepts a hexadecimal integer;
e,f,g :Accepts a oating-point number. The next eld is converted accordingly and stored
through the corresponding parameter, which should be a pointer to a oat. The input format
for oating-point numbers is a string of digits, with the following optional characteristics:
+ It can be a signed value.
+ It can be an exponential value, containing a decimal point followed by an exponent eld,
which consists of an E or an e followed by an (optionally signed) integer.
+ It can be one of the special values INF, NaN,
s :Accepts a string of characters.
c :character value is expected. The normal skip over white space is suppressed.
See Also : printf , read

1.0.117 stacksize set scilab stack size

CALLING SEQUENCE :
stacksize(n)
szstacksize()

PARAMETERS :
n : integer, the required stack size given in number of double precision words
sz : 2-vector [total used]
DESCRIPTION :
Scilab stores all variables in a unique stack stk.
stacksize(n) allows the user to increase or decrease this stack current size. The maximum
allowed size depends on the amount of cpu memory and swap space, and on the others tools
running.
This function with the n argument may only be called at the main prompt time. It cannot be
called within a scilab function.
sz=stacksize() returns a 2-vector which contains the current total and used stack size. It
can be used everywhere.
See Also : who
1.0.118 * multiplication
DESCRIPTION :
Multiplication. Usual meaning. Valid for constant, boolean, polynomial and rational matrices.
Element-wise multiplication is denoted x.*y. If x or y is scalar (1x1 matrix) .* is the same as *.
Kronecker product is x.*.y
See Also : mulf
1.0.119 startup startup le
DESCRIPTION :
The startup les .scilab (in your home directory) and .scilab in your working directory are
automatically executed (if present) when Scilab is invoked, in addition with the le scilab.star
in the Scilab directory.
Scilab Group May 1994 54
~ Scilab Function
1.0.120 str2code return scilab integer codes associated with a
character string
CALLING SEQUENCE :
c=str2code(str)
PARAMETERS :
str : a character string
c : vector of character integer codes
DESCRIPTION :
Return c such that c(i) is the scilab integer code of part(str,i))
EXAMPLE :
str2code('Scilab')

See Also : code2str

1.0.121 string conversion to string

CALLING SEQUENCE :
string(x)
[out,in,text]=string(x)
PARAMETERS :
x : real matrix or function
DESCRIPTION :
converts a matrix into a matrix of strings.
If x is a function [out,in,text]=string(x) returns three vectors strings : out is the vector of
output variables, in is the vector of input variables, and text is the (column) vector of the source
code of the function.
If x is a lib variable, text is a character string column vector. The rst element contains the path
of library le and the other the name of functions it denes.
Character strings are dened as 'string' (between quotes) or "string" (between doublequotes);
matrices of strings are dened as usual constant matrices.
Concatenation of strings is made by the + operation.
EXAMPLES :
string(rand(2,2))
deff('y=mymacro(x)','y=x+1')
[out,in,text]=string(mymacro)
x=123.356; 'Result is '+string(x)

See Also : part , length , format , quote , pol2str , ,

evstr execstr

1.0.122 Scilab object:string character strings

DESCRIPTION :
Strings are dened as 'string' (between quotes) or "string" (between doublequotes); matrices
of strings are dened as usual constant matrices.
Concatenation of two strings is made by a + : string1+string2.
EXAMPLE :
['this','is'; 'a 2x2','matrix']
"matrix"=="mat"+"rix"

See Also : part , length , strcat

Scilab Group April 1993 55

type Scilab Function
1.0.123 ~ logical not
CALLING SEQUENCE :
~m

PARAMETERS :
m : boolean matrix
DESCRIPTION :
~m is the negation of m.
1.0.124 Scilab object: tlist typed list denition
CALLING SEQUENCE :
tlist(typ,a1,....an )

PARAMETERS :
typ : Character string or vector of character strings
ai : any Scilab object (matrix, list,string...).
DESCRIPTION :
Creates atyped-list with elements ai's. The typ argument species the list type. Such
typed-list allow the user to dene new operations working on these object through scilab func-
tions. The only dierence between typed-list and list is the value of the type (16 instead of
15).
typ(1) species the list type (character string used to dene soft coded operations)
if specied typ(i) may give the i+1th element formal name
Standard Operations on list work similarly for typed-list:
extraction : [x,y,z...]=l(v) where v is a vector of indices; [x,y,z]=l(:) extracts all the
elements.
insertion : l(i)=a
deletion : l(i)=null() removes the i-th element of the tlist l.
display
Moreover if typ(2:n+1) are specied, user may point elements by their names
We give below examples where tlist are used.
Linear systems are represented by specic typed-list e.g. a linear system [A,B,C,D] is rep-
resented by the tlist Sys=tlist(['lss';'A';'B';'C';'D';'X','dt']),A,B,C,D,x0,'c') and
this specic list may be created by the function syslin.
Sys(2) or Sys('A') is the state-matrix
A rational matrix H is represented by the typed-list H=tlist(['r';'num';'den';'dt'],Num,Den)
where Num and Den are two polynomial matrices and a (e.g. continuous time) linear system with
transfer matrix H maybe created by syslin('c',H).
H(2) or H('num') is the transfer matrix numerator
See Also : null, percent, syslin, list
1.0.125 type variable type
CALLING SEQUENCE :
[i]=type(x)

PARAMETERS :
Scilab Group April 1993 56
unix s Scilab Function
x : Scilab object
i : integer
DESCRIPTION :
type(x) returns an integer which is the type of x as following :
1 : real or complex constant matrix.
2 : polynomial matrix.
4 : boolean matrix.
5 : sparse matrix.
10 : matrix of character strings.
11 : un-compiled function.
13 : compiled function.
14 : function library.
15 : list.
16 : typed list (tlist)
128 : pointer
See Also : typeof
1.0.126 unix shell (sh) command execution
CALLING SEQUENCE :
unix(command-name)

DESCRIPTION :
Sends a string command-name to Unix for execution by the sh shell. Standard output and standard
errors of the shell command are written in the calling shell.
EXAMPLE :
unix("ls $SCI/demos");
unix("emacs $SCI/demos/wheel2/Makefile");
deff('wd=pwd()','unix(''pwd>/tmp/path'');wd=read(''/tmp/path'',1,1,''(a)'')')
wd=pwd()

See Also : edit , manedit , unix_g , unix_s , unix_w , unix_x

1.0.127 unix g shell (sh) command execution, output redirected to a

variable
CALLING SEQUENCE :
rep=unix_g(cmd)

PARAMETERS :
cmd : a character string
rep : a column vector of character strings
DESCRIPTION :
Sends a string cmd to Unix for execution by the sh shell. The standard output is redirected to
scilab variable rep. Unix execution errors are trapped; *NOTE* that only the last shell command
error is reported when a list of command separated by ";" is sent: this is not recommanded.
EXAMPLE :
unix_g("ls $SCI/demos");
deff('wd=pwd()','wd=unix_g(''pwd'')')
wd=pwd()

See Also : edit , manedit , unix_s , unix_w , unix_x , unix

Scilab Group April 1993 57

user Scilab Function
1.0.128 unix s shell (sh) command execution, no output
CALLING SEQUENCE :
rep=unix_s(cmd)

PARAMETERS :
cmd : a character string
DESCRIPTION :
Sends a string cmd to Unix for execution by the sh shell. The standard output is redirected to
/dev/null. Unix execution errors are trapped; *NOTE* that only the last shell command error is
reported when a list of command separated by ";" is sent: this is not recommanded.
EXAMPLE :
unix_s("rm foo");

See Also : edit , manedit , unix_g , unix_w , unix_x , unix

1.0.129 unix w shell (sh) command execution, output redirected to

scilab window
CALLING SEQUENCE :
rep=unix_w(cmd)

PARAMETERS :
cmd : a character string
rep : a column vector of character strings
DESCRIPTION :
Sends a string cmd to Unix for execution by the sh shell. The standard output is redirected to
scilab window. Unix execution errors are trapped; *NOTE* that only the last shell command error
is reported when a list of command separated by ";" is sent: this is not recommanded.
EXAMPLE :
unix_w("ls $SCI/demos");

See Also : edit , manedit , unix_g , unix_s , unix_x , unix

1.0.130 unix x shell (sh) command execution, output redirected to a

window
CALLING SEQUENCE :
unix_x(cmd)

PARAMETERS :
cmd : a character string
DESCRIPTION :
Sends a string cmd to Unix for execution by the sh shell. The standard output is redirected to a
xless window. Unix execution errors are trapped; *NOTE* that only the last shell command error
is reported when a list of command separated by ";" is sent: this is not recommanded.
EXAMPLE :
unix_x("ls $SCI/demos");

See Also : edit , manedit , unix_g , unix_s , unix_w , unix

Scilab Group April 1993 58

where Scilab Function
1.0.131 user interfacing a fortran routine
CALLING SEQUENCE :
[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)

DESCRIPTION :
With this command it is possible to use an external program as a Scilab command where
(s 1,s 2,...,s lhs) are the output variables and (e 1,e 2,...,e rhs) are the input variables.
To insert this command in Scilab one has to write a few lines in the user fortran subroutine of
Scilab. See intersci or the Scilab documentation for more information.
See Also : fort, link
1.0.132 varn symbolic variable of a polynomial
CALLING SEQUENCE :
[symb]=varn(p)
[pm]=varn(x,var)

PARAMETERS :
p : polynomial (or matrix polynomial)
symb : character string
x : polynomial or polynomial matrix
var : symbolic variable (character string)
pm : matrix or polynomial matrix
DESCRIPTION :
symb=varn(p) returns in symb the symbolic variable of the polynomial p (i.e. varn(poly(0,'x'))
is 'x').
varn(x,'s') returns a polynomial matrix with same coecients as x but with 's' as symbolic
variable (change of variable name).
EXAMPLE :
s=poly(0,'s');p=[s^2+1,s];

varn(p)is the string 's' and varn(p,'x') is the polynomial matrix [x^2+1,x]
See Also : horner, poly
1.0.133 what list the Scilab primitives
DESCRIPTION :
List of low level primitives and commands.

1.0.134 where get current instruction calling tree

CALLING SEQUENCE :
[linenum,mac]=where()

PARAMETERS :
linenum : column vector of integer
mac : column vector of strings
Scilab Group May 1994 59
writb Scilab Function
DESCRIPTION :
returns linenum and mac such as current instruction has been called by the linenum(1) line of
function mac(1), mac(1) has been called by the linenum(2) line of function mac(2) and so on
mac(i) is in general the name of a function but it may also be "exec" or "execstr" if instruction
lies in ans exec le or an execstr instruction
See Also : whereami pause
EXAMPLE :

1.0.135 whereami display current instruction calling tree

CALLING SEQUENCE :
whereami()

DESCRIPTION :
Displays calling tree to instruction which contain whereami(). May be uses within pause levels.
EXAMPLE :
deff('y=test(a)',['y=sin(a)+1';
'y=t1(y)';
'y=y+1'])
deff('y=t1(y)',['y=y^2';'whereami()'])
test(1)

See Also : where , pause

1.0.136 whereis name of library containing a function

CALLING SEQUENCE :
[librname]=whereis(macro-name)

DESCRIPTION :
returns as a character string the name of the library containing the function macro-name. The
path of the library is returned by typing "librname".
See Also : lib
1.0.137 while while keyword
DESCRIPTION :
while clause. Must be terminated by
"end"
while expr ,instruction1,instruction2,...,end
while expr do instruction1,instruction2,...,end
while expr then instruction1,instruction2,...,end Notes:
- The only constraint is that each "then" or "do" keyword must be on the same line line as
"while" keyword.
- The "keyword "then" or "do" can be replaced by a carriage return or a comma.
EXAMPLE :
e=1; a=1; k=1;
while norm(a-(a+e),1) > %eps, e=e/2; k=k+1; end
e,k

See Also : for , select , break, return , pause

Scilab Group April 1993 60

write Scilab Function
1.0.138 who listing of variables
DESCRIPTION :
Returns current variables.
1.0.139 writb binary write
CALLING SEQUENCE :
writb('file-name',a)

DESCRIPTION :
writes in binary format the matrix a in the le 'filename'.
See Also : file, readb, write
1.0.140 write write in a formatted le
DESCRIPTION :
write(file-desc,a,[format])
write(file-desc,a,k,format)

PARAMETERS :
file-desc : character string specifying the le name or integer value specifying logical unit (see
le).
a : real matrix or column vector of character strings.
format : character string, species a "fortran" format. This character string must begin with a
right parenthesis and end with a left parenthesis. Formats cannot mix oating point , integer
or character edition modes
k : integer vector

DESCRIPTION :
writes row-by-row a real matrix or a column vector of character strings in a formatted le. Each
row of the a argument begin in a new line of file-desc le. Depending on format a given row
of the a argument may be written in more than one line of file-desc le.
Format examples : (1x,e10.3,5x,3(f3.0)) , (10x,a20) ;
See a Fortran book for more precision.
Direct access les : x=write(file desc,a,k,format). Here k is the vector of records (one record
by row, i.e. m=prod(size(k))
write(%io(2),....) writes on Scilab's window.
EXAMPLE :
unix('rm asave')
A=rand(5,3); write('asave',A); A=read('asave',5,3);
write(%io(2),A,'('' | '',3(f10.3,'' | ''))')
write(%io(2),string(1:10))
write(%io(2),strcat(string(1:10),','))
write(%io(2),1:10,'(10(i2,3x))')

unix('rm foo')
write('foo',A)

See Also : file , writb , read, print , string , ,

fprintf ,
printf sprintf

Scilab Group April 1993 61

write Scilab Function

Scilab Group April 1993 62

Chapter 2

Graphic Library

63
graphics Scilab Function
2.0.141 Graphic Graphic library for Scilab
DESCRIPTION :
GENERAL PLOTTING
plot3d : 3d plotting of a matrix of point.
plot3d1 : 3d plotting of a matrix of point with gray levels.
fplot3d : 3d plotting of a surface described by a function
fplot3d1 : 3d plotting of a surface described by a function with gray levels
plot2d : for 2d plotting plot2d1,plot2d2,plot2d3,plot2d4
fplot2d : 2d plotting of a a curve described by a function
errbar : adds error bars on a plot2d graphic
xgrid : adds a grid on a 2d graphic.
xtitle : adds title and axis names on a 2d graphic
param3d : plots curves in 3d space
stair2d : 2d piece-size constant plotting.
champ : vector eld in R2
fchamp : for a vector eld in R2 dened by a function
contour : level curves for a 3d function given by a matrix.
grayplot10 : gray level on a 2d plot
fcontour10 : level curves for a 3d function given by a function.
fgrayplot10 : gray level on a 2D plot
xchange : scale conversion between plot2d and pixels
gr menu : small interactive editor
hist3d : 3d histogram
xrpoly : graphic display of a regular polygon
titlepage : graphic title page
POLYLINES PLOTTING
xpoly : draws a polyline
xpolys : draws a set of polylines
xfpoly : lls a polygon
xfpolys : lls a set of polygons
SEGMENTS PLOTTING
xsegs : draws a set of unconnected segments.
ARROWS PLOTTING
xarrows : draws a set of unconnected arrows.
RECTANGLES PLOTTING
xrect : draws a single rectangle
xfrect : lls a single rectangle
xrects : lls or draws a set of rectangles
ARCS PLOTTING
xarc : draws an ellipsis
xfarc : lls an ellipsis
xarcs : lls or draws a set of ellipsis.
STRINGS
xstring : draws a string or a matrix of strings.
xstringl : computes a rectangle which surrounds a string
xstringb : draws a string in a specied box
xnumb : draws a set of numbers
AXIS DRAWING
xaxis : draws an axis.
UTILITIES
secto3d : Conversion of a surface description from sector to plot3d compatible data.
eval3d : evaluates a function on a regular grid. (see also feval)
COORDINATES TRANSFORMS
Scilab Group April 1993 64
black Scilab Function
isoview : isometric scale.
square : isometric scale.
scaling : scaling on datas
rotate : rotation
xgetech,xsetech : change of scale inside the graphic window (not fully released).
RECORDING
xtape : record graphic instructions
PRINTING AND REDISPLAY
xbasc : clears window and recorded graphics
xbasimp : redisplays graphics to postscript printer
xbasr : redisplays graphics
GRAPHICS PRIMITIVES
X-window and Postscript graphic primitives
driver : to select a graphic driver
xinit : to initialise a graphic driver
xclear : clears one or more graphic windows
xpause : a pause in milliseconds.
xselect : raises the current graphic window.
xclick : waits for a mouse click
xclea : clears a rectangular zone inside the current graphic window.
xend : closes a graphic session.
GRAPHIC CONTEXT
xset : to set graphic context values
xget : to get informations on the current graphic context
xlfont : to load a new family of fonts from the X-Window Manager

Author : J.Ph C
2.0.142 black Black's diagram (Nichol's chart)
CALLING SEQUENCE :
black( sl,[fmin,fmax] [,step] [,comments] )
black( sl,frq [,comments] )
black(frq,db,phi [,comments])
black(frq,repf [,comments])

PARAMETERS :
sl : list ( linear system syslin)
fmin,fmax : real scalars (frequency bounds)
frq : row vector or matrix (frequencies)
db,phi : row vectors or matrices (modulus, phase)
repf : row vectors or matrices (complex frequency response)
step : real
comments : string
DESCRIPTION :
Black's diagram (Nichols'chart) for a linear system sl. sl can be a continuous-time or discrete-
time SIMO system (see syslin). In case of multi-output the outputs are plotted with dierent
symbols.
The frequencies are given by the bounds fmin,fmax (in Hz) or by a row-vector (or a matrix for
multi-output) frq.
step is the ( logarithmic ) discretization step. (see calfrq for the choice of default value).
comments is a vector of character strings (captions).
db,phi are the matrices of modulus (in Db) and phases (in degrees). (One row for each response).

Scilab Group April 1993 65

champ Scilab Function
repf matrix of complex numbers. One row for each response.
To plot the grid of iso-gain and iso-phase of y/(1+y) use chart().
Default values for fmin and fmax are 1.d-3, 1.d+3 if sl is continuous-time or 1.d-3, 0.5 if sl
is discrete-time.
EXAMPLE :
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
chart();
sstr='(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)';
black(h,0.01,100,sstr);
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
black([h1;h],0.01,100,['h1';'h'])

See Also : bode, nyquist , chart , freq , repfreq , calfrq , phasemag

2.0.143 bode Bode plot

CALLING SEQUENCE :
bode(sl,[fmin,fmax] [,step] [,comments] )
bode(sl,frq [,comments] )
bode(frq,db,phi [,comments])
bode(frq, repf [,comments])

PARAMETERS :
:
sl syslin list (SISO or SIMO linear system) in continuous or discrete time.
fmin,fmax : real (frequency bounds (in Hz))
step : real (logarithmic step.)
comments : vector of character strings (captions).
frq : row vector or matrix (frequencies (in Hz) ) (one row for each SISO subsystem).
db : row vector or matrix ( magnitudes (in Db)). (one row for each SISO subsystem).
phi : row vector or matrix ( phases (in degree)) (one row for each SISO subsystem).
repf : row vector or matrix of complex numbers (complex frequency response).
DESCRIPTION :
Bode plot, i.e magnitude and phase of the frequency response of sl.
sl can be a continuous-time or discrete-time SIMO system (see syslin). In case of multi-
output the outputs are plotted with dierent symbols.
The frequencies are given by the bounds fmin,fmax (in Hz) or by a row-vector (or a matrix for
multi-output) frq.
step is the ( logarithmic ) discretization step. (see calfrq for the choice of default value).
comments is a vector of character strings (captions).
db,phi are the matrices of modulus (in Db) and phases (in degrees). (One row for each response).
repf matrix of complex numbers. One row for each response.
Default values for fmin and fmax are 1.d-3, 1.d+3 if sl is continuous-time or 1.d-3, 0.5 if sl
is discrete-time. Automatic discretization of frequencies is made by calfrq.
EXAMPLE :
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
title='(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)';
bode(h,0.01,100,title);
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
bode([h1;h],0.01,100,['h1';'h'])

See Also : black , nyquist , freq , repfreq , g_margin , p_margin , calfrq , phasemag

Scilab Group April 1993 66

chart Scilab Function
2.0.144 champ draw a 2d vector eld
CALLING SEQUENCE :
champ(x,y,fx,fy [,arfact,rect,strf])
champ1(x,y,fx,fy [,arfact,rect,strf])

PARAMETERS :
x,y : two vectors which dene the grid.
fx : a matrix which describes the x component of the vector eld. fx(i,j) is the x component
of the vector eld at point (x(i),y(j)).
fy : a matrix which describes the y component of the vector eld. fy(i,j) is the y component
of the vector eld at point (x(i),y(j)).
arfact : an optional argument of type real which gives a scale factor for the display of the arrow
heads on the plot (default value is 1.0)
rect : a vector rect=[xmin,ymin,xmax,ymax] which gives the boundaries of the graphic frame
to use.
strf : is a string of length 3 "xyz" which has the same meaning as the strf parameter of plot2d.
The parameter "x" has no eect with champ.
DESCRIPTION :
champ draws a 2d vector eld. If ones uses champ the length of the arrows are proportional to
the eld intensity and if one uses champ1 (with a color screen) the color of the arrow depends on
the intensity of the eld.
Enter the command champ() to see a demo.
EXAMPLE :
// using rect has graphic boundaries
champ(-5:5,-5:5,rand(11,11),rand(11,11),1,[-10,-10,10,10],"011");
xgrid();
xbasc();
// using (x,y) to get boundaries
champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021");
// using coloured arrows
xset("use color",1)
champ1(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021");

Author : J.Ph.C.
2.0.145 chart Nichols chart
CALLING SEQUENCE :
chart([flags])
chart(gain [,flags])
chart(gain,phase [,flags])

PARAMETERS :
gain : real vector ( gains (in DB))
phase : real vector (phases (in degree))
flags : a list of at most 4 ags list(sup [,leg [,cm [,cphi]]])
sup : 1 indicates superposition on the previous plot 0 no superposition is done
leg : 1 indicates that legends are drawn, o: no legends
cm : color number (see plot2d) for gain curves
cphi : color number (see plot2d) for phase curves

Scilab Group April 1993 67

driver Scilab Function
DESCRIPTION :
plot the Nichols'chart.
The default values for gain and phase are respectively :
[-12 -8 -6 -5 -4 -3 -2 -1.4 -1 -.5 0.25 0.5 0.7 1 1.4 2 2.3 3 4 5 6 8 12]
[-(1:10) , -(20:10:160)]
EXAMPLE :
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
black(h,0.01,100,'(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)')
chart(list(1,0,-2,-3));

Another example :
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
black([h1;h],0.01,100,['h1';'h'])
chart([-8 -6 -4],[80 120],list(1,0));

2.0.146 contour level curves of surface

CALLING SEQUENCE :
contour(x,y,z,nz,[theta,alpha,caption,flag,bbox,zlev])

PARAMETERS :
x,y : two real vectors of size respectively (1,n1) and (1,n2).
z : real matrix of size (n1,n2) (values)
nz : real vector of size > 1 (the level values) or an integer ( the number of level curves ).
flag : is a real vector of size three [mode,type,box]
zlev : real number
[rest] : see plot3d
DESCRIPTION :
Draws level curves of a surface z=f(x,y). The other arguments are optional, they are the same as
for the function plot3d (exept zlev) and their meaning are the same. They control the drawing
of level curves on a 3D plot. Only flag(1)=mode has a special meaning.
mode=0 : the level curves are drawn on the surface dened by (x,y,z)
mode=1 : the level curves are drawn on a 3D plot and on the plan dened by equation
z=zlev
mode=2 : The level curves are drawn on a 2D plot.

Enter the command contour() to see a demo.

See Also : fcontour
Author : J.Ph.C..
2.0.147 driver select a driver for plotting
CALLING SEQUENCE :
driver(driver_name)
curent_driver=driver()

PARAMETERS :
driver name : string (driver to be selected).
Scilab Group April 1993 68
eval3dp Scilab Function
DESCRIPTION :
This function is used to select a graphic driver, or with no arguments to get the current driver
name. Most of the time, a user can ignore this function and change its driver by calling high level
functions such as xbasc or xbasimp. The selected driver can be one of the following :
"X11" : an X Window driver.
"Pos" : a Postscript driver.
"Rec" : an X Window driver (X11) which also records all the graphic commands. this is the
default driver.
"Fig" : an XFig driver ( not fully released )

See Also : , ,
xtape xbasc xbasimp
Author : J.Ph.C.

2.0.148 errbar add error tic on a graphic

CALLING SEQUENCE :
errbar(x,y,em,ep)

PARAMETERS :
x,y,em,ep : four matrices of the same size.
DESCRIPTION :
Used to add vertical error bars on a 2D plot. x and y have the same meaning as in plot2d;
em(i,j) and ep(i,j) stands for the error interval on the value y(i,j)
[y(i,j)-em(i,j),y(i,j)+ep(i,j)]
Enter the commanderrbar() to see a demo.
EXAMPLE :
x=0:0.1:2*%pi;
y=[sin(x);cos(x)]';x=[x;x]';plot2d(x,y);
errbar(x,y,0.05*ones(x),0.03*ones(x));

Author : J.Ph.C..

2.0.149 eval3d values of a function on a grid

CALLING SEQUENCE :
[z]=eval3d(fun,x,[y])

PARAMETERS :
fun : function accepting vectors as arguments.
x,y : 2 vectors of size (1,n1) and (1,n2). (default value for y : ).
y=x
z : matrix of size (n1,n2).
DESCRIPTION :
this function returns a matrix z(n1,n2). z(i,j)=fun(x(i),y(j)). If the function fun doesn't
accept arguments of type vector use the primitive feval.
See Also : feval
Author : Steer S.
Scilab Group September 1994 69
fchamp Scilab Function
2.0.150 eval3dp computes facets of a 3D parametrized surface
CALLING SEQUENCE :
[x,y,z]=eval3dp(fun,p1,p2)

PARAMETERS :
fun : a function [X,Y,Z]=fun(p1,p2) which may compute the coordinate of the surface for each
values of the parameters p1 p2 [X(i),Y(i),Z(i)]=fun(p1(1),p2(i)
p1 : a vector of size n
p2 : a vector of size m
x,y,z : 4x(n*n) matrices

DESCRIPTION :
Computes a set of facets for a 3d parametrized surface
EXAMPLE :
deff('[x,y,z]=scp(p1,p2)',['x=p1.*sin(p1).*cos(p2)';
'y=p1.*cos(p1).*cos(p2)';
'z=p1.*sin(p2)'])
[x,y,z]=eval3dp(scp,0:0.3:2*%pi,-%pi:0.3:%pi);

See Also : eval3dp plot3d

2.0.151 evans Evans root locus

CALLING SEQUENCE :
evans(syst [,kmax])

PARAMETERS :
syst : list (linear system syslin )
kmax : real (maximum gain desired for the plot )

DESCRIPTION :
gives the Evans root locus for a linear system in state-space or transfer form (syslin list)
EXAMPLE :
h=syslin('c',352*poly(-5,'s')/poly([0,0,2000,200,25,1],'s','c'));
evans(h,100)

2.0.152 fac3d complex 3D surface plotting

CALLING SEQUENCE :
fac3d(x,y,z[,theta,alpha,leg,flag,ebox])
fac3d1(x,y,z[,theta,alpha,leg,flag,ebox])

PARAMETERS :
x,y,z : matrices of sizes (nf,n1) (facets coordinates). nf :facets size, n1: number of facets
rest : see plot3d.
DESCRIPTION :
Draw the surface dened by a set of n1 facets of coordinates x(:,i), y(:,i), z(:,i) i=1:n1
Enter the command fac3d() to see a demo.
See Also : plot3d, eval3dp, genfac3d.
Scilab Group April 1993 70
fcontour Scilab Function
2.0.153 fchamp draw a 2d vector eld
CALLING SEQUENCE :
fchamp(f,t,xr,yr,[arfact,brect,strf])

PARAMETERS :
f : a function which describes the vector eld.
- It can be a function name f, where f is supposed to be a function of type [y]=f(t,x,[u])
( f returns a column vector of dimension 2, y, which gives the value of the vector eld
f at point x and time t.
- It can also be an object of type list, list(f1,u1) where f1 is a function (f [y]=f1(t,x,u)
) and u1 gives the value of the parameter u.
t : The selected time.
xr,yr : two vectors of size (1,n1) (1,n2) which species the grid on which the vector eld is to
be computed.
arfact,brect,strf : optional arguments, see champ.

DESCRIPTION :
the fchamp is used to draw a two dimensional vector eld described by a a Scilab external.
Enter the command champ() to see a demo.
EXAMPLE :
deff('[xdot] = derpol(t,x)',['xd1 = x(2)';
"xd2 = -x(1) + (1 - x(1)**2)*x(2)";
"xdot = [ xd1 ; xd2 ]"]);
xf= -1:0.1:1;
yf= -1:0.1:1;
fchamp(derpol,0,xf,yf);
xbasc();
fchamp(derpol,0,xf,yf,1,[-2,-2,2,2],"011");

Author : J.Ph.C.

2.0.154 fcontour level curves

CALLING SEQUENCE :
fcontour(xr,yr,f,nz,[theta,alpha,caption,flag,bbox,zlev])

PARAMETERS :
xr,yr : two real vectors of size respectively (1,n1) and (1,n2).
f : is an external which gives the analytic expression of the surface. z=f(x,y) is rst computed
on the grid specied by xr.yr. Then, control is passed to the routine contour.
nz : species the level values or number.

- If nz is of size 1, its value considered as an integer gives the number of level curves equally
spaced from zmin to zmax.
- If nz is a vector, nz(j) gives the value of the jth level curve.
[rest] : for theta,alpha,caption, bbox see plot3d
flag : real vector of size 3 ; flag=[mode,type,box]; flag(2) and flag(3) are the same as in
plot3d; flag(1) has the following meaning :

flag(1)=0 : the level curves are drawn on the surface dened by (x,y,z)

Scilab Group April 1993 71

fplot3d Scilab Function
flag(1)=1 : the level curves are drawn on a 3D plot and on the plan dened by equation
z=zlev
flag(1)=2 : The level curves are drawn on a 2D plot.
DESCRIPTION :
Draws the level curves of a surface z=f(x,y)
Enter the command fcontour() to see a demo.
Author : J.Ph.C..

2.0.155 fgrayplot 2D plot with gray levels

CALLING SEQUENCE :
fgrayplot(x,y,f,[strf,rect,nax])

PARAMETERS :
x,y : real vectors of size respectively (1,n1) and (1,n2).
f : an external (analytic expression of the surface)
strf,rect,nax : optional arguments, ( see plot2d)
DESCRIPTION :
2D plot of a surface using gray levels; f gives the analytic expression of the surface. z=f(x,y) is
rst computed on the grid specied by xr.yr then control is passed to the routine grayplot.
Enter the Scilab command fgrayplot() to see a demo.
EXAMPLE :
deff('[z]=surf(x,y)','z=x**2+y**2');
fgrayplot(-1:0.1:1,-1:0.1:1,surf,"111",[-2,-2,2,2]);

Author : J.Ph.C..

2.0.156 fplot2d 2D plot of a curve dened by an external

CALLING SEQUENCE :
fplot2d(xr,f,[style,strf,leg,rect,nax])

PARAMETERS :
xr : vector of size (n1,1).
f : external (of type [y]=f(x))
[rest] : see plot2d

DESCRIPTION :
The curve is approximated by a piecewise linear interpolation using the points (xr(i),f(xr(i)).
Enter the command fplot2d() to see a demo.
EXAMPLE :
deff("[y]=f(x)","y=sin(x)+cos(x)");
fplot2d((0:0.1:10)*%pi/10,f);

Author : J.Ph.C..
Scilab Group April 1993 72
gainplot Scilab Function
2.0.157 fplot3d 3D plot of a surface dened by an external
CALLING SEQUENCE :
fplot3d(xr,yr,f,[theta,alpha,leg,flag,ebox])

PARAMETERS :
xr : matrix of size (1,n1)
yr : matrix of size (1,n2).
f : external (
z=f(x,y) )
theta, alpha : real (spherical coordinates in degrees of the observation point)
leg : string (caption for each axis. @ is a eld separator e.g. "X@Y@Z")
flag : real vector of size three flag=[mode,type,box]
mode : integer (treatment of hidden parts)
mode >=2 the hidden parts of the surface are removed and the surface is painted in
gray (from low gray to black according to the value of mode)
mode = 1 The hidden parts of the surface are drawn
mode <= 0 Only the shadow of the surface is painted with a gray level depending on
mode
type : Scaling
if type = 0 the plot is made using the current 3D scaling ( set by a previous call to
param3d, plot3d, contour, plot3d1
if type = 1, the value of
ebox=[xmin,xmax,ymin,ymax,zmin,zmax] species the
boundaries
else the boundaries are computed with the given datas.
box : frame display around the plot.
box=0 : Nothing is drawn around the plot
box=1 :not implemented
box=2 : only the axes behind the surface are drawn
box=3 : a box surrounding the surface is drawn and captions are added

DESCRIPTION :
This routines plots a surface dened by an external f. the values of f on the grid dened by
xr.yr are rst computed using feval, then control is passed to the primitive plot3d.
Enter the command fplot3d() to see a demo.
Author : J.Ph.C.

2.0.158 fplot3d1 gray level plotting of a surface

CALLING SEQUENCE :
fplot3d1(xr,yr,f [,theta,alpha,leg,flag,ebox])

PARAMETERS :
( ) : see fplot3d
DESCRIPTION :
This routines plots a surface dened by an external f. the value of f on the grid dened by xr.yr
is rst computed using feval, then control is passed to the primitive plot3d1.
Enter the command fplot3d1() to see a demo.
Author : J.Ph.C.
Scilab Group April 1993 73
geom3d Scilab Function
2.0.159 gainplot magnitude plot
CALLING SEQUENCE :
gainplot(sl,fmin,fmax [,step] [,comments] )
gainplot(frq,db,phi [,comments])
gainplot(frq, repf [,comments])

PARAMETERS :
sl : list (
syslin SIMO linear system).
fmin,fmax : real scalars (frequency interval).
step : real (discretization step (logarithmic scale))
comments : string
frq : matrix (row by row frequencies)
db,phi : matrices (magnitudes and phases corresponding to frq)
repf : complex matrix. One row for each frequency response.
DESCRIPTION :
Same as Bode but plots only the magnitude.
EXAMPLE :
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
gainplot(h,0.01,100,'(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)')
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
gainplot([h1;h],0.01,100,['h1';'h'])

See Also : bode, black , nyquist , freq , repfreq , g_margin , p_margin

2.0.160 genfac3d convert 3d datas to four sides facets

CALLING SEQUENCE :
[xx,yy,zz]=genfac3d(x,y,zmat [,mask])

PARAMETERS :
zmat : matrix , zmat(i,j)= F(x(j),y(i))
x :x axis coordinates vector
y :y axis coordinates vector
mask : boolean optional matrix with same size as zmat used to select entries of zmat to be
represented by facets
xx,yy,zz :4xn matrices. xx(:,i),yy(:,i),zz(:,i) are respectively the x-axis,y-axis and z-axis coor-
dinates of the ith facet
DESCRIPTION :
Converts 3d datas to facets representation
EXAMPLE :
t=(0:0.3:2*%pi)';
zmat=sin(t)*cos(t');
plot3d(t,t,zmat)
[xx,yy,zz]=genfac3d(t,t,zmat);
plot3d(xx,yy,zz)
plot3d([xx xx],[yy yy],[zz 4+zz])

See Also : plot3d , eval3dp.

Scilab Group April 1993 74

graduate Scilab Function
2.0.161 geom3d projection from 3D on 2D
CALLING SEQUENCE :
[x,y]=geom3d(x1,y1,z1)

PARAMETERS :
x1,y1,z1 : real matrices of the same size (points in R3)
x,y : real matrices of the same size as x1,y1 or z1
DESCRIPTION :
After having used a 3d plotting function as plot3d, plot3d1 and param3d, this function gives the
correspondence between a point in R3 space (x1(i),y1(i),z1(i)) and the corresponding point
in the projected graphic plan (x(i),y(j)). all the graphical primitives working on (x,y) can then
be used for superposition on a plot3d
EXAMPLE :
deff("[z]=surf(x,y)","z=sin(x)*cos(y)");
t=%pi*(-10:10)/10;
fplot3d(t,t,surf,35,45,"X@Y@Z");
//Gives a plot3d
//now (t,t,sin(t).*cos(t) ) is a curve on the surface
//which can be drawn using param3d or the following code
[x,y]=geom3d(t,t,sin(t).*cos(t));
xpoly(x,y,"lines")
//adding a comment
[x,y]=geom3d([0,0],[0,0],[5,0]);
xsegs(x,y);
xstring(x(1),y(1)," The point (0,0,0)");

Author : J.Ph.C.

2.0.162 gr menu simple interactive graphic editor

CALLING SEQUENCE :
[sd1]=gr_menu([sd,flag])

PARAMETERS :
sd : list (output of gr menu), or vector of length four [xmin,ymin,xmax,ymax] (boundaries of
the plot).
sd1 : list (graphical objects created under gr menu

DESCRIPTION :
gr menu is a simple interactive graphic editor. The created graphics are saved as a list which can
be given to gr menu as an entry value.
[sd]=gr menu([xmin,ymin,xmax,ymax]) : enters gr menu with a xed frame
[sd]=gr menu(); : enters gr menu with the xed frame [0 0 100 100].
[sd]=gr menu(sd) : redraws the graphics stored in sd and enters interactive mode [sd]=gr menu(sd,1)
: only draws the graphics stored in sd.
Author : S.S. & J.Ph.C.
Scilab Group November 1993 75
hist3d Scilab Function
2.0.163 graduate pretty axis graduations
CALLING SEQUENCE :
[xi,xa,np]=graduate( xmi, xma,n1,n2)
[xi,xa,np]=graduate( xmi, xma)

PARAMETERS :
xmi,xma : real scalars
n1, n2 : integers with default values 3,10
xi, xa :real scalars
np : integer
DESCRIPTION :
graduat looks for the minimum interval [xi,xa] and a number of tics np such that:
xi <= xmi <= xma <= xa
xa - xi / np = k(10^n),k in [1 3 5] for an integer n
n1 < np < n2
EXAMPLE :
y=(0:0.33:145.78)';
xbasc();plot2d1('enn',0,y)
[ymn,ymx,np]=graduate(mini(y),maxi(y))
rect=[1,ymn,prod(size(y)),ymx];
xbasc();plot2d1('enn',0,y,-1,'011',' ',rect,[10,3,10,np])

See Also : xsetech , plot2d

Author : S. Steer 1992

2.0.164 grayplot 2D plot of a surface using gray levels

CALLING SEQUENCE :
grayplot(x,y,z,[strf,rect,nax])

PARAMETERS :
x,y : real vectors of size respectively (1,n1) and (1,n2).
z : real matrix of size (n1,n2) (values of f)
strf,rect,nax : optional arguments, ( see plot2d)
DESCRIPTION :
The surface is given by values z(i,j)=f(x(i),y(j)) on a grid dened by x,y. Each rectangle
on the grid is lled with a gray level depending on the average value of f on the corners of the
rectangle.
Enter the command grayplot() to see a demo.
EXAMPLE :
x=-10:10;y=-10:10;m=rand(21,21);
grayplot(x,y,m,"111",[-20,-20,20,20]);

Author : J.Ph.C..
Scilab Group April 1993 76
isoview Scilab Function
2.0.165 hist3d 3D representation of an histogram
CALLING SEQUENCE :
hist3d(f [,theta,alpha,leg,flag,ebox])

PARAMETERS :
f : matrix or list :
- matrix f(i,j)= F(x(i),y(j)), x and y taken as 0:m and 0:n, ( (m,n) is the size of f).
- list of size 3; list(f,x,y) where f is a matrix of size (m,n) and x and y two vectors of
size (1,n+1) and (1,m+1)
rest : see plot3d

DESCRIPTION :
3 dimensional representation of an 2d histogram : the values associated to the intervals ([x(i)
x(i+1)[ X [y(i) y(i+1)[) Enter the command hist3d() to see a demo.
See Also : plot3d.
Author : Steer S. & JPhilippe C.
2.0.166 histplot plot an histogram
CALLING SEQUENCE :
histplot(npoint,data,[style,strf,leg,rect,nax])

PARAMETERS :
npoint : integer or a vector of increasing values of size (1,n1)
data : real vector
[rest ] : see plot2d
DESCRIPTION :
- if npoint is an integer, plots an histogram of the values stored in data using npoint-equally
spaced classes.
- if npoint is a vector plots an histogram of the values stored in data using the classes ]xi(k)
xi(k+1)].

Enter the command histplot() to see a demo.

2.0.167 isoview set scales for isometric plot
CALLING SEQUENCE :
isoview(xmin,xmax,ymin,ymax)

PARAMETERS :
xmin,xmax,ymin,ymax : four real values
DESCRIPTION :
isoview(xmin,xmax,ymin,ymax) is used to set the graphic scales in order to have isometric scales
on the X and Y axes. The requested values xmin, xmax, ymin, ymax must be contained in the
computed frame of the graphic window. This function sets the current graphic scales and can be
used in conjunction with graphic routines which request the current graphic scale ( strf="x0y"
in plot2d ). This function does not modify the size of the graphic window.
EXAMPLE :
Scilab Group April 1993 77
milkdrop Scilab Function
xbasc();
t=(0:0.1:2*%pi)';
isoview(-1,1,-1,1);
plot2d(sin(t),cos(t),-1,'001')

See Also : square

Author : Steer S.
2.0.168 locate mouse selection of a set of points
CALLING SEQUENCE :
[x]=locate([n,flag])

PARAMETERS :
n, flag : two integer values
x : vector (2,n1) ( n1=n if the parameter n is given)

DESCRIPTION :
This function is used to get the coordinates of one or more points selected with the mouse on a
graphic window. The coordinates are given using the current graphic scale.
x=locate(n) : if n>0, n points are selected and their coordinates are returned in x(2,n)
x=locate(n) : If n<=0 points are selected until the user click with the left button which stands
for stop. The last point ( clicked with the left button) is not returned.
x=locate() : same as x=locate(-1)
If flag = 1 a cross is drawn at location point each time the mouse is clicked.
See Also : xclick
Author : S.S. & J.Ph.C
2.0.169 m circle M-circle plot
CALLING SEQUENCE :
m_circle()
m_circle(gain)

PARAMETERS :
gain : vector of gains (in DB). The default value is
gain =[-12 -8 -6 -5 -4 -3 -2 -1.4 -1 -.5 0.25 0.5 0.7 1 1.4 2 2.3 3 4 5 6 8 12]

DESCRIPTION :
m circle is used with nyquist.
EXAMPLE :
//Example 1 :
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
nyquist(h,0.01,100,'(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)')
m_circle();
//Example 2:
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
nyquist([h1;h],0.01,100,['h1';'h'])
m_circle([-8 -6 -4]);

See Also : nyquist , chart , black.

Author : S.Steer.
Scilab Group April 1993 78
param3d Scilab Function
2.0.170 milk drop test for plot3d
CALLING SEQUENCE :
[z]=milk_drop(x,y)

PARAMETERS :
x,y : two vectors of size (1,n1) and (1,n2)
z : matrix of size (n1,n2)
DESCRIPTION :
milk drop is a function [z]=milk drop(x,y) which can be used to test the function eval3d
Author : Steer S.
2.0.171 nyquist nyquist plot
CALLING SEQUENCE :
nyquist( sl,[fmin,fmax] [,step] [,comments] )
nyquist( sl, frq [,comments] )
nyquist(frq,db,phi [,comments])
nyquist(frq, repf [,comments])
PARAMETERS :
sl :
syslin list (SIMO linear system in continuous or discrete time )
fmin,fmax : real scalars (frequency bounds (in Hz))
step : real (logarithmic discretization step)
comments : string vector (captions).
frq : vector or matrix of frequencies (in Hz) (one row for each output of sl).
db,phi : real matrices of modulus (in Db) and phases (in degree) (one row for each output of
sl ).
repf : matrix of complex numbers. Frequency response (one row for aech output of sl)
DESCRIPTION :
Nyquist plot i.e Imaginary part versus Real part of the frequency response of sl.
sl can be a continuous-time or discrete-time SIMO system (see syslin). In case of multi-
output the outputs are plotted with dierent symbols.
The frequencies are given by the bounds fmin,fmax (in Hz) or by a row-vector (or a matrix for
multi-output) frq.
step is the ( logarithmic ) discretization step. (see calfrq for the choice of default value).
comments is a vector of character strings (captions).
db,phi are the matrices of modulus (in Db) and phases (in degrees). (One row for each response).
repf matrix of complex numbers. One row for each response.
Default values for fmin and fmax are 1.d-3, 1.d+3 if sl is continuous-time or 1.d-3, 0.5 if sl
is discrete-time.
Automatic discretization of frequencies is made by calfrq.
EXAMPLE :
xbasc();
s=poly(0,'s');
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01));
comm='(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01)';
nyquist(h,0.01,100,comm);
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
xbasc();
nyquist([h1;h],0.01,100,['h1';'h'])
xbasc();nyquist([h1;h])

See Also : bode , black, calfrq, freq , repfreq , phasemag

Scilab Group April 1993 79

plot Scilab Function
2.0.172 param3d set of points or parametric curves in 3-D
CALLING SEQUENCE :
param3d(x,y,z,[theta,alpha,leg,flag,ebox]

PARAMETERS :
x,y,z : three matrices of the same size (considered as vectors with the Fortran storage conven-
tion) (points of the parametric curve)
theta, alpha : gives the coordinates in spherical angle of the observation point
leg : string describing the caption for each axis, the dierent elds in the string are separated
by the symbol @, for example : "X@Y@Z"
flag =[type,box] : where type and box have the same meaning as in plot3d
ebox : a vector of size (1,6) which gives the boundaries of the plot [xmin,xmax,ymin,ymax,zmin,zmax]
when the value of type is 1
DESCRIPTION :
param3d() is used to obtain a graphic of a parametric curve in R3, and can also be used to see
a set of points in R3
Enter the command param3d() to see a demo.
EXAMPLE :
t=0:0.1:5*%pi;
param3d(sin(t),cos(t),t/10,35,45,"X@Y@Z",[2,3])
xbasc();
xset("dashes",-3)
param3d(rand(1,100),rand(1,100),rand(1,100),35,45,"X@Y@Z",[2,3])

Author : J.Ph.C.
2.0.173 param3di parametric curves in 3-D with interactive view
selection
CALLING SEQUENCE :
param3di(x,y,z,[theta,alpha,leg,flag,ebox]

PARAMETERS :
x,y,z : three matrices of the same size (considered as vectors with the Fortran storage conven-
tion) (points of the parametric curve)
theta, alpha : gives the coordinates in spherical angle of the observation point
leg : string describing the caption for each axis, the dierent elds in the string are separated
by the symbol @, for exemple : "X@Y@Z"
flag =[type,box] : where type and box have the same meaning as in plot3d
ebox : a vector of size (1,6) which gives the boundaries of the plot [xmin,xmax,ymin,ymax,zmin,zmax]
when the value of type is 1
DESCRIPTION :
Draw the 3D curve f(x,y) and allow the user to change the view with the mouse :
Pick a point within the graphic window (Left mouse button) and drag the mouse (theta increases
for left to right move and alpha increases for down to up move). When view is ok click with the
left button to have the surface drawn. click right button to exit.
For Pos and Fig drivers plot3di works just like plot3d
Enter the command param3di() to see a demo.
Author : S Steer INRIA
Scilab Group April 1993 80
plot2d Scilab Function
2.0.174 plot simple plot
CALLING SEQUENCE :
plot(x,y,[xcap,ycap,caption])
plot(y,[xcap,ycap,caption])

PARAMETERS :
x,y : two vectors.
caption, xcap, ycap : character strings or string matrices
DESCRIPTION :
plot y as function of x. xcap and ycap are captions for x-axis and y-axis respectively. Invoked
with one argument, plot(y) plots the y vector or, if y is a matrix, its rows.
See Also : plot2d
Author : J.Ph.C..

2.0.175 plot2d multiple plot of functions

CALLING SEQUENCE :
plot2d(x,y,[style,strf,leg,rect,nax])

PARAMETERS :
x,y : two matrices of the same size [nl,nc].
nc : is the number of curves
nl : is the number of points of each curve for example : x=[ 1:10;1:10]',y= [ sin(1:10);cos(1:10)]'
style : is a real vector of size (1,nc). the style to use for curve j is dened by size(j).

- if style[i] is positive the curve is plotted using the mark of Id style[i],

- if style[i] is strictly negative a dashed or plain line of id abs(style[i]) is used.
- When only one curve is drawn style can be of size (1,2) [style,pos] where style is
used to specify the style and pos is an integer in the range 1,6 which species a position
to use for the caption (this can be useful when a user wants to draw multiple curves on
a plot by calling the function plot several times and wants to give a caption for each
curve)
strf : is a string of length 3 "xyz"

x : captions are displayed if x is the character 1. Captions are given by the string leg
"leg1@leg2@...."
y : controls the computation of the frame
y=0 : the current boundaries ( set by a previous call to an other high level plotting
function ) are used.
y=1 : the argument rect is used to specify the boundaries of the plot. rect=[xmin,ymin,xmax,ymax]
y=2 : the boundaries of the plot are computed using max and min values of x and y.
y=3 : like y=1 but produces isoview scaling
y=4 : like y=2 but produces isoview scaling
y=5 : like y=1 but the boundaries and nax can be changed to produce pretty gradua-
tions. This mode is used when the zoom button is activated.
y=6 : like y=2 but the boundaries and nax can be changed to produce pretty gradua-
tions. This mode is used when the zoom button is activated.
z : controls the display of information on the frame around the plot
Scilab Group April 1993 81
plot2d2 Scilab Function
z=1 : an axis is drawn the number of tics can be specied by the nax argument. nax
is a vector with four entries [nx,Nx,ny,Ny] where nx (ny) is the number of subgrads
on the x (y) axis and Nx (Ny) is the number of graduations on the x (y) axis
z=2 : the plot is only surrounded by a box
other value Nothing around the plot

DESCRIPTION :
plot2d simultaneously plot a set of 2D curves which are given by a set of points using piecewise
linear plotting
Enter the command plot2d() to see a demo.
EXAMPLE :
x=0:0.1:2*%pi;
plot2d([x;x;x]',[sin(x);sin(2*x);sin(3*x)]');
plot2d([x;x;x]',[sin(x);sin(2*x);sin(3*x)]',...
[-1,-2,3],"111","L1@L2@L3",[0,-2,2*%pi,2],[2,10,2,10]);
// isoview
plot2d(x',sin(x)',-1,'041')
// auto scale
plot2d(x',sin(x)',-1,'061')

See Also : , , ,
plot2d1 plot2d2 plot2d3 plot2d4
Author : J.Ph.C..

2.0.176 plot2d1 multiple plot of functions

CALLING SEQUENCE :
plot2d1(str,x,y,[style,strf,leg,rect,nax])

PARAMETERS :
str : is a string of length three "abc"
a : can have the following values : e j o j g
e : means empty and species the fact that the value of x won't be used ( the x values
are supposed to be regularly spaced) . The user must anyway give a value to the x
parameter when calling plot2d1, for example plot2d1("enn",1,y).
o : stands for one. if there are many curves, they all have the same x-values ( x is of size
x(n,1) and y of size y(n,n1). for example : plot2d1("onn",(1:10)',[sin(1:10);cos(1:10)]')
g : stands for general. x and y must then have the same size
b,c : can have the values n or l.
b=l : a logarithmic axis is used on the X-axis
c=l : a logarithmic axis is used on the Y-axis

DESCRIPTION :
plot2d1 simultaneously plot a set of 2D curves. Same as plot2d but with one more argument
str which enables logarithmic axis, and less specication for x.
Enter the command plot2d1() to see a demo.
See Also : plot2d
Author : J.Ph.C..
Scilab Group April 1993 82
plot3d Scilab Function
2.0.177 plot2d2 multiple plot of functions (step function)
CALLING SEQUENCE :
plot2d2(str,x,y,[style,strf,leg,rect,nax])

PARAMETERS :
[ ] : see plot2d1 and plot2d for a description of parameters.
DESCRIPTION :
Same as plot2d1 but the functions given by the set of points (x,y) which are to be drawn are
supposed to be piecewise constant.
Enter the command plot2d2() to see a demo.
EXAMPLE :
plot2d2("gnn",(1:4)',(1:4)',-1,'111','step function',[0,0,5,5])

will plot a step function of value i on the segment (i,i+1). the last segment is not drawn.
See Also : plot2d, plot2d1, plot2d3
Author : J.Ph.C..

2.0.178 plot2d3 multiple plot of functions (vertical bars)

CALLING SEQUENCE :
plot2d3(str,x,y,[style,strf,leg,rect,nax])

PARAMETERS :
see plot2d and plot2d1
DESCRIPTION :
Same as plot2d1 but curves are plotted using vertical bars.
Enter the command plot2d3() to see a demo.
See Also : plot2d, plot2d1, plot2d2, plot2d4
Author : J.Ph.C..

2.0.179 plot2d4 multiple plot of functions

CALLING SEQUENCE :
plot2d4(str,x,y,[style,strf,leg,rect,nax])

PARAMETERS :
see plot2d and plot2d1
DESCRIPTION :
Same as plot2d1 but curves are plotted using arrows style. This can be useful when plotting
solutions of ode in a phase space.
Enter the command plot2d4() to see a demo.
See Also : plot2d, plot2d1
Author : J.Ph.C..
Scilab Group April 1993 83
plotframe
2.0.180 plot3d surface plotting
CALLING SEQUENCE :
plot3d(x,y,z,theta,alpha,leg,flag,ebox)
plot3d(x,y,z,theta,alpha,leg,[flag,ebox)]

PARAMETERS :
x,y : matrices of sizes (1,n1) and (1,n2) (point coordinates)
z : matrix of size (n1,n2) ( z(i,j) : value of f at the point (x(i),y(j))
theta, alpha : real values giving in degree the spherical coordinates of the observation point
leg : string (captions for each axis. this is string with @ as a eld separator, for example :
"X@Y@Z")
flag : is a real vector of size three flag=[mode,type,box]

mode : string (treatment of hidden parts)

mode >=2 the hidden parts of the surface are removed and the surface is painted in
gray (from low gray to black according to the value of mode)
mode = 1 the hidden parts of the surface are drawn
mode <= 0 only the shadow of the surface is painted with a gray level depending on
mode
type : scaling
if type = 0 the plot is made using the current 3D scaling ( set by a previous call to
param3d, plot3d, contour, plot3d1)
if type = 1 the boundaries are specied by the value of the parameter
ebox=[xmin,xmax,ymin,ymax,zmin,zmax]
else the boundaries are computed with the given datas.
box : frame display around the plot.
box=0 nothing is drawn around the plot
box=1 unimplemented ( like box=0 )
box=2 only the axes behind the surface are drawn
box=3 a box surrounding the surface is drawn and captions are added
box=4 a box surrounding the surface is drawn, captions are added and axes too.

DESCRIPTION :
Draw the surface f(x,y) dened by a matrix of coordinates.
Enter the command plot3d() to see a demo.
EXAMPLE :
plot3d(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3])

Author : J.Ph.C.
2.0.181 plot3d1 gray level plotting of a surface
DESCRIPTION :
plot3d1(x,y,z,[theta,alpha,leg,flag,ebox])

PARAMETERS :
see plot3d (mode unused)
DESCRIPTION :
plots a surface z=f(x,y) (points)
Enter the command plot3d1() to see a demo.
Author : J.Ph.C.
Scilab October 1994 84
printing Scilab Function
2.0.182 plotframe graphic frame with scaling and grids
CALLING SEQUENCE :
plotframe(rect,tics,flags,captions)

PARAMETERS :
rect : vector [xmin,ymin,xmax,ymax] made of x and y bounds.
tics : vector [nx,mx,ny,my] where mx, nx (resp. my, ny) are the number of x-axis (resp.
y-axis) intervals and subintervals.
flags : vector [wantgrids,findbounds] where wantgrids is a boolean variable (%t or %f)
which indicates gridding. findbounds is a boolean variable. If findbounds is %t, the bounds
given in rect are allowed to be slightly modied in order to have simpler graduations (then
tics(2),tics(4) are ignored).
captions vector of 3 character strings [title, x-leg, y-leg]

DESCRIPTION :
This function is used with plotting functions plot2d, plot2d1,... to set a graphic frame. This
function is used before plot2d... which should be invoked with the "000" superposition mode.
EXAMPLE :
x=[-0.3:0.8:27.3]';
y=rand(x);
rect=[min(x),min(y),max(x),max(y)];
tics=[4,10,2,5]; //4 x-intervals and 2 y-intervals
xbasc();xbasc(1);xset("window",1);xselect();
plotframe(rect,tics,[%f,%f],['My plot','x','y']);
plot2d(x,y,-1,'000')
xbasc(2);xset("window",2);xselect();
plotframe(rect,tics,[%t,%f],['My plot with grids','x','y']);
plot2d(x,y,-1,'000')
xbasc(3);xset("window",3);xselect();
plotframe(rect,tics,[%t,%t],...
['My plot with grids and automatic bounds','x','y']);
plot2d(x,y,-1,'000')
xbasc(4);xset("window",4);xselect();
plotframe(rect,tics,[%f,%t],...
['My plot without grids but with automatic bounds','x','y']);
plot2d(x,y,-1,'000')

See Also : plot2d , graduate, xtitle , plot2d1 , plot2d2

2.0.183 plzr pole-zero plot

CALLING SEQUENCE :
plzr(sl)

PARAMETERS :
sl : list ( syslin)
DESCRIPTION :
produces a pole-zero plot of the linear system sl (syslin list)
EXAMPLE :
Scilab Group April 1993 85
rotate Scilab Function
s=poly(0,'s');
n=[1+s 2+3*s+4*s^2 5; 0 1-s s];
d=[1+3*s 5-s^3 s+1;1+s 1+s+s^2 3*s-1];
h=syslin('c',n./d);
plzr(h);

See Also : trzeros , syspoles , roots , syslin

2.0.184 printing printing scilab graphics

CALLING SEQUENCE :
Blatexpr xscale yscale filename.ps
BEpsf filename.ps
Blpr "Title" filename1.ps filename2.ps ... filenamen.ps | lpr

DESCRIPTION :
The scilab graphics can be saved with the xbasimp command into unix les. The Scilab command
:
xbasimp(xx,'des.ps',0)

will save the graphics recorded in the graphic window xx in the le des.ps.xx. This le can't be
directly send to a Postscript printer and a set of programs ( in the bin Scilab directory ) are given
with Scilab to print it :
BEpsf : The BEpsf command will create an Epsf le from your des.ps.xx under the name
des.epsf, this Epsf le can be printed on a Postscript printer or inserted into an other
Postscript document.
Blatexpr : The Blatexpr command will create an Epsf le from your des.ps.xx

mv des.ps.xx des.ps
Blatexpr 1.0 1.0 des.ps

under the name des.epsf and a LaTeX le des.tex. The le des.tex can be inserted in a
LaTeX le in order to get the latex gure as follows ( the postscript le is inserted with the
special command of LaTeX )

\input des.tex
\dessin{caption}{label}

Blpr : The Blpr command is used to print a set of graphics on a same sheet of paper. For
example to print two graphics on a unique page, one can use :
Blpr "Two graphics" file1.ps.0 file2.ps.1 | lpr

Blatexprs : The Blatexprs command is used to insert in a single LaTeX gure a set of Scilab
Graphics
Blatexprs res file1.ps.0 file2.ps.1

will create two les res.ps and res.tex. The le res.tex is used as in the Blatexpr
command in order to get the gure.
See Also : xbasimp

Scilab Group April 1993 86

square Scilab Function
2.0.185 rotate geometric rotation of a set of points
CALLING SEQUENCE :
[xy1]=rotate(xy,[theta,orig])

PARAMETERS :
xy,xy1 : matrices of size (2,.)
theta : real (angle en radian) , (default value=0)
orig : center of the rotation [0;0] if omitted
DESCRIPTION :
xy1(:,i) = M(theta) *xy(:,i) + orig where M stands for a rotation matrix of angle theta
EXAMPLE :
xsetech([0,0,1,1],[-1,-1,1,1])
xy=[(0:0.1:10);sin(0:0.1:10)]/10;
for i=2*%pi*(0:10)/10,[xy1]=rotate(xy,i);
xpoly(xy1(1,:),xy1(2,:),"lines")
end

2.0.186 scaling ane transform of a set of points

CALLING SEQUENCE :
[xy1]=scaling(xy,factor,orig)

PARAMETERS :
xy,xy1 : matrices of size (2,.)
factor : real scalar (linear transform coef)
orig : shift vector (default value =[0;0] )
DESCRIPTION :
xy1(:,i) = factor *xy(:,i) + orig

2.0.187 secto3d 3D surfaces conversion

CALLING SEQUENCE :
[m[,x]]=secto3d(seclist,npas)
[m]=secto3d(seclist ,x)

PARAMETERS :
seclist : a list whose elements are (2,.) matrices
npas : an integer
m : a matrix
x : a vector
DESCRIPTION :
Considering a surface given through a list seclist of sections in the (x,z) plane [m [,x]]=secto3d(seclist
[,npas]) returns a matrix m which contains a regular discretisation of the surface.
- The i-th row of the matrix m corresponds to the i-th section
- The j-th column of m corresponds to the x(j)

Scilab Group April 1993 87

xarc Scilab Function
Each section seclist(i) is described by a (2,.) matrix which gives respectively the x and z
coordinates of points.
[m]=secto3d(seclist ,x) : in that case the x-vector gives the discretisation of the x-axis for all
the sections
See Also : plot3d
Author : Steer S.

2.0.188 square sets scales for isometric graphics

CALLING SEQUENCE :
square(xmin,ymin,xmax,ymax)

PARAMETERS :
xmin,xmax,ymin,ymax : four real values
DESCRIPTION :
square(xmin,ymin,xmax,ymax) is used to set the graphic scales in order to have isometric scales
on the X and Y axes. The requested values xmin, xmax, ymin, ymax are the boundaries of the
graphic frame and this function changes the graphic window dimensions in order to get an isometric
plot. This function sets the current graphic scales and can be used in conjunction with graphic
routines which request the current graphic scale ( fstrf="x0y" in plot2d ).
See Also : isoview
Author : Steer S.

2.0.189 titlepage display a matrix of strings

CALLING SEQUENCE :
titlepage(str)

PARAMETERS :
str : matrix of strings
DESCRIPTION :
titlepage(str) displays the matrix str in the current graphic window with a size font as large
as possible
See Also : xtitle
Author : S. S.

2.0.190 xarc draws a part of an ellipsis

CALLING SEQUENCE :
xarc(x,y,w,h,a1,a2)

PARAMETERS :
x,y,w,h : real (rectangle def)
a1,a2 : real (angle def)
Scilab Group April 1993 88
xarrows Scilab Function
DESCRIPTION :
Draws a portion of an ellipsis contained in the rectangle (x,y,w,h) ( Upper-Left point, Width,
Height), and in the sector delimited by the angle alpha1 and the angle alpha1+alpha2. alpha1
and alpha2 are given respectively by a1/64 degrees and a2/64 degrees. This function uses the
current graphic state and graphic scale. which can be set by calling a high level drawing function
such as plot2d.
EXAMPLE :
// isoview scaling
plot2d(0,0,-1,"031"," ",[-2,-2,2,2])
xarc(-1,1,2,2,0,90*64)
xarc(-1.5,1.5,3,3,0,360*64)

See Also : ,
xarcs xfarc.
Author : J.Ph.C..
2.0.191 xarcs drawing a set of ellipsis
CALLING SEQUENCE :
[]=xarcs(arcs,[style])

PARAMETERS :
arcs : matrix of size (6,n) (ellipsis description)
style : vector of size (1,n) giving the style to use ( set xset("dashes",...).
DESCRIPTION :
draws a set of ellipsis described by arcs. arcs= [ x,y,w,h,a1,a2 ; x,y,w,h,a1,a2 ;.....]
' : each ellipsis is dened by the 6 parameters (x,y,w,h,a1,a2) (see xarc)
fill(i) gives the dash style which must be used to draw the ellipsis number i.
EXAMPLE :
plot2d(0,0,-1,"031",' ',[-1,-1,1,1])
set_arcs=[ -1.0 0.0 0.5 // upper left x
1.0 0.0 0.5 // upper left y
0.5 0.5 0.5 // widths
0.5 0.5 0.5 // height
0.0 0.0 0.0 // angle 1
360*64 360*64 360*64] // angle 2
xarcs(set_arcs,[0,1,2])

Author : J.Ph.C.
2.0.192 xarrows draw a set of arrows
CALLING SEQUENCE :
[]=xarrows(nx,ny,[arsize,style])

PARAMETERS :
nx : real matrix of size (n1,n2)
ny : real matrix of size (n1,n2)
arsize : real scalar (size of the arrow head). The default value can be obtained by setting arsize
to value -1.0.
Scilab Group April 1993 89
xbasimp Scilab Function
style : a matrix of size n or a scalar. If style is a positive scalar it gives the dash style to
use for all segments, if it is a negative scalar then current dash style is used, if it is a vector
style[i] gives the style to use for segment i.

DESCRIPTION :
This function draws a set of arrows which are given by the vector or matrices nx and ny. The ith
arrow is dened by (nx(i),ny(i))-->(nx(i+1),ny(i+1)). nx, ny can also be matrices :
nx=[ xi_1,x1_2,...; xf_1,xf_2,...]
ny=[ yi_1,y1_2,...; yf_1,yf_2,...]

in which case the arrows are (xi k,yi k)->(xf k,yf k)

This function uses the current graphic scale which can be set by calling a high level drawing
function such as plot2d.
EXAMPLE :
x=2*%pi*(0:9)/8;
x1=[sin(x);9*sin(x)];
y1=[cos(x);9*cos(x)];
plot2d([-10,10],[-10,10],[-1,-1],"022");
xset('clipgrf')
xarrows(x1,y1,1,0:9);
xset('clipoff')

See Also : plot2d , xchange.

Author : J.Ph.C..

2.0.193 xaxis draws an axis

CALLING SEQUENCE :
[]=xaxis(alpha,nsteps,size,init)

PARAMETERS :
alpha : real (slope in degree of the axis)
nsteps : real vector of size 2 (number of big and small intervals)
size : a real vector of size 3 (size of the intervals, the small and big tics)
DESCRIPTION :
Draw an axis in the alpha (in degree ) direction; nsteps ([n1,n2]) gives the number of big and
small intervals separated by tics. size=[s1,s2,c1] : s1 gives the size of the intervals , s2 gives
the size of the small tics along the axis and s2*c1 is the size of the big tics.
ex : n1=3,n2=2,alpha =0
(s2*c1)
| (s2) | | |
|______|_____|_____|______|_____|_____|
s1

Author : J.Ph.C..
Scilab Group April 1993 90
xchange Scilab Function
2.0.194 xbasc clear the recorded graphics associated to a window
CALLING SEQUENCE :
xbasc([win_num])

PARAMETERS :
win num : integer scalar or vector
DESCRIPTION :
clears the graphic window win num and erase the recorded graphics. If win num is omitted, it's
the current graphic window. win num can also be a vector of window Id to clear a set of windows
2.0.195 xbasimp send graphics to a postscript printer or in a le
CALLING SEQUENCE :
xbasimp(win_num,[filen,flag])

PARAMETERS :
win num : an integer scalar or vector
filen : string (Postscript le name). (default value=le). The window number is appended to
the filen.
flag : if ag =0 the les are created but not printed.

DESCRIPTION :
This function will send the recorded graphics of the window win num in the Postscript le filen
and will print the Postscript le with the command Blpr. This function will work only if the
selected driver is "Rec"
If fwin num is a vector several les are generated,one for each selected window (with names
filenxx), and the les are printed on a unique page with the command Blpr,
The window number is appended to filen.
See Also : printing
2.0.196 xbasr redraw a graphic window
CALLING SEQUENCE :
xbasr(win_num)

DESCRIPTION :
This function is used to redraw the content of the graphic window of id win num. It works only
with the driver "Rec".
See Also : xtape, driver
Author : J.Ph.C.
2.0.197 xchange coordinates transform
CALLING SEQUENCE :
[x1,y1,rect]=xchange(x,y,dir)

PARAMETERS :
x,y : two matrices of size (n1,n2) (coordinates of a set of points)
x1,y1 : two matrices of size (n1,n2) (coordinates of the set of points )
Scilab Group April 1993 91
xclick Scilab Function
rect : a vector of size 4 (values in pixel of the coordinates of the rectangle in which the scale
was xed)
DESCRIPTION :
After having used a graphic function, this function allows one to change real coordinates into pixel
coordinates and vice-versa, according to the value of the parameter dir. dir = 'f2i' or 'i2f'
( oat to int or int to oat) x1,y1 are the coordinates of the set of points described by x,y after
the coordinate change.
Author : J.Ph.C..

2.0.198 xclea erase a rectangle on a graphic window

CALLING SEQUENCE :
xclea(x,y,w,h)

PARAMETERS :
x,y,w,h : four real values (rectangle def)
DESCRIPTION :
clears on the current graphic window the rectangle [x,y,w,h] ( Upper left point , width,height)
using the current graphic scale.
Author : J.Ph.C.

2.0.199 xclear clear a graphic window

CALLING SEQUENCE :
xclear([window-id])

PARAMETERS :
window-id : integer vector
DESCRIPTION :
Without any argument, this function wipes out the current window. Otherwise it wipes out the
graphic windows whose numbers are included in the vector window-id, for example xclear(1:3).
If one of the windows does not exist then it is automatically created.
Warning : in recording mode the graphic command xclear wipes out the window, but it doesn't
wipe out the recorded commands. In this case one must use the function xbasc.
Author : J.Ph.C.

2.0.200 xclick wait for a mouse click

CALLING SEQUENCE :
[c_i,c_x,c_y]=xclick()
[c_i,c_x,c_y,c_w]=xclick()

PARAMETERS :
c i : integer (button number)
c x,c y : real scalars (position)
c w : integer (window number)
Scilab Group April 1993 92
xdel Scilab Function
DESCRIPTION :
if called with 3 lhs arguments waits for a mouse click in the current graphic window
if called with 4 lhs arguments waits for a mouse click in any graphic window
returned values:
c i : an integer which gives the number of the mouse button that was pressed [0,1,2] (for
[left,middle,right]) or i=-1 in case of problems with xclick.
c x,c y : the coordinates in the current graphic scale of the position of the mouse click.
c w : the window number where the click has occurred

KNOWN TROUBLES :
This function can return the message Can't grab the pointer if the graphic window is iconied
when calling the function xclick.
See Also : locate
Author : J.Ph.C.
2.0.201 xclip set a clip zone
CALLING SEQUENCE :
xclip([x,y,w,h])
xclip(rect)
xclip("clipgrf");

PARAMETERS :
x,y,w,h : four oat values
rect : a vector of size (1,4)

DESCRIPTION :
Sets a clip region given by the coordinates, in the current graphic scaling, of a rectangle (x,y,w,h)
(Upper-Left point,Width aba Height). If only one argument is used it stands for a rectangle
specication rect=[x,y,w,h].
xclip("clipgrf") is used to clip the usual graphic rectangle.
To unclip a region use the command xclip()
EXAMPLE :
x=0:0.2:2*%pi;
x1=[sin(x);100*sin(x)];
y1=[cos(x);100*cos(x)];
y1=y1+20*ones(y1);
// No clip
plot2d([-100,500],[-100,600],[-1,-1],"022");
xsegs(10*x1+200*ones(x1),10*y1+200*ones(y1));
xbasc()
//
// Rect clip
xbasc();plot2d([-100,500],[-100,600],[-1,-1],"022");
xrect(150,460,100,150);
xclip(150,460,100,150);
xsegs(10*x1+200*ones(x1),10*y1+200*ones(y1));
//
// usual graphic rectangle clip
xbasc();plot2d([-100,500],[-100,600],[-1,-1],"022");
xclip("clipgrf");

Scilab Group April 1993 93

xfarcs Scilab Function
xsegs(10*x1+200*ones(x1),10*y1+200*ones(y1));
// clipping off
xclip()

Author : J.Ph.C.

2.0.202 xdel delete a graphic window

CALLING SEQUENCE :
xdel([win-num])

DESCRIPTION :
Deletes the graphic window win-num if the name is specied or the current graphic window
otherwise
Author : J.Ph.C.

2.0.203 xend ends a graphic session

CALLING SEQUENCE :
xend()

DESCRIPTION :
This command is used to end a graphic session. Under the Postscript or Xg drivers this command
closes the current le which was opened by the command xinit.
Author : J.Ph.C.

2.0.204 xfarc ll a part of an ellipsis

CALLING SEQUENCE :
[]=xfarc(x,y,w,h,a1,a2)

PARAMETERS :
x,y,w,h : real scalars (rectangle def)
a1,a2 : real scalars (angle def)
DESCRIPTION :
Fills a portion of an ellipsis contained in the rectangle (x,y,w,h) ( upper-left point, width,
height), and in the sector delimited by the angle alpha1 and the angle alpha1+alpha2. alpha1
and alpha2 are given respectively by a1/64 degrees and a2/64 degrees. This function uses the
current graphic state which can be set by calling a high level drawing function such as plot2d.
EXAMPLE :
// isoview scaling
plot2d(0,0,-1,"031"," ",[-2,-2,2,2])
xfarc(-0.5,0.5,1,1,0,90*64)
xset("pattern",2)
xfarc(0.5,0.5,1,1,0,360*64)

See Also : ,
xarcs xarc.
Author : J.Ph.C..
Scilab Group April 1993 94
xfpolys Scilab Function
2.0.205 xfarcs drawing a set of ellipsis
CALLING SEQUENCE :
[]=xfarcs(arcs,[style])

PARAMETERS :
arcs : matrix of size (6,n) (ellipsis description)
style : vector of size (1,n) giving the style to use ( set xset("dashes",...).
DESCRIPTION :
draws a set of ellipsis described by arcs. arcs= [ x,y,w,h,a1,a2 ; x,y,w,h,a1,a2 ;.....]
' : each ellipsis is dened by the 6 parameters (x,y,w,h,a1,a2) (see xarc)
fill(i) gives the dash style which must be used to draw the ellipsis number i.
EXAMPLE :
plot2d(0,0,-1,"031",' ',[-1,-1,1,1])
set_arcs=[ -1.0 0.0 0.5 // upper left x
1.0 0.0 0.5 // upper left y
0.5 0.5 0.5 // widths
0.5 0.5 0.5 // height
0.0 0.0 0.0 // angle 1
360*64 360*64 360*64] // angle 2
xfarcs(set_arcs,[0,1,2])

Author : J.Ph.C.
2.0.206 xfpoly ll a polygon
CALLING SEQUENCE :
[]=xfpoly(xv,yv,[close])

PARAMETERS :
xv, yv : two vectors of size n (the points of the polygon)
close : an integer
DESCRIPTION :
Fills a polygon. If close is equal to 1 a point is added to the polyline xv,yv to dene a polygon.
EXAMPLE :
x=sin(2*%pi*(0:5)/5);
y=cos(2*%pi*(0:5)/5);
plot2d(0,0,-1,"010"," ",[-2,-2,2,2])
xfpoly(x,y)

Author : J.Ph.C.
2.0.207 xfpolys ll a set of polygons of the same size
CALLING SEQUENCE :
[]=xfpolys(xpols,ypols,[fill])

PARAMETERS :
Scilab Group April 1993 95
xget Scilab Function
xpols,ypols : two matrices of size (n1,n2) (polygon def)
fill : vector of size n2 (number of polygons) (pattern id's).
DESCRIPTION :
lls a set of polygons of the same size dened by the two matrices xpols,ypols . xpols=
[ xpol1;xpol2;...]' , each column of the matrix xpols gives the x-values of the points of a
polygon (i.e
ypols ).
fill(i) gives the id of the pattern for lling the polygon number i
- if fill(i) < xget("white")+1, the polygon is lled with pattern fill(i).
- if fill(i) >= xget("white")+1, the polyline is only drawn.
- if fill(i) >= xget("white")+2, the polygon is lled with the pattern id fill(i)+2*WID +2
(WID is the id of the white pattern ). Then its contour is drawn and closed if necessary
EXAMPLE :
plot2d(0,0,[-1],"012"," ",[0,-10,210,40]);
x1=[0,10,20,30,20,10,0];
y1=[15,30,30,15,0,0,15];
xpols=[x1;x1;x1;x1]';xpols=xpols + [0,60,120,180].*.ones(x1)';
ypols=[y1;y1;y1;y1]';
xfpolys(xpols,ypols,[1,2,3,4]);

Author : J.Ph.C.
2.0.208 xfrect ll a rectangle
CALLING SEQUENCE :
[]=xfrect(x,y,w,h)

PARAMETERS :
x,y,w,h : real scalars (rectangle def)
DESCRIPTION :
lls a rectangle [x,y,w,h] (upper-left point, width, height) using current scale and pattern
Author : J.Ph.C.
2.0.209 xget gets current values of the graphic context
CALLING SEQUENCE :
[x1]=xget(str [,flag])
xget()

PARAMETERS :
str : string
flag : optional. Set to 1 gives a verbose mode
DESCRIPTION :
this function is used to get values from the graphic context on the topic specied by the string
str . When called no arguments, a choice menu is created showing the current values and changes
can be performed through toggle buttons
number=xget("alufunction") : used to get the logical function number used for drawing.

0 : function " 0 ",

Scilab Group April 1993 96

xgetech Scilab Function
1 :
function " src AND dst "
2 :
function " src AND NOT dst "
3 :
function " src ", (Default value)
4 :
function " NOT src AND dst "
5 :
function " dst ",
6 :
function " src XOR dst ",
7 :
function " src OR dst ",
8 :
function " NOT src AND NOT dst ",
9 :
function " NOT src XOR dst ",
10 :
function " NOT dst ",
11 :
function " src OR NOT dst ",
12 :
function " NOT src ",
13 :
function " NOT src OR dst ",
14 :
function " NOT src OR NOT dst ",
15 :
function " 1 ";
rect=xget("clipping") : get the clipping zone rectangle rect=[x,y,w,h] (Upper-Left point
Width Height).
dash=xget("dashes") : get the dash style dash=[dash number,v] v contains the denition of
the dash
font=xget("font") : get font=[fontid,fontsize] the current font and its current size.
type=xget("line mode"); This function is used to get the line drawing mode. type=1 :Absolute
mode,type=0 relative mode (Warning : the mode type=0 is buged )
mark=xget("mark") : mark=[markid,marksize] the current mark and current mark size.
pat=xget("pattern") : to get the current pattern for lling functions, pat is an integer projected
in the interval [0,whiteid]. 0 is used for black lling and whiteid for white. The value of
whiteid can be obtained with xget("white").
value=xget("thickness") : get the thickness of lines in pixel ( 0 and 1 have the same meaning
: 1 pixel thick)
dim=xget("wdim") : dim=[width,height] the width and height of the current graphic window.
pos=xget("wpos",x,y); : pos=[x,y] the position of the upper left point of the graphic window.
win=xget("window") Get the current window to the window win
flag=xget("use color") if ag=1 then xset("pattern",.) or xset("dashes",.) will be used so as
to change the default color for drawing or for lling patterns. If ag=0 then we switch back
to the gray and dashes mode.
See Also : X11 documentation
Author : J.Ph.C.
2.0.210 xgetech get the current graphic 2d scale
CALLING SEQUENCE :
[frect1,frect,[logflag]]=xgetech()

PARAMETERS :
frect1, frect : real vectors (rect. def)
logflag : a string of size 2 "xy".
DESCRIPTION :
This function returns the current graphic scale. If one uses the current graphic scale, the points in
the frect rectangle [xmin,ymin,xmax,ymax] will be drawn in the the region of the current graphic
window specied by frect1.
frect1=[x,y,w,h] ( Upper-Left Width Height ) describes a region inside the graphic window.
The values in wrect1 are specied using proportion of the width or height of the graphic window.
frect1=[0,0,1.0,1.0] means that all the graphic window will be used.

Scilab Group April 1993 97

xinfo Scilab Function
frect1=[0.5,0,0.5,1.0] means that the graphic region will be the right half of the graphic
window. The logflag is a string of size 2 "xy", where x and y can be "n" or "l". It gives
information on the log scale status for the current scale, "n" stands for normal and "l" for logscale.
x is for the x-axis and y for the y-axis.
See Also : xsetech
Author : J.Ph.C.
2.0.211 xgetmouse get current position of the mouse
CALLING SEQUENCE :
rep=xgetmouse()

PARAMETERS :
rep : a three vector: [x,y,ibutton]
DESCRIPTION :
If the mouse is located in the current graphic window xgetmouse returns in rep the current mouse
position (x,y) and the value ibutton. The ibutton value indicate the button action at this point
if ibutton==-1 then no button clicked if ibutton==0,1 or 2 then the left, middle or right button
clicked
If the mouse is not located in the current graphic window xgetmouse waits
EXAMPLE :
xselect();xbasc();xsetech([0 0 1 1],[0 0 100 100])
xset('alufunction',6)
[b,x0,y0]=xclick();rep=[x0,y0,-1];x=x0;y=y0
plot2d([x0;x0;x;x;x0],[y0;y;y;y0;y0],-1,'000')
while rep(3)==-1 then
rep=xgetmouse()
plot2d([x0;x0;x;x;x0],[y0;y;y;y0;y0],-1,'000');
x=rep(1);y=rep(2);
plot2d([x0;x0;x;x;x0],[y0;y;y;y0;y0],-1,'000');
end
xset('alufunction',3)

See Also : ,
locate xclick.
Author : S. Steer
2.0.212 xgrid add a grid on a graphic
CALLING SEQUENCE :
xgrid([style])

PARAMETERS :
style : an integer
DESCRIPTION :
Adds a grid on a 2D plot. style stands for the dash style to use for the grid plotting.
EXAMPLE :
plot2d()
xgrid()

See Also : ,
xset plot2d
Author : J.Ph.C..
Scilab Group April 1993 98
xload Scilab Function
2.0.213 xinfo add an info string on a graphic window
CALLING SEQUENCE :
xinfo(string)

PARAMETERS :
string : a scilab string.
DESCRIPTION :
This function is used to add a sentence on the current graphic window.
2.0.214 xinit initialisation of a graphic driver
CALLING SEQUENCE :
xinit([driver-name])

PARAMETERS :
driver-name : string (default value : DISPLAY value or 'unix:0.0')
DESCRIPTION :
Initialisation of a given driver.
For X-Window driver-name must be a string which gives the name of a display and this function
creates a new graphic window. If the argument is omitted the value of the environment variable
DISPLAY is used if it exists or the value 'unix:0.0' is used.
For Postscript or Xg driver-name is a name of a le. The graphics operations will be recorded
in the specied le.
Author : J.Ph.C.
2.0.215 xlfont load a font in the graphic context
CALLING SEQUENCE :
[]=xlfont(font-name,font-id)

PARAMETERS :
font-name : string (name of the font family)
font-id : integer
DESCRIPTION :
This function is used to load an X11 font at dierent sizes inside the graphic context.
font-name : can be of 2 types

- if it contains the character '%', it is supposed to be an X11 font name with %s in the size
eld of the name, for example font-name="-b&h-lucidabright-demibold-r-normal--%s-*-75-75-p-*-
- if it doesn't contain the character '%' ,it is supposed to be an alias name and the fonts
aliased by font-name08,...,font-name24 are loaded.
font-id : the font font-name at sizes 08 10 12 14 18 24 is loaded in the graphic context
with the Scilab Id font-id.

See Also : X11 Font manual.

Author : J.Ph.C..
Scilab Group April 1993 99
xpoly Scilab Function
2.0.216 xload load a saved graphic
CALLING SEQUENCE :
xload('file-name' [, win-num] )

PARAMETERS :
win-num : an integer ( optional argument ) which stands for the graphic window in which the
graphics are to be loaded.
DESCRIPTION :
This function is used to reload the graphics contained in the le 'file-name' in the graphic-
window win-num. The graphics are stored in a binary le in a machine independent way ( using
the xdr library).
See Also : xsave
Author : J.Ph.C..

2.0.217 xnumb draw numbers on a graphic

CALLING SEQUENCE :
xnumb(x,y,nums,[flag,angle])

PARAMETERS :
x,y,nums : vectors or matrices of same size
flag : an integer value
angle : a vector of the same size as x,y,nums

DESCRIPTION :
Displays the value of nums[i] using the current number format at position x[i],y[i] in the
current scale. if flag is 1 a frame box is added around the strings. if angle is present it's a
vector. angle[i] gives the slope in degree (clockwise) to use for the display of the string.
EXAMPLE :
plot2d([-100,500],[-100,600],[-1,-1],"022");
x=0:100:200;
xnumb(x,500*ones(x),[10,20,35],1);

Author : J.Ph.C.

2.0.218 xpause suspends Scilab

CALLING SEQUENCE :
xpause(msecs)

DESCRIPTION :
Synchronises the X11-display and suspends the current process for the number of microseconds
specied by the argument. The actual suspension time may be an arbitrary amount longer because
of other activity in the system, or because of the time spent in processing the call.
Author : J.Ph.C.
Scilab Group April 1993 100
xrects Scilab Function
2.0.219 xpoly draw a single polyline
CALLING SEQUENCE :
[]=xpoly(xv,yv,dtype[,close])

PARAMETERS :
xv, yv : two matrices of the same size (p,n) (points of the polyline)
dtype : string (drawing style)
close : if close = 1, the polyline is closed. (default value is 0)
DESCRIPTION :
draws a single polyline described by (xv,yv). If xv and yv are matrices they are internally
considered as a vector using the Fortran internal storage convention. dtype can be "lines" for
using the current line style or "marks" for using the current mark to draw the polyline.
Author : J.Ph.C.
2.0.220 xpolys draw a set of polylines
CALLING SEQUENCE :
[]=xpolys(xpols,ypols,[draw])

PARAMETERS :
xpols, ypols : matrices of size (p,n)
draw : vector of size n
DESCRIPTION :
Draws a set of polyline using marks or dashed lines, each polyline points are store in a column of
.
xpols, ypols xpols =[ xpol1;xpol2;...] '
The style is given by
draw :
Ifdraw(i) is positive the mark of id
draw(i) is used to draw the polyline i.
Ifdraw(i) is negative the line style of id
abs(draw(i)) is used to draw the polyline i.
EXAMPLES :
plot2d(0,0,[-1],"012"," ",[0,0,1,1]);
rand('uniform');
xpolys(rand(10,5),rand(10,5));
xpolys(rand(10,5),rand(10,5),[-1,-2,0,1,2])
xset("use color",1)
xpolys(rand(10,5),rand(10,5),[-1,-4,0,1,2])

Author : J.Ph.C.
2.0.221 xrect draw a rectangle
CALLING SEQUENCE :
[]=xrect(x,y,w,h)

PARAMETERS :
x,y,w,h : four real values (rectangle def)
DESCRIPTION :
draws a rectangle [x,y,w,h] (upper-left point, width, height) using current scale and style.
Author : J.Ph.C.
Scilab Group April 1993 101
xsave Scilab Function
2.0.222 xrects draw a set of rectangles
CALLING SEQUENCE :
[]=xrects(rects,[fill])

PARAMETERS :
rects : matrix of size (4,n)
fill : vector of size n.
DESCRIPTION :
draws or lls a set of rectangle. each column of rects describes a rectangle ( Upper Left point,
width, height)
rects= [ x,y,w,h ; x,y,w,h ;.....] ' fill(n) gives the pattern to use for lling the rect-
angle n.
if fill(n) >= wid +1, the rectangles are drawn using the current line style but not lled. This
is also the default value if ll is not given. wid stands for the id of the white pattern which can
be obtained by the command xget("white").
Author : J.Ph.C..

2.0.223 xrpoly draw a regular polygon

CALLING SEQUENCE :
[]=xrpoly(orig,n,r,[theta])

PARAMETERS :
orig : vector of size 2
n : integer (number of sides)
r : real scalar
theta : real (angle in radian) ( 0 is the default value )
DESCRIPTION :
draws a regular polygon of n sides contained in the circle of diameter r and with the origin of the
circle set at point orig. theta species a rotation angle in radian. This function uses the current
graphic scales.

2.0.224 xs2g send graphics to a le in Xg syntax

CALLING SEQUENCE :
xs2fig(win_num,filen)

PARAMETERS :
win num : an integer scalar or vector
filen : string (le name).
DESCRIPTION :
This function will send the recorded graphics of the window win num in the le filen in Xg
syntax This function will work only if the selected driver is "Rec"
Scilab Group April 1993 102
xselect Scilab Function
2.0.225 xsave save graphics in a (reloadable) le.
CALLING SEQUENCE :
xsave('file-name' [, win-num] )

PARAMETERS :
win-num : an integer ( optional argument ) which stands for the graphic window which is to be
saved.
DESCRIPTION :
This function is used to save the graphics contained in the graphic-window win-num. The graphics
are stored in a binary le in a machine independent way ( using the xdr library) and can be reloaded
in Scilab whith the xload command.
See Also : xload
Author : J.Ph.C..

2.0.226 xsegs draw unconnected segments

CALLING SEQUENCE :
xsegs(nx,ny,[style])

PARAMETERS :
nx,ny : two matrices of the same size 2*n
style : a matrix of size n or a scalar. If style is a positive scalar it gives the dash style to
use for all segments, if it is a negative scalar then current dash style is used, if it is a vector
style[i] gives the style to use for segment i.

DESCRIPTION :
this function draws a set of unconnected segments given by nx,ny which are internally considered
as vectors ( using the Fortran storage convention). The coordinates of the two points dening a
segment are given by two consecutive values of nx and ny.
(nx[i],ny[i])-->(nx[i+1],nx[i+2])
Using matrices of size (2,.) the segments can be dened by
nx=[ xi_1,xi_
xf_1,xf_2,... ]

ny=[ yi_1,yi_2,.....;
yf_1,yf_2,... ]

the segments are then (xi k,yi k)->(xf k,yf k)

EXAMPLE :
x=2*%pi*(0:9)/8;
x1=[sin(x);9*sin(x)];
y1=[cos(x);9*cos(x)];
plot2d([-10,10],[-10,10],[-1,-1],"022");
xset('clipgrf')
xsegs(x1,y1,0:9);
xset('clipoff')

Author : C. J.Ph
Scilab Group April 1993 103
xset Scilab Function
2.0.227 xselect raise the current graphic window
CALLING SEQUENCE :
xselect()

DESCRIPTION :
raises the current graphic window and creates it if necessary. If the current graphic window is
iconied nothing is done.
Author : J.Ph.C.
2.0.228 xset set values of the graphic context
CALLING SEQUENCE :
xset(choice-name,x1,x2,x3,x4,x5)
xset()

PARAMETERS :
choice-name : string
x1,...,x5 : depending on
choice-name
xset("alufunction",number) : used to set the logical function for drawing, it works only under
X11. The logical function used is set by x1. The default value is 3.
0 : function " 0 ",
1 : function " src AND dst "
2 : function " src AND NOT dst "
3 : function " src ",
4 : function " NOT src AND dst "
5 : function " dst ",
6 : function " src XOR dst ",
7 : function " src OR dst ",
8 : function " NOT src AND NOT dst ",
9 : function " NOT src XOR dst ",
10 : function " NOT dst ",
11 : function " src OR NOT dst ",
12 : function " NOT src ",
13 : function " NOT src OR dst ",
14 : function " NOT src OR NOT dst ",
15 : function " 1 ";
xset("clipping",x,y,w,h) : set the clipping zone to the rectangle (x,y,w,h) (Upper-Left point
Width Height). This function uses the current scale
xset("default") : reset the graphic context to default values
xset("dashes",i) : set the dash style to style i (0 for solid line)
xset("font",fontid,fontsize) : to x the current font and its current size.
xset("line mode",type); This function is used to x the line drawing mode. Absolute mode
is xed withtype=1 an relative mode with type=0. (Warning : the mode type=0 is bugged )
xset("mark",markid,marksize) : is used to set the current mark and current mark size.
xset("pattern",value) : to set the current pattern for lling functions, value is an integer
projected in the interval [0,whiteid]. 0 is used for black lling and whiteid for white. The
value of whiteid can be obtained with xget("white").
xset("thickness",value) : xes the thickness of lines in pixel ( 0 and 1 have the same meaning
: 1 pixel thick)
xset("wdim",width,height) : xes the width and height of the current graphic window. This
option is not used by the postscript driver.
Scilab Group April 1993 104
xsetech Scilab Function
xset("wpos",x,y); : xes the position of the upper left point of the graphic window.
xset("window",window-number) Set the current window to the window window-number and
creates the window if it doesn't exists.
xset("use color",flag) if ag=1 then xset("pattern",.) or xset("dashes",.) will be used so as
to change the default Color for drawing or for lling patterns. If ag=0 then we switch back
to the gray and dashes mode.
xset("pixmap",flag) if ag=0 the graphics are directly displayed on the screen
if ag=1 the graphics are done on a Pixmap and are send to the graphic window with the
command xset("wshow"). The Pixmap is cleared with the command xset("wwpc")
or with the usual command xbasc().
xset("wshow") : see the function driver.
xset("wwpc") : see the function driver.

DESCRIPTION :
xset is used to set values of the graphic context. When called no arguments, a choice menu is
created showing the current values and changes can be performed through toggle buttons
See Also : X11 documentation
Author : J.Ph.C.
2.0.229 xsetech set the sub window of a graphic window to use for
graphics
CALLING SEQUENCE :
[]=xsetech(wrect [,frect,logflag])

PARAMETERS :
wrect : a vector of size 4 (sub window denition)
frect : a vector of size 4 (just like the rect argument of plot2d )
logflag : a string of size 2 "xy", where x and y can be "n" or "l". "n" for normal and "l" for
logscale. x is for the x-axis and y for the y-axis.
DESCRIPTION :
This function is mainly used to set the sub window of the graphic window which will be used for
graphics. The sub window is specied with the parameter wrect=[x,y,w,h] ( Upper-Left Width
Height ). The values in wrect are specied using proportion of the width or height of the current
graphic window. for example
wrect=[0,0,1.0,1.0] means that all the graphic window will be used.
wrect=[0.5,0,0.5,1.0] means that the graphic region will be the right half of the graphic win-
dow.
and can be used in conjunction with graphic routines which request the current graphic scale (for
example strf="x0y" in plot2d ). frect=[xmin,ymin,xmax,ymax] is used to set the graphic
scale and is just like the rect argument of plot2d. Its default value is [0,0,1,1].
EXAMPLE :
//In this first example xsetech is used to split the graphic window
//in two parts

// xsetech is used to fix the first sub window

// and the graphic scale
xsetech([0,0,1.0,0.5],[-5,-3,5,3]);
// then we call plot2d with the "001" option to use the graphic scale
// set by xsetech
plot2d((1:10)',(1:10)',-1,"001",' ');

Scilab Group April 1993 105

xstringb Scilab Function
// xsetech is used to fix the second sub window
xsetech([0,0.5,1.0,0.5]);
// the graphic scale is set by xsetech to [0,0,1,1] by default
// and we change it with the use of the rect argument in plot2d
plot2d((1:10)',(1:10)',-1,"011",' ',[-6,-6,6,6]);

//A second example with four graphics on a single graphic window

xset("font',2,0);
xsetech([0,0,0.5,0.5]);plot3d();
xsetech([0.5,0,0.5,0.5]);plot2d();
xsetech([0.5,0.5,0.5,0.5]);grayplot();
xsetech([0,0.5,0.5,0.5]);histplot();
// back to default values for the sub window
xsetech([0,0,1,1]);
xset("default');

Author : J.Ph.C.

2.0.230 xstring display a matrix of strings

CALLING SEQUENCE :
[]=xstring(x,y,str,[angle,flag])

PARAMETERS :
x,y : real scalars (point coordinates)
str : matrix of strings
angle : real (angle in degree) (clockwise) (default value =0)
flag : integer
DESCRIPTION :
draws a matrix of strings ( each line of the matrix stands for a line of text and the line elements
are separated by a white space) at location x,y ( lower-left point ) in the current graphic scale.
angle if given gives the slope in degree to use for drawing the string. if frame=1 a box is drawn
around the string (only if angle=0 )
EXAMPLE :
plot2d([0,1],[0,1])
xstring(0.5,0.5,["Scilab","is" ; "Not","Basilc"])

Author : J.Ph.C..

2.0.231 xstringb draw a matrix of strings

CALLING SEQUENCE :
xstringb(x,y,str,w,h,[option])

PARAMETERS :
x,y,w,h : real scalars (rectangle def)
str : matrix of strings
option : string
Scilab Group April 1993 106
xtape Scilab Function
DESCRIPTION :
plots the matrix of strings str centred inside the rectangle rect=[x,y,w,h] (Down left point ,
width ,height) in the current graphic scale. If option is given with the value "fill" the character
size is computed so as to ll as much as possible of the rectangle.
Enter the command xstringb() to see a demo.
EXAMPLE :
mat=['Scilab','is';'not','Basile'];
plot2d(0,0,[-1,1],'010',' ',[0,0,1,1]);
r=[0,0,1,0.5];
xstringb(r(1),r(2),mat,r(3),r(4),'fill');
xrect(r(1),r(2)+r(4),r(3),r(4))
r=[r(1),r(2)+r(4)+0.01,r(3),r(4)/2];
xrect(r(1),r(2)+r(4),r(3),r(4))
xstringb(r(1),r(2),mat,r(3),r(4),'fill');
r=[r(1),r(2)+r(4)+0.01,r(3),r(4)/2];
xrect(r(1),r(2)+r(4),r(3),r(4))
xstringb(r(1),r(2),mat,r(3),r(4),'fill');

See Also : ,
xtitle titlepage , xstring , xstringl
Author : J.Ph.C.
2.0.232 xstringl computes bounding box of the display of matrix of
strings
CALLING SEQUENCE :
[rect]=xstringl(x,y,str)

PARAMETERS :
x,y : real scalars (point coordinates)
str : matrix of strings
rect : vector of 4 real scalars (rectangle def [x,y,w,h])
DESCRIPTION :
returns in rect=[x,y,w,h] ( upper-left point, width, height) the size of a rectangle in the current
graphic scale. which if drawn would surround the string str drawn at location x,y.
REMARK :
The result can be approximative under the Postscript driver
EXAMPLE :
plot2d([0;1],[0;1])
rect=xstringl(0.5,0.5,["Scilab","is" ; "not","Basile"])

See Also : xstring

Author : J.Ph.C..
2.0.233 xtape set up the record process of graphics
CALLING SEQUENCE :
xtape(str,num)

PARAMETERS :
str : string ( 'on' or 'replay' or 'clear')
Scilab Group April 1993 107
zgrid Scilab Function
num : an integer
DESCRIPTION :
xtape is used to set up the record process of graphics
xtape('on') : just select the driver "Rec" which records all the graphics operations.
xtape('clear', num) : clear the graphic window num and clear the recorded graphics associ-
ated with window num.
xtape('replay',xx) : clear the window num and redisplay all the recorded graphics in it (
used when a user changes the size of a graphic window under xscilab).

Author : J.Ph.C.
2.0.234 xtitle add titles on a graphic window
CALLING SEQUENCE :
[]=xtitle(xtit,[xax,yax,encad])

PARAMETERS :
xtit, xax, yax : matrices of strings (global and x,y titles)
encad : integer value (if = 1 a framed box is added around each title).

DESCRIPTION :
Add titles on a 2D or 3D Scilab plot. xtit stand for a general title , xax for a title on the
X-axis and yax for a title on the Y-axis. This function must be called after a call to the high level
plotting function (plot2d,plot3d,...). If the arguments are matrices each line of the matrices is
displayed on a dierent line.
Enter the command xtitle() to see a demo.
Author : J.Ph.C.
2.0.235 zgrid zgrid plot
CALLING SEQUENCE :
zgrid()

DESCRIPTION :
plots z-plane grid lines: lines of constant damping factor (zeta) and natural frequency (Wn) are
drawn in within the unit Z-plane circle.
Iso-frequency curves are shown in frequency*step on the interval [0,0.5]. Upper limit corresponds
to Shannon frequency ( 1/dt > 2*f ).
See Also : frdmp, frdmp2tf, frep2tf, freson

Scilab Group April 1993 108

Chapter 3

Utilities and Elementary

Functions

109
addmenu Scilab Function
3.0.236 abs absolute value, magnitude
CALLING SEQUENCE :
[t]=abs(x)
PARAMETERS :
x : real or complex vector or matrix
t : real vector or matrix
DESCRIPTION :
abs(x) is the absolute value of the elements of x. When x is complex, abs(x) is the magnitude
of the elements .
3.0.237 acos cosine inverse
CALLING SEQUENCE :
[t]=acos(x)
PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
The components of vector t are cosine inverse of the corresponding entries of vector x. Denition
domain is [-1, 1].
acos takes values in :
]0; [] , 1 + 1[
[0]  [0; +1] and []] , 1; 0] (real x imag)
3.0.238 acosh hyperbolic cosine inverse
CALLING SEQUENCE :
[t]=acosh(x)
PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
the components of vector t are the ArgCosh of the corresponding entries of vector x. Denition
domain is ]1,+innity[. It takes his values in
]0; +1[] , ; ] and [0]  [0; ]

3.0.239 addf symbolic addition

CALLING SEQUENCE :
addf("a","b")
PARAMETERS :
"a","b" : character strings
DESCRIPTION :
Returns the character string "a+b". Trivial simplications such as addf("0","a") or addf("1",2")
are performed.
See Also : mulf, subf, ldivf, rdivf, eval, evstr
Scilab Group December 1995 110
amell Scilab Function
3.0.240 addmenu interactive button or menu denition
CALLING SEQUENCE :
addmenu(button [,submenus] [,action])
addmenu(gwin,button [,submenus] [,action])

PARAMETERS :
button : a character string. The button name
submenus : a vector of character string. The sub menus items names
action : a list with 2 elements action=list( ag,proc name)
: an integer (default value is 0)
flag

flag==0 : the action is dened by a scilab instruction

flag==1 : the action is dened by a C or Fortran procedure
proc name : a character string whith gives the name of scilab variable containing the in-
struction or the name of procedure to call.
gwin : integer. The number of graphic window where the button is required to be installed

DESCRIPTION :
The function allows the user to add new buttons or menus in the main window or graphics windows
command panels.
If action is not given the action associated with a button must be dened by a scilab instruc-
tion given by the character string variable which name is
button for a main window command
button gwin for a graphic window command
If proc name designes a C or Fortran procedure, this procedure may be interfaced in fortran
subroutine default/fbutn.f or dynamically linked with scilab using the link function.
Actions associated with the kth sub menu must be dened by scilab instructions stored in the kth
element of the character string variable which name is
button for a main window command
button gwin for a graphic window command
EXAMPLE :
addmenu('foo')
foo='disp(''hello'')'

addmenu('Hello',['Franck';'Peter'])
Hello=['disp(''hello Franck'')';'disp(''hello Peter'')']

addmenu(0,'Hello',['Franck';'Peter'])
Hello=['disp(''hello Franck'')';'disp(''hello Peter'')']

addmenu('Bye',list(0,'French_Bye'))
French_Bye='disp(''Au revoir'')'

See Also : setmenu , unsetmenu , delmenu

Scilab Group April 1993 111

atan Scilab Function
3.0.241 amell Jacobi's am function
CALLING SEQUENCE :
[sn]=amell(u,k)

PARAMETERS :
u : real scalar or vector
k : scalar
sn : real scalar or vector
DESCRIPTION :
Computes Jacobi's elliptic function am(u,k) where k is the parameter and u is the argument. If
u is a vector sn is the vector of the (element wise) computed values.
See Also : delip.
3.0.242 asin sine inverse
CALLING SEQUENCE :
[t]=asin(x)

PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
The components of vector t are sine inverse of the corresponding entries of vector x. Denition
domain is [-1, 1]. It takes his values in sets
] , =2; =2[] , 1 + 1[
[,=2]  [0; +1] and [=2]] , 1; 0] (real x imag)

3.0.243 asinh hyperbolic sine inverse

CALLING SEQUENCE :
[t]=asinh(x)

PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
The components of vector t are the hyperbolic sine inverse of the corresponding entries of vector
. Denition domain is ]-1,i[ It takes his values in sets
x

] , 1 + 1[] , =2; =2[

[,1; 0[[,=2] and [0; 1]  [=2] (real x imag)

Scilab Group April 1993 112

bloc2exp Scilab Function
3.0.244 atan tangent inverse
CALLING SEQUENCE :
[t]=atan(x)

PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
The components of vector t are the arctangent of the corresponding entries of vector x.
atan(x,y)is the same as atan(x/y) but y is allowed to be zero.
3.0.245 atanh hyperbolic tangent inverse
CALLING SEQUENCE :
[t]=atanh(x)

PARAMETERS :
x : real or complex vector
t : real or complex vector
DESCRIPTION :
The components of vector t are the hyperbolic tangent inverse of the corresponding entries of
vector x. Denition domain is ]-1,1[
This function takes values in
] , 1 + 1[] , =2; =2[
[,1; 0[[,=2] and ]0; 1[[=2] (real x imag)
3.0.246 bloc2exp block-diagram to symbolic expression
CALLING SEQUENCE :
[str]=bloc2exp(blocd)
[str,names]=bloc2exp(blocd)

PARAMETERS :
blocd : list
str : string
names : string
DESCRIPTION :
given a block-diagram representation of a linear system bloc2exp returns its symbolic evaluation.
The rst element of the list blocd must be the string 'blocd'. Each other element of this list
(blocd(2),blocd(3),...) is itself a list of one the following types :

list('transfer','name_of_linear_system')

list('link','name_of_link',
[number_of_upstream_box,upstream_box_port],
[downstream_box_1,downstream_box_1_portnumber],
[downstream_box_2,downstream_box_2_portnumber],
...)

Scilab Group April 1993 113

bloc2exp Scilab Function
The strings 'transfer' and 'links' are keywords which indicate the type of element in the
block diagram.
Case 1 : the second parameter of the list is a character string which may refer (for a possible
further evaluation) to the Scilab name of a linear system given in state-space representation (syslin
list) or in transfer form (matrix of rationals).
To each transfer block is associated an integer. To each input and output of a transfer block is
also associated its number, an integer (see examples)
Case 2 : the second kind of element in a block-diagram representation is a link. A link links one
output of a block represented by the pair [number of upstream box,upstream box port], to dif-
ferent inputs of other blocks. Each such input is represented by the pair [downstream box i,downstream box i portn
The dierent elements of a block-diagram can be dened in an arbitrary order.
For example
[1] S1*S2 with unit feedback.
There are 3 transfers S1 (number n s1=2) , S2 (number n s2=3) and an adder (number n add=4)
with symbolic transfer function ['1','1'].
There are 4 links. The rst one (named 'U') links the input (port 0 of ctitious block -1, omitted)
to port 1 of the adder. The second and third one link respectively (output)port 1 of the adder
to (input)port 1 of system S1, and (output)port 1 of S1 to (input)port 1 of S2. The fourth link
(named 'Y') links (output)port 1 of S2 to the output (port 0 of ctitious block -1, omitted) and
to (input)port 2 of the adder.
//Initialization
syst=list('blocd'); l=1;
//
//Systems
l=l+1;n_s1=l;syst(l)=list('transfer','S1'); //System 1
l=l+1;n_s2=l;syst(l)=list('transfer','S2'); //System 2
l=l+1;n_adder=l;syst(l)=list('transfer',['1','1']); //adder
//
//Links
// Inputs -1 --> input 1
l=l+1;syst(l)=list('link','U',[-1],[n_adder,1]);
// Internal
l=l+1;syst(l)=list('link',' ',[n_adder,1],[n_s1,1]);
l=l+1;syst(l)=list('link',' ',[n_s1,1],[n_s2,1]);
// Outputs // -1 -> output 1
l=l+1;syst(l)=list('link','Y',[n_s2,1],[-1],[n_adder,2]);
//Evaluation call
w=bloc2exp(syst);

The result is the character string: w=-(s2*s1-eye)s1.

Note that invoked with two output arguments, [str,names]= blocd(syst) returns in names the
list of symbolic names of named links. This is useful to set names to inputs and outputs.

[2] second example

//Initialization
syst=list('blocd'); l=1;
//
//System (2x2 blocks plant)
l=l+1;n_s=l;syst(l)=list('transfer',['P11','P12';'P21','P22']);
//
//Controller
l=l+1;n_k=l;syst(l)=list('transfer','k');
//

Scilab Group April 1993 114

bloc2ss Scilab Function
//Links
l=l+1;syst(l)=list('link','w',[-1],[n_s,1]);
l=l+1;syst(l)=list('link','z',[n_s,1],[-1]);
l=l+1;syst(l)=list('link','u',[n_k,1],[n_s,2]);
l=l+1;syst(l)=list('link','y',[n_s,2],[n_k,1]);
//Evaluation call
w=bloc2exp(syst);

In this case the result is a formula equivalent to the usual one:

P11+P12*invr(eye-K*P22)*K*P21;
See Also : bloc2ss
Author : S. S., F. D. (INRIA)
3.0.247 bloc2ss block-diagram to state-space conversion
CALLING SEQUENCE :
[sl]=bloc2ss(blocd)

PARAMETERS :
blocd : list
sl : list
DESCRIPTION :
Given a block-diagram representation of a linear system bloc2ss converts this representation to
a state-space linear system. The rst element of the list blocd must be the string 'blocd'. Each
other element of this list is itself a list of one the following types :
list('transfer','name_of_linear_system')

list('link','name_of_link',
[number_of_upstream_box,upstream_box_port],
[downstream_box_1,downstream_box_1_portnumber],
[downstream_box_2,downstream_box_2_portnumber],
...)

The strings 'transfer' and 'links' are keywords which indicate the type of element in the
block diagram.
Case 1 : the second parameter of the list is a character string which may refer (for a possible
further evaluation) to the Scilab name of a linear system given in state-space representation (syslin
list) or in transfer form (matrix of rationals).
To each transfer block is associated an integer. To each input and output of a transfer block is
also associated its number, an integer (see examples)
Case 2 : the second kind of element in a block-diagram representation is a link. A link links one
output of a block represented by the pair [number of upstream box,upstream box port], to dif-
ferent inputs of other blocks. Each such input is represented by the pair [downstream box i,downstream box i portn
The dierent elements of a block-diagram can be dened in an arbitrary order.
For example
[1] S1*S2 with unit feedback.
There are 3 transfers S1 (number n s1=2) , S2 (number n s2=3) and an adder (number n add=4)
with symbolic transfer function ['1','1'].
There are 4 links. The rst one (named 'U') links the input (port 0 of ctitious block -1, omitted)
to port 1 of the adder. The second and third one link respectively (output)port 1 of the adder
to (input)port 1 of system S1, and (output)port 1 of S1 to (input)port 1 of S2. The fourth link
(named 'Y') links (output)port 1 of S2 to the output (port 0 of ctitious block -1, omitted) and
to (input)port 2 of the adder.
Scilab Group April 1993 115
c link Scilab Function
//Initialization
syst=list('blocd'); l=1;
//
//Systems
l=l+1;n_s1=l;syst(l)=list('transfer','S1'); //System 1
l=l+1;n_s2=l;syst(l)=list('transfer','S2'); //System 2
l=l+1;n_adder=l;syst(l)=list('transfer',['1','1']); //adder
//
//Links
// Inputs -1 --> input 1
l=l+1;syst(l)=list('link','U1',[-1],[n_adder,1]);
// Internal
l=l+1;syst(l)=list('link',' ',[n_adder,1],[n_s1,1]);
l=l+1;syst(l)=list('link',' ',[n_s1,1],[n_s2,1]);
// Outputs // -1 -> output 1
l=l+1;syst(l)=list('link','Y',[n_s2,1],[-1],[n_adder,2]);

With s=poly(0,'s');S1=1/(s+1);S2=1/s; the result of the evaluation call sl=bloc2ss(syst);

is a state-space representation for 1/(s^2+s-1).

[2] LFT example

//Initialization
syst=list('blocd'); l=1;
//
//System (2x2 blocks plant)
l=l+1;n_s=l;syst(l)=list('transfer',['P11','P12';'P21','P22']);
//
//Controller
l=l+1;n_k=l;syst(l)=list('transfer','k');
//
//Links
l=l+1;syst(l)=list('link','w',[-1],[n_s,1]);
l=l+1;syst(l)=list('link','z',[n_s,1],[-1]);
l=l+1;syst(l)=list('link','u',[n_k,1],[n_s,2]);
l=l+1;syst(l)=list('link','y',[n_s,2],[n_k,1]);

With
P=syslin('c',A,B,C,D);
P11=P(1,1);
P12=P(1,2);
P21=P(2,1);
P22=P(2,2);
K=syslin('c',Ak,Bk,Ck,Dk);

bloc2exp(syst) returns the evaluation the lft of P and K.

See Also : bloc2exp
Author : S. S., F. D. (INRIA)
3.0.248 c link check dynamic link
CALLING SEQUENCE :
c_link('routine-name')

Scilab Group April 1993 116

convstr Scilab Function
DESCRIPTION :
c links is a boolean function which checks if the routine 'routine-name' is currently linked.
This function returns a boolean value true or false.
EXAMPLE :
if c_link('foo') then link('foo.o','foo');end

See Also : link , fort

3.0.249 calerf computes error functions.

SYNTAX :
y = calerf(x, ag)
PARAMETERS :
x : real vector
flag : integer indicator
y : real vector (of same size)
DESCRIPTION :
calerf(x,0) computes the error function:
p Zx
y = 2=  exp(,t2 )dt
0

calerf(x,1) computes the complementary error function:

p Z 1 exp(,t2 )dt
y = 2= 
x
y = 1 , erf(x)
calerf(x,2) computes the scaled complementary error function:
1 for large x
y = exp(x2)erfc(x) xsqrt

See Also : erf , erfc, calerf.

3.0.250 cmb lin symbolic linear combination

CALLING SEQUENCE :
[x]=cmb_lin(alfa,x,beta,y)

DESCRIPTION :
Evaluates alfa*x-beta*y. alfa, beta, x, y are character strings. (low-level routine)
See Also : mulf, addf

3.0.251 conj conjugate

CALLING SEQUENCE :
[y]=conj(x)

PARAMETERS :
x,y : real or complex matrix.
DESCRIPTION :
conj(x) is the complex conjugate of x.
Scilab Group April 1993 117
debug Scilab Function
3.0.252 convstr case conversion
CALLING SEQUENCE :
[y]=convstr(str-matrix, ["flag"])

PARAMETERS :
str-matrix, y : matrices of strings
"flag" : string ( for upper or "l" for lower (default value))
"u"

DESCRIPTION :
converts the matrix of strings str-matrix into lower case (for "l" ;default value) or upper case
(for "u").
3.0.253 cos cosine function
CALLING SEQUENCE :
[y]=cos(x)

PARAMETERS :
x : real or complex vector or real or complex symmetric matrix.
DESCRIPTION :
cos(x) is the cosine of the elements of x. If X is a square and symmetric matrix cos(X) returns
I , X 2 =2! + X 4 =4! + : : :
3.0.254 cosh hyperbolic cosine
CALLING SEQUENCE :
[t]=cosh(x)

PARAMETERS :
x,t : real or complex vectors
DESCRIPTION :
The elements of vector t are the hyperbolic cosine of the corresponding entries of vector x.
3.0.255 cotg cotangent
CALLING SEQUENCE :
[t]=cotg(x)

PARAMETERS :
x,t : real or complex vectors
DESCRIPTION :
The elements of vector t are the cotangents of the corresponding entries of vector X.
3.0.256 coth hyperbolic cotangent
CALLING SEQUENCE :
[t]=coth(x)

DESCRIPTION :
the elements of vector t are the hyperbolic cotangent of elements of the vector x.
Scilab Group April 1993 118
diag Scilab Function
3.0.257 debug debugging level
CALLING SEQUENCE :
debug(level-int)

PARAMETERS :
level-int : integer (0 to 4)
DESCRIPTION :
For the values 0,1,2,3,4 of level-int , debug denes various levels of debugging. (For Scilab
experts only).
3.0.258 delip elliptic integral
CALLING SEQUENCE :
[r]=delip(x,ck)

DESCRIPTION :
returns the value of the elliptic integral with parameter ck :
Zx 1
r= q dx
0 (1 , t )(1 , ck2t2 )
2

x real and positive. When called with x a real vector r is evaluated at each coordinate of x.
See Also : amell
3.0.259 delmenu interactive button or menu deletion
CALLING SEQUENCE :
delmenu(button)
delmenu(gwin,button)

PARAMETERS :
button : a character string. The button name
gwin : integer. The number of graphic window where the button is required to be installed
DESCRIPTION :
The function allows the user to delete buttons or menus create by addmenu in the main or graphics
windows command panels.
If possible, it is better to delete rst the lattest created button for a given window to avoid
gaps in command panels.
EXAMPLE :
addmenu('foo')
delmenu('foo')

See Also : setmenu , unsetmenu, addmenu

3.0.260 demos guide for scilab demos

CALLING SEQUENCE :
demos()

DESCRIPTION :
demos() is an interactive guide to execute various scilab demonstrations
Scilab Group April 1993 119
emptystr Scilab Function
3.0.261 diag diagonal including or extracting
CALLING SEQUENCE :
[y]=diag(vm, [k])

PARAMETERS :
vm : vector or matrix
k : integer (default value 0)
y : vector or matrix
DESCRIPTION :
for vm a (row or column) n-vector diag(vm) returns a diagonal matrix with entries of vm along
the main diagonal.
diag(vm,k) is a (n+abs(k))x(n+abs(k)) matrix with the entries of vm along the kth diagonal.
k=0 is the main diagonal k>0 is for upper diagonals and k<0 for lower diagonals.
For a matrix vm, diag(vm,k) is the column vector made of entries of the kth diagonal of vm.
diag(vm) is the main diagonal of vm. diag(diag(x)) is a diagonal matrix.
To construct a diagonal linear system, use sysdiag.
Note that eye(A).*A returns a diagonal matrix made with the diagonal entries of A. This is valid
for any matrix (constant, polynomial, rational, state-space linear system,...).
For example
diag(-m:m) + diag(ones(2*m,1),1) +diag(ones(2*m,1),-1)

gives a tri-diagonal matrix of order 2*m+1

See Also : sysdiag
3.0.262 edit function editing
CALLING SEQUENCE :
newname=edit(functionname [, editor])

PARAMETERS :
functionname : character string
editor : character string
DESCRIPTION :
If functionname is the name of a dened scilab function edit(functionname ,[editor]) try to
open the associated le functionname.sci. If this le can't be modied edit rst create a copy
of this le in the TMPDIR directory.
If functionname is the name of a undened scilab function edit create a functionname.sci le
in the TMPDIR directory.
When leaving the editor the modied or dened function is loaded into Scilab under the name
newname.
The editor character string can be used to specify your favorite text editor.
Default editor is Emacs. This function should be customized according to your needs.
EXAMPLE :
newedit=edit('edit') //open editor with text of this function
myfunction=edit('myfunction') //open editor for a new function

See Also : manedit

Scilab Group April 1993 120

erfcx Scilab Function
3.0.263 emptystr zero length string
CALLING SEQUENCE :
s=emptystr()
s=emptystr(a)
s=emptystr(m,n)

PARAMETERS :
a : any type of matrix
s : character string matrix
m,n : integers
DESCRIPTION :
Returns a matrix of zero length character strings
With no input argument returns a zero length character string.
With a matrix for input argument returns a zero length character strings matrix of the same size.
With two integer arguments returns a mxn zero length character strings matrix
EXAMPLE :
x=emptystr();for k=1:10, x=x+','+string(k);end

See Also : part , length , string

3.0.264 erf The error function.

CALING SEQUENCE :
y = erf(x)

PARAMETERS :
x : real vector
y : real vector (of same size)
DESCRIPTION :
erf computes the error function:
p Zx
y = 2= () exp(,t2 )dt
0

See Also : erfc , erfcx , calerf.

3.0.265 erfc The complementary error function.

CALING SEQUENCE :
y = erfc(x)

PARAMETERS :
x : real vector
y : real vector (of same size)
DESCRIPTION :
erfc computes the complementary error function:
p Z1
y = 2= () exp(,t2 )dt
x
y = 1 , erf(x)

See Also : erf , erfcx, calerf.

Scilab Group December 1994 121

getvalue Scilab Function
3.0.266 erfcx The scaled complementary error function.
CALING SEQUENCE :
y = erfcx(x)

PARAMETERS :
x : real vector
y : real vector (of same size)
DESCRIPTION :
erfcx computes the scaled complementary error function:
p
y = exp(x2)erfc(x) (1= pi)1=xfor largex

See Also : erf , erfc, calerf.

3.0.267 eval evaluation of a matrix of strings

CALLING SEQUENCE :
[H]= eval(Z)

DESCRIPTION :
returns the evaluation of the matrix of character strings Z.
EXAMPLE :
a=1; b=2; Z=['a','b'] ; eval(Z)

returns the matrix [1,2];

See Also : evstr, execstr
3.0.268 execstr command execution by evaluation of strings
CALLING SEQUENCE :
execstr('char-string')

DESCRIPTION :
executes the Scilab command in argument. This function does not return anything.
EXAMPLE :
execstr('a=1') // sets a=1.
execstr('1+1') // does nothing (while evstr('1+1') returns 2)

See Also : evstr

3.0.269 full sparse to full matrix conversion

CALING SEQUENCE :
X=full(sp)

PARAMETERS :
sp : real or complex sparse (or full) matrix
X : full matrix
Scilab Group November 1993 122
havewindow Scilab Function
DESCRIPTION :
X=full(sp) converts the sparse matrix sp into its full representation. (If sp is already full then
X equals ).
sp
EXAMPLE :
sp=sparse([1,2;5,4;3,1],[1,2,3]);
A=full(sp)

See Also : sparse , sprand , speye

3.0.270 getvalue xwindow dialog for data acquisition

CALLING SEQUENCE :
[ok,x1,..,x11]=getvalue(desc,labels,typ,ini)

PARAMETERS :
desc : column vector of strings, dialog general comment
labels : n column vector of strings,
labels(i) is the label of the ith required value
typ :
list(typ1,dim1,..,typn,dimn)

typi : denes the type of the ith value, may have the following values:
"mat" : for constant matrix
"col" : for constant column vector
"row" : for constant row vector
"vec" : for constant vector
"str" : for string
"lis" : for list
dimi : denes the size of the ith value it must be a integer or a 2-vector of integer, -1
stands for undened dimension
ini : n column vector of strings, ini(i) gives the suggested response for the ith required value
ok : boolean ,%t if ok button pressed, %f if cancel button pressed
xi : contains the ith value if ok=%t
DESCRIPTION :
This function encapsulate x mdialog function with error checking, evaluation of numerical re-
sponse, ...
REMARKS :
All valid expressions can be used as answers; for matrices and vectors getvalues automatically
adds [ ] around the given answer before numeric evaluation.
EXAMPLE :
labels=["magnitude";"frequency";"phase "];
[ok,mag,freq,ph]=getvalue("define sine signal",labels,...
list("vec",1,"vec",1,"vec",1),["0.85";"10^2";"%pi/3"])

See Also : x_mdialog , x_matrix , x_dialog

Author : S. Steer
3.0.271 halt stop execution
CALLING SEQUENCE :
halt()

DESCRIPTION :
stops execution until something is entered in the keyboard.
See Also : pause, return

Scilab Group September 1994 123

INTERP Scilab Function
3.0.272 havewindow return scilab window mode
CALLING SEQUENCE :
havewindow()

DESCRIPTION :
returns %t if scilab has it own window and %f for scilab -nw
3.0.273 input prompt for user input
CALLING SEQUENCE :
[x]=input(message,["string"])

PARAMETERS :
message : character string
"string" : the character string "string" (may be abbreviated to "s")
x : real number (or character string if "string" is in the calling sequence)
DESCRIPTION :
input(message) gives the user the prompt in the text string and then waits for input from the
keyboard.
The input can be expression which is evaluated by evstr.
Invoked with two arguments, the output is a character string which is the expression entered at
keyboard.
EXAMPLE :
x=input("How many iterations?")
x=input("What is your name?","string")

See Also : file , read, write, %io , evstr , x_dialog , x_mdialog

3.0.274 integrate integration by quadrature

CALLING SEQUENCE :
[x]=integrate(expr,v,x0,x1 [,ea [,er]])

PARAMETERS :
expr : external Scilab
v : string (integration variable)
x0,x1 : real numbers (bounds of integration)
ea,er : real numbers (absolute and relative errors)
DESCRIPTION :
computes : Zx 1
x= f(v)dv
x0
EXAMPLE :
integrate('sin(x)','x',0,%pi)
integrate(['if x=0 then 1,';
'else sin(x)/x,end'],'x',0,%pi)

See Also : intg

Scilab Group April 1993 124

isdef Scilab Function
3.0.275 interp interpolation
CALLING SEQUENCE :
[f0 [,f1 [,f2 [,f3]]]]=interp(xd,x,f,d)

PARAMETERS :
xd : real vector
x,f,d : real vectors from spline
fi : vectors (derivatives)
DESCRIPTION :
given three vectors (x,f,d) dening a spline function (see splin) with fi=S(xi), di = S'(xi)
this primitive evaluates S (resp. S', S'', S''') at xd(i).
x : vector of xi (x(1) < x(2) < ...)
f : vector of S(xi)
d : vector of S'(xi)
f0 : vector [S(xd(1),S(xd(2)),S(xd(3)),...]
f(1 2 3) : vector of rst, second, third derivative of S at xd=[xd(1),xd(2),...] i.e.
f1 = [S'(xd(1)),S'(xd(2)),...]
f2 = [S''(xd(1)),S''(xd(2)),...]

See Also : splin , smooth , interpln

3.0.276 interpln linear interpolation

CALLING SEQUENCE :
[y]=interpln(xyd,x)

PARAMETERS :
xyd : 2 row matrix (xy coordinates of points)
x : vector (abscissae)
y : vector (y-axis values)
DESCRIPTION :
given xyd a set of points in the xy-plane and x a set of increasing abscissae, this function computes
y the corresponding y-axis values by linear interpolation.
EXAMPLE :
x=[1 10 20 30 40];
y=[1 30 -10 20 40];
plot2d(x',y',[3],"011"," ",[-10,-40,50,50]);
yi=interpln([x;y],-4:45);
plot2d((-4:45)',yi',[-1],"000");

See Also : splin , interp , smooth.

Scilab Group April 1993 125

log Scilab Function
3.0.277 isdef check variable existence
CALLING SEQUENCE :
isdef('var-name')

DESCRIPTION :
returns %T if the variable 'var-name' exists and %F otherwise.
See Also : exists, whereis, type, typeof DESCRIPTION given xyd a set of points in
the xy-plane and x a set of increasing abscissae, this function computes y the corresponding y-axis
values by linear interpolation.
EXAMPLE :
x=[1 10 20 30 40];
y=[1 30 -10 20 40];
plot2d(x',y',[3],"011"," ",[-10,-40,50,50]);
yi=interpln([x;y],-4:45);
plot2d((-4:45)',yi',[-1],"000");

See Also : splin , interp , smooth.

3.0.278 kron Kronecker product

CALLING SEQUENCE :
kron(x,y)

DESCRIPTION :
Kronecker tensor product. Same as x.*.y
3.0.279 ldivf left symbolic division
CALLING SEQUENCE :
ldivf('d','c')

DESCRIPTION :
returns the string 'cnd' Trivial simplications such as '1nc' = 'c' are performed.
See Also : rdivf
3.0.280 linspace linearly spaced vector
CALLING SEQUENCE :
[v]=linspace(x1,x2 [,n])

PARAMETERS :
x1,x2 : real or complex scalars
n : integer (number of values) (default value = 100)
v : real or complex row vector
DESCRIPTION :
Linearly spaced vector. linspace(x1, x2) generates a row vector of n (default value=100)
linearly equally spaced points between x1 and x2.
See Also : logspace
Scilab Group April 1993 126
mac2for Scilab Function
3.0.281 log logarithm
CALLING SEQUENCE :
[y]=log(x)

PARAMETERS :
x : constant, vector or matrix
DESCRIPTION :
natural logarithm.If x is a vector log(x)=[log(x1),...,log(xn)]. If x is a matrix log(x) is
the matrix logarithm of x. The result is complex if x is not positive or denite positive. If x is a
symmetric matrix, then calculation is made by schur form. Otherwise, x is assumed diagonalizable.
One has exp(log(x))=x
See Also : exp

3.0.282 log logarithm

CALLING SEQUENCE :
y=log10(x)

PARAMETERS :
x : constant, vector or matrix
DESCRIPTION :
decimal logarithm.If x is a vector log10(x)=[log10(x1),...,log10(xn)]. If x is a matrix
log10(x) is the matrix logarithm of x. The result is complex if x is not positive or denite
positive. If x is a symmetric matrix, then calculation is made by schur form. Otherwise, x is
assumed diagonalizable.
See Also : log

3.0.283 logspace logarithmically spaced vector

CALLING SEQUENCE :
logspace(d1,d2, [n])

PARAMETERS :
d1,d2 : real or complex scalar (special meaning for %pi)
n : integer (number of values) (default value = 50)
DESCRIPTION :
returns a row vector of n logarithmically equally spaced points between 10^d1 and . If
10^d2
d2=%pi then the points are between 10^d1 and pi.
See Also : linspace
Scilab Group April 1993 127
macrovar Scilab Function
3.0.284 mac2for function to fortran routine conversion
CALLING SEQUENCE :
[txt]=mac2for(lst,vtps)

PARAMETERS :
lst : list
vtps : list
txt : string (fortran code)
DESCRIPTION :
lst is the output of Scilab's primitive macr2lst which converts a compiled function into a list
which codes the internal representation of the function. Thus, mac2for is usually invoked as:
txt=mac2for(macr2lst(function),vtps).

The elements of the list vtps give the type and dimensions of variables of the calling sequence :
vtps(i)=list(typ,row_dim,col_dim)

where :
typ : is a character string giving the type of the variable :
"0" : constant,integer vector or matrix
"1" : constant,double precision vector or matrix
"10" : character string
row dim : character string (row dimension)
col dim : character string (column dimension)

txt : fortran code

REMARKS :
the following keyword :
work,iwork,ierr
iw* iiw*
ilbN (N integer)

may not appear in the function code.

See Also : function
3.0.285 macr2lst function to list conversion
CALLING SEQUENCE :
[txt]=macr2lst(function-name)

DESCRIPTION :
This primitive converts a compiled Scilab function function-name into a list which codes the
internal representation of the function. For use with mac2for.
See Also : macrovars
Scilab Group April 1993 128
norm Scilab Function
3.0.286 macrovar variables of function
CALLING SEQUENCE :
vars=macrovar(function)

PARAMETERS :
vars : list
list(in,out,globals,called,locals)
function : name of a function
DESCRIPTION :
Returns in a list the set of variables used by a function. vars is a list made of ve column vectors
of character strings
in : input variables (vars(1))
out : output variables (vars(2))
globals : global variables (vars(3))
called : names of functions called (vars(4))
locals : local variables (vars(5))
See Also : string, macr2lst
3.0.287 manedit editing a manual item
CALLING SEQUENCE :
manedit(manitem ,[editor])

PARAMETERS :
manitem : character string (usually, name of a function)
editor : character string
DESCRIPTION :
edit(manitem ,[editor]) opens the le manitem in the editor given by editor.
Default editor is Emacs. This function should be customized according to your needs.
EXAMPLE :
manedit('lqg')

See Also : whereis , edit

3.0.288 modulo arithmetic remainder modulo m

CALLING SEQUENCE :
i=modulo(n,m)

PARAMETERS :
n,m: integers
DESCRIPTION :
computes i= n (modulo m) i.e. remainder of n divided by m (n and m integers).
i= n - m .* int (n ./ m)

3.0.289 mulf symbolic multiplication

CALLING SEQUENCE :
mulf('d','c')

DESCRIPTION :
returns the string 'c*d' Trivial simplications such as '1*c' = 'c' are performed.
See Also : rdivf, addf, subf

Scilab Group April 1993 129

pol2tex Scilab Function
3.0.290 norm matrix norms
CALLING SEQUENCE :
[y]=norm(x [,flag])

PARAMETERS :
x : vector or matrix
flag : string (type of norm) (default value =2)
DESCRIPTION :
For matrices
norm(x) : or
norm(x,2) is the largest singular value of x.
norm(x,1) : l 1 norm (the largest column sum).
x
norm(x,'inf') : l innity norm of x (the largest row sum).
norm(x,'fro') : Frobenius norm i.e. sqrt(sum(diag(x'*x)))
For vectors
norm(v,p) : l p norm (
sum(v(i)^p))^(1/p) .
norm(v) :
=norm(v,2) : l 2 norm
norm(v,'inf') :
max(abs(v(i))) .
See Also : H_norm , dhnorm , h2norm

3.0.291 pen2ea pencil to E,A conversion

CALLING SEQUENCE :
[E,A]=pen2ea(Fs)

PARAMETERS :
Fs : matrix pencil s*E-A
E,A : two matrices such that Fs=s*E-A
DESCRIPTION :
Utility function

3.0.292 pertrans pertranspose

CALLING SEQUENCE :
[Y]=pertrans(X)

PARAMETERS :
X : real or complex matrix
Y : real or complex matrix
DESCRIPTION :
Y=pertrans(X) returns the pertranspose of X, i.e. the symmetric of X w.r.t the second diagonal
(utility function).
Scilab Group April 1993 130
abs Scilab Function
3.0.293 pol2tex convert polynomial to TeX format
CALLING SEQUENCE :
[y]=pol2tex(x)

PARAMETERS :
x : polynomial
y : list
DESCRIPTION :
Latex source code for the polynomial x. (For use with texprint)
See Also : texprint
3.0.294 prod product
CALLING SEQUENCE :
[y]=prod(x)

PARAMETERS :
x : real or complex vector or matrix
y : real or complex scalar
DESCRIPTION :
For vectors and matrices, prod(x) is the product of the elements of x, e.g. prod(1:n) is n!
See Also : sum
3.0.295 rdivf right symbolic division
CALLING SEQUENCE :
["r"]=ldivf("d","c")

PARAMETERS :
"d","c","r" : strings
DESCRIPTION :
returns the string "c/d" Trivial simplications such as "c/1" = "c" are performed.
See Also : rdivf

3.0.296 readc read a character string

CALLING SEQUENCE :
[c]=readc_(unit)
[c]=readc_()

DESCRIPTION :
readc reads a character string This function allows one to interrupt an exec le without pause;
the exec le stops until carriage return is made.
See Also : read
Scilab Group April 1993 131
setmenu Scilab Function
3.0.297 sci2exp converts variable to a scilab expression
CALLING SEQUENCE :
t=sci2exp(a [,nam])

PARAMETERS :
a : a scilab variable, may be
- constant,
- polynomial
- string matrix
- list
- boolean matrix
nam : character string
t : vector of string, contains the expression or instruction denition

DESCRIPTION :
sci2exp converts variable to an instruction if nam is given or to an expression .
EXAMPLE :
a=[1 2;3 4]
sci2exp(a,'aa')

sci2exp(ssrand(2,2,2))
sci2exp(poly([1 0 3 4],'s'),'fi')

3.0.298 sci2map Scilab to Maple

CALLING SEQUENCE :
sci2map(a,Map-name)

PARAMETERS :
a : Scilab object (matrix, polynomial, list, string)
Map-name : string (name of the Maple variable)
DESCRIPTION :
makes Maple code necessary to send the Scilab variable a to Maple : the name of the variable in
Maple is Map-name.
See Also : maple2scilab in directory SCIDIR/maple
3.0.299 setmenu interactive button or menu activation
CALLING SEQUENCE :
setmenu(button [,nsub])
setmenu(gwin,button [,nsub])

PARAMETERS :
button : a character string. The button name
gwin : integer. The number of graphic window where the button is installed
nsub : integer. The number of submenu to de-activate (if any). If button has no sub-menu, nsub
is ignored
Scilab Group December 1995 132
solve Scilab Function
DESCRIPTION :
The function allows the user to make active buttons or menus created by addmenu in the main or
graphics windows command panels.
EXAMPLE :
addmenu('foo')
setmenu('foo')

See Also : delmenu , unsetmenu , addmenu

3.0.300 sin sine function

CALLING SEQUENCE :
[t]=sin(x)

PARAMETERS :
x : complex vector or symmetric matrix
DESCRIPTION :
For a vector, sin(x) is the sine of its elements . For a symmetric matrix , sin(X) returns
I , X 3 =3! + X 5 =5!:::

3.0.301 sinh hyperbolic sine

CALLING SEQUENCE :
[t]=sinh(x)

PARAMETERS :
x,t : real or complex vectors
DESCRIPTION :
the elements of vector t are the hyperbolic sine of elements of vector x.
3.0.302 smooth smoothing by spline functions
CALLING SEQUENCE :
[pt]=smooth(ptd [,step])

PARAMETERS :
ptd : (2xn) real vector
step : real (discretization step of abscissae) (default=0.01*magnitude(v))
pt : (2xn) real vector
DESCRIPTION :
this function computes interpolation by spline functions for a given set of points in the plane. The
coordinates are (ptd(1,i),ptd(2,i)). The components ptd(1,:) must be in ascending order.
The default value for the step is abs(maxi(ptd(1,:))-mini(ptd(1,:)))/100
EXAMPLE :
x=[1 10 20 30 40];
y=[1 30 -10 20 40];
plot2d(x',y',[3],"011"," ",[-10,-40,50,50]);
yi=smooth([x;y],0.1);
plot2d(yi(1,:)',yi(2,:)',[-1],"000");

See Also : splin , interp , interpln

Scilab Group April 1993 133

speye Scilab Function
3.0.303 solve symbolic linear system solver
CALLING SEQUENCE :
[x]=solve(A,b)

PARAMETERS :
A,b,c : matrix (resp. vectors) of character strings
DESCRIPTION :
solves A*x = b when A is an upper triangular matrix made of character strings.
See Also : trianfml

3.0.304 sort decreasing order sorting

CALLING SEQUENCE :
[s, [k]]=sort(v)

DESCRIPTION :
sorts v (decreasing order). [s,k]=sort(v) give in addition the indices of entries of s in v.
See Also : find
3.0.305 sparse sparse matrix denition
CALLING SEQUENCE :
sp=sparse(X)
sp=sparse(ij,v [,mn])

PARAMETERS :
X : real or complex full (or sparse) matrix
ij : two columns integer matrix (indices of non-zeros entries)
mn : integer vector with two entries (row-dimension, column-dimension)
sp : sparse matrix
DESCRIPTION :
sparse is used to build a sparse matrix. Only non-zero entries are stored.
sp = sparse(X) converts a full matrix to sparse form by squeezing out any zero elements. (If X
is already sparse sp is X).
sp=sparse(ij,v [,mn]) builds an mn(1)-by-mn(2) sparse matrix with sp(ij(k,1),ij(k,2))=v(k).
ij and v must have the same column dimension. If optional mn parameter is not given the sp
matrix dimensions are the max value of ij(:,1) and ij(:,2) respectively.
Operations (concatenation, addition, etc,) with sparse matrices are made using the same syntax
as for full matrices.
Elementary functions are also available (abs,maxi,sum,diag,...) for sparse matrices.
Mixed operations (full-sparse) are allowed. Results are full or sparse depending on the operations.
EXAMPLE :
sp=sparse([1,2;4,5;3,10],[1,2,3])
size(sp)
x=rand(2,2);abs(x)-full(abs(sparse(x)))

See Also : full , spget, sprand , speye , lufact

Scilab Group January 1995 134

sprand Scilab Function
3.0.306 speye sparse identity matrix
CALING SEQUENCE :
Isp=speye(nrows,ncols)
Isp=speye(A)

PARAMETERS :
nrows : integer (number of rows)
ncols : integer (number os columns)
A : sparse matrix
sp : sparse identity matrix
DESCRIPTION :
Isp=speye(nrows,ncols) returns a sparse identity matrix Isp with nrows rows, ncols columns.
(Non square identity matrix have a maximal number of ones along the main diagonal).
Isp=speye(A) returns a sparse identity matrix with same dimensions as A. If [m,n]=size(A),
speye(m,n) and speye(A) are equivalent. In particular speye(3) is not equivalent to speye(3,3).

See Also : sparse , full , eye , spzeros

3.0.307 spget retrieves entries of sparse matrix

CALLING SEQUENCE :
[ij,v,mn]=spget(sp)

PARAMETERS :
sp : real or complex sparse matrix
ij : two columns integer matrix (indices of non-zeros entries)
mn : integer vector with two entries (row-dimension, column-dimension)
v : column vector
DESCRIPTION :
spget is used to convert the internal representation of sparse matrices into the standard ij, v
representation.
Non zero entries of sp are located in rows and columns with indinces in ij.
EXAMPLE :
sp=sparse([1,2;4,5;3,10],[1,2,3])
[ij,v,mn]=spget(sp);

See Also : sparse , sprand , speye , lufact

3.0.308 splin spline function

CALLING SEQUENCE :
splin(x,f [,"periodic"])

PARAMETERS :
x : real vector
f : real vector of same size as x
"periodic" : string ag (a periodic spline is looked for)
Scilab Group January 1995 135
sqrt Scilab Function
DESCRIPTION :
Given values fi of a function f at given points xi (fi=f(xi)) this primitive computes a third order
spline function S which interpolates the function f. The components of x must be in increasing
order. For a periodic spline f(1) must equal f(n); S is dened through the triple (x,f,d) where
d=spline(x,f) is the vector of the estimated derivatives of S at xi (fi=S(xi),di=S'(xi)). This
function should be used in conjunction with interp.
See Also : interp, smooth
3.0.309 sprand sparse random matrix
CALING SEQUENCE :
sp=sprand(nrows,ncols,fill [,typ])

PARAMETERS :
nrows : integer (number of rows)
ncols : integer (number os columns)
fill : lling coecient (density)
typ : character string ('uniform' (default) or 'normal')
sp : sparse matrix
DESCRIPTION :
sp=sprand(nrows,ncols,fill) returns a sparse matrix sp with nrows rows, ncols columns
and approximately fill*nrows*ncols non-zero entries.
If typ='uniform' uniformly distributed values are generated. If typ='normal' normally dis-
tributed values are generated.
See Also : sparse, full, rand, speye
3.0.310 spzeros sparse zero matrix
SYNTAX :
Zsp=spzeros(nrows,ncols)
Zsp=spzeros(A)
PARAMETERS :
nrows : integer (number of rows)
ncols : integer (number os columns)
A : sparse matrix
sp : sparse zero matrix
DESCRIPTION :
Zsp=spzeros(nrows,ncols,fill) returns a sparse zero matrix Zsp with nrows rows, ncols
columns. (Equivalent to sparse([],[],[nrow,ncols]))
Zsp=spzeros(A) returns a sparse zero matrix with same dimensions as A. If [m,n]=size(A),
spzeros(m,n) and spzeros(A) are equivalent. In particular spzeros(3) is not equivalent to
spzeros(3,3).
See Also : sparse, full, eye, speye
3.0.311 sqrt square root
CALLING SEQUENCE :
[y]=sqrt(x)

PARAMETERS :
Scilab Group April 1993 136
ssrand Scilab Function
x : complex vector or symmetric matrix
DESCRIPTION :
is the square root of x. Result is complex if x is negative or non-negative denite.
EXAMPLE :
x=[2,1;1,0];
norm(x)
w=sqrt(x);
norm(w*w)

See Also : sqroot

3.0.312 ssprint pretty print for linear system

CALLING SEQUENCE :
ssprint(sl [,out])

PARAMETERS :
sl : list (syslin list)
out : output (default value out=%io(2))
DESCRIPTION :
pretty print of a linear system in state-space form sl=(A,B,C,D) syslin list.
EXAMPLE :
a=[1 1;0 1];b=[0 1;1 0];c=[1,1];d=[3,2];
ssprint(syslin('c',a,b,c,d))
ssprint(syslin('d',a,b,c,d))

See Also : texprint.

3.0.313 ssrand random system generator

CALLING SEQUENCE :
sl=ssrand(nout,nin,nstate)
[sl,U]=ssrand(nout,nin,nstate,flag)

PARAMETERS :
nout : integer (number of output)
nin : integer (number of input)
nstate : integer (dimension of state-space)
flag : list made of one character string and one or several integers
sl : list (
syslin list)
U square (nstate x nstate) nonsingular matrix
DESCRIPTION :
sl=ssrand(nout,nin,nstate) returns a random strictly proper (D=0) state-space system of size
[nout,nint] represented by a
syslin list and with nstate state variables.
[sl,U]=ssrand(nout,nin,nstate,flag) returns a test linear system with given properties spec-
ied by .
flag flag can be one of the following:
Scilab Group April 1993 137
subf Scilab Function
flag=list('co',dim_cont_subs)
flag=list('uo',dim_unobs_subs)
flag=list('ncno',dim_cno,dim_ncno,dim_co,dim_nco)
flag=list('st',dim_cont_subs,dim_stab_subs,dim_stab0)
flag=list('dt',dim_inst_unob,dim_instb0,dim_unobs)
flag=list('on',nr,ng,ng0,nv,rk)
flag=list('ui',nw,nwu,nwui,nwuis,rk)

The complete description of the Sys is given in the code of the ssrand function (in SCIDIR/macros/util).
For example with flag=list('co',dim cont subs) a non-controllable system is return and dim cont subs
is the dimension of the controllable subspace of Sys. The character strings 'co','uo','ncno','st','dt','on','ui'
stand for "controllable", "unobservable", "non-controllable-non-observable", "stabilizable","detectable","output-
nulling","unknown-input".
EXAMPLE :
//flag=list('st',dim_cont_subs,dim_stab_subs,dim_stab0)
//dim_cont_subs<=dim_stab_subs<=dim_stab0
//pair (A,B) U-similar to:
// [*,*,*,*; [*;
// [0,s,*,*; [0;
//A= [0,0,i,*; B=[0;
// [0,0,0,u] [0]
//
// (A11,B1) controllable s=stable matrix i=neutral matrix u=unstsble matrix
// [Sl,U]=ssrand(2,3,8,list('st',2,5,5));
// w=ss2ss(Sl,inv(U)) //undo the random change of basis => form as above
// [n,nc,u,sl]=st_ility(Sl);n,nc

See Also : syslin

3.0.314 strcat catenate character strings

CALLING SEQUENCE :
[txt]=strcat(vstr [,strp])

PARAMETERS :
txt,strp : strings
vstr : vector of strings
DESCRIPTION :
catenates character strings : txt=strs(1)+...+strs(n)
txt=strcat(strs,opt) returns txt=strs(1)+opt+...+opt+strs(n)
EXAMPLE :
strcat(string(1:10),',')

The plus symbol does the same: "a"+"b" is the same as strcat("a","b")
See Also : string, strings
3.0.315 subf symbolic subtraction
CALLING SEQUENCE :
["c"]=subf("a","b")

PARAMETERS :
Scilab Group April 1993 138
sysdiag Scilab Function
"a","b","c" : strings
DESCRIPTION :
returns the character string c="a-b" Trivial simplications such as subf("0","a") or subf("1","2")
are performed.
See Also : mulf, ldivf, rdivf, eval, evstr.
3.0.316 sum sum of vector/matrix entries
CALLING SEQUENCE :
[y]=sum(x)
PARAMETERS :
x : vector or matrix (real, complex or polynomial)
y : scalar or vector
DESCRIPTION :
For a vector or a matrix x , sum(x) is the sum of all its entries.
See Also : prod
3.0.317 sysconv system conversion
CALLING SEQUENCE :
[s1,s2]=sysconv(s1,s2)
PARAMETERS :
s1,s2 : list (linear syslin systems)
DESCRIPTION :
Converts s1 and s2 into common representation in order that system interconnexion operations
can be applied. Utility function for experts. The conversion rules in given in the following table.
"c" : continuous time system
"d" : discrete time system
n : sampled system with sampling period n
[] : system with undened time domain
For mixed systems s1 and s2 are put in state-space representation.
s1\\s2| "c" | "d" | n2 | [] |
---------------------------------------------------------------
"c" | nothing |uncompatible | c2e(s1,n2) | c(s2) |
---------------------------------------------------------------
"d" |uncompatible| nothing | e(s1,n2) | d(s2) |
---------------------------------------------------------------
n1 | c2e(s2,n1) | e(s2,n1) | n1<>n2 uncomp | e(s2,n1) |
| | | n1=n2 nothing | |
---------------------------------------------------------------
[] | c(s1) | d(s1) | e(s1,n2) | nothing |
---------------------------------------------------------------

With the following meaning:

n1,n2 : sampling period
c2e(s,n) : the continuous-time system s is transformed into a sampled system with sampling
period n.
c(s) : conversion to continuous (time domain is "c")
d(s) : conversion to discrete (time domain is "d")
e(s,n) : conversion to samples system with period n

See Also : syslin, ss2tf, tf2ss

Scilab Group April 1993 139
syslin Scilab Function
3.0.318 sysdiag block diagonal system connection
CALLING SEQUENCE :
r=sysdiag(a1,a2,...,an)

DESCRIPTION :
Returns the block-diagonal system made with subsystems put in the main diagonal
ai : subsystems (i.e. gains, or linear systems in state-space or transfer form)

Used in particular for system interconnections.

REMARK :
At most 17 arguments.
EXAMPLES :
s=poly(0,'s')
sysdiag(rand(2,2),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])
sysdiag(tf2ss(1/s),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])

s=poly(0,'s')
sysdiag(rand(2,2),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])
sysdiag(tf2ss(1/s),1/(s+1),[1/(s-1);1/((s-2)*(s-3))])

See Also : ,
concatenation insertion , feedback.

3.0.319 syslin linear system denition

CALLING SEQUENCE :
[sl]=syslin(dom,A,B,C [,D [,x0] ])
[sl]=syslin(A,B,C [,D [,x0] ])
[sl]=syslin(dom,N,D)
[sl]=syslin(dom,H)

PARAMETERS :
dom : character string ('c', 'd'), or [] or a scalar. (If omitted, dom=[])
A,B,C,D : matrices of the state-space representation (D optional with default value zero matrix).
For improper systems D is a polynomial matrix.
x0 : vector (initial state; default value is 0)
N, D : polynomial matrices
H : rational matrix
sl : list ("syslin" list) representing the linear system

DESCRIPTION :
syslin denes a linear system as a list and checks consistency of data.
dom species the time domain of the system and can have the following values:
dom='c' for a continuous time system, dom='d' for a discrete time system, n for a sampled system
with sampling period n (in seconds).
dom=[] if the time domain is undened (dom can be omitted in the calling sequence)
State-space representation:
sl=syslin(dom,A,B,C [,D [,x0] ])

represents the system :

s x = A*x + B*u
y = C*x + D*u
x(0) = x0

Scilab Group April 1993 140

texprint Scilab Function
The output of syslin is a list of the following form: sl=list('lss',A,B,C,D,x0,dom) Note that
D is allowed to be a polynomial matrix (improper systems).
Transfer matrix representation:
sl=syslin(dom,N,D)
sl=syslin(dom,H)

The output of syslin is a list of the followingform : sl=list('r',N,D,dom) or sl=list('r',H(2),H(3),dom).

Linear systems dened as syslin can be manipulated as usual matrices (concatenation, extraction,
transpose, multiplication, etc) both in state-space or transfer representation.
Most of state-space control functions receive a syslin list as input instead of the four matrices
dening the system.
EXAMPLES :
A=[0,1;0,0];B=[1;1];C=[1,1];
S1=syslin('c',A,B,C)
s=poly(0,'s');
D=s;
S2=syslin('c',A,B,C,D)
H1=(1+2*s)/s^2, S1bis=syslin('c',H1)
H2=(1+2*s+s^3)/s^2, S2bis=syslin('c',H2)
S1+S2
[S1,S2]
ss2tf(S1)-S1bis
S1bis+S2bis
S1*S2bis
size(S1)

See Also : ssrand , ss2tf , tf2ss , dscr

3.0.320 tan tangent

CALLING SEQUENCE :
[t]=tan(x)

PARAMETERS :
x : vector or symmetric matrix
t : vector or matrix
DESCRIPTION :
the elements of vector t are the tangent of the elements of vector x. If x is a square and symmetric
matrix tan(x) is the series.

3.0.321 tanh hyperbolic tangent

CALLING SEQUENCE :
[t]=tanh(x)

DESCRIPTION :
the elements of vector t are the hyperbolic tangents of the elements of th vector x
Scilab Group April 1993 141
tril Scilab Function
3.0.322 texprint TeX output of Scilab object
CALLING SEQUENCE :
[text]= texprint(a)

PARAMETERS :
a : Scilab object
text : list
DESCRIPTION :
returns the Tex source code of the Scilab variable a. a is a matrix (constant, polynomial, rational)
or a linear system (syslin list).
See Also : pol2tex, pol2str
3.0.323 timer cpu time
CALLING SEQUENCE :
timer()

DESCRIPTION :
Returns the CPU time from the preceding call to timer().
3.0.324 toeplitz toeplitz matrix
CALING SEQUENCE :
A=toeplitz(c [,r])

PARAMETERS :
a,c,r : constant, polynomial or character chain matrices
DESCRIPTION :
returns the Toeplitz matrix whose rst row is r and rst column is c. c(1) must be equal to
.
r(1) toeplitz(c) returns the symmetric Toeplitz matrix.
3.0.325 trfmod poles and zeros display
CALLING SEQUENCE :
[hm]=trfmod(h [,job])

DESCRIPTION :
To visualize the pole-zero structure of a SISO transfer function h .
job='p' : visualization of polynomials (default)
job='f' : visualization of natural frequencies and damping
Interactive simplication of h.
See Also : poly
3.0.326 trianfml symbolic triangularization
CALLING SEQUENCE :
[f [,sexp]]=trianfml(f [,sexp])

DESCRIPTION :
Triangularization of the symbolic matrix f ; triangularization is performed by elementary row
operations; sexp is a set of common expressions stored by the algorithm.
Scilab Group April 1993 142
unsetmenu Scilab Function
3.0.327 tril lower triangular part of matrix
CALLING SEQUENCE :
tril(x [,k])

PARAMETERS :
x : matrix
k : integer (default value 0)
DESCRIPTION :
Lower triangle part of a matrix. tril(x,k) is made by entries below the kth diagonal : k>0
(upper diagonal) and k<0 (diagonals below the main diagonal).
3.0.328 trisolve symbolic linear system solver
CALLING SEQUENCE :
[x [,sexp]] = trisolve(A,b [,sexp])

PARAMETERS :
A,b : matrices of strings
DESCRIPTION :
symbolically solves A*x =b , A being assumed to be upper triangular.
sexp is a vector of common subexpressions in A, b, x.
See Also : trianfml
Author : F.D, S.S
3.0.329 triu upper triangle
DESCRIPTION :
Upper triangle. See tril.
3.0.330 typeof object type
CALLING SEQUENCE :
[t]=typeof(object)

PARAMETERS :
object : Scilab object
t : string
DESCRIPTION :
t=typeof(object) returns one of the following strings:
"usual" if object is a real or complex matrix
"polynomial" if object is a polynomial matrix
"macro" if object is a function
"character" if object is a matrix made of character strings
"boolean" if object is a boolean matrix
"list" if object is a list
"rational" if object is a rational matrix (transfer matrix)
"state-space" if object is a state-space model (see syslin)
"sparse" if object is a (real) sparse matrix.

See Also : type, strings, rationals, syslin, poly

Scilab Group December 1995 143
x choose Scilab Function
3.0.331 unsetmenu interactive button or menu or submenu
de-activation
CALLING SEQUENCE :
unsetmenu(button,[nsub])
unsetmenu(gwin,button,[nsub])

PARAMETERS :
button : a character string. The button name
gwin : integer. The number of graphic window where the button is installed
nsub : integer. The number of submenu to de-activate (if any). If button has no sub-menu, nsub
is ignored
DESCRIPTION :
The function allows the user to desactivate buttons or menus created by addmenu in the main or
graphics windows command panels.
EXAMPLE :
addmenu('foo')
unsetmenu('foo')

unsetmenu('File',2)

See Also : delmenu , setmenu, addmenu

3.0.332 x choices interactive Xwindow choices through toggle

buttons
CALLING SEQUENCE :
[rep]=x_choices(title,items)

PARAMETERS :
title : vector of strings, title for the popup window.
items : a list of items items=list(item1,...,itemn), where each item is also a list of the
following type : item=list('label',default choice,choices). default choice is an
integer which gives the default toggle on entry and choices is a row vector of strings which
gives the possible choices.
rep : an integer vector which gives for each item the number of the selected toggle.

DESCRIPTION :
Select items through toggle lists and return in rep the selected items
Type x choices() to see an example.
EXAMPLE :
l1=list('choice 1',1,['toggle c1','toggle c2','toggle c3']);
l2=list('choice 2',2,['toggle d1','toggle d2','toggle d3']);
l3=list('choice 3',3,['toggle e1','toggle e2']);
rep=x_choices('Toggle Menu',list(l1,l2,l3));

Scilab Group April 1993 144

x mdialog Scilab Function
3.0.333 x choose interactive Xwindow choice
CALLING SEQUENCE :
[num]=x_choose(items,title)

PARAMETERS :
items : column vector of string, items to choose
title : column vector of string, comment for the dialog
num : integer, choosen item number or 0 if dialog resumed with "Cancel" button
DESCRIPTION :
Returns in num the number of the chosen item.
EXAMPLE :
n=x_choose(['item1';'item2';'item3'],['that is a comment';'for the dialog'])

3.0.334 x dialog Xwindow dialog

CALLING SEQUENCE :
result=x_dialog(labels,valueini)

PARAMETERS :
labels : column vector of strings, comment for dialog
valueini : n column vector of strings, initial value suggested
result : response : n column vector of strings if returned with "Ok" button or [] if returned
with "Cancel" button
DESCRIPTION :
Creates an X-window multi-lines dialog
EXAMPLE :
gain=evstr(x_dialog('value of gain ?','0.235'))

x_dialog(['Method';'enter sampling period'],'1')

m=evstr(x_dialog('enter a 3x3 matrix ',['[0 0 0';'0 0 0';'0 0 0]']))

See Also : x_mdialog , x_matrix , evstr , execstr

3.0.335 x matrix Xwindow editing of matrix

CALLING SEQUENCE :
[result]=x_matrix(label,matrix-init)

PARAMETERS :
label : chracter string (name of matrix)
matrix-init : real matrix
DESCRIPTION :
For reading or editing a matrix .
EXAMPLE :
m=evstr(x_matrix('enter a 3x3 matrix ',rand(3,3)))

See Also : x_mdialog , x_dialog

Scilab Group April 1993 145

x message Scilab Function
3.0.336 x mdialog Xwindow dialog
CALLING SEQUENCE :
result=x_mdialog(title,labels,default_inputs_vector)
result=x_mdialog(title,labelsv,labelsh,default_input_matrix)

PARAMETERS :
title : column vector of strings, dialog general comment
labels : n column vector of strings, labels(i) is the label of the ith required value
default input vector : n column vector of strings, default input vector(i) is the initial
value of the ith required value
labelsv : n vector of strings, labelsv(i) is the label of the ith line of the required matrix
labelsh : m vector of strings, labelsh(j) is the label of the jth column of the required matrix
default input matrix : n x m matrix of strings, default input matrix(i,j) is the initial
value of the (i,j) element of then required matrix
result : n x m matrix of string if returned with "Ok" button or [] if returned with "Cancel"
button
DESCRIPTION :
X-window vector/matrix interactive input function
EXAMPLES :
txt=['magnitude';'frequency';'phase '];
sig=x_mdialog('enter sine signal',txt,['1';'10';'0'])
mag=evstr(sig(1))
frq=evstr(sig(2))
ph=evstr(sig(3))

rep=x_mdialog(['System Simulation';'with PI regulator'],...

['P gain';'I gain '],[' ';' '])

n=5;m=4;mat=rand(n,m);
row='row';labelv=row(ones(1,n))+string(1:n)'
col='col';labelh=col(ones(1,m))+string(1:m)'
new=evstr(x_mdialog('Matrix to edit',labelv,labelh,string(mat)))

See Also : x_dialog , x_choose , x_message , getvalue , evstr , execstr

3.0.337 x message X window message

CALLING SEQUENCE :
[num]=x_message(strings [,buttons])

PARAMETERS :
strings : vector of characters strings to be displayed
buttons : character string or 2 vector of character strings wich species button(s) name(s).
Default value is "Ok"
num : number of button clicked (if 2 buttons are specied)

DESCRIPTION :
for displaying a message (diagnostic, user-guide ...)
EXAMPLES :
Scilab Group April 1993 146
zeros Scilab Function
gain=0.235;x_message('value of gain is :'+string(gain))
x_message(['singular matrix';'use least squares'])

r=x_message(['Your problem is ill conditionned';

'continue ?'],['Yes','No'])

See Also : x_dialog, x_mdialog

3.0.338 xgetle dialog to get a le path

CALLING SEQUENCE :
path=xgetfile([file_mask], [dir])

PARAMETERS :
file mask : a character string which gives the le mask to use for le selection. file mask is
written with Unix convention. the default value is '*'.
dir : a character string which gives the initial directory used for le search. by default xgetle
uses the previously selected directory.
path : is the user selected le path if user answers "Ok" or the " " string if user answers "Cancel"

DESCRIPTION :
Creates a dialog window for le selection
EXAMPLE :
xgetfile()
xgetfile('*.sci','SCI/macros/xdess')

See Also : x_dialog, file , read , write , exec , getf

3.0.339 zeros matrix made of zeros

CALLING SEQUENCE :
[y]=zeros(m,n)
[y]=zeros(x)

PARAMETERS :
x,y : matrices
m,n : integers
DESCRIPTION :
Matrix made of zeros (same as 0*ones).
zeros(m,n) : for an (m,n) matrix.
zeros(A) : for a matrix of same size of A.
zeros(3) : is zeros(a) with a=3 i.e it is NOT a 3x3 matrix!

If x is a syslin list (linear system in state-space or transfer form), zeros(x) is also valid and
returns a zero matrix.
See Also : eye, ones

Scilab Group April 1993 147

zeros Scilab Function

Scilab Group April 1993 148

Chapter 4

General System and Control

macros

149
abinv Scilab Function
4.0.340 abcd state-space matrices
CALLING SEQUENCE :
[A,B,C,D]=abcd(sl)

PARAMETERS :
sl : linear system (syslin list) in state-space or transfer form
A,B,C,D : real matrices of appropriate dimensions
DESCRIPTION :
returns the A,B,C,D matrices from a linear system Sl.
Utility function. For transfer matrices Sl is converted into state-space form by tf2ss.
The matrices A,B,C,D are the elements 2 to 5 of the syslin list Sl, i.e. [A,B,C,D] = Sl(2:5)
.
See Also : syslin
4.0.341 abinv AB invariant subspace
CALLING SEQUENCE :
[X,nr,nvg,nv,F,k,Z]=abinv(Sl,alfa)

PARAMETERS :
:
sl syslin list containing the matrices [A,B,C,D].
alpha : real number or vector (possibly complex, location of closed loop poles)
X : orthogonal matrix of size nx (dim of state space).
nr,nvg,nv : three integers with nr<=nvg<=nv
F : real matrix (state feedback)
k : integer (normal rank of Sl)
Z : non-singular linear system (syslin list)
DESCRIPTION :
Output nulling subspace (maximal unobservable subspace) for Sl = linear system dened by a
syslin list containing the matrices [A,B,C,D] of Sl. The nv rst columns of X i.e V=X(:,1:nv),
span this subspace which is also the unobservable subspace of (A+B*F,C+D*F).
The nr rst columns of X spans R, the controllable part of V, (nr<=nv). nr=0 for a left invertible
system.
The nvg rst columns of X spans Vg=maximal AB-stabilizable subspace. (nr<=nvg<=nv). The
modes of X2'*(A*BF)*X(:,1:nvg) are either assignable or stable. For X=[V,X2] (X2=X(:,nv+1:nx))
one has X2'*(A+B*F)*V=0 and (C+D*F)*V=0.
The zeros are given by : X0=X(:,nr+1:nv); spec(X0'*(A+B*F)*X0) i.e. nv-nr closed-loop xed
modes. If the optional real parameter alfa is given as input, the nr controllable modes of (A+BF)
are set to alfa.
Z is a column compression of Sl and k the normal rank of Sl. (nv=nx i C^(-1)(D)=0).

DDPS:
Find u=Fx+Rd which reject Q*d and stabilizes the plant:

xdot=Ax+Bu+Qd
y=Cx+Du
DDPS has a solution iff Im(Q) is included in Vg + Im(B).
Let G=(X(:,nvg+1:nx))'= left anihilator of Vg i.e. G*Vg=0;
B2=G*B; Q2=G*Q; DDPS solvable iff B2(:,1:k)*R1 + Q2 =0 has a solution.
R=[R1;*] is the solution (with F=output of abinv).
Im(Q2) is in Im(B2) means row-compression of B2=>row-compression of Q2
Then C*[(sI-A-B*F)^(-1)+D]*(Q+B*R) =0 (<=>G*(Q+B*R)=0)

Scilab Group April 1993 150

ARL2 Scilab Function
EXAMPLE :
nu=3;ny=4;nx=7;
nrt=2;ngt=3;ng0=3;nvt=5;rk=2;
flag=list('on',nrt,ngt,ng0,nvt,rk);
Sl=ssrand(ny,nu,nx,flag);alfa=-1;
[X,nr,nvg,nv,F,k,Z]=abinv(Sl,alfa);
[A,B,C,D]=abcd(Sl);
V=X(:,1:nv);X2=X(:,nv+1:nx);
X2'*(A+B*F)*V
(C+D*F)*V
X0=X(:,nr+1:nv); spec(X0'*(A+B*F)*X0)
trzeros(Sl)
clean(ss2tf(Sl*Z))

Author : F.D.
See Also : abinv , st_ility , ssrand

4.0.342 arhnk Hankel norm approximant

CALLING SEQUENCE :
[slm]=arhnk(sl,ord,[tol])

PARAMETERS :
sl : linear system (syslin list)
ord : integer, order of the approximant
tol : threshold for rank determination in equil1
DESCRIPTION :
computes slm , the optimal Hankel norm approximant of the continuous-time linear system
sl=[A,B,C,D] .
See Also : equil , equil1

4.0.343 arl2 SISO model realization by L2 transfer approximation

CALLING SEQUENCE :
[den,num,err]=arl2(y,den0,n [,imp])
[den,num,err]=arl2(y,den0,n [,imp],'all')

PARAMETERS :
y : real vector or polynomial in z^-1, it contains the coecients of the Fourier's series of the
rational system to approximate (the impulse response)
den0 : a polynomial which gives an initial guess of the solution, it may be poly(1,'z','c')
n : integer, the degree of approximating transfer function (degree of den)
imp : integer in (0,1,2) (verbose mode)
den : polynomial or vector of polynomials, contains the denominator(s) of the solution(s)
num : polynomial or vector of polynomials, contains the numerator(s) of the solution(s)
err : real constant or vector , the l2-error achieved for each solutions

DESCRIPTION :
[den,num,err]=arl2(y,den0,n [,imp]) nds a pair of polynomials num and den such that the
transfer function num/den is stable and it's impulse response approximates (with a minimal l2
norm) the vector y assumed to be completed by an innite number of zeros.
Scilab Group April 1993 151
cainv Scilab Function
If :
y(z) = y(1)( z1 ) + y(2)( 1z )2 + : : : + y(ny)( z1 )n y
then l2-norm of num/den - y(z) is err.
n is the degree of the polynomial den.
The num/den transfer function is a L2 approximant of the
Various intermediate results are printed according to imp.
[den,num,err]=arl2(y,den0,n [,imp],'all') returns in the vectors of polynomials num and
den a set of local optimums for the problem. The solutions are sorted with increasing errors err.
In this case den0 is already assumed to be poly(1,'z','c')
EXAMPLE :
v=ones(1,20);
xbasc();
plot2d1('enn',0,[v';zeros(80,1)],-2,'051',' ',[1,-0.5,100,1.5])

[d,n,e]=arl2(v,poly(1,'z','c'),1)
plot2d1('enn',0,ldiv(n,d,100),-2,'000')
[d,n,e]=arl2(v,d,3)
plot2d1('enn',0,ldiv(n,d,100),-3,'000')
[d,n,e]=arl2(v,d,8)
plot2d1('enn',0,ldiv(n,d,100),-5,'000')

[d,n,e]=arl2(v,poly(1,'z','c'),5,'all')
plot2d1('enn',0,ldiv(n(1),d(1),100),-10,'000')

See Also : ldiv , imrep2ss , time_id , armax , frep2tf

4.0.344 balreal balanced realization

CALLING SEQUENCE :
[slb [,U] ] = balreal(sl)

PARAMETERS :
sl,slb : linear systems (syslin lists)
DESCRIPTION :
Balanced realization of linear system sl=[A,B,C,D]. sl can be a continuous-time or discrete-time
state-space system.
slb=[inv(U)*A*U ,inv(U)*B , C*U , D]

is the balanced realization.

slb is returned as a syslin list.
See Also : ctr_gram , obs_gram, hankelsv , equil , equil1

4.0.345 cainv Dual of abinv

CALLING SEQUENCE :
[Y,ns,nsg,nn,J,k,Z]=cainv(Sl,alfa)

PARAMETERS :
:
sl syslin list containing the matrices [A,B,C,D].
alpha : real number or vector (possibly complex, location of closed loop poles)
Scilab Group April 1993 152
calfrq Scilab Function
Y : orthogonal matrix of size nx (dim of state space).
ns,nsg,nn : three integers
J : real matrix (output injection)
k : integer (normal rank of Sl)
Z : non-singular linear system (syslin list)
DESCRIPTION :
cainv nds a basis Y and output injection J such that the abcd matrices of ss2ss(Sl,Y,[],J))
are:
[*,*,*,*] [*]
(Y'A + J*C)*Y = [0,u,*,*] B + J*D = [0]
[0,0,s,*] [0]
[0,0,0,*] [0]

C*Y = [*,*,*,*] D= [*]

[0,0,0,*] [0]

where the modes of A22 (u) are unstable, modes of A33 (s) are stable, pair (A44, C24) is observable,
poles of A44 set to alfa.
The ns rst columns of Y span S= smallest (C,A) invariant subspace which contains Im(B), nsg
rst columns of Y span Sg, nn rst columns of Y span N=S+V. (ns=0 i B(ker(D))=0).
// DDEP: dot(x)=A x + Bu + Gd
// y= Cx (observation)
// z= Hx (z=variable to be estimated, d=disturbance)
// Find: dot(w) = Fw + Ey + Ru such that
// zhat = Mw + Ny
// z-Hx goes to zero at infinity
// Solution exists iff Ker H contains Sg(A,C,G) inter KerC
//i.e. H is such that:
// For any W which makes a column compression of [Yp(1:nsg,:);C]
// with Yp=Y' and [Y,ns,nsg,nn,J,k,Z]=cainv(syslin('c',A,G,C));
// [Yp(1:nsg,:);C]*W = [0 | *] one has
// H*W = [0 | *] (with at least as many columns as above).

See Also : abinv , dt_ility

4.0.346 calfrq frequency response discretization

CALLING SEQUENCE :
[frq,bnds]=calfrq(h,[fmin,fmax])

PARAMETERS :
h : SISO linear system (syslin list)
fmin,fmax : real scalars (min and max frequencies)
frq : row vector (discretization of interval)
bnds : vector (bounds of the response)
DESCRIPTION :
frequency response discretization ; frq is the discretization of [fmin,fmax] such that the peaks
in the frequency response are well represented. The bounds of real part and imaginary part of the
frequency response in [fmin,fmax] are given by bnds.
Default values for fmin and fmax are 1.d-3, 1.d+3 if h is continuous-time or 1.d-3, 0.5 if h is
discrete-time.
EXAMPLE :
Scilab Group April 1993 153
colregul Scilab Function
s=poly(0,'s')
h=syslin('c',(s^2+2*0.9*10*s+100)/(s^2+2*0.3*10.1*s+102.01))
h1=h*syslin('c',(s^2+2*0.1*15.1*s+228.01)/(s^2+2*0.9*15*s+225))
[f1,b1]=calfrq(h1,0.01,1000);
rf=repfreq(h1,f1);
plot2d(real(rf)',imag(rf)')

See Also : bode , black , nyquist , freq , repfreq , logspace

4.0.347 canon canonical controllable form

CALLING SEQUENCE :
[Ac,Bc,U,ind]=canon(A,B)

PARAMETERS :
Ac,Bc : canonical form
U : current basis (square nonsingular matrix)
ind : vector of integers, controllability indices
DESCRIPTION :
gives the canonical controllable form of the pair (A,B).
Ac=inv(U)*A*U, Bc=inv(U)*B
See Also : obsv_mat , cont_mat , ctr_gram , contrss , ppol , contr
Author : F.D.

4.0.348 cls2dls bilinear transform

CALLING SEQUENCE :
[sl1]=cls2dls(sl,T [,fp])

PARAMETERS :
sl,sl1 : linear systems (syslin lists)
T : real number, the sampling period
fp : prevarping frequency in hertz
DESCRIPTION :
given sl=[A,B,C,D] (syslin list),a continuous time system cls2dls returns the sampled system
obtained by the bilinear transform s=(2/T)*(z-1)/(z+1).
EXAMPLE :
s=poly(0,'s');z=poly(0,'z');
sl=syslin('c',(s+1)/(s^2-5*s+2)); //Continuous-time system in transfer form
slss=tf2ss(sl); //Now in state-spece form
sl1=cls2dls(slss,0.2); //sl1= output of cls2dls
sl1t=ss2tf(sl1) // Converts in transfer form
sl2=horner(sl,(2/0.2)*(z-1)/(z+1)) //Compare sl2 and sl1

See Also : horner

Scilab Group April 1993 154

CONTR Scilab Function
4.0.349 colregul removing poles and zeros at innity
CALLING SEQUENCE :
[Stmp,Ws]=colregul(Sl,alfa,beta)

PARAMETERS :
:
Sl,Stmp syslin lists
alfa,beta : reals (new pole and zero positions)
DESCRIPTION :
computes a prelter Ws such that Stmp=Sl*Ws is proper and with full rank D matrix.
Poles at innity of Sl are moved to alfa;
Zeros at innity of Sl are moved to beta;
Sl is a assumed to be a left invertible linear system (syslin list) in state-space representation
with possibly a polynomial D matrix.
See Also : invsyslin, inv, rowregul
Author : F. D. , R. N.
4.0.350 cont frm transfer to controllable state-space
CALLING SEQUENCE :
[sl]=cont_frm(num,den)

PARAMETERS :
NUM : polynomial matrix
den : polynomial
:
sl syslin list, sl=[A,B,C,D].
DESCRIPTION :
controllable state-space form of the transfer NUM/den.
EXAMPLE :
s=poly(0,'s');NUM=[1+s,s];den=s^2-5*s+1;
sl=cont_frm(NUM,den);
slss=ss2tf(sl); //Compare with NUM/den

See Also : tf2ss , canon

4.0.351 cont mat controllability matrix

CALLING SEQUENCE :
[cc]=cont_mat(A,B)
[cc]=cont_mat(sl)

PARAMETERS :
a,b : two real matrices of appropriate dimensions
sl : linear system (syslin list)
DESCRIPTION :
cont mat returns the controllability matrix of the pair A,B (resp. of the system sl=[A,B,C,D]).
cc=[B, AB, A^2 B,..., A^(n-1) B]

See Also : ctr_gram

Scilab Group April 1993 155

csim Scilab Function
4.0.352 contr controllability, controllable subspace
CALLING SEQUENCE :
[n [,U]]=contr(A,B [,tol])
[A1,B1,U,ind]=contr(A,B [,tol])

PARAMETERS :
A, B : real matrices
tol : may be the constant rtol or the 2 vector [rtol atol]
rtol :tolerance used when evaluating ranks (QR factorizations).
atol :absolute tolerance (the B matrix is assumed to be 0 if norm(B)<atol)
n : dimension of controllable subspace.
U : orthogonal change of basis which puts (A,B) in canonical form.
A1 : block Hessenberg matrix
B1 : is U'*B.
ind : vector of controllability indexes (dimensions of subspaces B, B+A*B,...)

DESCRIPTION :
[n,[U]]=contr(A,B,[tol]) gives the controllable form of an (A,B) pair.(dx/dt = A x + B u
or x(n+1) = A x(n) +b u(n)). The n rst columns of U make a basis for the controllable sub-
space.
If V=U(:,1:n), then V'*A*V and V'*B give the controllable part of the (A,B) pair.
[A1,B1,U,ind]=contr(A,B) returns the Hessenberg controllable form of (A,B).
See Also : canon, cont_mat, unobs, stabil
4.0.353 contrss controllable part
CALLING SEQUENCE :
[slc]=contrss(sl [,tol])

PARAMETERS :
sl : linear system (syslin list)
tol : is a threshold for controllability (see contr). default value is sqrt(%eps).
DESCRIPTION :
returns the controllable part of the linear system sl = (A,B,C,D) in state-space form.
EXAMPLE :
A=[1,1;0,2];B=[1;0];C=[1,1];sl=syslin('c',A,B,C); //Non minimal
slc=contrss(sl);
sl1=ss2tf(sl);sl2=ss2tf(slc); //Compare sl1 and sl2

See Also : cont_mat , ctr_gram , cont_frm , contr

4.0.354 csim simulation (time response) of linear system

CALLING SEQUENCE :
[y [,x]]=csim(u,t,sl,[x0])

PARAMETERS :
u : function, list or string (control)
t : real vector specifying times with, t(1) is the initial time (x0=x(t(1))).
Scilab Group April 1993 156
des2tf Scilab Function
sl : list (syslin)
y : a matrix such that y=[y(t(i)], i=1,..,n
x : a matrix such that x=[x(t(i)], i=1,..,n
DESCRIPTION :
simulation of the controlled linear system sl. sl is assumed to be a continuous-time system
represented by a syslin list.
u is the control and x0 the initial state.
y is the output and x the state.
The control can be:
1. a function : [inputs]=u(t)
2. a list : list(ut,parameter1,....,parametern) such that: inputs=ut(t,parameter1,....,parametern)
(ut is a function)
3. the string "impuls" for impulse response calculation (here sl is assumed SISO without direct
feed through and x0=0)
4. the string "step" for step response calculation (here sl is assumed SISO without direct feed-
through and x0=0)
EXAMPLE :
s=poly(0,'s');rand('seed',0);w=ssrand(1,1,3);w(2)=w(2)-2*eye;
t=0:0.05:5;
//impulse(w) = step (s * w)
xbasc(0);xset("window",0);xselect();
plot2d([t',t'],[(csim('step',t,tf2ss(s)*w))',0*t'])
xbasc(1);xset("window",1);xselect();
plot2d([t',t'],[(csim('impulse',t,w))',0*t'])
//step(w) = impulse (s^-1 * w)
xbasc(3);xset("window",3);xselect();
plot2d([t',t'],[(csim('step',t,w))',0*t'])
xbasc(4);xset("window",4);xselect();
plot2d([t',t'],[(csim('impulse',t,tf2ss(1/s)*w))',0*t'])

See Also : syslin , dsimul , flts , ltitr , rtitr , ode, impl

4.0.355 ctr gram controllability gramian

CALLING SEQUENCE :
[Gc]=ctr_gram(A,B [,dom])
[Gc]=ctr_gram(sl)

PARAMETERS :
A,B : two real matrices of appropriate dimensions
dom : character string ('c' (default value) or 'd')
sl : linear system, syslin list
DESCRIPTION :
Controllability gramian of (A,B) or sl (a syslin linear system).
dom character string giving the time domain : "d" for a discrete time system and "c" for contin-
uous time (default case).
Z1 X
1
Gc = eAt BB 0 eA tdt Gc = Ak BB 0 A0 k
0

0 0

See Also : cont_mat , cont_frm , contrss

Author : S. Steer INRIA 1988
Scilab Group April 1993 157
dsimul Scilab Function
4.0.356 des2tf descriptor to transfer function conversion
CALLING SEQUENCE :
[S]=des2tf(sl)
[Bfs,Bis,chis]=des2tf(sl)

PARAMETERS :
sl : list (linear system in descriptor form)
Bfs, Bis : two polynomial matrices
chis : polynomial
S : rational matrix
DESCRIPTION :
Given the linear system in descriptor form i.e. Sl=list('des',A,B,C,0,E), des2tf converts sl
into its transfer function representation:
S=C*(s*E-A)^(-1)*B

Called with 3 outputs arguments des2tf returns Bfs and Bis two polynomial matrices, and chis
polynomial such that:
S=Bfs/chis - Bis

chis is the determinant of (s*E-A) (up to a xcative constant);

See Also : glever, pol2des, tf2des, ss2tf, des2ss, rowshuff
Author : F. D.
4.0.357 dscr discretization of linear system
CALLING SEQUENCE :
[sld [,r]]=dscr(sl,dt [,m])

PARAMETERS :
:
sl syslin list containing [A,B,C,D].
dt : real number, sampling period
m : covariance of the input noise (continuous time)(default value=0)
r : covariance of the output noise (discrete time) given if m is given as input
sld : sampled (discrete-time) linear system, syslin list
DESCRIPTION :
Discretization of linear system. sl is a continuous-time system:
dx/dt=A*x+B*u (+ noise) .
sld is the discrete-time system obtained by sampling sl with the sampling period dt.
See Also : flts, dsimul
4.0.358 dsimul discrete time response
CALLING SEQUENCE :
[y]=dsimul(sl,u)

PARAMETERS :
sl : syslin list for a state-space discrete time linear system, sl=syslin('d',A,B,C,D,x0)
u : matrix of inputs
Scilab Group April 1993 158
equil1 Scilab Function
y : matrix of outputs
DESCRIPTION :
Time response for the strictly proper discrete-time system sl dened by:
x(k+1)=A*x(k)+B*u(k)
y(k+1)=C*x(k+1)
x(0)=x0

with inputs u=[u(1),....,u(n)] (u(i) = vector of inputs at time i.

Note that the d matrix of sl is zero.
See Also : rtitr, ltitr, dscr
4.0.359 dt ility detectability test
CALLING SEQUENCE :
[k, [n [,U [,Sld ] ] ]]=dt_ility(Sl [,tol])

PARAMETERS :
Sl : linear system (syslin list)
n : dimension of unobservable subspace
k : dimension of unstable, unobservable subspace ( k<=n ).
U : orthogonal matrix
Sld : linear system (syslin list)
tol : threshold for controllability test.
DESCRIPTION :
Detectability test for sl, a linear system in state-space representation. U is a basis whose k rst
columns span the unstable, unobservable subspace of Sl (intersection of unobservable subspace of
(A,C) and unstable subspace of A). Detectability means k=0.
Sld = (U'*A*U,U'*B,C*U,D) displays the "detectable part" of Sl=(A,B,C,D), i.e.

[*,*,*]
U'*A*U = [0,*,*]
[0,0,*]

C*U = [0,0,*]

with (A33,C3) observable (dimension nx-n), A22 stable (dimension n-k) and A11 unstable (di-
mension k).
See Also : contr, st_ility, unobs
4.0.360 equil balancing of pair of symmetric matrices
CALLING SEQUENCE :
[T]=equil(P,Q)

PARAMETERS :
P, Q : two positive denite symmetric matrices
T : nonsingular matrix
DESCRIPTION :
equilreturns t such that:
T*P*T' and inv(T)'*Q*inv(T) are both equal to a same diagonal and positive matrix.
See Also : equil1, balanc, ctr_gram
Scilab Group April 1993 159
 ts Scilab Function
4.0.361 equil1 balancing (nonnegative) pair of matrices
CALLING SEQUENCE :
[T [,siz]]=equil1(P,Q [,tol])

PARAMETERS :
P, Q : two non-negative symmetric matrices
T : nonsingular matrix
siz : vector of three integers
tol : threshold
DESCRIPTION :
equil1 computes such that:
t
P1=T*P*T' and
Q1=inv(T)'*Q*inv(T) are as follows:
P1 = diag(S1,S2,0,0) and
Q1 = diag(S1,0,S3,0) with S1,S2,S3 positive and diagonal ma-
trices with respective dimensions
siz=[n1,n2,n3]
tol is a threshold for rank determination in SVD
See Also : balreal, minreal, equil
Author : S. Steer 1987

4.0.362 feedback feedback operation

CALLING SEQUENCE :
Sl=Sl1/.Sl2

PARAMETERS :
Sl1,Sl2 : linear systems (syslin list) in state-space or transfer form, or ordinary gain matrices.
Sl : linear system (syslin list) in state-space or transfer form
DESCRIPTION :
The feedback operation is denoted by /. (slashdot). This command returns Sl=Sl1*(I+Sl2*Sl1)^-1,
i.e the (negative) feedback of Sl1 and Sl2. Sl is the transfer v -> y for y = Sl1 u , u = v -
Sl2 y.
The result is the same as Sl=LFT([0,I;I,-Sl2],Sl1).
Caution: do not use with decimal point (e.g. 1/.1 is ambiguous!)
EXAMPLE :
S1=ssrand(2,2,3);S2=ssrand(2,2,2);
W=S1/.S2;
ss2tf(S1/.S2)
//Same operation by LFT:
ss2tf(lft([zeros(2,2),eye(2,2);eye(2,2),-S2],S1))
//Other approach: with constant feedback
BigS=sysdiag(S1,S2); F=[zeros(2,2),eye(2,2);-eye(2,2),zeros(2,2)];
Bigclosed=BigS/.F;
W1=Bigclosed(1:2,1:2); //W1=W (in state-space).
ss2tf(W1)
//Inverting
ss2tf(S1*inv(eye+S2*S1))

See Also : lft , sysdiag , augment , obscont

Scilab Group April 1993 160

frep2tf Scilab Function
4.0.363 ts time response (discrete time, sampled system)
CALLING SEQUENCE :
[y [,x]]=flts(u,sl [,x0])
[y]=flts(u,sl [,past])

PARAMETERS :
u : matrix (input vector)
sl : list (linear system syslin)
x0 : vector (initial state ; default value=0)
past : matrix (of the past ; default value=0)
x,y : matrices (state and output)
DESCRIPTION :
State-space form:
sl is a
syslin list containing the matrices of the following linear system
sl=syslin('d',A,B,C,D) (see syslin):
x[t+1] = A x[t] + B u[t]
y[t] = C x[t] + D u[t]
or, more generally, if D is a polynomial matrix (p = degree(D(z))) :
D(z) = D0 + zD1 + z 2 D2 + :: + z p Dp
yt = Cxt + D0 ut + D1 ut+1 + :: + Dp ut+p
u = [u0; u1; :::un](input)
y = [y0 ; y1; :::yn,p](output)
x = xn,p+1
(nal state, used as x0 at next call to ts)
Transfer form:
y=flts(u,sl[,past]) . Here
sl is a linear system in transfer matrix representation i.e
sl=syslin('d',transfer matrix) (see syslin).
 
past = uy ,nd :: :: :: uu,1
,nd ,1
is the matrix of past values of u and y.
nd is the maximum of degrees of lcm's of each row of the denominator matrix of sl.
u=[u0 u1 ... un] (input)
y=[y0 y1 ... yn] (output)
p is the dierence between maximum degree of numerator and maximum degree of denominator
EXAMPLE :
sl=syslin('d',1,1,1);u=1:10;
y=flts(u,sl); [y1,x1]=flts(u(1:5),sl);y2=flts(u(6:10),sl,x1);
y-[y1,y2]

//With polynomial D:
z=poly(0,'z');sl=syslin('d',1,1,1,1+z+z^2);p=2;
y=flts(u,sl);[y1,x1]=flts(u(1:5),sl);
y2=flts(u(5-p+1:10),sl,x1); // (update)
y-[y1,y2]

//Delay (transfer form): flts(u,1/z)

See Also : ltitr , dsimul , rtitr

Scilab Group April 1993 161

g margin Scilab Function
4.0.364 frep2tf transfer function realization of a frequency response
CALLING SEQUENCE :
[h [,err]]=frep2tf(frq,repf,dg)

PARAMETERS :
frq : vector of frequencies
repf : vector of frequency response
dg : degree of linear system
h : SISO transfer function
err : error norm([ n(2i*pi*frq) - rep.*d(2i*pi*frq)],'fro')

DESCRIPTION :
Frequency response to transfer function conversion. The order of h is a priori given in dg which
must be provided.
See Also : imrep2ss, arl2, time_id , armax
4.0.365 freq frequency response
CALLING SEQUENCE :
[x]=freq(A,B,C [,D],f)
[x]=freq(NUM,DEN,f)

PARAMETERS :
A, B, C, D : real matrices of respective dimensions nxn, nxp, mxn, mxp .
NUM,DEN : polynomial matrices of dimension mxp
x : real or complex matrix
DESCRIPTION :
x=freq(A,B,C [,D],f) returns a real or complex mxp*t matrix such that:
x(:,k*p:(k+1)*p)= C*inv(f(k)*eye-A)*B + D .
Thus, for taking values along the imaginary axis or on the unit circle x is the continous or
f
discrete time frequency response of
(A,B,C,D) .
x=freq(NUM,DEN,f) returns a real or complex matrix x such that columns k*(p-1)+1 to k*p of
x contain the matrix
NUM(f(k))./DEN(f(k))
See Also : repfreq, horner.
4.0.366 freson peak frequencies
CALLING SEQUENCE :
[fr [,g]]=freson(h [,select])

PARAMETERS :
:
h syslin list
select : string ('f' or 'g')
fr,g : vectors (frequencies and gains)
DESCRIPTION :
returns the vector of peak frequencies for the SISO plant h.
select ='f' or 'g' (stands for 'frequencies' (default) and 'gains').
optional output: g vector of gains.
See Also : frep2tf, zgrid
Scilab Group April 1993 162
lin Scilab Function
4.0.367 g margin gain margin
CALLING SEQUENCE :
[gm [,fr])=g_margin(h)

PARAMETERS :
h : syslin list representing a linear system in state-space or transfer form
DESCRIPTION :
returns gm, the gain margin (dB) of h (SISO plant) and fr, the achieved corresponding frequency.
See Also : p_margin , black , chart

4.0.368 imrep2ss state-space realization of an impulse response

CALLING SEQUENCE :
[sl]=imrep2ss(v [,deg])

PARAMETERS :
v : vector coecients of impulse response, v(:,k) is the kth sample
deg : integer (order required)
sl syslin: list
DESCRIPTION :
Impulse response to linear system conversipon (one input)
See Also : frep2tf, arl2, time_id , armax
4.0.369 invsyslin system inversion
CALLING SEQUENCE :
[sl2]=invsyslin(sl1)

PARAMETERS :
sl1,sl2 : syslin lists (linear systems in state space representation)
DESCRIPTION :
computes the state form of the inverse sl2 of the linear system sl1 (which is also given in state
form).
The D-matrix is supposed to be full rank.
See Also : rowregul, inv
4.0.370 lin linearization
CALLING SEQUENCE :
[A,B,C,D]=lin(sim,x0,u0)
[sl]=lin(sim,x0,u0)

PARAMETERS :
sim : function
x0, u0 : vectors of compatible dimensions
A,B,C,D : real matrices
Scilab Group April 1993 163
lqg Scilab Function
sl : syslin list
DESCRIPTION :
linearization of the non-linear system [y,xdot]=sim(x,u) around x0,u0.
sim is a function which computes y and xdot.
The output is a linear system (syslin list) sl or the four matrices (A,B,C,D) For example, if
ftz is the function passed to ode e.g.

[zd]=ftz(t,z,u)

and if we assume that y=x

[z]=ode(x0,t0,tf,list(ftz,u) compute x(tf).
Ifsimula is the following function:
deff('[y,xd]=simula(x,u)','xd=ftz(tf,x,u); y=x;');

the tangent linear system sl can be obtained by:

[A,B,C,D]=lin(simula,z,u)
sl = syslin('c',A,B,C,D,x0)

See Also : external , derivat

4.0.371 lqe linear quadratic estimator (Kalman Filter)

CALLING SEQUENCE :
[K,X]=lqe(P21)

PARAMETERS :
P21 syslin: list
K, X : real matrices
DESCRIPTION :
lqe returns the Kalman gain for the ltering problem in continuous or discrete time.
P21 is a syslin list representing the system P21=[A,B1,C2,D21]
The input to P21 is a white noise with variance:
[B1 ] [Q S]
BigV=[ ] [ B1' D21'] = [ ]
[D21] [S' R]

X is the solution of the stabilizing Riccati equation and A+K*C2 is stable.

In continuous time:
(A-S*inv(R)*C2)*X+X*(A-S*inv(R)*C2)'-X*C2'*inv(R)*C2*X+Q-S*inv(R)*S'=0

K=-(X*C2'+S)*inv(R)

In discrete time:
X=A*X*A'-(A*X*C2'+B1*D21')*pinv(C2*X*C2'+D21*D21')*(C2*X*A'+D21*B1')+B1*B1'

K=-(A*X*C2'+B1*D21')*pinv(C2*X*C2'+D21*D21')
j
xhat(t+1)= E(x(t+1) y(0),...,y(t)) (one-step predicted x) satises the recursion:
xhat(t+1)=(A+K*C2)*xhat(t) - K*y(t).

See Also : lqr

Author : F. D.
Scilab Group April 1993 164
lqg2stan Scilab Function
4.0.372 lqg LQG compensator
CALLING SEQUENCE :
[K]=lqg(P,r)

PARAMETERS :
P : syslin list (augmented plant) in state-space form
r : 1x2 row vector = (number of measurements, number of inputs) (dimension of the 2,2 part of
P)
K : syslin list (controller)
DESCRIPTION :
lqg computes the linear optimalLQG (H2) controller for the "augmented" plant P=syslin('c',A,B,C,D)
(continuous time) or P=syslin('d',A,B,C,D) (discrete time).
The function lqg2stan returns P and r given the nominal plant, weighting terms and variances
of noises.
K is given by the following ABCD matrices: [A+B*Kc+Kf*C+Kf*D*Kc,-Kf,Kc,0] where Kc=lqr(P12)
is the controller gain and Kf=lqe(P21) is the lter gain. See example in lqg2stan.
See Also : lqg2stan, lqr, lqe, h_inf, obscont
Author : F.D.
4.0.373 lqg2stan LQG to standard problem
CALLING SEQUENCE :
[P,r]=lqg2stan(P22,bigQ,bigR)

PARAMETERS :
:
P22 syslin list (nominal plant) in state-space form
:
bigQ [Q,S;S',N] (symmetric) weighting matrix
:
bigR [R,T;T',V] (symmetric) covariance matrix
: x row vector = (number of measurements, number of inputs) (dimension of the 2,2 part of
r 1 2
P )
:
P syslin list (augmented plant)
DESCRIPTION :
lqg2stan returns the augmented plant for linear LQG (H2) controller design.
P22=syslin(dom,A,B2,C2) is the nominal plant; it can be in continuous time (dom='c') or dis-
crete time (
dom='d' ).
.
x = Ax + w1 + B2u
y = C2x + w2

for continuous time plant.

x[n+1]= Ax[n] + w1 + B2u
y = C2x + w2

for discrete time plant.

The (instantaneous) cost function is [x' u'] bigQ [x;u].
The covariance of [w1;w2] is E[w1;w2] [w1',w2'] = bigR
If [B1;D21] is a factor of bigQ, [C1,D12] is a factor of bigR and [A,B2,C2,D22] is a realiza-
tion of P22, then P is a realization of [A,[B1,B2],[C1,-C2],[0,D12;D21,D22]. The (negative)
feedback computed by lqg stabilizes P22, i.e. the poles of cl=P22/.K are stable.
EXAMPLE :
Scilab Group April 1993 165
LTITR Scilab Function
ny=2;nu=3;nx=4;
P22=ssrand(ny,nu,nx);
bigQ=rand(nx+nu,nx+nu);bigQ=bigQ*bigQ';
bigR=rand(nx+ny,nx+ny);bigR=bigR*bigR';
[P,r]=lqg2stan(P22,bigQ,bigR);K=lqg(P,r); //K=LQG-controller
spec(h_cl(P,r,K)) //Closed loop should be stable
//Same as Cl=P22/.K; spec(Cl(2))
s=poly(0,'s')
lqg2stan(1/(s+2),eye(2,2),eye(2,2))

See Also : lqg, lqr, lqe , obscont , h_inf , augment , fstabst , feedback
Author : F.D.
4.0.374 lqr LQ compensator (full state)
CALLING SEQUENCE :
[K,X]=lqr(P12)

PARAMETERS :
P12 : syslin list (state-space linear system)
K,X : two real matrices
DESCRIPTION :
lqr computes the linear optimal LQ full-state gain for the plant P12=[A,B2,C1,D12] in contin-
uous or discrete time.
P12 is a syslin list (e.g. P12=syslin('c',A,B2,C1,D12)).
The cost function is l2-norm of z'*z with z=C1 x + D12 u i.e. [x,u]' * BigQ * [x;u] where
[C1' ] [Q S]
BigQ= [ ] * [C1 D12] = [ ]
[D12'] [S' R]

The gain K is such that A + B2*K is stable.

X is the stabilizing solution of the Riccati equation.
For a continuous plant:
(A-B2*inv(R)*S')'*X+X*(A-B2*inv(R)*S')-X*B2*inv(R)*B2'*X+Q-S*inv(R)*S'=0

K=-inv(R)*(B2'*X+S)

For a discrete plant:

X=A'*X*A-(A'*X*B2+C1'*D12)*pinv(B2'*X*B2+D12'*D12)*(B2'*X*A+D12'*C1)+C1'*C1;

K=-pinv(B2'*X*B2+D12'*D12)*(B2'*X*A+D12'*C1)

An equivalent form for X is

X=Abar'*inv(inv(X)+B2*inv(r)*B2')*Abar+Qbar

with Abar=A-B2*inv(R)*S' and Qbar=Q-S*inv(R)*S'

The 3-blocks matrix pencils associated with these Riccati equations are:
discrete continuous
|I 0 0| | A 0 B2| |I 0 0| | A 0 B2|
z|0 A' 0| - |-Q I -S| s|0 I 0| - |-Q -A' -S|
|0 B2' 0| | S' 0 R| |0 0 0| | S' -B2' R|

See Also : lqe , gcare , leqr

Author : F.D.
Scilab Group April 1993 166
minss Scilab Function
4.0.375 ltitr discrete time response (state space)
CALLING SEQUENCE :
[X]=ltitr(A,B,U,[x0])
[xf,X]=ltitr(A,B,U,[x0])
PARAMETERS :
A,B : real matrices of appropriate dimensions
U,X : real matrices
x0,xf : real vectors (default value=0 for x0))
DESCRIPTION :
calculates the time response of the discrete time system
x[t+1] = Ax[t] + Bu[t].
The inputs ui's are the columns of the U matrix
U=[u0,u1,...,un];
x0 is the vector of initial state (default value : 0) ;
X is the matrix of outputs (same number of columns as U).
X=[x0,x1,x2,...,xn]
xf is the vector of nal state xf=X[n+1]
See Also : rtitr, flts.
4.0.376 markp2ss Markov parameters to state-space
CALLING SEQUENCE :
[sl]=markp2ss(markpar,n,nout,nin)
PARAMETERS :
markpar : matrix
n,nout,nin : integers
:
Sl syslin list
DESCRIPTION :
given a set of n Markov parameters stacked in the (row)-matrix markpar of size noutX(n*nin)
markp2ss returns a state-space linear system sl (syslin list) such that with [A,B,C,D]=abcd(sl):
C*B = markpar(1:nout,1:nin),
C*A*B =marpar(1:nout,nin+1:2*nin),....

4.0.377 minreal minimal balanced realization

CALLING SEQUENCE :
[slb]=minreal(sl [,tol])
PARAMETERS :
sl,slb : syslin lists
tol : real (threshold)
DESCRIPTION :
[ae,be,ce]=minreal(a,b,c,domain [,tol]) returns the balanced realization of linear system
(
sl syslin list).
sl is assumed stable.
tol threshold used in
equil1 .
See Also : balreal, arhnk , equil , equil1 , hoalg
Author : S. Steer INRIA 1987
Scilab Group April 1993 167
obscont Scilab Function
4.0.378 minss minimal realization
CALLING SEQUENCE :
[slc]=minss( sl [,tol])

PARAMETERS :
sl,slc : syslin lists (linear systems in state-space form)
tol : real (threshold for rank determination (see contr))
DESCRIPTION :
minss returns in slc the minimal realization of sl.
EXAMPLE :
sl=syslin('c',[1 0;0 2],[1;0],[2 1]);
ssprint(sl);
ssprint(minss(sl))

See Also : contr , minreal , arhnk , contrss , obsvss

4.0.379 obs gram observability grammian

CALLING SEQUENCE :
[Go]=obsv_gram(A,C [,dom])
[Go]=obsv_gram(sl)

PARAMETERS :
A,C : real matrices (of appropriate dimensions)
dom : string ( or "c" (default value))
"d'
:
sl syslin list
DESCRIPTION :
Observability gramian of the pair (A,C) or linear system sl (syslin list). dom is the domain
which can be
"c" : continuous system (default)
"d" : discrete system

Z1 X
1
Go = eA tC 0 CeAtdt
0
Go = A0 k C 0CAk
0 0

See Also : contrss , ctr_gram , obsvss , obs_mat

4.0.380 obscont observer based controller

CALLING SEQUENCE :
[K]=obscont(P,Kc,Kf)
[J,r]=obscont(P,Kc,Kf)

PARAMETERS :
:
P syslin list (nominal plant) in state-space form, continuous or discrete time
Kc : real matrix, (full state) controller gain
Kf : real matrix, lter gain
Scilab Group April 1993 168
onserver Scilab Function
K : syslin list (controller)
J : syslin list (extended controller)
r : 1x2 row vector
DESCRIPTION :
obscont returns the observer-based controller associated with a nominal plant P with matrices
(
[A,B,C,D] syslin list).
The full-state control gain is Kc and the lter gain is Kf. These gains can be computed, for
example, by pole placement.
A+B*Kc and A+Kf*C are (usually) assumed stable.
K is a state-space representation of the compensator K: y->u in:
xdot = A x + B u, y=C x + D u, zdot= (A + Kf C)z -Kf y +B u, u=Kc z
K is a linear system (
syslin list) with matrices given by:
K=[A+B*Kc+Kf*C+Kf*D*Kc,Kf,-Kc] .
The closed loop feedback system
Cl: v - y > with (negative) feedback (i.e.
K y = P u, u = v -
K y , or
xdot = A x + B u, y = C x + D u, zdot = (A + Kf C) z - Kf y + B u, u = v -F
z) is given by
Cl = P/.(-K)
The poles of (
Cl spec(cl(2)) ) are located at the eigenvalues of
A+B*Kc A+Kf*C and .
Invoked with two output arguments
obscont returns a (square) linear system which parametrizes
K
all the stabilizing feedbacks via a LFT.
Let Q an arbitrary stable linear system of dimension r(2)xr(1) i.e. number of inputs x number of
outputs in P. Then any stabilizing controller K for P can be expressed as K=lft(J,r,Q). The con-
troller which corresponds to Q=0 is K=J(1:nu,1:ny) (this K is returned by K=obscont(P,Kc,Kf)).
r is size(P) i.e the vector [number of outputs, number of inputs];
EXAMPLE :
ny=2;nu=3;nx=4;P=ssrand(ny,nu,nx);[A,B,C,D]=abcd(P);
Kc=-ppol(A,B,[-1,-1,-1,-1]);Kf=-ppol(A',C',[-2,-2,-2,-2]);Kf=Kf';
cl=P/.(-obscont(P,Kc,Kf));spec(cl(2))
[J,r]=obscont(P,Kc,Kf);
Q=ssrand(nu,ny,3);Q(2)=Q(2)-(maxi(real(spec(Q(2))))+0.5)*eye(Q(2))
//Q is a stable parameter
K=lft(J,r,Q);
spec(h_cl(P,K)) // closed-loop A matrix (should be stable);

See Also : ppol , lqg, lqr, lqe , h_inf , lft , syslin , feedback , observer
Author : F.D.
4.0.381 observer observer design
CALLING SEQUENCE :
[Obs,U,m]=observer(Sys,flag,alfa)

PARAMETERS :
:
Sys syslin list (linear system)
flag : character strings ('pp' or 'st' (default))
alfa : location of closed-loop poles (optional parameter, default=-1)
Obs : linear system (syslin list), the observer
U : orthogonal matrix (see dt ility)
m : integer
DESCRIPTION :
Observer returns in
Obs an observer for (the observable part of) linear system Sys: dotx=A x
+ Bu, y=Cx + Du represented by a syslin list. Sys has nx state variables, nu inputs and ny
outputs.Obs is a linear system with matrices [Ao,Bo,Identity], where Ao is no x no, Bo is no
, is
x (nu+ny) Co no x no and no=nx-m.
Scilab Group April 1993 169
p margin Scilab Function
Input to Obs is [u,y] and output of Obs is:
xhat=estimate of x modulo unobservable subsp. (case 'pp') or
xhat=estimate of x modulo unstable unobservable subsp. (case 'st')
case flag='st': z=H*x can be estimated with stable observer i H*U(:,1:m)=0 and assignable
poles of the observer are set to alfa(1),alfa(2),...
case flag='pp': z=H*x can be estimated with given error spectrum i H*U(:,1:m)=0 all poles of
the observer are assigned and set to alfa(1),alfa(2),...
If H saties the constraint: H*U(:,1:m)=0 (ker(H) contains unobs-subsp. of Sys) one has H*U=[0,H2]
and the observer for z=H*x is is H2*Obs with H2=H*U(:,m+1:nx) i.e. Co, the C-matrix of the
observer for H*x, is Co=H2.
EXAMPLE :
// nx=5;nu=1;ny=1;un=3;us=2;Sys=ssrand(ny,nu,nx,list('dt',us,us,un));
// nx=5 states, nu=1 input, ny=1 output,
// un=3 unobservable states, us=2 of them unstable.
// [Obs,U,m]=observer(Sys); //Stable observer (default)
// W=U';H=W(m+1:nx,:);[A,B,C,D]=abcd(Sys); //H*U=[0,eye(no,no)];
// Sys2=ss2tf(syslin('c',A,B,H)) //Transfer u-->z
// Idu=eye(nu,nu);ss2tf(Obs*sysdiag(Idu,Sys)*[Idu;Idu])
// Transfer u-->[u;u]-->w=[u;y=Sys*u]-->Obs*w i.e. u-->output of Obs
// this transfer must equal Sys2, the u-->z transfer (H2=eye).

See Also : dt_ility , unobs , stabil

Author : F.D.
4.0.382 obsv mat observability matrix
CALLING SEQUENCE :
[O]=obsv_mat(A,C)
[O]=obsv_mat(sl)

PARAMETERS :
A,C,O : matrices
:
sl syslin list
DESCRIPTION :
obsv mat returns the observability matrix
O=[C; CA; CA^2;...; CA^(n-1) ]

See Also : contrss , obsvss , obs_gram

4.0.383 obsvss observable part

CALLING SEQUENCE :
[Ao,Bo,Co]=obsvss(A,B,C [,tol])
[slo]=obsvss(sl [,tol])

PARAMETERS :
A,B,C,Ao,Bo,Co : real matrices
:
sl,slo syslin lists
tol : real (threshold) (default value 100*%eps)
DESCRIPTION :
slo=(Ao,Bo,Co) is the observable part of linear system sl=(A,B,C) (syslin list)
tol threshold to test controllability (see contr); default value = 100*%eps
See Also : contr, contrss, obsv_mat, obs_gram
Scilab Group April 1993 170
phasemag Scilab Function
4.0.384 p margin phase margin
CALLING SEQUENCE :
[phm,fr]=p_margin(h)
[phm]=p_margin(h)

PARAMETERS :
h : SISO linear system (syslin list).
phm : phase margin (in degree)
fr : corresponding frequency (hz)
DESCRIPTION :
Phase margin calculation
See Also : chart, black, g_margin
Author : S. S.
4.0.385 pfss partial fraction decomposition
CALLING SEQUENCE :
elts=pfss(Sl,['cord'])

PARAMETERS :
Sl : syslin list (state-space or transfer linear system) cord : character string 'c' or 'd'.
DESCRIPTION :
Partial fraction decomposition of the linear system Sl (in state-space form, transfer matrices are
automatically converted to state-space form by tf2ss):
elts is the list of linear systems which add up to Sl i.e. elts=list(S1,S2,S3,...,Sn) with:
Sl = S1 + S2 +... +Sn.
Each Si contains some poles of S according to the block-diagonalization of the A matrix of S.
For non proper systems the polynomial part of Sl is put in the last entry of elts.
If S is given in transfer form, it is rst converted into state-space and each subsystem is then
converted in transfer form.
If the optional ag cord='c' is given the elements in elts are sorted according to the real part
(resp. magnitude if cord='d') of the eigenvalues of A matrices.
EXAMPLE :
W=ssrand(1,1,6);
elts=pfss(W);
W1=0;for k=1:size(elts), W1=W1+ss2tf(elts(k));end
clean(ss2tf(W)-W1)

See Also : pbig , bdiag , coffg, dtsi

Author : F.D.
4.0.386 phasemag phase magnitude computation
CALLING SEQUENCE :
[phi,db]=phasemag(z [,mod])

PARAMETERS :
z : matrix or row vector of complex numbers.
mod : character string
Scilab Group April 1993 171
repfreq Scilab Function
mod='c' : representation between -innity and +360
mod='m' : representation between -360 and 0 (default)
phi : phases (in degree) of z (element-by-element)
db : magnitude (en db)
DESCRIPTION :
phasemag computes the phases and magnitudes of the entries of a complex matrix
EXAMPLE :
s=poly(0,'s');
h=syslin('c',1/((s+5)*(s+10)*(100+6*s+s*s)*(s+.3)));
[frq,rf]=repfreq(h,0.1,20,0.005);
xbasc(0);
plot2d(frq',phasemag(rf,'c')');
xbasc(1);
plot2d(frq',phasemag(rf,'m')');

See Also : repfreq , gainplot

4.0.387 ppol pole placement

CALLING SEQUENCE :
[K]=ppol(A,B,poles)

PARAMETERS :
A,B : real matrices of dimensions nxn and nxm.
poles : real or complex vector of dimension n.
K : real matrix
DESCRIPTION :
K=ppol(A,B,poles) returns a mxn gain matrix K such that the eigenvalues of A-B*K are poles.
The pair (A,B) must be controllable. Complex number in poles must appear in conjugate pairs.
An output-injection gain F for (A,C) is obtained as follows:
Ft=ppol(A',C',poles); F=Ft'
The algorithm is by P.H. Petkov.
See Also : canon, stabil
4.0.388 projsl linear system projection
CALLING SEQUENCE :
[slp]=projsl(sl,Q,M)

PARAMETERS :
sl,slp : syslin lists
Q,M : matrices (projection factorization)
DESCRIPTION :
slp= projected model of sl where Q*M is the full rank factorization of the projection.
If (A,B,C,D) is the representation of sl, the projected model is given by (M*A*Q,M*B,C*Q,D).
Usually, the projection Q*M is obtained as the spectral projection of an appropriate auxiliary matrix
W e.g. W = product of (weighted) gramians or product of Riccati equations.
See Also : pbig
Author : F. D.
Scilab Group April 1993 172
rowregul Scilab Function
4.0.389 repfreq frequency response
CALLING SEQUENCE :
[frq,db,phi] =repfreq(sys,fmin,fmax [,step])
[frq,db,phi] =repfreq(sys,frq)
[ [frq,] repf]=repfreq(sys,fmin,fmax [,step])
[ [frq,] repf]=repfreq(sys,frq)

PARAMETERS :
:
sys syslin list : SIMO linear system
fmin,fmax : two real numbers (frequency bounds)
frq : vector of frequencies (Hz)
step : logarithmic discretization step
db,phi : vector of gains (db) and phases at frq
repf : vector of the complex frequency response
DESCRIPTION :
repfreq returns the frequency response calculation of a linear system
See Also : bode, freq, calfrq
Author : S. S.
4.0.390 ricc Riccati equation
CALLING SEQUENCE :
[X]=ricc(A,B,C,"cont")
[X]=ricc(F,G,H,"disc")

PARAMETERS :
A,B,C : real matrices of appropriate dimensions
F,G,H : real matrices of appropriate dimensions
X : real matrix
"cont","disc"' : imposed string ( ag for continuous or discrete)
DESCRIPTION :
Riccati solver.
Continuous time
X=ricc(A,B,C,'cont')

gives a solution to the continuous time ARE

A'*X+X*A-X*B*X+C=0 .

B and C are assumed to be nonnegative denite. (A,G) is assumed to be stabilizable with G*G'
a full rank factorization of B.
(A,H) is assumed to be detectable with H*H' a full rank factorization of C.
Discrete time
X=ricc(F,G,H,'disc')

gives a solution to the discrete time ARE

X=F'*X*F-F'*X*G1*((G2+G1'*X*G1)^-1)*G1'*X*F+H

F is assumed invertible and G = G1*inv(G2)*G1'.

One assumes (F,G1) stabilizable and (C,F) detectable with C'*C full rank factorization of H.
See Also : riccati, ric_desc, schur, gschur
Scilab Group April 1993 173
sm2des Scilab Function
4.0.391 rowregul removing poles and zeros at innity
CALLING SEQUENCE :
[Stmp,Ws]=rowregul(Sl,alfa,beta)
PARAMETERS :
:
Sl,Stmp syslin lists
alfa,beta : reals (new pole and zero positions)
DESCRIPTION :
computes a postlter Ws such that Stmp=Ws*Sl is proper and with full rank D matrix.
Poles at innity of Sl are moved to alfa;
Zeros at innity of Sl are moved to beta;
Sl is a assumed to be a right invertible linear system (syslin list) in state-space representation
with possibly a polynomial D matrix.
This function is the dual of colregul (see function code).
See Also : invsyslin, colregul
Author : F. D. , R. N.
4.0.392 rtitr discrete time response (transfer matrix)
CALLING SEQUENCE :
[y]=rtitr(Num,Den,u [,up,yp])
PARAMETERS :
Num,Den : polynomial matrices (resp. dimensions : nxm and nxn)
u : real matrix (dimension mx(t+1)
up,yp : real matrices (dimension m x (maxi(degree(Den))) (default values=0)
y : real matrix
DESCRIPTION :
y=rtitr(Num,Den,u [,up,yp]) returns the time response of the discrete time linear system with
transfer matrix Den^-1 Num for the input u, i.e y and u are such that Den y = Num u at t=0,1,...
If d1=maxi(degree(Den)), and d2=maxi(degree(Num)) the polynomialmatrices Den(z) and Num(z)
may be written respectively as:
D(z)= D_0 + D_1 z + ... + D_d1 z^d1
N(z)= N_0 + N_1 z + ... + N_d2 z^d2
and Den y = Num u is interpreted as the recursion:
D(0)y(t)+D(1)y(t+1)+...+ D(d1)y(t+d1)= N(0) u(t) +....+ N(d2) u(t+d2)
The columns of u are the inputs of the system at t=0,1,...,T:
u=[u(0) , u(1),...,u(T)]
The outputs at t=0,1,...,T+d1-d2 are the columns of the matrix y:
y=[y(0), y(1), .... y(t+d1-d2)]
up and yp dene the initial conditions for t < 0 i.e
up=[u(-d1), ..., u(-1) ]
yp=[y(-d2), ... y(-1) ]
The default values of up and yp are zero: up = 0*ones(m,d1), yp=0*ones(n,d2)
EXAMPLE :
z=poly(0,'z');
Num=1+z;Den=1+z;u=[1,2,3,4,5];
rtitr(Num,Den,u)-u

See Also : ltitr , exp, flts.

Scilab Group April 1993 174

ss2des Scilab Function
4.0.393 sm2des system matrix to descriptor
CALLING SEQUENCE :
[Des]=sm2des(Sm);

PARAMETERS :
Sm : polynomial matrix (pencil system matrix)
Des : descriptor system (list('des',A,B,C,D,E))
DESCRIPTION :
Utility fonction: converts the system matrix:
Sm = [-sE + A B;
[ C D]

to descriptor system Des=list('des',A,B,C,D,E)).

See Also : ss2des, sm2ss
4.0.394 sm2ss system matrix to state-space
CALLING SEQUENCE :
[Sl]=sm2ss(Sm);

PARAMETERS :
Sm : polynomial matrix (pencil system matrix)
Sl : linear system (syslin list)
DESCRIPTION :
Utility function: converts the system matrix:
Sm = [-sI + A B;
[ C D]

to linear system in state-space representation.

See Also : ss2des
4.0.395 specfact spectral factor
CALLING SEQUENCE :
[W0,L]=specfact(A,B,C,D)

DESCRIPTION :
Given a spectral density matrix phi(s):
-1 -1
R + C*(s*I-A) * B + B'*(-s*I-A') * C' with R=D+D' > 0

specfact computes
W0 and L such that W(s)=W0+L*(s*I-A)^-1 * B is a spectral factor of of
PHI(s) , i.e.
PHI(s)=W'(-s)*W(s)
See Also : sfact , fspec , fspecg
Author : F. D.
Scilab Group April 1993 175
ss2tf Scilab Function
4.0.396 ss2des (polynomial) state-space to descriptor form
CALLING SEQUENCE :
[S]=ss2des(Sl)

PARAMETERS :
Sl : syslin list: proper or improper linear system.
S : list
DESCRIPTION :
Given the linear system in state-space representation Sl (syslin list), with a D matrix which is ei-
ther polynomialor constant, but not zero ss2des returns a descriptor system as list('d',A,B,C,0,E)
such that:
Sl=C*(s*E-A)^(-1)*B

Note that the (constant) "D matrix" of the descriptor system is zero but Sl cannot be strictly
proper.
See Also : pol2des, tf2des, des2ss
Author : F. D.

4.0.397 ss2ss state-space to state-space conversion, feedback,

injection
CALLING SEQUENCE :
[Sl1,right,left]=ss2ss(Sl,T, [F, [G]])

PARAMETERS :
Sl : linear system (
syslin list) in state-space form
T : square (non-singular) matrix
Sl1, right, left : linear systems (syslin lists) in state-space form
F : real matrix (state feedback gain)
G : real matrix (output injection gain)
DESCRIPTION :
Returns the linear system Sl1=[A1,B1,C1,D1] where A1=inv(T)*A*T, B1=inv(T)*B, C1=C*T,
D1=D .
Optional parameters F and G are state feedback and output injection respectively.
For example, Sl1=ss2ss(Sl,T,F) returns Sl1=[A1,B1,C1,D1] with A1=inv(T)*(A+B*F)*T; B1=inv(T)*B;
C1=(C+D*F)*T; D1=D;
If is given as input then right is a non singular linear system such that Sl1=Sl*right.
F
Sl1*inv(right) is a factorization of Sl.
Idem for left: if and are given, Sl1=left*Sl*right.
F G
EXAMPLE :
Sl=ssrand(2,2,5); trzeros(Sl) // zeros are invariant:
Sl1=ss2ss(Sl,rand(5,5),rand(2,5),rand(5,2));
trzeros(Sl1), trzeros(rand(2,2)*Sl1*rand(2,2))

See Also : projsl , feedback

Scilab Group April 1993 176

stabil Scilab Function
4.0.398 ss2tf conversion from state-space to transfer function
CALLING SEQUENCE :
[h]=ss2tf(sl)
[Ds,NUM,chi]=ss2tf(sl)

PARAMETERS :
sl : linear system (syslin list)
h : transfer matrix
DESCRIPTION :
Called with three outputs [Ds,NUM,chi]=ss2tf(sl) returns the numerator polynomial matrix
, the characteristic polynomial chi and the polynomial part Ds separately i.e.:
NUM

h=NUM/chi + Ds

Method
One uses the characteristic polynomial and det(A+Eij)=det(A)+C(i,j) where C is the adju-
gate matrix of A.
See Also : tf2ss, syslin, leverrier, glever

4.0.399 st ility stabilizability test

CALLING SEQUENCE :
[ns, [nc, [,U [,Slo] ]]]=st_ility(Sl [,tol])

PARAMETERS :
Sl : syslin list (linear system)
ns : integer (dimension of stabilizable subspace)
nc : integer (dimension of controllable subspace nc <= ns)
U : basis such that its ns (resp. nc) rst components span the stabilizable (resp. controllable)
subspace
Slo : a linear system (syslin list)
tol : threshold for controllability detection (see contr)

DESCRIPTION :
Slo=( U'*A*U, U'*B, C*U, D, U'*x0 ) (syslin list) displays the stabilizable form of Sl. Sta-
bilizability means ns=nx (dim. of A matrix).
[*,*,*] [*]
U'*A*U = [0,*,*] U'*B = [0]
[0,0,*] [0]

(where (A11,B1) is controllable and A22 is stable). "Stable" means real part of eigenvalues nega-
tive for a continuous linear system, and magnitude of eigenvalues lower than one for a discrete-time
system (as dened by syslin).
See Also : dt_ility, contr, stabil, ssrand
Author : S. Steer INRIA 1988
Scilab Group April 1993 177
tf2ss Scilab Function
4.0.400 stabil stabilization
CALLING SEQUENCE :
F=stabil(A,B,alfa)
PARAMETERS :
A : square real matrix (nx x nx)
B : real matrix (nx x nu)
alfa : real or complex vector (conjugate pairs)
F : real matrix (nx x nu)
DESCRIPTION :
F=stabil(A,B,alfa) returns a gain matrix F such that A+B*F is stable if pair (A,B) is stabi-
lizable. Assignable poles are set to alfa(1),alfa(2),.... If (A,B) is not stabilizable a warning
is given and assignable poles are set to alfa(1),alfa(2),....
EXAMPLE :
//Sys=ssrand(0,2,5,list('st',2,3,3));
//[A,B,C,D]=abcd(Sys);F=stabil(A,B);
//spec(A) //2 controllable modes 2 unstable uncontrollable modes
//and one stable uncontrollable mode
//spec(A+B*F) //the two controllable modes are set to -1.

See Also : st_ility , contr , ppol

4.0.401 svplot singular-value sigma-plot

CALLING SEQUENCE :
[SVM]=svplot(sl,[w])
PARAMETERS :
sl : syslin list
w : real vector (optional parameter)
DESCRIPTION :
computes for the system sl=(A,B,C,D) the singular values of its transfer function matrix:
G(jw) = C(jw*I-A)B^-1+D
or
G(exp(jw)) = C(exp(jw)*I-A)B^-1+D
evaluated over the frequency range specied by w.
sl is a syslin list representing the system [A,B,C,D] in state-space form.
The i-th column of the output matrix SVM contains the singular values of G(exp(jw)) for the i-th
frequency value w(i).
SVM = svplot(sl)
is equivalent to
SVM = svplot(sl,logspace(-3,3)) (continuous)
SVM = svplot(sl,logspace(-3,%pi)) (discrete)

EXAMPLE :
x=logspace(-3,3);
y=svplot(ssrand(2,2,4));
xbasc();plot2d([x',x'],20*log(y')/log(10));
xtitle("Singular values (db)");
xbasc();gainplot(x,y);

Author : F.D
Scilab Group April 1993 178
trzeros Scilab Function
4.0.402 tf2ss transfer to state-space
CALLING SEQUENCE :
[sl]=tf2ss(h)

PARAMETERS :
h : rational matrix
sl : linear system (syslin list sl=[A,B,C,D(s)])
DESCRIPTION :
transfer to state-space conversion:
h=C*(s*eye-A)^-1*B+D(s)
See Also : ss2tf , tf2des , des2tf

4.0.403 time id SISO least square identication

CALLING SEQUENCE :
[H [,err]]=time_id(n,u,y)

PARAMETERS :
n : order of transfer
u : one of the following
:a vector of inputs to the system
u1
"impuls": if y is an impulse response
: if y is a step response.
"step"
y : vector of response.
H : rational function with degree n denominator and degree n-1 numerator.
err : jjy - impuls(H,npt)jj^2, where impuls(H,npt) are the npt rst coecients of impulse
response of H
DESCRIPTION :
identication of discrete time response (least square).
Author : Serge Steer INRIA
See Also : imrep2ss , arl2 , armax , frep2tf

4.0.404 trzeros transmission zeros and normal rank

CALLING SEQUENCE :
[tr]=trzeros(Sl)
[nt,dt,rk]=trzeros(Sl)

PARAMETERS :
Sl : linear system (syslin list)
nt : complex vectors
dt : real vector
rk : integer (normal rank of Sl)
Scilab Group April 1993 179
zeropen Scilab Function
DESCRIPTION :
Called with one output argument, trzeros(Sl) returns the transmission zeros of the linear system
Sl .
Sl may have a polynomial (but square) D matrix.
Called with 2 output arguments, trzeros returns the transmission zeros of the linear system Sl
as tr=nt./dt;
(Note that some components of dt may be zeros)
Called with 3 output arguments, rk is the normal rank of Sl
Transfer matrices are converted to state-space.
If Sl is a (square) polynomial matrix trzeros returns the roots of its determinant.
For usual state-space system trzeros uses the state-space algorithm of Emami-Naeni & Van
Dooren.
If D is invertible the transmission zeros are the eigenvalues of the "A matrix" of the inverse system
: A - B*inv(D)*C;
If C*B is invertible the transmission zeros are the eigenvalues of N*A*M where M*N is a full rank
factorization of eye(A)-B*inv(C*B)*C;
For systems with a polynomial D matrix zeros are calculated as the roots of the determinant of
the system matrix.
Caution: the computed zeros are not always reliable, in particular in case of repeated zeros.
EXAMPLE :
W1=ssrand(2,2,5);trzeros(W1)
roots(det(systmat(W1)))
s=poly(0,'s');W=[1/(s+1);1/(s-2)];W2=(s-3)*W*W';[nt,dt,rk]=trzeros(W2);
St=systmat(tf2ss(W2));[Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(St);
St1=Q*St*Z;rowf=(Qd(1)+Qd(2)+1):(Qd(1)+Qd(2)+Qd(3));
colf=(Zd(1)+Zd(2)+1):(Zd(1)+Zd(2)+Zd(3));
roots(St1(rowf,colf)), nt./dt

See Also : gspec , kroneck

4.0.405 unobs unobservable subspace

CALLING SEQUENCE :
[n,[U]]=unobs(A,C,[tol])

PARAMETERS :
A, C : real matrices
tol : tolerance used when evaluating ranks (QR factorizations).
n : dimension of unobservable subspace.
U : orthogonal change of basis which puts (A,B) in canonical form.
DESCRIPTION :
[n,[U]]=unobs(A,B,[tol]) gives the unobservable form of an (A,C) pair. The n rst columns
of U make a basis for the controllable subspace.
The (2,1) block (made of last nx-n rows and n rst columns) of U'*A*U is zero and and the n
rst columns of C*U are zero.
See Also : contr, contrss, canon, cont_mat, spantwo, dt_ility
4.0.406 zeropen zero pencil
CALLING SEQUENCE :
[Z,U]=zeropen(Sl)

Scilab Group April 1993 180

zeropen Scilab Function
PARAMETERS :
Sl : a linear system (syslin list in state-space form [A,B,C,D])
Z : matrix pencil Z=s*E-A
U : square orthogonal matrix
DESCRIPTION :
Z = sE - F is the zero pencil of the linear system Sl with matrices [A,B,C,D].
With U row compression of [B;D] i.e, U*[B;D]=[0;*]; one has:
U*[-sI+A |B; [ Z |0;
C |D] = [ * |*]

The zeros of Z are the zeros of Sl.

See Also : systmat, kroneck
Author : F. D.

Scilab Group April 1993 181

zeropen Scilab Function

Scilab Group April 1993 182

Chapter 5

Robust control toolbox

183
ccontrg Scilab Function
5.0.407 augment augmented plant
CALLING SEQUENCE :
[P,r]=augment(G,[flag])

PARAMETERS :
G : linear system (syslin list), the nominal plant
flag : one of the following (upper case) character string: 'S' , 'R' , 'T' 'SR' , 'ST' , 'RT'
'SRT'
P : linear system (syslin list), the \augmented" plant
r : 1x2 row vector, dimension of P22 = G
DESCRIPTION :
If flag='SRT' (default value), returns the "full" augmented plant
[ I | -G] -->'S'
[ 0 | I] -->'R'
P = [ 0 | G] -->'T'
[-------]
[ I | -G]

'S' , 'R' , 'T' refer to the rst three (block) rows of P respectively.
If one of these letters is absent in flag, the corresponding row in P is missing.
Note that weighting functions can be introduced by left-multipying P by a diagonal system of
appropriate dimension, e.g., P = sysdiag(W1,W2,W3,eye(G))*P.
Sensitivity functions can be calculated by lft.
See Also : lft, sensi
5.0.408 bstap hankel approximant
CALLING SEQUENCE :
[Q]=bstap(Sl)

PARAMETERS :
sl : linear system (syslin list) assumed continuous-time and anti-stable.
Q : best stable approximation of Sl (syslin list).
DESCRIPTION :
Computes the best approximant Q of the linear system Sl
kSl , Qk1 = kT k
where is the H-innity norm of the Hankel operator associated with Sl.
See Also : syslin
5.0.409 ccontrg central H-innity controller
CALLING SEQUENCE :
[K]=ccontrg(P,r,gamma);

PARAMETERS :
P : syslin list (linear system in state-space representation)
r : 1x2 row vector, dimension of the 2,2 part of P
Scilab Group April 1993 184
dcf Scilab Function
gamma : real number
DESCRIPTION :
returns a realization K of the central controller for the general standard problem in state-space
form.
Note that gamma must be > gopt (ouput of gamitg)
P contains the parameters of plant realization (A,B,C,D) (syslin list) with
B = ( B1 , B2 ) , C= ( C1 ) , D = ( D11 D12)
( C2 ) ( D21 D22)

r(1) and r(2) are the dimensions of D22 (rows x columns)

See Also : gamitg, h_inf.
Author : P. Gahinet (INRIA)
5.0.410 colinout inner-outer factorization
CALLING SEQUENCE :
[Inn,X,Gbar]=colinout(G)

PARAMETERS :
G : linear system (syslin list) [A,B,C,D]
Inn : inner factor (syslin list)
Gbar : outer factor (syslin list)
X : row-compressor of G (syslin list)
DESCRIPTION :
Inner-outer factorization (and column compression) of (lxp) G =[A,B,C,D] with l<=p.
G is assumed to be fat (l<=p) without zero on the imaginary axis and with a D matrix which is
full row rank.
G must also be stable for having Gbar stable.
Dual of rowinout.
See Also : syslin, rowinout
5.0.411 copfac right coprime factorization
CALLING SEQUENCE :
[N,M,XT,YT]=copfac(G [,polf,polc,tol])

PARAMETERS :
G :
syslin list (continuous-time linear system )
polf, polc : respectively the poles of XT and YT and the poles of n and M (default values =-1).
tol : real threshold for detecting stable poles (default value 100*%eps)
N,M,XT,YT : linear systems represented by syslin lists
DESCRIPTION :
[N,M,XT,YT]=copfac(G,[polf,polc,[tol]]) returns a right coprime factorization of G.
G = N*M^-1 where and are stable, proper and right coprime. (i.e. [N M] left-invertible with
N M
stability)
XT and YT satisfy:
[XT -YT].[M N]' = eye (Bezout identity)
G is assumed stabilizable and detectable.
See Also : syslin, lcf
Scilab Group April 1993 185
fourplan Scilab Function
5.0.412 dcf double coprime factorization
CALLING SEQUENCE :
[N,M,X,Y,NT,MT,XT,YT]=dcf(G,[polf,polc,[tol]])
PARAMETERS :
G :syslin list (continuous-time linear system)
polf, polc : respectively the poles of XT and YT and the poles of N and M (default values =-1).
tol : real threshold for detecting stable poles (default value 100*%eps).
N,M,XT,YT,NT,MT,X,Y : linear systems represented by syslin lists
DESCRIPTION :
returns eight stable systems (N,M,X,Y,NT,MT,XT,YT) for the doubly coprime factorization
 XT ,Y T   M Y 
,NT MT  M X = eye
G must be stabilizable and detectable.
See Also : copfac
5.0.413 des2ss descriptor to state-space
CALLING SEQUENCE :
[Sl]=des2ss(A,B,C,D,E [,tol])
[Sl]=des2ss(Des)
PARAMETERS :
A,B,C,D,E : real matrices of appropriate dimensions
Des : list
:
Sl syslin list
tol : real parameter (threshold) (default value 100*%eps).
DESCRIPTION :
Descriptor to state-space transform.
Sl=des2ss(A,B,C,D,E) returns a linear system equivalent to the descriptor system (E,A,B,C,D).
Sl
For index one
(E,A) pencil, explicit formula is used and for higher index pencils rowshuff is used.
Sl=des2ss(Des) with
Des=list('des',A,B,C,0,E) returns a linear system Sl in state-space
form with possibly a polynomial matrix.
D
Note that now is set to here. A generalized Leverrier is used.
D 0
See Also : des2tf, glever, rowshuff
5.0.414 dtsi stable anti-stable decomposition
CALLING SEQUENCE :
[Ga,Gs,Gi]=dtsi(G,[tol])
PARAMETERS :
G : linear system (syslin list)
Ga : linear system (syslin list) antistable and strictly proper
Gs : linear system (syslin list) stable and strictly proper
Gi : real matrix (or polynomial matrix for improper systems)
tol : optional parameter for detecting stables poles. Default value: 100*%eps
DESCRIPTION :
returns the stable-antistable decomposition of G:
,
G = Ga + Gs + Gi (Gi = G(oo))
G can be given in state-space form or in transfer form.
See Also : syslin, pbig, psmall, pfss
Scilab Group April 1993 186
fstabst Scilab Function
5.0.415 fourplan augmented plant to four plants
CALLING SEQUENCE :
[P11,P12,P21,P22]=fourplan(P,r)

PARAMETERS :
:
P syslin list (linear system)
r : 1x2 row vector, dimension of P22
P11,P12,P21,P22 : syslin lists.
DESCRIPTION :
Utility function.
Pbeing partitioned as follows:
P=[ P11 P12;
P21 P22]

with size(P22)=r this function returns the four linear systems P11,P12,P21,P22.
See Also : lqg, lqg2stan, lqr, lqe, lft
5.0.416 fspecg stable factorization
CALLING SEQUENCE :
[gm]=fspecg(g).

PARAMETERS :
g,gm : syslin lists (linear systems in state-space representation)
DESCRIPTION :
returns gm with gm and gm^-1 stable such that:
gtild(g)*g = gtild(gm)*gm

g and gm are continuous-time linear systems in state-space form.

Imaginary-axis poles are forbidden.
5.0.417 fstabst Youla's parametrization
CALLING SEQUENCE :
[J]=fstabst(P,r)

PARAMETERS :
P : syslin list (linear system)
r : 1x2 row vector, dimension of P22
J : syslin list (linear system in state-space representation)
DESCRIPTION :
Parameterization of all stabilizing feedbacks.
Pis partitioned as follows:
P=[ P11 P12;
P21 P22]

(in state-space or transfer form: automatic conversion in state-space is done for the computations)
r = size of P22 subsystem, (2,2) block of P

Scilab Group April 1993 187

gcare Scilab Function
J =[ J11 J12;
J21 J22]

K is a stabilizing controller for P (i.e. P22) i K=lft(J,r,Q) with Q stable.

The central part of J , J11 is the lqg regulator for P
This J is such that dening T as the 2-port lft of P and J : [T,rt]=lft(P,r,J,r) one has that
T12 is inner and T21 is co-inner.
EXAMPLE :
ny=2;nu=3;nx=4;
P22=ssrand(ny,nu,nx);
bigQ=rand(nx+nu,nx+nu);bigQ=bigQ*bigQ';
bigR=rand(nx+ny,nx+ny);bigR=bigR*bigR';
[P,r]=lqg2stan(P22,bigQ,bigR);
J=fstabst(P,r);
Q=ssrand(nu,ny,1);Q(2)=-1; //Stable Q
A=h_cl(P,r,Q); spec(A)

See Also : obscont , lft , ,

lqg lqg2stan

5.0.418 gamitg H-innity gamma iterations

CALLING SEQUENCE :
[gopt]=gamitg(G,r,prec [,options]);

PARAMETERS :
G :syslin list (plant realization )
r : 1x2 row vector (dimension of G22)
prec : desired relative accuracy on the norm
option : string 't'
gopt : real scalar, optimal H-innity gain
DESCRIPTION :
gopt=gamitg(G,r,prec [,options]) returns the H-innity optimal gain gopt.
G contains the state-space matrices
[A,B,C,D] of the plant with the usual partitions:
B = ( B1 , B2 ) , C = ( C1 ) , D = ( D11 D12)
( C2 ) ( D21 D22)

These partitions are implicitely given in r: r(1) and r(2) are the dimensions of D22 (rows x
columns)
With option='t', gamitg traces each bisection step, i.e., displays the lower and upper bounds
and the current test point.
See Also : ccontrg, H_inf
Author : P. Gahinet
5.0.419 gcare control Riccati equation
CALLING SEQUENCE :
[X,F]=gcare(Sl)

PARAMETERS :
Sl : linear system (syslin list)
X : symmetric matrix
Scilab Group April 1993 188
h2norm Scilab Function
F : real matrix
DESCRIPTION :
Generalized Control Algebraic Riccati Equation (GCARE). X = solution , F = gain.
The GCARE for Sl=[A,B,C,D] is:
(A-B*Si*D'*C)'*X+X*(A-B*Si*D'*C)-X*B*Si*B'*X+C'*Ri*C=0

where S=(eye+D'*D), , ,
Si=inv(S) R=(eye+D*D') Ri=inv(R) and F=-Si*(D'*C+B'*X) is such
that A+B*F is stable.
See Also : gfare
5.0.420 gfare lter Riccati equation
CALLING SEQUENCE :
[Z,H]=gfare(Sl)

PARAMETERS :
Sl : linear system (syslin list)
Z : symmetric matrix
H : real matrix
DESCRIPTION :
Generalized Filter Algebraic Riccati Equation (GFARE). Z = solution, H = gain.
The GFARE for Sl=[A,B,C,D] is:
(A-B*D'*Ri*C)*Z+Z*(A-B*D'*Ri*C)'-Z*C'*Ri*C*Z+B*Si*B'=0

where S=(eye+D'*D), , ,
Si=inv(S) R=(eye+D*D') Ri=inv(R) and H=-(B*D'+Z*C')*Ri is such
that A+H*C is stable.
See Also : gcare
5.0.421 gtild tilde operation
CALLING SEQUENCE :
[gt]=gtild(g)
[at,bt,ct,dt]=gtild(a,b,c,[d])

PARAMETERS :
g : linear system (syslin list) or g=g(s) (rational or polynomial)
gt : linear system (syslin list) (same as g)
DESCRIPTION :
gtild returns gtild(s) = g(-s)' (in transfer form or in state-space).
g is any matrix (constant, polynomial, transfer matrix, or state-space representaion with possibly
a polynomial D matrix).
EXAMPLE :
s=poly(0,'s');w=[1/s,s;2/(s+1),1];gtild(w)
ss2tf(gtild(tf2ss(w)))

See Also : syslin , horner

Scilab Group April 1993 189

H inf Scilab Function
5.0.422 h2norm H2 norm
CALLING SEQUENCE :
[n]=h2norm(Sl [,tol])

PARAMETERS :
Sl : linear system (syslin list)
n : real scalar
DESCRIPTION :
produces the H2 norm of a linear continuous time system Sl.
(For Sl in state-space form h2norm uses the observability gramian and for Sl in transfer form
h2norm uses a residue method)

5.0.423 h cl closed loop matrix

CALLING SEQUENCE :
[Acl]=h_cl(P,r,K)
[Acl]=h_cl(P22,K)

PARAMETERS :
P, P22 : linear system (syslin list), augmented plant or nominal plant respectively
r : 1x2 row vector, dimensions of 2,2 part of P (r=[rows,cols]=size(P22))
K : linear system (syslin list), controller
Acl : real square matrix
DESCRIPTION :
Given the standard plant P (with r=size(P22)) and the controller K, this function returns the
closed loop matrix Acl.
The poles of Acl must be stable for the internal stability of the closed loop system.
Acl is the A-matrix of the linear system [I -P22;-K I]^-1 i.e. the A-matrix of lft(P,r,K)
See Also : lft
Author : F. D.
5.0.424 h inf H-innity (central) controller
CALLING SEQUENCE :
[Sk,ro]=h_inf(P,r,romin,romax,nmax)
[Sk,rk,ro]=h_inf(P,r,romin,romax,nmax)

PARAMETERS :
P :
syslin list : continuous-time linear system (\augmented" plant given in state-space form
or in transfer form)
r : size of the P22 plant i.e. 2-vector [#outputs,#inputs]
romin,romax : a priori bounds on ro with ro=1/gama^2; (romin=0 usually)
nmax : integer, maximum number of iterations in the gama-iteration.

DESCRIPTION :
h inf computes H-innity optimal controller for the continuous-time plant P.
The partition of P into four sub-plants is given through the 2-vector r which is the size of the 22
part of P.
Scilab Group April 1993 190
hankelsv Scilab Function
P is given in state-space e.g. P=syslin('c',A,B,C,D) with A,B,C,D = constant matrices or
P=syslin('c',H) with H a transfer matrix.
[Sk,ro]=H_inf(P,r,romin,romax,nmax) returns ro in [romin,romax] and the central con-
troller Sk in the same representation as P.
(All calculations are made in state-space, i.e conversion to state-space is done by the function, if
necessary).
Invoked with three LHS parameters, [Sk,rk,ro]=H_inf(P,r,romin,romax,nmax) returns
ro and the parameterization of all stabilizing controllers:
a stabilizing controller K is obtained by K=lft(Sk,r,PHI) where PHI is a linear system with
dimensions r' and satisfy:
H norm(PHI) < gamma. rk (=r) is the size of the Sk22 block and ro = 1/gama^2 after nmax
iterations.
Algorithm is adapted from Safonov-Limebeer. Note that P is assumed to be a continuous-time
plant.
See Also : gamitg, ccontrg, leqr
Author : F.D. (1990)

5.0.425 H inf st static H innity problem

CALLING SEQUENCE :
[Kopt,gamaopt]=h_inf_stat(D,r)

PARAMETERS :
D : real matrix
r : 1x2 vector
Kopt : matrix
DESCRIPTION :
computes a matrix Kopt such that largest singular value of:
lft(D,r,K)=D11+D12* K*inv(I-D22*K)* D21 is minimal (Static H-innity four blocks problem).
D is partionned as D=[D11 D12; D21 D22] where size(D22)=r=[r1 r2]
Author : F.D.

5.0.426 H norm H-innity norm

CALLING SEQUENCE :
[hinfnorm [,frequency]]=h_norm(sl [,rerr])

PARAMETERS :
sl : the state space system (syslin list)
rerr : max. relative error, default value 1e-8
hinfnorm : the innity norm of Sl
frequency : frequency at which maximum is achieved
DESCRIPTION :
produces the innity norm of a state-space system (the maximum over all frequencies of the
maximum singular value).
See Also : linfn, linf
Scilab Group April 1993 191
lqr Scilab Function
5.0.427 hankelsv Hankel singular values
CALLING SEQUENCE :
[nk2,W]=hankelsv(sl [,tol])
[nk2]=hankelsv(sl [,tol])

PARAMETERS :
:
sl syslin list representing the linear system (state-space).
tol : tolerance parameter for detecting imaginary axis modes (default value is 1000*%eps).
DESCRIPTION :
returns nk2, the squared Hankel singular values of sl and W = P*Q = controllability gramian
times observability gramian.
nk2 is the vector of eigenvalues of W.
EXAMPLE :
A=diag([-1,-2,-3]);
sl=syslin('c',A,rand(3,2),rand(2,3));[nk2,W]=hankelsv(sl)
[Q,M]=pbig(W,nk2(2)-%eps,'c');
slr=projsl(sl,Q,M);hankelsv(slr)

See Also : balreal , equil , equil1

5.0.428 lcf normalized coprime factorization

CALLING SEQUENCE :
[N,M]=lcf(sl)

PARAMETERS :
sl : linear system given in state space or transfer function (syslin list)
N,M : two linear systems (syslin list)
DESCRIPTION :
Computes normalized coprime factorization of the linear dynamic system sl.
sl = M^-1 N
Author : F. D.
5.0.429 leqr H-innity LQ gain (full state)
CALLING SEQUENCE :
[K,X,err]=leqr(P12,Vx)

PARAMETERS :
P12 : syslin list
Vx : symmetric nonnegative matrix (should be small enough)
K,X : two real matrices
err : a real number (l1 norm of LHS of Riccati equation)
DESCRIPTION :
leqr computes the linear suboptimal H-innity LQ full-state gain for the plant P12=[A,B2,C1,D12]
in continuous or discrete time.
P12 is a syslin list (e.g. P12=syslin('c',A,B2,C1,D12)).

Scilab Group April 1993 192

lft Scilab Function
[C1' ] [Q S]
[ ] * [C1 D12] = [ ]
[D12'] [S' R]
Vx is related to the variance matrix of the noise w perturbing x; (usually Vx=gama^-2*B1*B1').
The gain K is such that A + B2*K is stable.
X is the stabilizing solution of the Riccati equation.
For a continuous plant:
(A-B2*inv(R)*S')'*X+X*(A-B2*inv(R)*S')-X*(B2*inv(R)*B2'-Vx)*X+Q-S*inv(R)*S'=0

K=-inv(R)*(B2'*X+S)

For a discrete plant:

X-(Abar'*inv((inv(X)+B2*inv(R)*B2'-Vx))*Abar+Qbar=0

K=-inv(R)*(B2'*inv(inv(X)+B2*inv(R)*B2'-Vx)*Abar+S')

with Abar=A-B2*inv(R)*S' and Qbar=Q-S*inv(R)*S'

The 3-blocks matrix pencils associated with these Riccati equations are:
discrete continuous
|I -Vx 0| | A 0 B2| |I 0 0| | A Vx B2|
z|0 A' 0| - |-Q I -S| s|0 I 0| - |-Q -A' -S |
|0 B2' 0| | S' 0 R| |0 0 0| | S' -B2' R|

See Also : lqr. leqe

Author : F.D.
5.0.430 lft linear fractional transformation
CALLING SEQUENCE :
[P1]=LFT(P,K)
[P1]=LFT(P,r,K)
[P1,r1]=LFT(P,r,P#,r#)

PARAMETERS :
P : linear system (syslin list), the \augmented" plant, implicitly partitioned into four blocks
(two input ports and two output ports).
K : linear system (syslin list), the controller (possibly an ordinary gain).
r : 1x2 row vector, dimension of P22
P# : linear system (syslin list), implicitly partitioned into four blocks (two input ports and two
output ports).
r# : 1x2 row vector, dimension of P#22

DESCRIPTION :
Linear fractional transform between two standard plants P and P# in state space form or in
transfer form (syslin lists).
r= size(P22) r#=size(P22#)
LFT(P,r, K) is the linear fractional transform between P and a controller K (K may be a gain or
a controller in state space form or in transfer form);
LFT(P,K) is LFT(P,r,K) with r=size of K transpose;
P1= P11+P12*K* (I-P22*K)^-1 *P21
[P1,r1]=LFT(P,r,P#,r#) returns the generalized (2 ports) lft of P and P#.
P1 is the pair two-port interconnected plant and the partition of P1 into 4 blocks in given by r1
which is the dimension of the block of P1.
22
P and can be PSSDs i.e. may admit a polynomial D matrix.
R
EXAMPLE :
Scilab Group April 1993 193
linfn Scilab Function
s=poly(0,'s');
P=[1/s, 1/(s+1); 1/(s+2),2/s]; K= 1/(s-1);
lft(P,K)
lft(P,[1,1],K)
P(1,1)+P(1,2)*K*inv(1-P(2,2)*K)*P(2,1) //Numerically dangerous!
ss2tf(lft(tf2ss(P),tf2ss(K)))
lft(P,-1)
f=[0,0;0,1];w=P/.f; w(1,1)
//Improper plant (PID control)
W=[1,1;1,1/(s^2+0.1*s)];K=1+1/s+s
lft(W,[1,1],K); ss2tf(lft(tf2ss(W),[1,1],tf2ss(K)))

See Also : sensi , augment , feedback , sysdiag

5.0.431 linf innity norm

CALLING SEQUENCE :
linf(g [,eps],[tol])

PARAMETERS :
g : is a syslin linear system.
eps : is error tolerance on n.
tol : threshold for imaginary axis poles.
DESCRIPTION :
returns the L innity norm of g.
n=sup [sigmax(g(jw)]
w

(sigmax largest singular value).

See Also : H_norm, linfn
5.0.432 linfn innity norm
CALLING SEQUENCE :
[x,freq]=linfn(G,PREC,RELTOL,options);

PARAMETERS :
G : is a syslin list
PREC : desired relative accuracy on the norm
RELTOL : relative threshold to decide when an eigenvalue can be considered on the imaginary
axis.
options : available options are 'trace' or 'cond'
x is the computed norm.
freq : vector

DESCRIPTION :
Computes the Linf (or Hinf) norm of G This norm is well-dened as soon as the realization
G=(A,B,C,D) has no imaginary eigenvalue which is both controllable and observable.
freq is a list of the frequencies for which jjGjj is attained,i.e., such that jjG (j om)jj = jjGjj.
If -1 is in the list, the norm is attained at innity.
If -2 is in the list, G is all-pass in some direction so that jjG (j omega)jj = jjGjj for all frequencies
omega.
Scilab Group April 1993 194
Macglov Scilab Function
The algorithm follows the paper by G. Robel (AC-34 pp. 882-884, 1989). The case D=0 is not
treated separately due to superior accuracy of the general method when (A,B,C) is nearly non
minimal.
The 'trace' option traces each bisection step, i.e., displays the lower and upper bounds and the
current test point.
The 'cond' option estimates a condence index on the computed value and issues a warning if
computations are ill-conditioned
In the general case (A neither stable nor anti-stable), no upper bound is prespecied.
If by contrast A is stable or anti stable, lower and upper bounds are computed using the associated
Lyapunov solutions.
Author : P. Gahinet
5.0.433 lqg ltr LQG with loop transform recovery
CALLING SEQUENCE :
[kf,kc]=lqg_ltr(sl,mu,ro)

PARAMETERS :
sl : linear system in state-space form (syslin list)
mu,ro : real positive numbers chosen \small enough"
kf,kc : controller and observer Kalman gains.
DESCRIPTION :
returns the Kalman gains for:
x = a*x + b*u + l*w1
(sl)
y = c*x + mu*I*w2

z = h*x

Cost function: Z1
Jlqg = E( [z(t)0  z(t) + ro2  u(t)0  u(t)]dt)
0

The lqg/ltr approach looks for L,mu,H,ro such that: J(lqg) = J(freq) where
Z1
Jfreq = tr[SWW ? S ? ] + tr[TT ?]dw
0

and
S = (I + G*K)^(-1)
T = G*K*(I+G*K)^(-1)

See Also : syslin

5.0.434 Macglov Mac Farlane Glover problem

CALLING SEQUENCE :
[P,r]=Macglov(Sl)

PARAMETERS :
Sl : linear system (syslin list)
P : linear system (syslin list), \augmented" plant
Scilab Group April 1993 195
ric desc Scilab Function
r : 1x2 vector, dimension of P22
DESCRIPTION :
[P,r]=Macglov(Sl) returns the standard plant P for the Glover-McFarlane problem.
For this problem ro optimal = 1-hankel norm([N,M]) with [N,M]=LCF(Sl) (Normalized coprime
factorization) i.e.
gama optimal = 1/sqrt(ro optimal)
Author : F. D.
5.0.435 nehari Nehari approximant
CALLING SEQUENCE :
[x]=nehari(R [,tol])

PARAMETERS :
R : linear system (syslin list)
x : linear system (syslin list)
tol : optional threshold
DESCRIPTION :
[x]=nehari(R [,tol]) returns the Nehari approximant of R.
R = linear system in state-space representation (syslin list).
R is strictly proper and - R~ is stable (i.e. R is anti stable).
|| R - X ||oo = min || R - Y ||oo
Y in Hoo

5.0.436 parrot Parrot's problem

CALLING SEQUENCE :
[K]=parrot(D,r)

PARAMETERS :
D,K : matrices
r : 1X2 vector (dimension of the 2,2 part of D)
DESCRIPTION :
Given a matrix D partionned as [D11 D12; D21 D22] where size(D22)=r=[r1,r2] compute a
matrix K such that largest singular value of [D11 D12; D21 D22+K] is minimal (Parrot's problem)
See Also : H_inf_stat

5.0.437 ric desc Riccati equation

CALLING SEQUENCE :
[X1,X2,zero]=ric_desc(H,E)
[X1,X2,zero]=ric_desc(H [,E])

PARAMETERS :
H,E : real square matrices
X1,X2 : real square matrices
zero : real number
Scilab Group April 1993 196
rowinout Scilab Function
DESCRIPTION :
Riccati solver with hamiltonian matrices as inputs.
In the continuous time case calling sequence is (one input): ric_descr(H)
Riccati equation is:
(Ec) A'*X + X*A + X*R*X -Q = 0.

Dening the hamiltonian matrix H by:

H = [A R;
Q -A']

with the calling sequence [X1,X2,err]=ric descr(H), the solution X is given by X=X1/X2.
zero = L1 norm of rhs of (Ec)
The solution X is also given by X=riccati(A,Q,R,'c'))
In the discrete-time case calling sequence is (two inputs): ric_descr(H,E)
The Riccati equation is:
(Ed) A'*X*A-(A'*X*B*(R+B'*X*B)^-1)*(B'*X*A)+C-X = 0.

Dening G=B/R*B' and the hamiltonian pencil (E,H) by:

E=[eye(n,n),G; H=[A, 0*ones(n,n);
0*ones(n,n),A'] -C, eye(n,n)];

with the calling sequence [X1,X2,err]=ric descr(H,E), the solution X is given by X=X1/X2.
zero= L1 norm of rhs of (Ed)
The solution X is also given by X=riccati(A,G,C,'d') with G=B/R*B'
See Also : riccati
5.0.438 riccati Riccati equation
CALLING SEQUENCE :
[X1,[X2]]=riccati(A,B,C,dom,[typ])

PARAMETERS :
A,B,C : real matrices nxn, B and C symetric.
dom :
'c' or 'd' for the time domain (continuous or discrete)
typ : string : 'eigen' for block diagonalization or schur' for Schur method.
DESCRIPTION :
Riccati solver X=X1/X2 solves:
A'*X+X*A-X*B*X+C=0

in continuous time case, or:

A'*X*A-(A'*X*B1/(B2+B1'*X*B1))*(B1'*X*A)+C-X

with B=B1/B2*B1' in the discrete time case. If called with LHS=1 (one output argument) riccati
returns X.
See Also : ric_desc
Scilab Group April 1993 197
tf2des Scilab Function
5.0.439 rowinout inner-outer factorization
CALLING SEQUENCE :
[Inn,X,Gbar]=rowinout(G)

PARAMETERS :
G : linear system (syslin list) [A,B,C,D]
Inn : inner factor (syslin list)
Gbar : outer factor (syslin list)
X : row-compressor of G (syslin list)
DESCRIPTION :
Inner-outer factorization (and row compression) of (lxp) G =[A,B,C,D] with l>=p.
G is assumed to be tall (l>=p) without zero on the imaginary axis and with a D matrix which is
full column rank.
G must also be stable for having Gbar stable.
G admits the following inner-outer factorization:

G = [ Inn ] | Gbar |
| 0 |

where Inn is square and inner (all pass and stable) and Gbar square and outer i.e: Gbar is square
bi-proper and bi-stable (Gbar inverse is also proper and stable);
Note that:
[ Gbar ]
X*G = [ - ]
[ 0 ]

is a row compression of G where X = Inn inverse is all-pass i.e:

T
X (-s) X(s) = Identity

(for the continous time case).

See Also : syslin, colinout
5.0.440 sensi sensitivity functions
CALLING SEQUENCE :
[Se,Re,Te]=sensi(G,K)

PARAMETERS :
G : standard plant (syslin list)
K : compensator (syslin list)
Se : sensitivity function (I+G*K)^-1
Re : K*Se
Te : G*K*Se (complementary sensitivity)
DESCRIPTION :
computes sensitivity functions. Calculation is made by lft, e.g., Se can be given by the commands
,
P = augment(G,'S') Se=lft(P,K) .
See Also : augment, lft, h_cl
Scilab Group April 1993 198
tf2des Scilab Function
5.0.441 tf2des transfer function to descriptor
CALLING SEQUENCE :
[S]=tf2des(G)

PARAMETERS :
G : linear system (syslin list) with polynomial D matrix
S : list
DESCRIPTION :
Transfer function to descriptor form: S=list('d',A,B,C,0,E)
E*xdot = A*x+B*u
y = C*x + D*u with D=0.

Note that D=0 !

See Also : pol2des, tf2ss , ss2des , des2tf

Scilab Group April 1993 199

tf2des Scilab Function

Scilab Group April 1993 200

Chapter 6

Non-linear tools (optimization

and simulation)

201
colnew Scilab Function
6.0.442 colnew boundary value problems for ODE
CALLING SEQUENCE :
[z]=colnew(points,ncomp,m,aleft,aright,zeta,ipar,ltol,tol,fixpnt,...
fsub1,dfsub1,gsub1,dgsub1,guess1)

PARAMETERS :
z The solution of the ode evaluated on the mesh given by points
points an array which gives the points for which we want the solution
ncomp no. of dierential equations (ncomp .le. 20)
m a vector of size ncomp. m(j) gives the order of the j-th dierential equation
X
ncomp
mstar = m(i)  40
i=1
aleft left end of interval
aright right end of interval
zeta zeta(j) gives j-th side condition point (boundary point). must have zeta(j)  zeta(j +
1).all side condition points must be mesh points in all meshes used, see description of
ipar(11) and fixpnt below.
ipar an integer array dimensioned at least 11. a list of the parameters in ipar and their meaning
follows some parameters are renamed in colnew; these new names are given in parentheses.
ipar(1) ( = nonlin )
= 0 if the problem is linear
= 1 if the problem is nonlinear
ipar(2) = no. of collocation points per subinterval (= k ) where max m(i)  k  7.if
ipar(2)=0 then colnew sets k = max(max m(i) + 1; 5 , max m(i))
ipar(3) = no. of subintervals in the initial mesh ( = n ). if ipar(3) = 0 then colnew
arbitrarily sets
n = 5 .
ipar(4) = no. of solution and derivative tolerances. ( = ntol ) we require 0 < ntol <
mstar :
ipar(5) = dimension of
fspace ( = ndimf ) a real work array. its size provides a con-
straint on nmax. choose ipar(5) according to the formula
ipar(5)  nmaxns where ns = 4 + 3mstar + (5 + kd )kd m + (2mstar , nrec)2mstar

ipar(6) = dimension of ispace ( = ndimi )an integer work array. its size provides a
constraint on nmax, the maximum number of subintervals. choose ipar(6) according
to the formula
ipar(6)  nmaxni whereni = 3 + kd m kd m = kd + mstar kd = kncomp

ipar(7) output control ( = iprint )

= -1 for full diagnostic printout
= 0 for selected printout
= 1 for no printout
ipar(8) ( = iread )
= 0 causes colnew to generate a uniform initial mesh.
= xx Other values are not implemented yet in Scilab
= 1 if the initial mesh is provided by the user. it is dened in fspace as follows:
the mesh
aleft = x(1) < x(2) < : : : < x(n) < x(n + 1) = aright

will occupy fspace(1), ..., fspace(n+1). the user needs to supply only the
interior mesh points fspace(j) = x(j), j = 2, ..., n.
Scilab Group June 1993 202
colnew Scilab Function
= 2 if the initial mesh is supplied by the user as with ipar(8)=1, and
in addition no adaptive mesh selection is to be done.
ipar(9) ( = iguess )
= 0 if no initial guess for the solution is provided.
= 1 if an initial guess is provided by the user in subroutine guess.
= 2 if an initial mesh and approximate solution coecients are provided by the user
in fspace. (the former and new mesh are the same).
= 3 if a former mesh and approximate solution coecients are provided by the user
in fspace, and the new mesh is to be taken twice as coarse; i.e.,every second point
from the former mesh.
= 4 if in addition to a former initial mesh and approximate solution coecients, a
new mesh is provided in fspace as well. (see description of output for further details
on iguess = 2, 3, and 4.)
ipar(10) = 0 if the problem is regular
= 1 if the rst relax factor is =rstart, and the nonlinear iteration does not rely on
past covergence (use for an extra sensitive nonlinear problem only).
= 2 if we are to return immediately upon (a) two successive nonconvergences, or (b)
after obtaining error estimate for the rst time.
ipar(11) = no. of xed points in the mesh other than aleft and aright. ( = nfxpnt
, the dimension of fixpnt) the code requires that all side condition points other than
aleft and aright (see description of zeta ) be included as xed points in fixpnt.
ltol an array of dimension ipar(4). ltol(j) = l species that the j-th tolerance in tol controls
the error in the l-th component of z(u). also require that
1  ltol(1) < ltol(2) < ::: < ltol(ntol)  mstar
tol an array of dimension ipar(4). tol(j) is the error tolerance on the ltol(j) -th component
of z(u). thus, the code attempts to satisfy for j=1,...,ntol on each subinterval
jz(v) , z(u)jltol(j )  tol(j)  jz(u)jltol(j ) + tol(j)
if
v(x) is the approximate solution vector.
fixpnt an array of dimension ipar(11). it contains the points, other than aleft and aright,
which are to be included in every mesh.
externals The function fsub,dfsub,gsub,dgsub,guess are Scilab externals i.e. functions
(see syntax below) or the name of a fortran subroutine (character string) with specied
calling sequence or a list. An external as a character string refers to the name of a Fortran
subroutine. The Fortran coded function interface to colnew are specied in the le fcol.f.
fsub name of subroutine for evaluating

f(x; z(u(x))) = (f1 ; : : :; fncomp)t

at a point x in (aleft,aright). it should have the heading [f]=fsub(x,z) where f
is the vector containing the value of fi(x,z(u)) in the i-th component and
z(u(x)) = (z1 ; : : :; zmstar)t
is dened as above under purpose .
dfsub name of subroutine for evaluating the jacobian of f(x,z(u)) at a point x. it should
have the heading [df]=dfsub (x , z ) where z(u(x)) is dened as for fsub and the
(ncomp) by (mstar) array df should be lled by the partial derivatives of f, viz, for a
particular call one calculates
df(i; j) = dfi =dzj ; i = 1; : : :; ncomp j = 1; : : :; mstar:
Scilab Group June 1993 203
colnew Scilab Function
gsub name of subroutine for evaluating the i-th component of
g(x; z(u(x))) = gi (zeta(i); z(u(zeta(i))))
at a point x = zeta(i) where 1  i  mstar:it should have the heading[g]=gsub (i
, z) where z(u) is as for fsub, and i and g=gi are as above. note that in contrast to
f in fsub , here only one value per call is returned in g.
dgsub name of subroutine for evaluating the i-th row of the jacobian of g(x,u(x)). it
should have the heading [dg]=dgsub (i , z ) where z(u) is as for fsub, i as for gsub
and the mstar-vector dg should be lled with the partial derivatives of g, viz, for a
particular call one calculates
dg(i; j) = dgi=dzj ; j = 1; : : :; mstar:
guess name of subroutine to evaluate the initial approximationfor z(u(x)) and for dmval(u(x))=
vector of the mj-th derivatives of u(x). it should have the heading [z,dmval]= guess
(x ) note that this subroutine is used only if ipar(9) = 1, and then all mstar com-
ponents of z and ncomp components of dmval should be specied for any x, aleft 
x  aright:
DESCRIPTION :
this package solves a multi-point boundary value problem for a mixed order system of ode-s given
by
u(im(i)) = f(x; z(u(x))) i = 1; : : :; ncomp aleft < x < aright
X
ncomp
gj (zeta(j); z(u(zeta(j)))) = 0 j = 1; : : :; mstar mstar = m(i)
i=1
where u = (u1; u2; : : :; uncomp)t is the exact solution vector u(im(i)) is the mi=m(i) th derivative of
ui.
(m1 ,1) (mncomp,1)
z(u(x)) = (u1 (x); u(1)
1 (x); : : :; u1 (x); : : :; uncomp (x))
fi (x; z(u)) is a (generally) nonlinear function of z(u) = z(u(x)). gj (zeta(j); z(u)) is a (generally)
nonlinear function used to represent a boundary condition.the boundary points satisfy
 zeta(1)  : : :  zeta(mstar)  aright
aleft

the orders mi of the dierential equations satisfy 1  m(i)  4. See the directory demos/colnew
for a demo le
function [z,z1]=col1()
fixpnt=0
m=[4]
ncomp=1
aleft=1
aright=2
zeta=[1,1,2,2]
ipar=0*ones(1,11)
ipar(3)=1;ipar(4)=2;ipar(5)=2000;ipar(6)=200;ipar(7)=1
ltol=[1,3]
tol=[1.e-11,1.e-11]
res=aleft:0.1:aright
z=colnew(res,ncomp,m,aleft,aright,zeta,ipar,ltol,tol,fixpnt,...
fsub,dfsub,gsub,dgsub,guess)
z1=[]
for x=res,z1=[z1,trusol(x)]; end;

Scilab Group June 1993 204

dasrt Scilab Function
function [df]=dfsub(x,z)
df=[0,0,-6/x**2,-6/x]

function [f]=fsub(x,z)
f=(1 -6*x**2*z(4)-6*x*z(3))/x**3

function [g]=gsub(i,z)
g=[z(1),z(3),z(1),z(3)]
g=g(i)

function [dg]=dgsub(i,z)
dg=[1,0,0,0;0,0,1,0;1,0,0,0;0,0,1,0]
dg=dg(i,:)

function [z,mpar]=guess(x)
// unused here
z=0
mpar=0

function [u]=trusol(x)
u=0*ones(4,1)
U(1) = .25* (10.*LOG(2.)-3.) * (1.-X) +0.5* (1./X+ (3.+X)*LOG(X) - X)
U(2) = -.25* (10.*LOG(2.) - 3.) + .5 * (-1./X/X + LOG(X) + (3.+X)/X - 1.)
U(3) = .5 * (2./X**3 + 1./X -3./X/X)
U(4) = .5 * (-6./X**4 - 1./X/X + 6./X**3)

Author : U.ASCHER G.BADER

See Also : fort, link, external.

6.0.443 dasrt DAE solver with zero crossing

CALLING SEQUENCE :
[r,nn,[,hd]]=dasrt(x0,t0,t [,atol,[rtol]],res [,jac],ng, surf, info [,hd])

PARAMETERS :
x0 : is either (
y0 ydot0 is estimated by dassl with zero as rst estimate) or the matrix [y0
.
ydot0] g(t,y0,ydot0) must be equal to zero. If you only know an estimate of ydot0 set
info(7)=1

: real column vector of initial conditions.

y0
ydot0 : real column vector of the time derivative of y at t0 (may be an estimate).
t0 : real number is the initial instant.
t : real scalar or vector. Gives instants for which you want the solution. Note that you can get
solution at each dassl's step point by setting info(2)=1.
nn : times at which the surface is crossed
atol,rtol : real scalars or column vectors of same size as y. atol,rtol give respectively
absolute and relative error tolerances of solution. If vectors the tolerances are specied for
each component of y.
res : external (function or list or string). Computes the value of g(t,y,ydot).

function : Its calling sequence must be [r,ires]=res(t,y,ydot) and res must return
the residue r=g(t,y,ydot) and error ag ires. ires = 0 if res succeeds to compute
r, =-1 if residue is locally not dened for (t,y,ydot), =-2 if parameters are out of
admissible range.
list : it must be as follows:

Scilab Group June 1993 205

dasrt Scilab Function
list(res,x1,x2,...)

where the calling sequence of the function res is now

r=res(t,y,ydot,x1,x2,...)

res still returns r=g(t,y,ydot) as a function of (t,y,ydot,x1,x2,...).

string : it must refer to the name of a fortran subroutine (see source code of fresd.f).
jac : external (function or list or string). Computes the value of dg/dy+cj*dg/dydot for a given
value of parameter cj
function : Its calling sequence must be r=jac(t,y,ydot,cj) and the jac function must
return r=dg(t,y,ydot)/dy+cj*dg(t,y,ydot)/dydot where cj is a real scalar
list : it must be as follows

list(jac,x1,x2,...)

where the calling sequence of the function jac is now

r=jac(t,y,ydot,x1,x2,...)

jac still returns

dg/dy+cj*dg/dydot as a function of (t,y,ydot,cj,x1,x2,...).
character string : it must refer to the name of a fortran subroutine (see source code of
jacdd.f ).
surf : external (function or list or string). Computes the value of the column vector surf(t,y,ydot)
with ng components. Each component denes a surface.
function : Its calling sequence must be surf(t,y,ydot)
list : it must be as follows

list(surf,x1,x2,...)

where the calling sequence of the function surf is now

r=surf(t,y,ydot,x1,x2,...)
character string : it must refer to the name of a fortran subroutine (see source code of
fsurfd.f ) in directory SCDIR/default
info : list which contains 7 elements:

info(1) : real scalar which gives the maximum time for which g is allowed to be evaluated
or an empty matrix [] if no limits imposed for time.
info(2) : ag which indicates if dassl returns its intermediate computed values (flag=1)
or only the user specied time point values (flag=0).
info(3) : 2 components vector which give the denition [ml,mu] of band matrix com-
puted by jac; r(i - j + ml + mu + 1,j) = "dg(i)/dy(j)+cj*dg(i)/dydot(j)". If
jac returns a full matrix set info(3)=[].
info(4) : real scalar which gives the maximum step size. Set info(4)=[] if no limitation.
info(5) : real scalar which gives the initial step size. Set info(4)=[] if not specied.
info(6) : set info(6)=1 if the solution is known to be non negative, else set info(6)=0.
info(7) : set info(7)=1 if ydot0 is just an estimation, info(7)=0 if g(t0,y0,ydot0)=0.
hd : real vector which allows to store the dassl context and to resume integration
r : real matrix . Each column is the vector [t;x(t);xdot(t)] where t is time index for which the
solution had been computed
DESCRIPTION :
Solution of the implicit dierential equation
g(t,y,ydot)=0
y(t0)=y0 and ydot(t0)=ydot0

Scilab Group June 1993 206

dassl Scilab Function
Returns the surface crossing instants and the number of the surface reached in nn . Detailed
examples in SCIDIR/dassldasrt.tst
EXAMPLE :
//dy/dt = ((2*log(y)+8)/t -5)*y, y(1) = 1, 1<=t<=6
//g1 = ((2*log(y)+8)/t - 5)*y
//g2 = log(y) - 2.2491
y0=1;t=2:6;t0=1;y0d=3;
info=list([],0,[],[],[],0,0);
atol=1.d-6;rtol=0;ng=2;

deff('[delta,ires]=res1(t,y,ydot)','ires=0;delta=ydot-((2*log(y)+8)/t-5)*y')
deff('[rts]=gr1(t,y,yd)','rts=[((2*log(y)+8)/t-5)*y;log(y)-2.2491]')
comp(res1);comp(gr1);
[yy,nn]=dasrt([y0,y0d],t0,t,atol,rtol,res1,ng,gr1,info);
//(Should return nn=2.47...)

See Also : ode , dassl , impl , fort , link , external and directory SCIDIR/default

6.0.444 dassl dierential algebraic equation

CALLING SEQUENCE :
[r [,hd]]=dassl(x0,t0,t [,atol,[rtol]],res [,jac],info [,hd])

PARAMETERS :
x0 : is either
y0 ydot0( is estimated by dassl with zero as rst estimate) or the matrix [y0
.
ydot0] g(t,y0,ydot0) must be equal to zero. If you only know an estimate of ydot0 set
info(7)=1

: real column vector of initial conditions.

y0
ydot0 : real column vector of the time derivative of y at t0 (may be an estimate).
t0 : real number is the initial instant.
t : real scalar or vector. Gives instants for which you want the solution. Note that you can get
solution at each dassl's step point by setting info(2)=1.
atol,rtol : real scalars or column vectors of same size as y. atol,rtol give respectively
absolute and relative error tolerances of solution. If vectors the tolerances are specied for
each component of y.
res : external (function or list or string). Computes the value of g(t,y,ydot).

function : Its calling sequence must be [r,ires]=res(t,y,ydot) and res must return
the residue r=g(t,y,ydot) and error ag ires. ires = 0 if res succeeds to compute
r, =-1 if residue is locally not dened for (t,y,ydot), =-2 if parameters are out of
admissible range.
list : it must be as follows:

list(res,x1,x2,...)

where the calling sequence of the function res is now

r=res(t,y,ydot,x1,x2,...)

resstill returns r=g(t,y,ydot) as a function of (t,y,ydot,x1,x2,...).

string: it must refer to the name of a fortran subroutine (see source code of fresd.f).
jac : external (function or list or string). Computes the value of dg/dy+cj*dg/dydot for a given
value of parameter cj
Scilab Group June 1993 207
fsolve Scilab Function
function : Its calling sequence must be r=jac(t,y,ydot,cj) and the jac function must
return r=dg(t,y,ydot)/dy+cj*dg(t,y,ydot)/dydot where cj is a real scalar
list : it must be as follows
list(jac,x1,x2,...)
where the calling sequence of the function jac is now
r=jac(t,y,ydot,x1,x2,...)
jac still returns
dg/dy+cj*dg/dydot as a function of (t,y,ydot,cj,x1,x2,...).
character string : it must refer to the name of a fortran subroutine (see source code of
jacdd.f ).
info : list which contains 7 elements:

info(1) : real scalar which gives the maximum time for which g is allowed to be evaluated
or an empty matrix [] if no limits imposed for time.
info(2) : ag which indicates if dassl returns its intermediate computed values (flag=1)
or only the user specied time point values (flag=0).
info(3) : 2 components vector which give the denition [ml,mu] of band matrix com-
puted by jac; r(i - j + ml + mu + 1,j) = "dg(i)/dy(j)+cj*dg(i)/dydot(j)". If
jac returns a full matrix set info(3)=[].
info(4) : real scalar which gives the maximum step size. Set info(4)=[] if no limitation.
info(5) : real scalar which gives the initial step size. Set info(4)=[] if not specied.
info(6) : set info(6)=1 if the solution is known to be non negative, else set info(6)=0.
info(7) : set info(7)=1 if ydot0 is just an estimation, info(7)=0 if g(t0,y0,ydot0)=0.
hd : real vector which allows to store the dassl context and to resume integration
r : real matrix . Each column is the vector [t;x(t);xdot(t)] where t is time index for which the
solution had been computed
DESCRIPTION :
Solution of the implicit dierential equation
g(t,y,ydot)=0
y(t0)=y0 and ydot(t0)=ydot0
Detailed examples are given in SCIDIR/dassldasrt.tst
EXAMPLES :
deff('[r,ires]=chemres(t,y,yd)',[
'r(1)=-0.04*y(1)+1d4*y(2)*y(3)-yd(1);';
'r(2)=0.04*y(1)-1d4*y(2)*y(3)-3d7*y(2)*y(2)-yd(2);'
'r(3)=y(1)+y(2)+y(3)-1;'
'ires=0']);
deff('[pd]=chemjac(x,y,yd,cj)',[
'pd=[-0.04-cj , 1d4*y(3) , 1d4*y(2);';
'0.04 ,-1d4*y(3)-2*3d7*y(2)-cj ,-1d4*y(2);';
'1 , 1 , 1 ]'])
comp(chemres);comp(chemjac)
y0=[1;0;0];
yd0=[-0.04;0.04;0];
t=[1.d-5:0.02:.4,0.41:.1:4,40,400,4000,40000,4d5,4d6,4d7,4d8,4d9,4d10];

info=list([],0,[],[],[],0,0)
y=dassl([y0,yd0],0,t,chemres,info);
info(2)=1
y=dassl([y0,yd0],0,4d10,chemres,info);
y=dassl([y0,yd0],0,4d10,chemres,chemjac,info);

See Also : ode , dasrt , impl, fort , link , external.

Scilab Group August 1993 208

impl Scilab Function
6.0.445 fsolve nd a zero of a system of n nonlinear functions
CALLING SEQUENCE :
[x [,v [,info]]]=fsolve(x0,fct [,fjac] [,tol])

PARAMETERS :
x0 : real vector (initial value of function argument).
fct : external (i.e function or list or string).
fjac : external (i.e function or list or string).
tol : real scalar. precision tolerance: termination occurs when the algorithm estimates that the
relative error between x and the solution is at most tol. (tol=1.d-10 is the default value).
x : real vector (nal value of function argument, estimated zero).
v : real vector (value of function at x).
info : termination indicator

0 : improper input parameters.

1 : algorithm estimates that the relative error between x and the solution is at most tol.
2 : number of calls to fcn reached
3 : tol is too small. No further improvement in the approximate solution x is possible.
4 : iteration is not making good progress.

DESCRIPTION :
nd a zero of a system of n nonlinear functions in n variables by a modication of the powell
hybrid method. Jacobian may be provided.
0 = fct(x) w.r.t x.

fct is an "external". This external returns v=fct(x) given x.

The simplest calling sequence for fct is:
[v]=fct(x).

Iffct is a character string, it refers to a fortran routine which must be linked to Scilab (see
fsolvf.f for the calling sequence). Dynamic link is possible (help link).
jac is an "external". This external returns v=d(fct)/dx (x) given x.
The simplest calling sequence for jac is:
[v]=jac(x).

Ifjac is a character string, it refers to a fortran routine which must be linked to Scilab (see
fsolvj.f for the calling sequence). Dynamic link is possible (help link).
See Also : external, quapro, linpro, optim
6.0.446 impl dierential algebraic equation
DESCRIPTION :
y=impl(['type',]y0,ydot0,t0,t1[,atol,[rtol]],res,adda[,jac])

PARAMETERS :
y0,ydot0 : real vectors
t0 : real number
t : real row vector
res,adda,jac : externals (function or list or string)
type : string
'adams' or 'stiff'
atol,rtol : real numbers or real vectors
Scilab Group April 1993 209
intc Scilab Function
DESCRIPTION :
Solution of the implicit dierential equation

A(t,y)ydot=g(t,y)
y(t0)=y0 and ydot(t0)=ydot0

t0 is the initial instant.

y0 is the vector of initial conditions.
ydot0 is the vector of the time derivative of y at t0.
res : External
a function its syntax must be r=res(t,y,ydot) and res must return r=g(t,y)-A(t,y)*ydot
a list it must be : list(res,x1,x2,...) where the syntax of the function res is now
r=res(t,y,ydot,x1,x2,...)

res still returns r=g(t,y)-A(t,y)*ydot as a function of (t,y,ydot,x1,x2,...).

a string

it refer to the name of a fortran subroutine or C procedure (see source code of fres.f).
adda : External
a function its syntax must be r=adda(t,y,p) and adda must return r=A(t,y)+p
a list it must be : list(adda,x1,x2,...) where the syntax of the function adda is now
r=adda(t,y,x1,x2,...)

adda still returns r=A(t,y)+p as a function of (t,y,x1,x2,...).

a string

it refer to the name of a fortran subroutine or C procedure (see source code of fadda.f).
jac : External
a function its syntax must be j=jac(t,y,ydot) and adda must return the jacobian of
r=g(t,y)-A(t,y)*ydot
a list it must be : list(jac,x1,x2,...) where the syntax of the function jac is now
r=jac(t,y,ydot,x1,x2,...)

jac still returns the jacobian of r=g(t,y)-A(t,y)*ydot as a function of (t,y,ydot,x1,x2,...).

a string

it refer to the name of a fortran subroutine or C procedure (see source code of fjac.f).
More details are provided in help ode.
fortran call (see fres.f and fadda.f fjac.f )
EXAMPLES :
impl([1;0;0],[-0.04;0.04;0],0,0.4,'resid','aplusp')

See Also : ode , external.

Scilab Group April 1993 210

karmarkar Scilab Function
6.0.447 intc Cauchy integral
CALING SEQUENCE :
[y]=intc(a,b,f)
PARAMETERS :
a,b : two complex numbers
f : "external" function
DESCRIPTION :
If f is a complex-valued function, intc(a,b,f) computes the integral from a to b of f(z)dz
along the straight line a b of the complex plane.
See Also : intg, intl
Author : F. D.
6.0.448 intg denite integral
CALLING SEQUENCE :
[v,err]=intg(a,b,f [,ea [,er])
PARAMETERS :
a,b : real numbers
f : external (function or list or string)
ea, er : real numbers
ea : absolute error required on the result. Default value: 0
er : relative error required on the result. Default value: 1.d-8
err : estimated absolute error on the result.
DESCRIPTION :
intg(a,b,f) evaluates the denite integral from a to b of f(t)dt. The evaluation hopefully
satises following claim for accuracy: abs(I-v)<= max(ea,er*abs(I)) where I stands for the
exact value of the integral.
f is an external :
If f is function its denition must be as follows y = f(t)
If f is a list the list must be as follows: list(f,x1,x2,...) where f is a function with calling
sequence f(t,x1,x2,...).
If f is a string it refers to a the name of a Fortran subroutine (see source code of fintg.f)
See Also : intc, intl
6.0.449 intl Cauchy integral
CALLING SEQUENCE :
[y]=intl(a,b,z0,r,f)
PARAMETERS :
z0 : complex number
a,b : two real numbers
r : positive real number
f : "external" function
DESCRIPTION :
If f is a complex-valued function, intl(a,b,z0,r,f) computes the integral of f(z)dz along the
curve in the complex plane dened by z0 + r.exp(%i*t) for a<=t<=b .(part of the circle with
center z0 and radius r with phase between a and b)
See Also : intc
Author : F. D.
Scilab Group April 1993 211
linpro Scilab Function
6.0.450 karmarkar karmarkar (test program)
CALLING SEQUENCE :
[x1]=karmarkar(a,b,c,x0)

PARAMETERS :
a : matrix (n,p)
b : n - vector
c : p - vector
x0 : initial vector
eps : threshold (default value : 1.d-5)
gamma : descent step 0<gamma<1 , default value : 1/4
x1 : solution
crit : value of c'*x1
DESCRIPTION :
Computes x which minimizes
c'*x

under constraints:
a*x = b
x>=0

EXAMPLE :
n=10;p=20;
a=rand(n,p);c=rand(p,1);x0=abs(rand(p,1));b=a*x0;x1=karmarkar(a,b,c,x0);

6.0.451 linpro linear programming solver

CALLING SEQUENCE :
[x,lagr,f]=linpro(p,C,b [,x0])
[x,lagr,f]=linpro(p,C,b,ci,cs [,x0])
[x,lagr,f]=linpro(p,C,b,ci,cs,mi [,x0])
[x,lagr,f]=linpro(p,C,b,ci,cs,mi,x0 [,imp])

PARAMETERS :
p : real (column) vector (dimension n)
C : real matrix (dimension (mi + md) x n) (If no constraints are given, you can set C = [])
b : RHS vector (dimension 1 x (mi + md))
ci : (column) vector of lower-bounds (dimension n). If there are no lower bound constraints, put
ci = []. If some components of x are bounded from below, set the other (unconstrained)
values of ci to a very large negative number (e.g. ci(j) = -(% eps)^(-1).
cs : (column) vector of upper-bounds. (Same remarks as above).
mi : number of equality constraints (i.e. C(1:mi,:)*x = b(1:mi))
x0 : either an initial guess for x or one of the character strings 'v' or 'g'. If x0='v' the
calculated initial feasible point is a vertex. If x0='g' the calculated initial feasible point is
arbitrary.
imp : verbose option (optional parameter) (Try imp=7,8,...)
x : optimal solution found.
f : optimal value of the cost function (i.e. f=p'*x).

Scilab Group April 1993 212

lmisolver Scilab Function
lagr : vector of Lagrange multipliers. If lower and upper-bounds ci,cs are provided, lagr has
n + mi + md components and lagr(1:n) is the Lagrange vector associated with the bound
constraints and lagr (n+1 : n + mi + md) is the Lagrange vector associated with the
linear constraints. (If an upper-bound (resp. lower-bound) constraint i is active lagr(i) is
> 0 (resp. <0). If no bounds are provided, lagr has only mi + md components.
DESCRIPTION :
[x,lagr,f]=linpro(p,C,b [,x0])
Minimize p'*x
under the constraints
C*x <= b

[x,lagr,f]=linpro(p,C,b,ci,cs [,x0])
Minimize p'*x
under the constraints
C*x <= b ci <= x <= cs

[x,lagr,f]=linpro(p,C,b,ci,cs,mi [,x0])
Minimize p'*x
under the constraints
C(j,:) x = b(j), j=1,...,mi
C(j,:) x <= b(j), j=mi+1,...,mi+md
ci <= x <= cs

If no initial point is given the program computes a feasible initial point which is a vertex of the
region of feasible points if x0='v'.
If x0='g', the program computes a feasible initial point which is not necessarily a vertex. This
mode is advisable when the quadratic form is positive denite and there are a few constraints in
the problem or when there are large bounds on the variables that are security bounds and very
likely not active at the optimal solution.
EXAMPLE :
//Find x in R^6 such that:
//C1*x = b1 (3 equality constraints i.e mi=3)
C1= [1,-1,1,0,3,1;
-1,0,-3,-4,5,6;
2,5,3,0,1,0];
b1=[1;2;3];
//C2*x <= b2 (2 inequality constraints)
C2=[0,1,0,1,2,-1;
-1,0,2,1,1,0];
b2=[-1;2.5];
//with x between ci and cs:
ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
//and minimize p'*x with
p=[1;2;3;4;5;6]
//No initial point is given: x0='v';
C=[C1;C2]; b=[b1;b2] ; mi=3; x0='v';
[x,lagr,f]=linpro(p,C,b,ci,cs,mi,x0)
// Lower bound constraints 3 and 4 are active and upper bound
// constraint 5 is active --> lagr(3:4) < 0 and lagr(5) > 0.
// Linear (equality) constraints 1 to 3 are active --> lagr(7:9) <> 0

See Also : quapro

Author : E. Casas, C. Pola Mendez
Scilab Group April 1993 213
lmitool Scilab Function
6.0.452 lmisolver linear matrix inequation solver
CALLING SEQUENCE :
[XLISTF[,OPT]] = lmisolver(XLIST0,evalfunc [,options])

PARAMETERS :
XLIST0 : a list of containing initial guess (e.g.
XLIST0=list(X1,X2,..,Xn) )
evalfunc : a Scilab function ("external" function with specic syntax)
XLISTF : a list of matrices (e.g.
XLIST0=list(X1,X2,..,Xn) )
options : optional parameter. If given,
options is a real row vector with 5 components
[Mbound,abstol,nu,maxiters,reltol]

The syntax the function evalfunc must be as follows:

[LME,LMI,OBJ]=evalfunct(X) where X is a list of matrices, LME, LMI are lists and OBJ a real
scalar.
DESCRIPTION :
lmisolver solves the following problem:
minimize f(X1,X2,...,Xn) a linear function of Xi's
under the linear constraints: Gi(X1,X2,...,Xn)=0 for i=1,...,p and LMI (linear matrix inequali-
ties) constraints:
Hj(X1,X2,...,Xn) > 0 for j=1,...,q
The functions f, G, H are coded in the Scilab function evalfunc and the set of matrices Xi's in
the list X (i.e. X=list(X1,...,Xn)).
The function evalfun must return in the list LME the matrices G1(X),...,Gp(X) (i.e. LME(i)=Gi(X1,...,Xn),
i=1,...,p). evalfun must return in the list LMI the matrices H1(X0),...,Hq(X) (i.e. LMI(j)=Hj(X1,...,Xn),
j=1,...,q). evalfun must return in OBJ the value of f(X) (i.e. OBJ=f(X1,...,Xn)).
lmisolver returns in XLISTF, a list of real matrices, i. e. XLIST=list(X1,X2,..,Xn) where the
Xi's solve the LMI problem:
Dening Y,Z and cost by:
[Y,Z,cost]=evalfunc(XLIST), Y is a list of zero matrices, Y=list(Y1,...,Yp), Y1=0, Y2=0,
..., Yp=0.
Z is a list of square symmetric matrices, Z=list(Z1,...,Zq) , which are semi positive denite
Z1>0, Z2>0, ..., Zq>0 (i.e. spec(Z(j)) > 0),
cost is minimized.
lmisolver can also solve LMI problems in which the Xi's are not matrices but lists of matrices.
More details are given in the documentation of LMITOOL.
EXAMPLE :
//Find diagonal matrix X (i.e. X=diag(diag(X), p=1) such that
//A1'*X+X*A1+Q1 < 0, A2'*X+X*A2+Q2 < 0 (q=2) and trace(X) is maximized
n=2;A1=rand(n,n);A2=rand(n,n);
Xs=diag(1:n);Q1=-(A1'*Xs+Xs*A1+0.1*eye);
Q2=-(A2'*Xs+Xs*A2+0.2*eye);
deff('[LME,LMI,OBJ]=evalf(Xlist)','X=Xlist(1),LME=X-diag(diag(X));...
LMI=list(-(A1''*X+X*A1+Q1),-(A2''*X+X*A2+Q2)),OBJ= -sum(diag(X)) ');
X=lmisolver(list(zeros(A1)),evalf);X=X(1)
[Y,Z,c]=evalf(X)

See Also : lmitool

6.0.453 lmitool tool for solving linear matrix inequations

CALLING SEQUENCE :
Scilab Group April 1993 214
ode Scilab Function
lmitool()

lmitool(filename)

txt=lmitool(probname,varlist,datalist)

PARAMETERS :
filename : a string referring to a .sci function
probname : a string containing the name of the problem
varlist : a string containing the names of the unknown matrices (separated by commas if there
are more than one)
datalist : a string containing the names of data matrices (separated by commas if there are
more than one)
txt : a string providing information on what the user should do next

DESCRIPTION :
lmitool() or lmitool(filename) is used to dene interactively a LMI problem. In the non
interactive mode, txt=lmitool(probname,varlist,datalist) generates a le in the current di-
rectory. The name of this le is obtained by adding .sci to the end of probname. This le is the
skeleton of a solver function and the corresponding evaluation function needed by lmisolver.
See Also : lmisolver
6.0.454 ode ordinary dierential equation solver
CALLING SEQUENCE :
[yt]=ode(y0,t0,t,f)
[yt,w,iw]=ode([type],y0,t0,t [,rtol [,atol]],f [,jac] [,w,iw])
[yt,rd,w,iw]=ode('root',y0,t0,t [,rtol [,atol]],f [,jac],ng,g [,w,iw])
[yt]=ode('discrete',y0,k0,kvect,f)

PARAMETERS :
y0 : real vector or matrix (initial conditions).
t0, : real scalar (initial time).
t : real (row) vector.
f : Scilab "external" i.e. function or character string or list.
type : one of the following character string: 'adams' 'stiff' 'rgk' 'discrete' 'roots'
rtol,atol : real constants or real vector of the same size as y.
jac : external i.e. function or character string or list.
w,iw : real vectors.
ng : integer.
g : external i.e. function or character string or list.
k0,kvect k0 : an integer ( initial time). kvect integer vector.
DESCRIPTION :
1.Simple call
y=ode(y0,t0,t,f) computes the solution to the system of dierential equations
dy/dt=f(t, y) , y(t0)=y0.
t is a vector of instants where the solution y is computed.
y is the vector y=[y(t(1)),y(t(2)),...].
The input f to ode is an external i.e. a function with specied syntax or the name a fortran
subroutine (character string) with specied calling sequence or a list.
If f is a function, its syntax must be as follows:
ydot = f(t,y)

Scilab Group April 1993 215

ode Scilab Function
Where t is a real scalar and y a real vector or matrix.
This function evaluates dy/dt as a function of the scalar t and the real vector or matrix y (f is
the RHS of the dierential equation dy/dt=f(t,y)).
If f is a character string, it refers to the name of a Fortran subroutine i.e. if ode(y0,t0,t,'fex')
is the command, then the subroutine fex is called. See the source code of subroutine fydot for
an example.
The f argument can also be a list:
if ode(y0,t0,t,lst) is the command, then lst must be a list with the following structure:
lst=list(f,u1,u2,...un)

where f is a function with syntax:

ydot = f(t,y,u1,u2,...,un)

2.Extended call
This command allows to integrate the dierential system
dy/dt=f(t,y,u1,u2,...,un)

the ui's can be any Scilab object e.g. vectors or matrices or functions...
type : is the character string which indicates the method used by the integration routine:

"adams" : Adams method

"stiff" : BDF method
"rgk" : Runge Kutta method
rtol, atol : are threshold for relative and absolute estimated errors. The estimated error on
y(i) is rtol(i)*abs(y(i)) + 0.01*atol(i) and integration is carried out as far as this
error is small for all components of the state. If rtol and/or atol is a constant rtol(i)
and/or atol(i) are set to this constant value. Default values for atol and rtol are re-
spectively rtol=1.d-5 and atol=1.d-7.
jac : is a function or character string or list which returns the Jacobian of the RHS function.

If jac is function the syntax should be as follows:

J=jac(t,y)

Matrix J must evaluate to df/dx i.e. J(k,i) = d fk /d xi with fk = kth component of f.

If jac is a character string it refers to the name of a Fortran subroutine (see source code fjac.f
for an example)
If jac is a list the same conventions as for f apply.
w,iw : vectors for storing information returned by the integration routine. When these vectors
are provided in RHS of ode the integration re-starts with the same parameters as in its
previous stop.
3.Integration with a stopping time
[yt,rd]=ode('root',y0,t0,t,f,ng,g)
computes the solution of the dierential equation dy/dt=f(t,y) until the state y(t) traverses
the surface
g(t,y)=0.

Here g can be a function or a list or character string (which refers to the name of a Fortran
subroutine). g should give the equation of the surface. If g is a function its syntax must be
surface = g(t,y) and it returns a vector of size ng which corresponds to the ng constraints.
Conventions concerning Fortran routine are found in fsurf.f. Conventions concerning g as a
list are the usual ones (see f above). Ouput rd is a 1xk vector. The rst entry contains the
Scilab Group April 1993 216
odedc Scilab Function
stopping time. Other entries indicate which components of g have changed sign. k larger than
two indicates that more than one surface (k-1) has been simultaneously traversed.
4.Discrete time simulation
yt=ode('discrete',y0,k0,kvect,f)
computes recursively
y(k+1)=f(k,y(k) ) from an initial state y(k0) and returns y(k) for k in
.
kvect kvect(1) must be greater or equal to k0.
Optional parameters can be given by a global variable. For this enter odeoptions().
Below are a few examples.
y=ode('discrete',y1,1,1:n,function);
y=ode('discrete',y1,1,3:2:9,function);

in the second example y evaluates to y=[y3,y5,y7,y9];

For example
[1] Computation of exp(A) with A=[1,1;0,2];

deff('[xdot]=f(t,x)','xdot=A*x');
ode(eye(A),0,1,f)

Same example integrated with Adams integration routine

ode('adams',0,1,f)

Same example with sti f (Jacobian provided) A=[10,0;0,-1]

deff('[J]=Jacobian(t,y)','J=A')
ode('stiff',[0;1],0,1,f,Jacobian)

[2] Integration of the Riccati dierential equation Xdot=A'*X + X*A - X'*B*X + C , X(0)=Identity
Solution at t=[1,2]
deff('[Xdot]=ric(t,X)','Xdot=A''*X+X*A-X''*B*X+C')
A=[1,1;0,2]; B=[1,0;0,1]; C=[1,0;0,1];
X=ode(eye(A),0,t,ric)

[3] Simulation of dx/dt = A x(t) + B u(t) with u(t)=sin(omega*t), x0=[1;0] ; solution x(t)
desired at t=0.1, 0.2, 0.5 ,1. Here the A matrix and the u function are passed to the RHS
function in a list. B and omega are passed through the environment.
deff('[xdot]=linear(t,x,A,u)','xdot=A*x+B*u(t)')
deff('[ut]=u(t)','ut=sin(omega*t)')
A=[1 1;0 2];B=[1;1];omega=5;
ode([1;0],0,[0.1,0.2,0.5,1],list(linear,A,u))

[4] Stopping time Integration of the dierential equation ydot = y , y(0)= y0=1; and nds
To=infft such that y(t)=2g
deff('[ydot]=f(t,y)','ydot=y')
deff('[surface]=g(t,y)','surface=y-2')
ng=1;
[y,rd]=ode('roots',y0,0,2,f,ng,g)

[5] Fortran called (see source code of fydot.f and fjac.f)

y0=[1;0;0]; t0=0; t=[0.4,4]
ode('stiff',y0,t0,t,'fex','jex')

See Also : odeoptions , impl, ltitr , rtitr , exp , csim , external , directory SCIDIR/default

Scilab Group April 1993 217

odedc Scilab Function
6.0.455 odedc discrete/continuous ode solver
CALLING SEQUENCE :
yt=odedc(y0,nd,stdel,t0,t,f)

PARAMETERS :
y0 : real column vector (initial conditions),y0=[y0c;y0d] where y0d has nd components.
nd : integer, dimension of y0d
stdel : real vector with two entries, stdel=[step, delay]
t0 : real scalar (initial time).
t : real (row) vector, instants where yt is calculated
f : Scilab "external" i.e. function or character string or list with calling sequence: yp=f(t,yc,yd,flag)
DESCRIPTION :
y=odedc([y0c;y0d],nd,[h,delta],t0,t,f) computes the solution of:
dyc/dt=f(t,yc,yd,0) , yc(t0)=y0c,
such that at instants td=[delta, delta+h, delta+2*h,...] the discrete variable yd is up-
dated by:
yd(td+)=f(yc(t-),yd(t-1),1)
The calling parameters of f are xed: xcd=f(t,xc,xd,flag); this function must return the deriva-
tive of the vector xc if flag=0 and the update of xd if flag=1.
t is a vector of instants where the solution y is computed.
y is the vector y=[y(t(1)),y(t(2)),...]. This function can be called with the same optional
parameters as the ode function (provided nd and stdel are given in the calling sequence as second
and third parameters). It particular integration ags, tolerances can be set. Optional parameters
can be set by the odeoptions function.
EXAMPLE :
//Linear system with switching input
deff('xdu=f(t,x,u,flag)','if flag=0 then xdu=A*x+B*u; else xdu=1-u;end');
x0=[1;1];A=[-1,2;-2,-1];B=[1;2];u=0;nu=1;stdel=[1,0];u0=0;t=0:0.05:10;
xu=odedc([x0;u0],nu,stdel,0,t,f);x=xu(1:2,:);u=xu(3,:);
[xi,xa,npx]=graduate(min(t),1.1*max(t));
[yi,ya,npy]=graduate(1.1*min(min(x),min(u)),1.1*max(max(x),max(u)));
rect=[xi,yi,xa,ya];nx=2;//cont. componemts
plot2d1('onn',t',x',-[1:nx],'111',' ',rect,[4,npx,2,npy]);
plot2d2('onn',t',u',-[nx+1:nx+nu],'111',' ',rect,[4,npx,2,npy]);

//Sampled feedback
//
// | xcdot=fc(t,xc,u)
// (system) |
// | y=hc(t,xc)
//
//
// | xd+=fd(xd,y)
// (feedback) |
// | u=hd(t,xd)
//
deff('xcd=f(t,xc,xd,iflag)',...
'if iflag==0 then ...
xcd=fc(t,xc,e(t)-hd(t,xd));...
else xcd=fd(xd,hc(t,xc));end');
comp(f);

Scilab Group April 1993 218

optim Scilab Function
A=[-10,2,3;4,-10,6;7,8,-10];B=[1;1;1];C=[1,1,1];
Ad=[1/2,1;0,1/20];Bd=[1;1];Cd=[1,1];
deff('st=e(t)','st=sin(3*t)')
deff('xdot=fc(t,x,u)','xdot=A*x+B*u')
deff('y=hc(t,x)','y=C*x')
deff('xp=fd(x,y)','xp=Ad*x + Bd*y')
deff('u=hd(t,x)','u=Cd*x')
comp(e);comp(fc);comp(hc);comp(fd);comp(hd);
h=0.1;t0=0;t=0:0.1:2;
x0c=[0;0;0];x0d=[0;0];nd=2;
xcd=odedc([x0c;x0d],nd,h,t0,t,f);
plot2d([t',t',t'],xcd(1:3,:)');
xset("window",2);plot2d2("gnn",[t',t'],xcd(4:5,:)');
xset("window",0);

See Also : ode , odeoptions , csim , external , directory SCIDIR/default

6.0.456 odeoptions sets options for odepack solvers

CALLING SEQUENCE :
odeoptions()

DESCRIPTION :
This functions interactively displays a command which should be executed to set various options of
ode solvers. A global variable %ODEOPTIONS sets the options. Caution: the ode function checks if
this variable exists and in that case uses it. For using default values you should clear this variable.
Note that odeoptions does not create this variable. To create it you must execute with the mouse
the command line displayed by odeoptions.
See Also : ode, documentation in source code of lsode, lsoda.
6.0.457 optim non-linear optimization routine
CALLING SEQUENCE :
[f,xopt]=optim(costf,x0)
[f,[xopt,[gradopt,[work]]]]=optim(costf,[contr],x0,['algo'],[df0,[mem]],
[work],[stop],['in'])

PARAMETERS :
costf : external, i.e Scilab function or string (costf is the cost function: see below its calling
sequence (Scilab or Fortran)).
x0 : real vector (initial value of variable to be minimized).
f : value of optimal cost (f=costf(xopt))
xopt : best value of x found.
contr : 'b',binf,bsup with binf and bsup real vectors with same dimension as x0. binf
and bsup are lower and upper bounds on x.
"algo" : 'qn' or 'gc' or 'nd' . This string stands for quasi-Newton (default), conjugate
gradient or non-dierentiable respectively. Note that 'nd' does not accept bounds on x ).
df0 : real scalar. Guessed decreasing of f at rst iteration. (df0=1 is the default value).
mem : integer, number of variables used to approximate the Hessian, (algo='gc' or 'nd'). De-
fault value is around 6.
stop : sequence of optional parameters controlling the convergence of the algorithm. stop=
'ar',nap, [iter [,epsg [,epsf [,epsx]]]]

"ar" : reserved keyword for stopping rule selection dened as follows:

Scilab Group April 1993 219
optim Scilab Function
nap : maximum number of calls to costf allowed.
iter : maximum number of iterations allowed.
epsg : threshold on gradient norm.
epsf : threshold controlling decreasing of f
epsx : threshold controlling variation of x. This vector (possibly matrix) of same size as
x0 can be used to scale x.
"in" : reserved keyword for initialization of parameters used when costf in given as a Fortran
routine (see below).
gradopt : gradient of costf at xopt
work : working array for hot restart for quasi-Newton method. This array is automatically
initialized by optim when optim is invoked. It can be used as input parameter to speed-up
the calculations.
DESCRIPTION :
Non-linear optimization routine for programs without constraints or with bound constraints:
min costf(x) w.r.t x.

costf is an "external" i.e function, or list or Fortran routine (see "external"). This external must
return f (costf(x)) and g (gradient of costf) given x.
If costf is a function, the calling sequence for costf must be:
[f,g,ind]=costf(x,ind).

Here, costf is a function which returns f, value (real number) of cost function at x, and g, gradient
vector of cost function at x. The variable ind is used by optim and is described below.
If ind=2 (resp. 3, 4), costf must provide f (resp. g, f and g).
If ind=1 nothing is computed (used for display purposes only).
On output, ind<0 means that f cannot be evaluated at x and ind=0 interrupts the optimization.
If costf is a character string, it refers to the name of a Fortran routine which must be linked to
Scilab (see examples in the routines foptim.f and e.g. genros.f in the directory SCIDIR/default)
Dynamic link of Fortran routine is also possible (help link).
Here, the generic calling sequence for the Fortran subroutine is: function costf(ind,n,x,f,g,ti,tr,td)
ind has the same meaning as above if set to 0,1,2 but the values ind=10 and ind=11 are now
valid. These values are used for initializations (see below).
n is the dimension of x, x is an n vector, ti,tr,td are working arrays.
The Fortran function costf must return f and the vector g, given x, ind, n, ti, tr, td.
If costf is given as a Fortran routine, it is possible to initialize parameters or to send Scilab
variables to this routine.
This facility is managed by the parameter 'in.
If the string 'in' is present, initialization is done by Fortran: optim makes two calls to the Fortran
function costf, once with ind=10 and once with ind=11. In this case, for ind=10, costf must
set the dimensions nti, ntr, ntd of ti, tr, td in the common/nird/nti, ntr, ntd and, for
ind=11, costf must initialize the vectors ti , tr, td (integer vector, real vector, double preci-
sion vector respectively).
In the calling sequence of optim, the string 'in' can be replaced by 'ti', valti ,'td' , valtd.
Then, the Fortran function costf(ind, x, f, g, ti, tr, td) is evaluated with ti=valti and
td=valtd whatever the value of ind. Thus, the Scilab variables valti and valtd (integer vector
and real vector) are sent to the Fortran function costf.
It is also possible to save the content of of the working arrays ti and td. This is possible by
adding the strings 'si' and/or 'sd' at the ned of the calling sequence of optim. Then, the output
variables must be: [f,[x,[g],[to]]],[ti],[td]].
EXAMPLES :
xref=[1;2;3];x0=[1;-1;1]
deff('[f,g,ind]=cost(x,ind)','f=0.5*norm(x-xref)^2,g=x-xref');

Scilab Group April 1993 220

quapro Scilab Function
[f,xopt]=optim(cost,x0) //Simplest call
[f,xopt,gopt]=optim(cost,x0,'gc') // By conjugate gradient
[f,xopt,gopt]=optim(cost,x0,'nd') //Seen as non differentiable
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0) // Bounds on x
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc') // Bounds on x
[f,xopt,gopt]=optim(cost,'b',[-1;0;2],[0.5;1;4],x0,'gc','ar',3)
// Here, 3 calls to cost are allowed.
//Now calling the Fortran subroutine "genros.f" in SCIDIR/default
// (see also the interface foptim.f)
[f,xopt,gopt]=optim('genros',[1;2;3]) //Rosenbrock's function

See Also : external , quapro , linpro

6.0.458 quapro linear quadratic programming solver

CALLING SEQUENCE :
[x,lagr,f]=quapro(Q,p,C,b [,x0])
[x,lagr,f]=quapro(Q,p,C,b,ci,cs [,x0])
[x,lagr,f]=quapro(Q,p,C,b,ci,cs,mi [,x0])
[x,lagr,f]=quapro(Q,p,C,b,ci,cs,mi,x0 [,imp])

PARAMETERS :
Q : real symmetric matrix (dimension n x n).
p : real (column) vector (dimension 1 x n)
C : real matrix (dimension (mi + md) x n) (If no constraints are given, you can set C = [])
b : RHS vector (dimension 1 x (mi + md))
ci : (column) vector of lower-bounds (dimension 1 x n). If there are no lower bound con-
straints, put ci = []. If some components of x are bounded from below, set the other
(unconstrained) values of ci to a very large negative number (e.g. ci(j) = -(% eps)^(-1).
cs : (column) vector of upper-bounds. (Same remarks as above).
mi : number of equality constraints (i.e. C(1:mi,:)*x = b(1:mi))
x0 : either an initial guess for x or one of the character strings 'v' or 'g'. If x0='v' the
calculated initial feasible point is a vertex. If x0='g' the calculated initial feasible point is
arbitrary.
imp : verbose option (optional parameter) (Try imp=7,8,...).
x : optimal solution found.
f : optimal value of the cost function (i.e. f=p'*x).
lagr : vector of Lagrange multipliers. If lower and upper-bounds ci,cs are provided, lagr has
n + mi + md components and lagr(1:n) is the Lagrange vector associated with the bound
constraints and lagr (n+1 : n + mi + md) is the Lagrange vector associated with the
linear constraints. (If an upper-bound (resp. lower-bound) constraint i is active lagr(i) is
> 0 (resp. <0). If no bounds are provided, lagr has only mi + md components.
DESCRIPTION :
[x,lagr,f]=quapro(Q,p,C,b [,x0])
Minimize 0.5*x'*Q*x + p'*x
under the constraint
C*x <= b

[x,lagr,f]=quapro(Q,p,C,b,ci,cs [,x0])
Minimize 0.5*x'*Q*x + p'*x
under the constraints
C*x <= b ci <= x <= cs

Scilab Group April 1993 221

semidef Scilab Function
[x,lagr,f]=quapro(Q,p,C,b,ci,cs,mi [,x0])
Minimize 0.5*x'*Q*x + p'*x
under the constraints
C(j,:) x = b(j), j=1,...,mi
C(j,:) x <= b(j), j=mi+1,...,mi+md
ci <= x <= cs

If no initial point is given the program computes a feasible initial point which is a vertex of the
region of feasible points if x0='v'.
If x0='g', the program computes a feasible initial point which is not necessarily a vertex. This
mode is advisable when the quadratic form is positive denite and there are few constraints in the
problem or when there are large bounds on the variables that are just security bounds and very
likely not active at the optimal solution.
Note that Q is not necessarily non-negative, i.e. Q may have negative eigenvalues.
EXAMPLE :
//Find x in R^6 such that:
//C1*x = b1 (3 equality constraints i.e mi=3)
C1= [1,-1,1,0,3,1;
-1,0,-3,-4,5,6;
2,5,3,0,1,0];
b1=[1;2;3];
//C2*x <= b2 (2 inequality constraints)
C2=[0,1,0,1,2,-1;
-1,0,2,1,1,0];
b2=[-1;2.5];
//with x between ci and cs:
ci=[-1000;-10000;0;-1000;-1000;-1000];cs=[10000;100;1.5;100;100;1000];
//and minimize 0.5*x'*Q*x + p'*x with
p=[1;2;3;4;5;6]; Q=eye(6,6);
//No initial point is given;
C=[C1;C2] ; //
b=[b1;b2] ; //
mi=3;
[x,lagr,f]=quapro(Q,p,C,b,ci,cs,mi)
//Only linear constraints (1 to 4) are active (lagr(1:6)=0):
[x,lagr,f]=quapro(Q,p,C,b,[],[],mi) //Same result as above

See Also : linpro

Author : E. Casas, C. Pola Mendez
6.0.459 semidef semidenite programming
CALLING SEQUENCE :
[x,Z,ul,info]=semidef(x0,Z0,F,blck_szs,c,options)

PARAMETERS :
x0 : m x 1 real column vector (must be strictly primal feasible, see below)
Z0 : L x 1 real vector (compressed form of a strictly feasible dual matrix, see below)
F : L x (m+1) real matrix
blck szs : p x 2 integer matrix (sizes of the blocks) dening the dimensions of the (square)
diagonal blocks size(Fi(j)=blck szs(j) j=1,...,m+1.
c : m x 1 real vector
options : row vector with ve entries [nu,abstol,reltol,0,maxiters]

Scilab Group April 1993 222

semidef Scilab Function
ul : row vector with two entries
DESCRIPTION :
[x,Z,ul,info]=semidef(x0,Z0,F,blck szs,c,options) solves semidenite program:

minimize c'*x
subject to F_0 + x_1*F_1 + ... + x_m*F_m >= 0

and its dual

maximize -Tr F_0 Z

subject to Tr F_i Z = c_i, i=1,...,m
Z >= 0

exploiting block structure in the matrices F i.

It interfaces L. Vandenberghe and S. Boyd sp.c program.
The Fi's matrices are stored columnwise in F in compressed format: if F i^j, i=0,..,m, j=1,...,L
denote the jth (symmetric) diagonal block of F i, then
[ pack(F_0^1) pack(F_1^1) ... pack(F_m^1) ]
[ pack(F_0^2) pack(F_1^2) ... pack(F_m^2) ]
F= [ ... ... ... ]
[ pack(F_0^L) pack(F_1^L) ... pack(F_m^L) ]

where pack(M), for symmetric M, is the vector [M(1,1);M(1,2);...;M(1,n);M(2,2);M(2,3);...;M(2,n);...;M(n,

(obtained by scanning columnwise the lower triangular part of M).
blck szs gives the size of block j, ie, size(F i^j)=blck szs(j).
Z is a block diagonal matrix with L blocks Z^0, ..., Z^fL-1g. Z^j has size blck szs[j] times
blck szs[j]. Every block is stored using packed storage of the lower triangular part.
The 2 vector ul contains the primal objective value c'*x and the dual objective value -Tr F 0*Z.
The entries of options are respectively: nu = a real parameter which ntrols the rate of conver-
gence. abstol = absolute tolerance. reltol = relative tolerance (has a special meaning when
negative). tv target value, only referenced if reltol < 0. iters = on entry: maximum number
of iterations >= 0, on exit: the number of iterations taken.
info returns 1 if maxiters exceeded, 2 if absolute accuracy is reached, 3 if relative accuracy is
reached, 4 if target value is reached, 5 if target value is not achievable; negative values indicate
errors.
Convergence criterion:
(1) maxiters is exceeded
(2) duality gap is less than abstol
(3) primal and dual objective are both positive and
duality gap is less than (reltol * dual objective)
or primal and dual objective are both negative and
duality gap is less than (reltol * minus the primal objective)
(4) reltol is negative and
primal objective is less than tv or dual objective is greater
than tv

EXAMPLE :
F0=[2,1,0,0;
1,2,0,0;
0,0,3,1
0,0,1,3];

Scilab Group April 1993 223

semidef Scilab Function
F1=[1,2,0,0;
2,1,0,0;
0,0,1,3;
0,0,3,1]
F2=[2,2,0,0;
2,2,0,0;
0,0,3,4;
0,0,4,4];
blck_szs=[2,2];
F01=F0(1:2,1:2);F02=F0(3:4,3:4);
F11=F1(1:2,1:2);F12=F1(3:4,3:4);
F21=F2(1:2,1:2);F22=F2(3:4,3:4);
x0=[0;0]
Z0=2*F0;
Z01=Z0(1:2,1:2);Z02=Z0(3:4,3:4);
FF=[[F01(:);F02(:)],[F11(:);F12(:)],[F21(:);F22(:)]]
ZZ0=[[Z01(:);Z02(:)]];
c=[trace(F1*Z0);trace(F2*Z0)];
options=[10,1.d-10,1.d-10,0,50];
[x,Z,ul,info]=semidef(x0,pack(ZZ0),pack(FF),blck_szs,c,options)
w=vec2list(unpack(Z,blck_szs),[blck_szs;blck_szs]);Z=sysdiag(w(1),w(2))
c'*x+trace(F0*Z)
spec(F0+F1*x(1)+F2*x(2))
trace(F1*Z)-c(1)
trace(F2*Z)-c(2)

Scilab Group April 1993 224

Chapter 7

Signal Processing toolbox

225
Signal Scilab Function
7.0.460 %K Jacobi's complete elliptic integral
CALLING SEQUENCE :
[K]=%K(m)

PARAMETERS :
m : parameter of the elliptic integral 0<m<1 (m can be a vector)
K : value of the elliptic integral from 0 to 1 on the real axis
DESCRIPTION :
Calculates Jacobi's complete elliptic integral of the rst kind :
Z1 dt
K=
0 [(1 , t )(1 , mt )]
2 2 1=2

REFERENCES :
Abramowitz and Stegun page 598
Author : F.D.
7.0.461 %asn elliptic integral
CALLING SEQUENCE :
[y]=%asn(x,m)

PARAMETERS :
x : upper limit of integral (x>0) (can be a vector)
m : parameter of integral (0<m<1)
y : value of the integral
DESCRIPTION :
Calculates the elliptic integral
Zx dt
K=
0 [(1 , t )(1 , mt )]
2 2 1=2

If x is a vector, y is a vector of same dimension as x.

Author : F. D.
7.0.462 %sn Jacobi 's elliptic function
CALLING SEQUENCE :
[y]=%sn(x,m)

PARAMETERS :
x : a point inside the fundamental rectangle dened by the elliptic integral; x is a vector of
complex numbers
m : parameter of the elliptic integral (0<m<1)
y : result
DESCRIPTION :
Jacobi 's sn elliptic function with parameter m: the inverse of the elliptic integral for the parameter
m .
The amplitude am is computed in fortran and the addition formulas for elliptic functions are
applied
See Also : %asn, %K
Author : F. D.
Scilab Group April 1993 226
Signal Scilab Function
7.0.463 Signal Signal manual description
FILTERS :
analpf : analog low-pass lter
buttmag : squared magnitude response of a Butterworth lter
casc : creates cascade realization of lter
cheb1mag : square magnitude response of a type 1 Chebyshev lter
cheb2mag : square magnitude response of a type 1 Chebyshev lter
chepol : recursive implementation of Chebychev polynomial
convol : convolution of 2 discrete series
ell1 mag : squared magnitude of an elliptic lter
eqfir : minimax multi-band, linear phase, FIR lter
eqiir : design of iir lter
faurre : optimal lqg lter.
lindquis : optimal lqg lter lindquist algorithm
ffilt : FIR low-pass,high-pass, band-pass, or stop-band lter
filter : compute the lter model
find freq : parameter compatibility for elliptic lter design
findm : for elliptic lter design
frmag : magnitude of the frequency responses of FIR and IIR lters.
fsfirlin : design of FIR, linear phase (frequency sampling technique)
fwiir : optimum design of IIR lters in cascade realization,
iir : designs an iir digital lter using analog lter designs.
iirgroup : group delay of iir lter
iirlp : Lp IIR lters optimization
group : calculate the group delay of a digital lter
optfir : optimal design of linear phase lters using linear programming
remezb : minimax approximation of a frequency domain magnitude response.
kalm : Kalman update and error variance
lev : resolve the Yule-Walker equations :
levin : solve recursively Toeplitz system (normal equations)
srfaur : square-root algorithm for the algebraic Riccati equation.
srkf : square-root Kalman lter algorithm
sskf : steady-state Kalman lter
system : generates the next observation given the old state
trans : transformation of standardized low-pass lter into low-pass, high-pass, band-pass, stop-
band.
wfir : linear-phase windowed FIR low-pass, band-pass, high-pass, stop-band
wiener : Wiener estimate (forward-backward Kalman lter formulation)
wigner : time-frequency wigner spectrum of a signal.
window : calculate symmetric window
zpbutt : Butterworth analog lter
zpch1 : poles of a type 1 Chebyshev analog lter
zpch2 : poles and zeros of a type 2 Chebyshev analog lter
zpell : poles and zeros of prototype lowpass elliptic lter

SPECTRAL ESTIMATION :
corr : correlation coecients
cspect : spectral estimation using the modied periodogram method.
czt : chirp z-transform algorithm
intdec : change the sampling rate of a 1D or 2D signal
mese : calculate the maximum entropy spectral estimate
pspect : auto and cross-spectral estimate
wigner : Wigner-Ville time/frequency spectral estimation
Scilab Group April 1993 227
buttmag Scilab Function
TRANSFORMS :
dft : discrete fourier transform
fft : fast fourier transform
hilb : Hilbert transform centered around the origin.
hank : hankel matrix of the covariance sequence of a vector process
mfft : t for a multi-dimensional signal
IDENTIFICATION :
lattn,lattp : recursive solution of normal equations
phc : State space realisation by the principal hankel component approximation method,
rpem : identication by the recursive prediction error method
MISCELLANOUS :
lgfft : computes p = ceil (log 2(x))
sinc : calculate the function sin(2*pi* *t)/(pi*t)
sincd : calculates the function Sin(N*x)/Sin(x)
%K : Jacobi's complete elliptic integral
%asn : .TP the elliptic integral :
%sn : Jacobi 's elliptic function with parameter m
bilt : bilinear transform or biquadratic transform.
jmat : permutes block rows or block columns of a matrix

7.0.464 analpf create analog low-pass lter

CALLING SEQUENCE :
[hs,pols,zers,gain]=analpf(n,fdesign,rp,omega)

PARAMETERS :
n : positive integer : lter order
fdesign : string : lter design method : 'butt' or 'cheb1' or 'cheb2' or 'ellip'
rp : 2-vector of error values for cheb1, cheb2 and ellip lters where only rp(1) is used for cheb1
case, only rp(2) is used for cheb2 case, and rp(1) and rp(2) are both used for ellip case.
0<rp(1),rp(2)<1

-for cheb1 lters 1-rp(1)<ripple<1 in passband

-for cheb2 lters 0<ripple<rp(2) in stopband
-for ellip lters 1-rp(1)<ripple<1 in passband 0<ripple<rp(2) in stopband
omega : cut-o frequency of low-pass lter in Hertz
hs : rational polynomial transfer function
pols : poles of transfer function
zers : zeros of transfer function
gain : gain of transfer function

DESCRIPTION :
Creates analog low-pass lter with cut-o frequency at omega.
hs=gain*poly(zers,'s')/poly(pols,'s')
Author : C. B.
Scilab Group April 1993 228
Cheb2mag Scilab Function
7.0.465 buttmag response of Butterworth lter
CALLING SEQUENCE :
[h]=buttmag(order,omegac,sample)

PARAMETERS :
order : integer : lter order
omegac : real : cut-o frequency in Hertz
sample : vector of frequency where buttmag is evaluated
h : Butterworth lter values at sample points
DESCRIPTION :
squared magnitude response of a Butterworth lter omegac = cuto frequency ; sample = sample
of frequencies
Author : F. D.
7.0.466 casc cascade realization of lter from coecients
CALLING SEQUENCE :
[cels]=casc(x,z)

PARAMETERS :
x : (4xN)-matrix where each column is a cascade element, the rst two column entries being the
numerator coecients and the second two column entries being the denominator coecients
z : string representing the cascade variable
cels : resulting cascade representation

DESCRIPTION :
Creates cascade realization of lter from a matrix of coecients
EXAMPLE :
x=[1,2,3;4,5,6;7,8,9;10,11,12]
cels=casc(x,'z')

Author : F. D.
7.0.467 cheb1mag response of Chebyshev type 1 lter
CALLING SEQUENCE :
[h2]=cheb1mag(n,omegac,epsilon,sample)

PARAMETERS :
n : integer : lter order
omegac : real : cut-o frequency
epsilon : real : ripple in pass band
sample : vector of frequencies where cheb1mag is evaluated
h2 : Chebyshev I lter values at sample points
DESCRIPTION :
Square magnitude response of a type 1 Chebyshev lter.
omegac=passband edge.
epsilon : such that 1/(1+epsilon^2)=passband ripple.
sample: vector of frequencies where the square magnitude is desired.
Author : F. D.
Scilab Group April 1993 229
corr Scilab Function
7.0.468 Cheb2mag response of type 2 Chebyshev lter
CALLING SEQUENCE :
[h2]=cheb2mag(n,omegar,A,sample)

PARAMETERS :
n : integer ; lter order
omegar : real scalar : cut-o frequency
A : attenuation in stop band
sample : vector of frequencies where cheb2mag is evaluated
h2 : vector of Chebyshev II lter values at sample points
DESCRIPTION :
Square magnitude response of a type 2 Chebyshev lter.
omegar = stopband edge, sample = vector of frequencies where the square magnitude h2 is de-
sired.
Author : F. D.
7.0.469 chepol Chebychev polynomial
CALLING SEQUENCE :
[Tn]=chepol(n,var)

PARAMETERS :
n : integer : polynomial order
var : string : polynomial variable
Tn : polynomial in the variable var
DESCRIPTION :
Recursive implementation of Chebychev polynomial
Author : F. D.
7.0.470 convol convolution
CALLING SEQUENCE :
[y]=convol(h,x)
[y,e1]=convol(h,x,e0)

PARAMETERS :
x,h :input sequences (h is a "short" sequence, x a "long" one)
e0 : old tail to overlap add (not used in rst call)
y : output of convolution
e1 : new tail to overlap add (not used in last call)
DESCRIPTION :
calculates the convolution y= h*x of two discrete sequences by using the t. Overlap add method
can be used.
USE OF OVERLAP ADD METHOD: For x=[x1,x2,...,xNm1,xN]First call is [y1,e1]=convol(h,x1);
Subsequent calls : [yk,ek]=convol(h,xk,ekm1); Final call : [yN]=convol(h,xN,eNm1); Finally
y=[y1,y2,...,yNm1,yN]
See Also : corr, fft, pspec and polynomial product.
Author : F. D , C. Bunks Date 3 Oct. 1988
Scilab Group April 1993 230
cspect Scilab Function
7.0.471 corr correlation, covariance
CALLING SEQUENCE :
[cov,mean]=corr(x,[y],nlags)
[cov,mean]=corr('fft',xmacro,[ymacro],n,sect)

[w,xu]=corr('updt',x1,[y1],w0)
[w,xu]=corr('updt',x2,[y2],w,xu)
...
[wk]=corr('updt',xk,[yk],w,xu)

DESCRIPTION :
Computes
n,X
m,1
cov(m) = (xk , E(x))(yk , E(y))
0

for m=0,..,nlag-1 and two vectors x=[x(1),..,x(n)] y=[y(1),..,y(n)]

Note that if x and y sequences are dierents corr(x,y,...) is dierent with corr(y,x,...)
Short sequences
returns the rst nlags correlation coecients and mean =
[cov,mean]=corr(x,[y],nlags)
mean of (mean of
x if is an argument). The sequence x (resp. y) is assumed real, and x
[x,y] y
and are of same dimension n.
y
Long sequences
[cov,mean]=corr('fft',xmacro,[ymacro],n,sect)
Here xmacro is either
- a function of type [xx]=xmacro(sect,istart) which returns a vector xx of dimension nsect
containing the part of the sequence with indices from istart to istart+sect-1.
- a fortran subroutine which performs the same calculation. (See the source code of dgetx for
an example). n = total size of the sequence. sect = size of sections of the sequence. sect
must be a power of 2. cov has dimension sect. Calculation is performed by FFT.
"Updating method"
[w,xu]=corr('updt',x1,[y1],w0)
[w,xu]=corr('updt',x2,[y2],w,xu)
...
wk=corr('updt',xk,[yk],w,xu)

With this calling sequence the calculation is updated at each call to corr.
w0 = 0*ones(1,2*nlags);
nlags = power of 2.

x1,x2,... are parts of x such that x=[x1,x2,...] and sizes of xi a power of 2. To get nlags
coecients a nal t must be performed c=fft(w,1)/n; cov=c(1nlags) (n is the size of x (y)).
Caution: this calling sequence assumes that xmean = ymean = 0.
See Also : fft
7.0.472 cspect spectral estimation (periodogram method)
CALLING SEQUENCE :
[sm,cwp]=cspect(nlags,ntp,wtype,x,y,wpar)

PARAMETERS :
x : data if vector, amount of input data if scalar
Scilab Group April 1993 231
ell1mag Scilab Function
y : data if vector, amount of input data if scalar
nlags : number of correlation lags (positive integer)
ntp : number of transform points (positive integer)
wtype : string : 're','tr','hm','hn','kr','ch' (window type)
wpar : optional window parameters for wtype='kr', wpar>0 and for wtype='ch', 0 < wpar(1)
< .5, wpar(2) > 0
sm : power spectral estimate in the interval [0,1]
cwp : calculated value of unspecied Chebyshev window parameter

DESCRIPTION :
Spectral estimation using the modied periodogram method. Cross-spectral estimate of x and y
is calculated when both x and y are given. Auto-spectral estimate of x is calculated if y is not
given.
Author : C. Bunks

7.0.473 czt chirp z-transform algorithm

CALLING SEQUENCE :
[czx]=czt(x,m,w,phi,a,theta)

PARAMETERS :
x : input data sequence
m : czt is evaluated at m points in z-plane
w : magnitude multiplier
phi : phase increment
a : initial magnitude
theta : initial phase
czx : chirp z-transform output
DESCRIPTION :
chirp z-transform algorithm which calcultes the z-transform on a spiral in the z-plane at the points
[a*exp(j*theta)][w^kexp(j*k*phi)] for k=0,1,...,m-1.
Author : C. Bunks

7.0.474 dft discrete fourier transform

CALLING SEQUENCE :
[xf]=dft(x,flag);

PARAMETERS :
x : input vector
flag : indicates dft or idft
xf : output vector
DESCRIPTION :
Function which computes dft of vector x
See Also : fft
Author : C. B.
Scilab Group April 1993 232
faurre Scilab Function
7.0.475 ell1mag magnitude of elliptic lter
CALLING SEQUENCE :
[v]=ell1mag(eps,m1,z)

PARAMETERS :
eps : passband ripple=1/(1+eps^2)
m1 : stopband ripple=1/(1+(eps^2)/m1)
z : sample vector of values in the complex plane
v : elliptic lter values at sample points
DESCRIPTION :
Function used for squared magnitude of an elliptic lter. Usually m1=eps*eps/(a*a-1).

7.0.476 eqr minimax approximation of FIR lter

CALLING SEQUENCE :
[hn]=eqfir(nf,bedge,des,wate)

PARAMETERS :
nf : number of output lter points desired
bedge : Mx2 matrix giving a pair of edges for each band
des : M-vector giving desired magnitude for each band
wate : M-vector giving relative weight of error in each band
hn : output of linear-phase FIR lter coecients
DESCRIPTION :
Minimax approximation of multi-band, linear phase, FIR lter
Author : C. B.
7.0.477 eqiir Design of iir lters
CALLING SEQUENCE :
[cells,fact,zzeros,zpoles]=eqiir(ftype,approx,om,deltap,deltas)

PARAMETERS :
ftype : lter type ('lp','hp','sb','bp')
approx : design approximation ('butt','cheb1','cheb2','ellip')
om : 4-vector of cuto frequencies (in radians) om=[om1,om2,om3,om4], 0 <= om1 <= om2 <=
om3 <= om4 <= pi. When ftype=3 or 4, om3 and om4 are not used and may be set to 0.
deltap : ripple in the passband. 0<= deltap <=1
deltas : ripple in the stopband. 0<= deltas <=1
cells : realization of the lter as second order cells
fact : normalization constant
zzeros : zeros in the z-domain
zpoles : poles in the z-domain
DESCRIPTION :
Design of iir lter interface with eqiir (syredi)
The lter obtained is h(z)=fact*product of the elements of cells.
That is hz=fact*prod(cells(2))./prod(cells(3))
Scilab Group April 1993 233
FFT Scilab Function
7.0.478 faurre lter
CALLING SEQUENCE :
[Pn,Rt,T]=faurre(n,H,F,G,r0)

PARAMETERS :
n : number of iterations.
H, F, G : estimated triple from the covariance sequence of y.
r0 : E(yk*yk')
Pn : solution of the Riccati equation after n iterations.
Rt, T : gain matrix of the lter.
DESCRIPTION :
function which computes iteratively the minimal solution of the algebraic Riccati equation and
gives the matrices Rt and Tt of the lter model.
Author : G. Le V.
7.0.479 lt coecients of FIR low-pass
CALLING SEQUENCE :
[x]=ffilt(ft,n,fl,fh)

PARAMETERS :
ft : lter type where ft can take the values
"lp" : for low-pass lter
"hp" : for high-pass lter
"bp" : for band-pass lter
"sb" : for stop-band lter
n : integer (number of lter samples desired)
fl : real (low frequency cut-o)
fh : real (high frequency cut-o)
x : vector of lter coecients

DESCRIPTION :
Get n coecients of a FIR low-pass, high-pass, band-pass, or stop-band lter. For low and high-
pass lters one cut-o frequency must be specied whose value is given in fl. For band-pass and
stop-band lters two cut-o frequencies must be specied for which the lower value is in fl and
the higher value is in fh
Author : C. B.
7.0.480 t fast fourier transform.
CALLING SEQUENCE :
[x]=fft(a,-1)
[x]=fft(a,1)
x=fft(a,-1,dim,incr)
x=fft(a,1,dim,incr)

PARAMETERS :
x : real or complex vector. Real or complex matrix (2-dim t)
a : real or complex vector.
Scilab Group April 1993 234
nd freq Scilab Function
dim : integer
incr : integer
DESCRIPTION :
Short syntax (one or two dimensional t)
x=fft(a,-1) gives a direct transform (the -1 refers to the sign of the exponent..., NOT to
"inverse"), that is X
x(k) = a(m)exp(,2imk=n)
m
for k varying from 0 to n-1 (n=size of vector a).
(known bug fft(x,-1) for x of size 99 innite loop! add one or more zeros...)
a=fft(x,1) performs the inverse transform normalized by 1/n.
(fft(fft(.,-1),1) is identity).
When the rst argument given to fft is a matrix a two-dimensional FFT is performed.
Long syntax (multidimensional FFT) x=fft(a,-1,dim,incr) allows to perform an
multidimensional t.
If a is a real or complex vector implicitly indexed by x1,x2,..,xp i.e. a(x1,x2,..,xp) where x1
lies in 1..dim1, x2 in 1.. dim2,... one gets a p-dimensional FFT p by calling p times fft
as follows
a1=fft(a ,-1,dim1,incr1)
a2=fft(a1,-1,dim2,incr2) ...

where dimi is the dimension of the current variable w.r.t which one is integrating and incri is the
increment which separates two successive xi elements in a.
In particular,if a is an nxm matrix, x=fft(a,-1) is equivalent to the two instructions:
a1=fft(a,-1,m,1) and x=fft(a1,-1,n,m).
See Also : corr.
7.0.481 lter modelling lter
CALLING SEQUENCE :
[y,xt]=filter(n,F,H,Rt,T)

PARAMETERS :
n : number of computed points.
F, H : relevant matrices of the Markovian model.
Rt, T : gain matrices.
y : output of the lter.
xt : lter process.
DESCRIPTION :
This function computes the modelling lter
See Also : faurre
Author : G. Le V.
7.0.482 nd freq parameter compatibility for elliptic lter design
CALLING SEQUENCE :
[m]=find_freq(epsilon,A,n)

PARAMETERS :
epsilon : passband ripple
Scilab Group April 1993 235
fwiir Scilab Function
A : stopband attenuation
n : lter order
m : frequency needed for construction of elliptic lter
DESCRIPTION :
Search for m such that
n=K(1-m1)K(m)/(K(m1)K(1-m)) with
m1=(epsilon*epsilon)/(A*A-1) ;
Ifm = omegar^2/omegac^2 , the parameters
epsilon,A,omegac,omegar and n are then compat-
ible for dening a prototype elliptic lter.
Author : F. D.
7.0.483 ndm for elliptic lter design
CALLING SEQUENCE :
[m]=findm(chi)

DESCRIPTION :
Search for m such that chi = %k(1-m)/%k(m) (For use with find freq).
See Also : %K
Author : F. D.
7.0.484 frmag magnitude of FIR and IIR lters
CALLING SEQUENCE :
[xm,fr]=frmag(num[,den],npts)

PARAMETERS :
npts : integer (number of points in frequency response)
xm : mvector of magnitude of frequency response at the points fr
fr : points in the frequency domain where magnitude is evaluated
num : if den is omitted vector coecients/polynomial/rational polynomial of lter
num : if den is given vector coecients/polynomial of lter numerator
den : vector coecients/polynomial of lter denominator
DESCRIPTION :
calculates the magnitude of the frequency responses of FIR and IIR lters. The lter description
can be one or two vectors of coecients, one or two polynomials, or a rational polynomial.
Author : C. B.
7.0.485 fsrlin design of FIR, linear phase lters
CALLING SEQUENCE :
[hst]=fsfirlin(hd,flag)

PARAMETERS :
hd : vector of desired frequency response samples
flag : is equal to 1 or 2, according to the choice of type 1 or type 2 design
hst : vector giving the approximated continuous response on a dense grid of frequencies
DESCRIPTION :
function for the design of FIR, linear phase lters using the frequency sampling technique
Author : G. Le V.
Scilab Group April 1993 236
hank Scilab Function
7.0.486 fwiir IIR lters in cascade realization
CALLING SEQUENCE :
[maxer,gain,trfun]=fwiir(nbit1,nbit2,w,x,y,weight,nsect)

PARAMETERS :
nbit1 : desired number of bits for coding the lter coecients
nbit2 : initial search increment
w : grid of frequencies were the specications on the response are given. They must be given in
normalized frequency (i.e. in [0-0.5])
x : initial "innite precision" coecients.
y : desired magnitude response at the specied grid of frequency (must be equal to zero or one
in the present function)
weight : weighting in each specied frequency for the error criterion
nsect : number of second order sections. maxer : maximum error on the frequency response.
gain : gain of the nite precision lter.
trfun : transfer function of the nite precision lter in second order sections cascade form.

DESCRIPTION :
function for the optimum design of IIR lters in cascade realization, with prescribed number of
bits.
7.0.487 group group delay for digital lter
CALLING SEQUENCE :
[tg,fr]=group(npts,a1i,a2i,b1i,b2i)

PARAMETERS :
npts : integer : number of points desired in calculation of group delay
a1i : in coecient, polynomial, rational polynomial, or cascade polynomial form this variable is
the transfer function of the lter. In coecient polynomial form this is a vector of coecients
(see below).
a2i : in coe poly form this is a vector of coes
b1i : in coe poly form this is a vector of coes
b2i : in coe poly form this is a vector of coes
tg : values of group delay evaluated on the grid fr
fr : grid of frequency values where group delay is evaluated

DESCRIPTION :
Calculate the group delay of a digital lter with transfer function h(z).
The lter specication can be in coecient form, polynomial form, rational polynomial form,
cascade polynomial form, or in coecient polynomial form.
In the coecient polynomial form the tranfer function is formulated by the following expression
h(z)=prod(a1i+a2i*z+z**2)/prod(b1i+b2i*z+z**2)
Author : C. B.
7.0.488 hank hankel matrix
CALLING SEQUENCE :
[hk]=hank(m,n,cov)

PARAMETERS :
Scilab Group April 1993 237
iirgroup Scilab Function
m : number of bloc-rows
n : number of bloc-columns
cov : sequence of covariances; it must be given as :[R0 R1 R2...Rk]
hk : computed hankel matrix
DESCRIPTION :
this function builds the hankel matrix of size (m*d,n*d) from the covariance sequence of a vector
process
Author : G. Le V.

7.0.489 hilb Hilbert transform

CALLING SEQUENCE :
[xh]=hilb(n[,wtype][,par])

PARAMETERS :
n : odd integer : number of points in lter
wtype : string : window type ('re','tr','hn','hm','kr','ch') (default ='re')
par : window parameter for wtype='kr' or 'ch' default par=[0 0] see the function window
for more help
xh : Hilbert transform

DESCRIPTION :
returns the rst n points of the Hilbert transform centered around the origin.
That is, xh=(2/(n*pi))*(sin(n*pi/2))^2.
Author : C. B.

7.0.490 iir iir digital lter

CALLING SEQUENCE :
[hz]=iir(n,ftype,fdesign,frq,delta)

PARAMETERS :
n : lter order (pos. integer)
ftype : string specifying the lter type 'lp','hp','bp','sb'
fdesign : string specifying the analog lter design ='butt','cheb1','cheb2','ellip'
frq : 2-vector of discrete cut-o frequencies (i.e., 0<frq<.5). For lp and hp lters only frq(1)
is used. For bp and sb lters frq(1) is the lower cut-o frequency and frq(2) is the upper
cut-o frequency
delta : 2-vector of error values for cheb1, cheb2, and ellip lters where only delta(1) is
used for cheb1 case, only delta(2) is used for cheb2 case, and delta(1) and delta(2)
are both used for ellip case. 0<delta(1),delta(2)<1
- for cheb1 lters 1-delta(1)<ripple<1 in passband
- for cheb2 lters 0<ripple<delta(2) in stopband
- for ellip lters 1-delta(1)<ripple<1 in passband and 0<ripple<delta(2) in stop-
band
DESCRIPTION :
function which designs an iir digital lter using analog lter designs.
Author : C. B.
Scilab Group April 1993 238
jmat Scilab Function
7.0.491 iirgroup group delay Lp IIR lter optimization
CALLING SEQUENCE :
[lt,grad]=iirgroup(p,r,theta,omega,wt,td)
[cout,grad,ind]=iirlp(x,ind,p,[flag],lambda,omega,ad,wa,td,wt)

PARAMETERS :
r : vector of the module of the poles and the zeros of the lters
theta : vector of the argument of the poles and the zeros of the lters
omega : frequencies where the lter specications are given
wt : weighting function for and the group delay
td : desired group delay
lt, grad : criterium and gradient values
DESCRIPTION :
optimization of IIR lters for the Lp criterium for the the group delay. (Rabiner & Gold pp270-
273).

7.0.492 iirlp Lp IIR lter optimization

CALLING SEQUENCE :
[cost,grad,ind]=iirlp(x,ind,p,[flag],lambda,omega,ad,wa,td,wt)

PARAMETERS :
x : 1X2 vector of the module and argument of the poles and the zeros of the lters
flag : string : 'a' for amplitude, 'gd' for group delay; default case for amplitude and group
delay.
omega : frequencies where the lter specications are given
wa,wt : weighting functions for the amplitude and the group delay
lambda : weighting (with 1-lambda) of the costs ('a' and 'gd' for getting the global cost.
ad, td : desired amplitude and group delay
cost, grad : criterium and gradient values

DESCRIPTION :
optimization of IIR lters for the Lp criterium for the amplitude and/or the group delay. (Rabiner
& Gold pp270-273).
7.0.493 intdec Changes sampling rate of a signal
CALLING SEQUENCE :
[y]=intdec(x,lom)

PARAMETERS :
x : input sampled signal
lom : For a 1D signal this is a scalar which gives the rate change. For a 2D signal this is a
2-Vector of sampling rate changes lom=(col rate change,row rate change)
y : Output sampled signal
DESCRIPTION :
Changes the sampling rate of a 1D or 2D signal by the rates in lom
Author : C. B.
Scilab Group April 1993 239
lattn Scilab Function
7.0.494 jmat row or column block permutation
CALLING SEQUENCE :
[j]=jmat(n,m)

PARAMETERS :
n : number of block rows or block columns of the matrix
m : size of the (square) blocks
DESCRIPTION :
This function permutes block rows or block columns of a matrix

7.0.495 kalm Kalman update

CALLING SEQUENCE :
[x1,p1,x,p]=kalm(y,x0,p0,f,g,h,q,r)

PARAMETERS :
f,g,h : current system matrices
q, r : covariance matrices of dynamics and observation noise
x0,p0 : state estimate and error variance at t=0 based on data up to t=-1
y : current observation Output from the function is:
x1,p1 : updated estimate and error covariance at t=1 based on data up to t=0
x : updated estimate and error covariance at t=0 based on data up to t=0
DESCRIPTION :
function which gives the Kalman update and error variance
Author : C. B.

7.0.496 lattn recursive solution of normal equations

CALLING SEQUENCE :
[la,lb]=lattn(n,p,cov)

PARAMETERS :
n : maximum order of the lter
p : xed dimension of the MA part. If p= -1, the algorithm reduces to the classical Levinson
recursions.
cov : matrix containing the Rk's (d*d matrices for a d-dimensional process).It must be given the
following way 2 R0 3
66 R1 77
cov = 66 R.2 77
4 .. 5
Rnlag
la : list-type variable, giving the successively calculated polynomials (degree 1 to degree n),with
coecients Ak
Scilab Group April 1993 240
levin Scilab Function
DESCRIPTION :
solves recursively on n (p being xed) the following system (normal equations), i.e. identies the
AR part (poles) of a vector ARMA(n,p) process
0 Rp+1 Rp+2 : : : Rp+n 1
( I ,A1 ,A2 : : : ,An ) B
B Rp Rp+1 : : : Rp+n,1 C
@ ... .. C =0
. A
..
. :::
Rp+1,n Rp+2,n : : : Rp
where fRk;k=1,nlagg is the sequence of empirical covariances
Author : G. Le V.

7.0.497 lattp lattp

CALLING SEQUENCE :
[la,lb]=lattp(n,p,cov)

DESCRIPTION :
see lattn
Author : G.Levey

7.0.498 lev Yule-Walker equations (Levinson's algorithm)

CALLING SEQUENCE :
[ar,sigma2,rc]=lev(r)

PARAMETERS :
r : correlation coecients
ar : auto-Regressive model parameters
sigma2 : scale constant
rc : re ection coecients
DESCRIPTION :
resolve the Yule-Walker equations
0 r r1 : : : rN ,1 1
0 a 1 0 1
BB r
0
r0 : : : rN ,2 C BB a C
1

C BB 0 2
CC
1
@ .. C B .. A B
C
2
= CA
: : : .. A @
.. . @ ...
. . .
rN ,1 rN ,2 : : : r0 aN ,1 0
using Levinson's algorithm.
Author : C. B.

7.0.499 levin Toeplitz system solver

CALLING SEQUENCE :
[la,sig,lb]=levin(n,cov)

PARAMETERS :
n : maximum order of the lter
Scilab Group April 1993 241
mese Scilab Function
cov : matrix containing the Rk(d x d matrices for a d-dimensional process). It must be given
the following way : 0 R 1
BB R01 CC
BB R2 CC
B@ .. CA
.
Rnlag
la : list-type variable, giving the successively calculated polynomials (degree 1 to degree n), with
coecients Ak
sig : list-type variable, giving the successive mean-square errors.

DESCRIPTION :
function which solves recursively on n the following Toeplitz system (normal equations)
0 R1 R2 : : : Rn 1
B R0 R1 : : : Rn,1 C
, I , A : : : , A
BBB R,1 R0 : : : Rn,2 CCC = 0
n B ..
. : : : .. C
.. .
1
B@ . C
R2,n R3,n : : : R1 A
R1,n R2,n : : : R0
where fRk;k=1,nlagg is the sequence of nlag empirical covariances
Author : G. Le V.
7.0.500 lgt utility for t
CALLING SEQUENCE :
[y]=lgfft(x)

PARAMETERS :
x : real or complex vector
DESCRIPTION :
returns the lowest power of 2 larger than size(x) (for FFT use).
7.0.501 lindquist Lindquist's algorithm
CALLING SEQUENCE :
[Pn,Rt,T]=lindquist(n,H,F,G,r0)

PARAMETERS :
n : number of iterations.
H, F, G : estimated triple from the covariance sequence of y.
r0 : E(yk*yk')
Pn : solution of the Riccati equation after n iterations.
RtP Tt : gain matrices of the lter.
DESCRIPTION :
computes iteratively the minimal solution of the algebraic Riccati equation and gives the matrices
Rtand Tt of the lter model, by the Lindquist's algorithm.
Author : G. Le V.
Scilab Group April 1993 242
pspect Scilab Function
7.0.502 mese maximum entropy spectral estimation
CALLING SEQUENCE :
[sm,fr]=mese(x [,npts]);
PARAMETERS :
x : Input sampled data sequence
npts : Optional parameter giving number of points of fr and sm (default is 256)
sm : Samples of spectral estimate on the frequency grid fr
fr : npts equally spaced frequency samples in [0,.5)
DESCRIPTION :
Calculate the maximum entropy spectral estimate of x
Author : C. B.
7.0.503 mt multi-dimensional t
CALLING SEQUENCE :
[xk]=mfft(x,flag,dim)
PARAMETERS :
x : x(i,j,k,...) input signal in the form of a row vector whose values are arranged so that
the i index runs the quickest, followed by the j index, etc.
flag : (-1) FFT or (1) inverse FFT
dim : dimension vector which gives the number of values of x for each of its indices
xk : output of multidimensional t in same format as for x
DESCRIPTION :
FFT for a multi-dimensional signal
For example for a three dimensional vector which has three points along its rst dimension,
two points along its second dimension and three points along its third dimension the row vector is
arranged as follows
x=[x(1,1,1),x(2,1,1),x(3,1,1),
x(1,2,1),x(2,2,1),x(3,2,1),
x(1,1,2),x(2,1,2),x(3,1,2),
x(1,2,2),x(2,2,2),x(3,2,2),
x(1,1,3),x(2,1,3),x(3,1,3),
x(1,2,3),x(2,2,3),x(3,2,3)]
and the dim vector is: dim=[3,2,3]
Author : C. B.
7.0.504 phc from the hankel matrix to state-space model
CALLING SEQUENCE :
[H,F,G]=phc(hk,d,r)
PARAMETERS :
hk : hankel matrix
d : dimension of the observation
r : desired dimension of the state vector for the approximated model
H, F, G : relevant matrices of the state-space model
DESCRIPTION :
function which computes the matrices H, F, G by the principal hankel component approximation
method, from the hankel matrix built from the covariance sequence of a stochastic process.
Author : G. Le V.
Scilab Group April 1993 243
remezb Scilab Function
7.0.505 pspect cross-spectral estimate between 2 series
CALLING SEQUENCE :
[sm,cwp]=pspect(sec_step,sec_leng,wtype,x,y,wpar)

PARAMETERS :
x : data if vector, amount of input data if scalar
y : data if vector, amount of input data if scalar
sec step : oset of each data window
sec leng : length of each data window
wtype : window type (re,tr,hm,hn,kr,ch)
wpar : optional parameters for wtype='kr', wpar>0 for wtype='ch', 0<wpar(1)<.5, wpar(2) 0 >
sm : power spectral estimate in the interval [0,1]
cwp : unspecied Chebyshev window parameter
DESCRIPTION :
Cross-spectral estimate between x and y if both are given and auto-spectral estimate of x oth-
erwise. Spectral estimate obtained using the modied periodogram method
Author : C. B.
7.0.506 remez Remez's algorithm
CALLING SEQUENCE :
[an]=remez(nc,fg,ds,wt)

PARAMETERS :
nc : integer, number of cosine functions
fg,ds,wt : real vectors
fg : grid of frequency points in [0,.5)
ds : desired magnitude on grid fg
wt : weighting function on error on grid fg
DESCRIPTION :
minimax approximation of a frequency domain magnitude response. The approximation takes the
form
h = sum[a(n)*cos(wn)]

for n=0,1,...,nc. An FIR, linear-phase lter can be obtained from the the output of remez by using
the following commands:
hn(1nc-1)=an(nc-12)/2;
hn(nc)=an(1);
hn(nc+12*nc-1)=an(2nc)/2;

where an = cosine lter coecients

7.0.507 remezb Minimax approximation of magnitude response
CALLING SEQUENCE :
[an]=remezb(nc,fg,ds,wt)

PARAMETERS :
nc : Number of cosine functions
Scilab Group April 1993 244
rpem Scilab Function
fg : Grid of frequency points in [0,.5)
ds : Desired magnitude on grid fg
wt : Weighting function on error on grid fg
an : Cosine lter coecients
DESCRIPTION :
Minimax approximation of a frequency domain magnitude response. The approximation takes the
form h = sum[a(n)*cos(wn)] for n=0,1,...,nc. An FIR, linear-phase lter can be obtained from
the the output of the function by using the following commands
hn(1:nc-1)=an(nc:-1:2)/2;
hn(nc)=an(1);
hn(nc+1:2*nc-1)=an(2:nc)/2;

Author : C. B.
7.0.508 rpem RPEM estimation
CALLING SEQUENCE :
[w1,[v]]=rpem(w0,u0,y0,[lambda,[k,[c]]])

PARAMETERS :
:
a,b,c a=[a(1),...,a(n)], b=[b(1),...,b(n)], c=[c(1),...,c(n)]
:
w0 list(theta,p,phi,psi,l) where:
theta : [a,b,c] is a real vector of order 3*n
p : (3*n x 3*n) real matrix.
phi,psi,l : real vector of dimension 3*n

During the rst call on can take:

theta=phi=psi=l=0*ones(1,3*n). p=eye(3*n,3*n)

u0 : real vector of inputs (arbitrary size) (if no input take u0=[ ]).
y0 : vector of outputs (same dimension as u0 if u0 is not empty). (y0(1) is not used by rpem).
If the time domain is (t0,t0+k-1) the u0 vector contains the inputs
u(t0),u(t0+1),..,u(t0+k-1) and y0 the outputs
y(t0),y(t0+1),..,y(t0+k-1)
DESCRIPTION :
Recursive estimation of parameters in an ARMAX model. Uses Ljung-Soderstrom recursive
prediction error method. Model considered is the following:
y(t)+a(1)*y(t-1)+...+a(n)*y(t-n)=
b(1)*u(t-1)+...+b(n)*u(t-n)+e(t)+c(1)*e(t-1)+...+c(n)*e(t-n)

The eect of this command is to update the estimation of unknown parameter theta=[a,b,c]
with
a=[a(1),...,a(n)], b=[b(1),...,b(n)], c=[c(1),...,c(n)].
OPTIONAL PARAMETERS :
lambda : optional parameter (forgetting constant) choosed close to 1 as convergence occur:
lambda=[lambda0,alfa,beta] evolves according to :

lambda(t)=alfa*lambda(t-1)+beta

Scilab Group April 1993 245

srfaur Scilab Function
with lambda(0)=lambda0
k : contraction factor to be chosen close to 1 as convergence occurs.
k=[k0,mu,nu] evolves according to:

k(t)=mu*k(t-1)+nu

with k(0)=k0.
c : large parameter.(c=1000 is the default value).
OUTPUT PARAMETERS: :
w1 : update for w0.
v : sum of squared prediction errors on u0, y0.(optional).
In particular w1(1) is the new estimate of theta. If a new sample u1, y1 is available the update
is obtained by:
[w2,[v]]=rpem(w1,u1,y1,[lambda,[k,[c]]]). Arbitrary large series can thus be treated.

7.0.509 sinc samples of sinc function

CALLING SEQUENCE :
[x]=sinc(n,fl)

PARAMETERS :
n : number of samples
fl : cut-o frequency of the associated low-pass lter in Hertz.
x : samples of the sinc function
DESCRIPTION :
Calculate n samples of the function sin(2*pi*fl*t)/(pi*t) for t=-n/2:n/2 (i.e. centered
around the origin).
See Also : sincd
Author : C. B.

7.0.510 sincd sinc function

CALLING SEQUENCE :
[s]=sincd(n,flag)

PARAMETERS :
n : integer
flag : if flag = 1 the function is centered around the origin; if flag = 2 the function is delayed
by %pi/(2*n)
s : vector of values of the function on a dense grid of frequencies
DESCRIPTION :
function which calculates the function Sin(N*x)/Sin(x)
Author : G. Le V.
Scilab Group April 1993 246
system Scilab Function
7.0.511 srfaur square-root algorithm
CALLING SEQUENCE :
[p,s,t,l,rt,tt]=srfaur(h,f,g,r0,n,p,s,t,l)

PARAMETERS :
h, f, g : convenient matrices of the state-space model.
r0 : E(yk*yk').
n : number of iterations.
p : estimate of the solution after n iterations.
s, t, l : intermediate matrices for successive iterations;
rt, tt : gain matrices of the lter model after n iterations.
p, s, t, l : may be given as input if more than one recursion is desired (evaluation of inter-
mediate values of p).
DESCRIPTION :
square-root algorithm for the algebraic Riccati equation.
7.0.512 srkf square root Kalman lter
CALLING SEQUENCE :
[x1,p1]=srkf(y,x0,p0,f,h,q,r)

PARAMETERS :
f, h : current system matrices
q, r : covariance matrices of dynamics and observation noise
x0, p0 : state estimate and error variance at t=0 based on data up to t=-1
y : current observation Output from the function is
x1, p1 : updated estimate and error covariance at t=1 based on data up to t=0
DESCRIPTION :
square root Kalman lter algorithm
Author : C. B.
7.0.513 sskf steady-state Kalman lter
CALLING SEQUENCE :
[xe,pe]=sskf(y,f,h,q,r,x0)

PARAMETERS :
y : data in form [y0,y1,...,yn], yk a column vector
f : system matrix dim(NxN)
h : observations matrix dim(NxM)
q : dynamics noise matrix dim(NxN)
r : observations noise matrix dim(MxM)
xe : estimated state
pe : steady-state error covariance
DESCRIPTION :
steady-state kalman lter
Author : C. B.
Scilab Group April 1993 247
wr Scilab Function
7.0.514 system observation update
CALLING SEQUENCE :
[x1,y]=system(x0,f,g,h,q,r)

PARAMETERS :
x0 : input state vector
f : system matrix
g : input matrix
h : Output matrix
q : input noise covariance matrix
r : output noise covariance matrix
x1 : output state vector
y : output observation
DESCRIPTION :
dene system function which generates the next observation given the old state. System recursively
calculated
x1=f*x0+g*u
y=h*x0+v

where u is distributed N(0,q) and v is distribute N(0,r).

Author : C. B.
7.0.515 trans low-pass to other lter transform
CALLING SEQUENCE :
hzt=trans(pd,zd,gd,tr_type,frq)

PARAMETERS :
hz : input polynomial
tr type : type of transformation
frq : frequency values
hzt : output polynomial
DESCRIPTION :
function for transforming standardized low-pass lter into one of the following lters: low-pass,
high-pass, band-pass, stop-band.
Author : C. Bunks
7.0.516 wr linear-phase FIR lters
CALLING SEQUENCE :
[wft,wfm,fr]=wfir(ftype,forder,cfreq,wtype,fpar)

PARAMETERS :
ftype : string :
'lp','hp','bp','sb' (lter type)
forder : Filter order (pos integer)(odd for
ftype='hp' 'sb' or )
cfreq : 2-vector of cuto frequencies ( <
0 cfreq(1),cfreq(2) .5 < ) only cfreq(1) is used when
ftype='lp' or
'hp'
wtype : Window type (
're','tr','hm','hn','kr','ch' )
Scilab Group April 1993 248
window Scilab Function
fpar : 2-vector of window parameters. Kaiser window fpar(1)>0 fpar(2)=0. Chebyshev win-
dow fpar(1)>0, fpar(2)<0 or fpar(1)<0, 0<fpar(2)<.5
wft : time domain lter coecients
wfm : frequency domain lter response on the grid fr
fr : Frequency grid

DESCRIPTION :
Function which makes linear-phase, FIR low-pass, band-pass, high-pass, and stop-band lters
using the windowing technique. Works interactively if called with no arguments.
Author : C. Bunks

7.0.517 wiener Wiener estimate

CALLING SEQUENCE :
[xs,ps,xf,pf]=wiener(y,x0,p0,f,g,h,q,r)

PARAMETERS :
f, g, h : system matrices in the interval [t0,tf]
f =[f0,f1,...,ff], and fk is a nxn matrix
g =[g0,g1,...,gf], and gk is a nxn matrix
h =[h0,h1,...,hf], and hk is a mxn matrix
q, r : covariance matrices of dynamics and observation noise

q =[q0,q1,...,qf], and qk is a nxn matrix

r =[r0,r1,...,rf], and gk is a mxm matrix
x0, p0 : initial state estimate and error variance
y : observations in the interval [t0,tf]. y=[y0,y1,...,yf], and yk is a column m-vector
xs : Smoothed state estimate xs= [xs0,xs1,...,xsf], and xsk is a column n-vector
ps : Error covariance of smoothed estimate ps=[p0,p1,...,pf], and pk is a nxn matrix
xf : Filtered state estimate xf= [xf0,xf1,...,xff], and xfk is a column n-vector
pf : Error covariance of ltered estimate pf=[p0,p1,...,pf], and pk is a nxn matrix

DESCRIPTION :
function which gives the Wiener estimate using the forward-backward Kalman lter formulation
Author : C. B.

7.0.518 wigner 'time-frequency' wigner spectrum

CALLING SEQUENCE :
[tab]=wigner(x,h,deltat,zp)

PARAMETERS :
tab : wigner spectrum (lines correspond to the time variable)
x : analyzed signal
h : data window
deltat : analysis time increment (in samples)
zp : length of FFT's. %pi/zp gives the frequency increment.
DESCRIPTION :
function which computes the 'time-frequency' wigner spectrum of a signal.
Scilab Group April 1993 249
zpbutt Scilab Function
7.0.519 window symmetric window
CALLING SEQUENCE :
[win_l,cwp]=window(wtype,n,par)

PARAMETERS :
wtype : window type (re,tr,hn,hm,kr,ch)
n : window length
par : parameter 2-vector (kaiser window: par(1)=beta>0) (Chebychev window par =[dp,df]) ,
dp =main lobe width (0<dp<.5), df=side lobe height (df>0)
win : window
cwp : unspecied Chebyshev window parameter
DESCRIPTION :
function which calculates symmetric window
Author : C. B.
7.0.520 yulewalk least-square lter design
CALLING SEQUENCE :
Hz = yulewalk(N,frq,mag)

PARAMETERS :
N : integer (order of derired lter)
frq : real row vector (non-decreasing order), frequencies.
mag : non negative real row vector (same size as frq), desired magnitudes.
Hz : lter B(z)/A(z)
DESCRIPTION :
Hz = yulewalk(N,frq,mag) nds the N-th order iir lter
n-1 n-2
B(z) b(1)z + b(2)z + .... + b(n)
H(z)= ---- = ---------------------------------
n-1 n-2
A(z) z + a(1)z + .... + a(n)

which matches the magnitude frequency response given by vectors frq and mag. Vectors frq and
mag specify the frequency and magnitude of the desired frequency response. The frequencies in
frq must be between 0.0 and 1.0, with 1.0 corresponding to half the sample rate. They must be in
increasing order and start with 0.0 and end with 1.0.
EXAMPLE :
// f=[0,0.4,0.4,0.6,0.6,1];H=[0,0,1,1,0,0];Hz=yulewalk(8,f,H);//fs=1000;fhz = f*fs/2; //xbasc(0);xset('window',0);plo
//xtitle('Desired Frequency Response (Magnitude)') //[frq,repf]=repfreq(Hz,0:0.001:0.5); //xbasc(1);xset('window',1
//xtitle('Obtained Frequency Response (Magnitude)')
7.0.521 zpbutt Butterworth analog lter
CALLING SEQUENCE :
[pols,gain]=zpbutt(n,omegac)

PARAMETERS :
n : integer (lter order)
Scilab Group April 1993 250
zpell Scilab Function
omegac : real (cut-o frequency in Hertz)
pols : resulting poles of lter
gain : resulting gain of lter
DESCRIPTION :
computes the poles of a Butterworth analog lter of order n and cuto frequency omegac transfer
function H(s) is calculated by H(s) = gain/real(poly(pols,'s'))
Author : F.D.

7.0.522 zpch1 Chebyshev analog lter

CALLING SEQUENCE :
[poles,gain]=zpch1(n,epsilon,omegac)

PARSMETERS :
n : integer (lter order)
epsilon : real : ripple in the pass band (0<epsilon<1)
omegac : real : cut-o frequency in Hertz
poles : resulting lter poles
gain : resulting lter gain
DESCRIPTION :
Poles of a Type 1 Chebyshev analog lter. The transfer function is given by :
H(s)=gain/poly(poles,'s')

Author : F.D.

7.0.523 zpch2 Chebyshev analog lter

CALLING SEQUENCE :
[zeros,poles,gain]=zpch2(n,A,omegar)

PARAMETERS :
n : integer : lter order
A : real : attenuation in stop band (A>1)
omegar : real : cut-o frequency in Hertz
zeros : resulting lter zeros
poles : resulting lter poles
gain : Resulting lter gain
DESCRIPTION :
Poles and zeros of a type 2 Chebyshev analog lter gain is the gain of the lter
H(s)=gain*poly(zeros,'s')/poly(poles,'s')

Author : F.D.
Scilab Group April 1993 251
zpell Scilab Function
7.0.524 zpell lowpass elliptic lter
CALLING SEQUENCE :
[zeros,poles,gain]=zpell(epsilon,A,omegac,omegar)

PARAMETERS :
epsilon : real : ripple of lter in pass band (0<epsilon<1)
A : real : attenuation of lter in stop band (A>1)
omegac : real : pass band cut-o frequency in Hertz
omegar : real : stop band cut-o frequency in Hertz
zeros : resulting zeros of lter
poles : resulting poles of lter
gain : resulting gain of lter
DESCRIPTION :
Poles and zeros of prototype lowpass elliptic lter. gain is the gain of the lter
Author : F.D.

Scilab Group April 1993 252

armap Scilab Function
7.0.525 arma Scilab arma library
DESCRIPTION :
armac : this function creates a description as a list of an ARMAX process A(z^-1)y= B(z^-1)u
+ D(z^-1)sig*e(t)
armap : Display in the le out or on the screen the armax equation associated with ar
armax : is used to identify the coecients of a n-dimensional ARX process A(z^-1)y= B(z^-1)u
+ sig*e(t)
armax1 : armax1 is used to identify the coecients of a 1-dimensional ARX process A(z^-1)y=
B(z^-1)u + D(z^-1)sig*e(t)
arsimul : armax trajectory simulation
arspec : Spectral power estimation of armax processes. Test of mese and arsimul
exar1 : An Example of ARMAX identication ( K.J. Astrom) The armax process is described
by : a=[1,-2.851,2.717,-0.865] b=[0,1,1,1] d=[1,0.7,0.2]
exar2 : ARMAX example ( K.J. Astrom). A simulation of a bi dimensional version of the
example of exar1.
exar3 : Spectral power estimation of arma processes from Sawaragi et all where a value of
m=18 is used. Test of mese and arsimul
gbruit : noise generation
narsimul : armax simulation ( using rtitr)
odedi : Simple tests of ode and arsimul. Tests the option 'discret' of ode
prbs a : pseudo random binary sequences generation
reglin : Linear regression

Author : J.P.C
7.0.526 armac Scilab description of an armax process
CALLING SEQUENCE :
[ar]=armac(a,b,d,ny,nu,sig)

PARAMETERS :
a=[Id,a1,..,a r] : is a matrix of size (ny,r*ny)
b=[b0,.....,b s] : is a matrix of size (ny,(s+1)*nu)
d=[Id,d1,..,d p] : is a matrix of size (ny,p*ny);
ny : dimension of the output y
nu : dimension of the output u
sig : a matrix of size (ny,ny)
DESCRIPTION :
this function creates a description as a list of an ARMAX process
A(z ,1 )y = B(z ,1 )u + D(z ,1 )sig  e(t)

EXAMPLE :
a=[1,-2.851,2.717,-0.865].*.eye(2,2)
b=[0,1,1,1].*.[1;1];
d=[1,0.7,0.2].*.eye(2,2);
sig=eye(2,2);
ar=armac(a,b,d,2,1,sig);
armap(ar);

See Also : armap

Scilab Group April 1993 253

armax1 Scilab Function
7.0.527 armap display of armax equations
CALLING SEQUENCE :
[]=armap(ar,[out])

PARAMETERS :
ar : a list describing an arma process.
out : a le name
DESCRIPTION :
Display in the le out or on the screen the armax equation associated with ar. ar is created with
armac
See Also : armac
7.0.528 armax armax identication
CALLING SEQUENCE :
[la,lb,sig,resid]=armax(r,s,y,u,[b0f,prf])

PARAMETERS :
y : output process y(ny,n); ( ny: dimension of y , n : sample size)
u : input process u(nu,n); ( nu: dimension of u , n : sample size)
r and s : auto-regression orders r >=0 et s >=-1
b0f : optional parameter. Its default value is 0 and it means that the coecient b0 must be
identied. if bof=1 the b0 is supposed to be zero and is not identied
prf : optional parameter for display control. If prf =1, the default value, a display of the
identied Arma is given.
la : is the list(a,a+eta,a-eta) ( la = a in dimension 1) ; where eta is the estimated standard
deviation. , a=[Id,a1,a2,...,ar] where each ai is a matrix of size (ny,ny)
lb : is the list(b,b+etb,b-etb) (lb =b in dimension 1) ; where etb is the estimated standard
deviation. b=[b0,.....,b s] where each bi is a matrix of size (nu,nu)
sig : is the estimated standard deviation of the noise and resid=[ sig*e(t0),....] (

DESCRIPTION :
armax is used to identify the coecients of a n-dimensional ARX process
A(z^-1)y= B(z^-1)u + sig*e(t)

where e(t) is a n-dimensional white noise with variance I. sig an nxn matrix and A(z) and B(z):
A(z) = 1+a1*z+...+a_r*z^r; ( r=0 => A(z)=1)
B(z) = b0+b1*z+...+b_s z^s ( s=-1 => B(z)=0)

for the method see Eykho in trends and progress in system identication, page 96. with z(t)=[y(t-
1),..,y(t-r),u(t),...,u(t-s)] and coef= [-a1,..,-ar,b0,...,b s] we can write y(t)= coef* z(t) + sig*e(t)
and the algorithm minimises sum ft=1g^N ( [y(t)- coef'z(t)]^2) where t0=maxi(maxi(r,s)+1,1))).
EXAMPLE :
[a,b,sig,resid]=armax(); // will gives an example in dimension 1

Author : J-Ph. Chancelier.

See Also : imrep2ss , time_id , arl2 , armax , frep2tf

Scilab Group April 1993 254

arsimul Scilab Function
7.0.529 armax1 armax identication
CALLING SEQUENCE :
[a,b,d,sig,resid]=armax1(r,s,q,y,u,[b0f])

PARAMETERS :
y : output signal
u : input signal
r,s,q : auto regression orders with r >=0, s >=-1.
b0f : optional parameter. Its default value is 0 and it means that the coecient b0 must be
identied. if bof=1 the b0 is supposed to be zero and is not identied
a : is the vector [1,a1,...,a r]
b : is the vector [b0,......,b s]
d : is the vector [1,d1,....,d q]
sig : resid=[ sig*echap(1),....,];

DESCRIPTION :
armax1 is used to identify the coecients of a 1-dimensional ARX process:
A(z^-1)y= B(z^-1)u + D(z^-1)sig*e(t)
e(t) is a 1-dimensional white noise with variance 1.
A(z)= 1+a1*z+...+a_r*z^r; ( r=0 => A(z)=1)
B(z)= b0+b1*z+...+b_s z^s ( s=-1 => B(z)=0)
D(z)= 1+d1*z+...+d_q*z^q ( q=0 => D(z)=1)

for the method, see Eykho in trends and progress in system identication) page 96. with z(t)=[y(t-
1),..,y(t-r),u(t),..., u(t-s),e(t-1),...,e(t-q)] and coef= [-a1,..,-ar,b0,...,b s,d1,...,d q]' y(t)= coef'* z(t)
+ sig*e(t).
a sequential version of the AR estimation where e(t-i) is replaced by an estimated value is used
(RLLS). With q=0 this method is exactly a sequential version of armax
Author : J.-Ph.C
7.0.530 arsimul armax simulation
CALLING SEQUENCE :
[z]=arsimul(a,b,d,sig,u,[up,yp,ep])
[z]=arsimul(ar,u,[up,yp,ep])

PARAMETERS :
ar : an armax process. See armac.
a : is the matrix[Id,a1,...,a r] of dimension (n,(r+1)*n)
b : is the matrix[b0,......,b s] of dimension (n,(s+1)*m)
d : is the matrix[Id,d 1,......,d t] of dimension (n,(t+1)*n)
u : is a matrix (m,N), which gives the entry u(:,j)=u j
sig : is a (n,n) matrix e fkg is an n-dimensional Gaussian process with variance I
up, yp : optional parameter which describe the past. up=[ u 0,u f-1g,...,u fs-1g]; yp=[ y 0,y f-
1g,...,y fr-1g]; ep=[ e 0,e f-1g,...,e fr-1g]; if they are omitted, the past value are supposed to
be zero
z : z=[ y(1),....,y(N)]
DESCRIPTION :
simulation of an n-dimensional armax process A(z^-1) z(k)= B(z^-1)u(k) + D(z^-1)*sig*e(k)
A(z)= Id+a1*z+...+a r*z^r; ( r=0 => A(z)=Id) B(z)= b0+b1*z+...+b s z^s; ( s=-1 =>
B(z)=0) D(z)= Id+d1*z+...+d t z^t; ( t=0 => D(z)=Id)
Scilab Group April 1993 255
gbruit Scilab Function
z et e are in R^n et u in R^m
METHOD :
a state-space representation is constructed and ode with the option "discret" is used to compute
z
Author : J-Ph.C.

7.0.531 arspec Spectral power estimation

CALLING SEQUENCE :
[]=arspec(z)

DESCRIPTION :
Spectral power estimation of armax processes. Test of mese and arsimul

7.0.532 exar1 armax identication example

CALLING SEQUENCE :
[z,zd,u,ar]=exar1()

PARAMETERS :
z : output without noise.
zd : output with noise
u : entry ( PRBS)
ar : the armax description ( see armac)
DESCRIPTION :
An Example of ARMAX identication ( K.J. Astrom) The armax process is described by : a=[1,-
2.851,2.717,-0.865] b=[0,1,1,1] d=[1,0.7,0.2] and the entry is a pseudo random binary signal. a
sample of the processed is generated and used to identify the parameters using armax. Since in
this example the noise is a coloured noise armax will give biased estimators
See Also : armac
7.0.533 exar2 armax identication example
CALLING SEQUENCE :
[z,zd,u,ar]=exar2()

DESCRIPTION :
ARMAX example ( K.J. Astrom). A simulation of a bi dimensional version of the example of
exar1.
See Also : exar1
7.0.534 exar3 armax identication example
CALLING SEQUENCE :
[]=exar3(m)

DESCRIPTION :
Spectral power estimation of arma processes from Sawaragi et all where a value of m=18 is used.
Test of mese and arsimul
Scilab Group April 1993 256
reglin Scilab Function
7.0.535 gbruit noise generation
CALLING SEQUENCE :
[]=gbruit(pas,Tmax,sig)

DESCRIPTION :
generates a Scilab macro [b]=bruit(t) where bruit(t) is a piecewise constant function ( con-
stant on [k*pas,(k+1)*pas] ). The value on each constant interval are random values from i.i.d
Gaussian variables of standard deviation sig. The function is constant for t<=0 and t>=Tmax.

7.0.536 narsimul armax simulation ( using rtitr)

CALLING SEQUENCE :
[z]=narsimul(a,b,d,sig,u,[up,yp,ep])
[z]=narsimul(ar,u,[up,yp,ep])

DESCRIPTION :
ARMAX simulation. Same as arsimul but the method is dierent the simulation is made with
rtitr
Author : J-Ph. Chancelier ENPC Cergrene

7.0.537 odedi test of ode

CALLING SEQUENCE :
[]=odedi()

DESCRIPTION :
Simple tests of ode and arsimul. Tests the option 'discret' of ode

7.0.538 prbs a pseudo random binary sequences generation

CALLING SEQUENCE :
[u]=prbs_a(n,nc,[ids])

DESCRIPTION :
generation of pseudo random binary sequences u=[u0,u1,...,u (n-1)]; u takes values in f-1,1g
and changes at most nc times its sign. ids can be used to x the date at which u must change its
sign ids is then an integer vector with values in [1:n].

7.0.539 reglin Linear regression

CALLING SEQUENCE :
[a,b,sig,]=reglin(x,y,[disp])

DESCRIPTION :
solve the regression problem y=a*x+ b in the least square sense. sig is the standard deviation
of the residual. x yand are two matrices of size x(p,n) and y(q,n), so the estimator a
is a matrix of size (q,p) and b is a vector of size (q,1)
EXAMPLE :
Scilab Group April 1993 257
reglin Scilab Function
// simulation of data for a(3,5) and b(3,1)
x=rand(5,100);
aa=matrix('magi',5);aa=aa(1:3,:);
bb=[9;10;11]
y=aa*x +bb*ones(1,100)+ 0.1*rand(3,100);
// identification
[a,b,sig]=reglin(x,y);
maxi(abs(aa-a))
maxi(abs(bb-b))

Scilab Group April 1993 258

Chapter 8

Polynomial calculations

259
cog Scilab Function
8.0.540 bezout Bezout equation for polynomials
CALLING SEQUENCE :
[gcd,U]=bezout(p1,p2)

PARAMETERS :
p1, p2 : two real polynomials

DESCRIPTION :
[gcd,U]=bezout(p1,p2) computes GCD gcd of p1 and p2 and in addition a (2x2) unimod-
ular matrix U such that:
[p1,p2]*U = [gcd,0]
The lcm ofp1 and
is given by:
p2
p1*U(1,2) (or )
-p2*U(2,2)
See Also : poly, roots, simpl, cleanp , lcm

8.0.541 clean cleans matrices (round to zero small entries)

CALLING SEQUENCE :
[B]=clean(A [,epsa [,epsr]])

PARAMETERS :
A : a numerical matrix (scalar, polynomial, sparse...)
epsa,epsr : real numbers (default values resp. 1.d-10 and 1.d-10)
DESCRIPTION :
This function eliminates (i.e. set to zero) all the coecients with absolute value < epsa and rela-
tive value < epsr (relative means relative w.r.t. 1-norm of coecients) in a polynomial (possibly
matrix polynomial or rational matrix).
Default values are epsa=1.d-10 and epsr=1.d-10;
For a constant (non polynomial) matrix clean(A,epsa) sets to zero all entries of A smaller than
epsa.
Author : F.D.

8.0.542 cmndred common denominator form

CALLING SEQUENCE :
[n,d]=cmndred(num,den)

PARAMETERS :
num, den : two polynomial matrices of same dimensions
DESCRIPTION :
[n,d]=cmndred(num,den) computes a polynomial matrix n and a common denominator poly-
nomial d such that:
n/d=num./den
The rational matrix dened by num./den is n/d
See Also : simp, clean
Scilab Group April 1993 260
derivat Scilab Function
8.0.543 cog inverse of polynomial matrix
CALLING SEQUENCE :
[Ns,d]=coffg(Fs)

PARAMETERS :
Fs : square polynomial matrix
DESCRIPTION :
coffg computes Fs^-1 where Fs is a polynomial matrix by co-factors method.
Fs inverse = Ns/d
d = common denominator; Ns = numerator (a polynomial matrix)
(For large matrices,be patient...results are generally reliable)
EXAMPLE :
s=poly(0,'s')
a=[ s, s^2+1; s s^2-1];
[a1,d]=coffg(a);
(a1/d)*a

See Also : determ , detr , invr, penlaur , glever

Author : F. D.
8.0.544 colcompr column compression of polynomial matrix
CALLING SEQUENCE :
[Y,rk,ac]=colcompr(A);

PARAMETERS :
A : polynomial matrix
Y : square polynomial matrix (right unimodular basis)
rk : normal rank of A
Ac : Ac=A*Y, polynomial matrix
DESCRIPTION :
column compression of polynomial matrix A (compression to the left)
EXAMPLE :
s=poly(0,'s');
p=[s;s*(s+1)^2;2*s^2+s^3];
[Y,rk,ac]=colcompr(p*p');
p*p'*Y

See Also : rowcompr

8.0.545 denom denominator

CALLING SEQUENCE :
den=denom(r)

PARAMETERS :
r : rational or polynomial or constant matrix.
den : polynomial matrix
DESCRIPTION :
den=denom(r) returns the denominator of a rational matrix.
Since rationals are represented as r=list('r',num,den,[]), denom(r) is the same as r(3).
See Also : numer
Scilab Group April 1993 261
diophant Scilab Function
8.0.546 derivat rational matrix derivative
CALLING SEQUENCE :
pd=derivat(p)

PARAMETERS :
p : polynomial or rational matrix
DESCRIPTION :
computes the derivative of the polynomial or rational function matrix w.r.t the dummy variable.
EXAMPLE :
s=poly(0,'s');
derivat(1/s) // -1/s^2;

8.0.547 determ determinant of polynomial matrix

CALLING SEQUENCE :
res=determ(W [,k])

PARAMETERS :
W : real square polynomial matrix
k : integer (upper bound for the degree of the determinant of W)
DESCRIPTION :
res=determ(W [,k]) returns the determinant of a real polynomial matrix (computation made
by FFT).
k is an integer larger than the actual degree of the determinant of W.
The default value of k is the smallest power of 2 which is larger than n*maxi(degree(W)).
Method: evaluate the determinant of W for the Fourier frequencies and apply inverse FFT to the
coecients of the determinant.
See Also : det, detr, coffg
Author : F.D.

8.0.548 detr polynomial determinant

CALLING SEQUENCE :
d=detr(h)

PARAMETERS :
h : polynomial or rational square matrix
DESCRIPTION :
d=detr(h) returns the determinant d of the polynomial or rational function matrix h. Based
on Leverrier's algorithm.
See Also : det, determ
Scilab Group April 1993 262
gcd Scilab Function
8.0.549 diophant diophantine (Bezout) equation
CALLING SEQUENCE :
[x,err]=diophant(p1p2,b)

PARAMETERS :
p1p2 : polynomial vector p1p2 = [p1 p2]
b : polynomial
x : polynomial vector [x1;x2]
DESCRIPTION :
diophant solves the bezout equation:
p1*x1+p2*x2=b with p1p2 a polynomial vector. If the equation is not solvable err = jjp1x1 +
p2x2 , bjj=jjbjjelse err=0
EXAMPLE :
s=poly(0,'s');p1=(s+3)^2;p2=(1+s);
x1=s;x2=(2+s);
[x,err]=diophant([p1,p2],p1*x1+p2*x2);
p1*x1+p2*x2-p1*x(1)-p2*x(2)

8.0.550 factors numeric real factorization

CALLING SEQUENCE :
[lnum,g]=factors(pol [,'flag'])
[lnum,lden,g]=factors(rat [,'flag'])

PARAMETERS :
pol : real polynomial
rat : real rational polynomial (rat=pol1/pol2)
lnum : list of polynomials (of degrees 1 or 2)
lden : list of polynomials (of degrees 1 or 2)
g : real number
flag : character string 'c' or 'd'
DESCRIPTION :
returns the factors of polynomial pol in the list lnum and the "gain" g.
One has pol= g times product of entries of the list lnum. If argument of factors is a 1x1 rational
rat=pol1/pol2, the factors of the numerator pol1 and the denominator pol2 are returned in the
lists lnum and lden respectively.
The "gain" is returned as g,i.e. one has: rat= g times (product entries in lnum) / (product entries
in lden).
If flag is 'c' (resp. 'd'), the roots of pol are refected wrt the imaginary axis (resp. the unit
circle), i.e. the factors in lnum are stable polynomials.
Same thing if factors is invoked with a rational arguments: the entries in lnum and lden are
stable polynomials if flag is given.
8.0.551 gcd gcd calculation
CALLING SEQUENCE :
[pgcd,U]=gcd(p)

PARAMETERS :
Scilab Group April 1993 263
horner Scilab Function
p : polynomial row vector p=[p1,..,pn]
DESCRIPTION :
[pgcd,u]=gcd(p) computes the gcd of components of p and a unimodular matrix (with
polynomial inverse) U, with minimal degree such that
p*U=[0 ... 0 pgcd]
EXAMPLE :
s=poly(0,'s');
p=[s,s*(s+1)^2,2*s^2+s^3];
[pgcd,u]=gcd(p);
p*u

See Also : bezout, bez actors of polynomial pol in the list lnum and the "gain" g.
One has pol= g times product of entries of the list lnum. If argument of factors is a 1x1 rational
rat=pol1/pol2, the factors of the numerator pol1 and the denominator pol2 are returned in the
lists lnum and lden respectively.
The "gain" is returned as g,i.e. one has: rat= g times (product entries in lnum) / (product entries
in lden).
If flag is 'c' (resp. 'd'), the roots of pol are refected wrt the imaginary axis (resp. the unit
circle), i.e. the factors in lnum are stable polynomials.
Same thing if factors is invoked with a rational arguments: the entries in lnum and lden are
stable polynomials if flag is given.
8.0.552 hermit Hermite form
CALLING SEQUENCE :
[Ar,U]=hermit(A)

PARAMETERS :
A : polynomial matrix
Ar : triangular polynomial matrix
U : unimodolar polynomial matrix
DESCRIPTION :
Hermite form: U is an unimodular matrix such that A*U is in Hermite triangular form:
The output variable is Ar=A*U.
Warning: Experimental version
EXAMPLE :
s=poly(0,'s');
p=[s, s*(s+1)^2, 2*s^2+s^3];
[Ar,U]=hermit(p'*p);
p'*p*U, determ(U)

8.0.553 horner polynomial/rational evaluation

CALLING SEQUENCE :
horner(P,x)

PARAMETERS :
P : polynomial or rational matrix
x : real number or polynomial or rational
Scilab Group April 1993 264
invr Scilab Function
DESCRIPTION :
evaluates the polynomial or rational matrix P = P(s) when the variable s of the polynomial is
replaced by x:
horner(P,x)=P(x)
Example (Bilinear transform): Assume P = P(s) is a rational matrix then the rational matrix
P((1+s)/(1-s)) is obtained by horner(P,(1+s)/(1-s)).
To evaluate a rational matrix at given frequencies use preferably the freq primitive.
EXAMPLES :
s=poly(0,'s');M=[s,1/s];
horner(M,1)
horner(M,%i)
horner(M,1/s)

See Also : freq , repfreq , evstr.

8.0.554 hrmt gcd of polynomials

CALLING SEQUENCE :
[pg,U]=hrmt(v)

PARAMETERS :
v : row of polynomials i.e. 1xk polynomial matrix
pg : polynomial
U : unimodular matrix polynomial
DESCRIPTION :
[pg,U]=hrmt(v) returns a unimodular matrix U and pg = gcd of row of polynomials v such
that v*U= [pg,0] .
See Also : gcd

8.0.555 htrianr triangularization of polynomial matrix

CALLING SEQUENCE :
[Ar,U,rk]=htrianr(A)

PARAMETERS :
A : polynomial matrix
Ar : polynomial matrix
U : unimodular polynomial matrix
rk : integer, normal rank of A
DESCRIPTION :
triangularization of polynomial matrix A.
A is[m,n] , m <= n.
Ar=A*U
Warning: there is an elimination of "small" terms (see function code).
See Also : hrmt
Scilab Group April 1993 265
numerX Scilab Function
8.0.556 invr inversion of (rational) matrix
CALLING SEQUENCE :
F = invr(H)

PARAMETERS :
H : polynomial or rational matrix
F : polynomial or rational matrix
DESCRIPTION :
If H is a polynomial or rational fonction matrix, invr computes H^(-1) using Leverrier's algo-
rithm (see function code)
EXAMPLE :
s=poly(0,'s')
H=[s,s*s+2;1-s,1+s]; invr(H)
[Num,den]=coffg(H);Num/den
H=[1/s,(s+1);1/(s+2),(s+3)/s];invr(H)

See Also : glever , coffg

8.0.557 lcm least common multiple

CALLING SEQUENCE :
[pp,fact]=lcm(p)

PARAMETERS :
p :
fact : polynomial vector
pp : polynomial
DESCRIPTION :
pp=lcm(p) computes the lcm pp of polynomial vector p.
[pp,fact]=lcm(p) computes in addition the vector fact such that:
p.*fact=pp*ones(p)
EXAMPLE :
s=poly(0,'s');
p=[s,s*(s+1)^2,s^2*(s+2)];
[pp,fact]=lcm(p);
p.*fact, pp

See Also : gcd , bezout

8.0.558 ldiv polynomial matrix long division

CALLING SEQUENCE :
[x]=ldiv(n,d,k)

PARAMETERS :
n,d : two real polynomial matrices
k : integer
DESCRIPTION :
x=ldiv(n,d,k) gives the k rst coecients of the long division of n by d i.e. the Taylor expan-
sion of the rational matrix [nij(z)/dij(z)] near innity.
Coecients of expansion of nij/dij are stored in x((i-1)*n+k,j) k=1:n
See Also : arl2
Scilab Group April 1993 266
polfact Scilab Function
8.0.559 numer numerator
CALLING SEQUENCE :
NUM=numer(R)
PARAMETERS :
R : rational matrix
DESCRIPTION :
Utility fonction. NUM=numer(R) returns the numerator NUM of a rational function matrix R (R
may be also a constant or polynomial matrix). numer(R) is equivalent to R(3).
See Also : denom
8.0.560 pdiv polynomial division
CALLING SEQUENCE :
[R,Q]=pdiv(P1,P2)
PARAMETERS :
P1 : polynomial matrix
P2 : polynomial or polynomial matrix
R,Q : two polynomial matrices
DESCRIPTION :
Element-wise euclidan division of the polynomial matrix P1 by the polynomial P2 or by the
polynomial matrix P2. Rij is the matrix of remainders, Qij is the matrix of quotients and P1ij
= Qij*P2 + Qij or P1ij = Qij*P2ij + Qij.
See Also : pdiv, ldiv
8.0.561 pol2des polynomial matrix to descriptor form
CALLING SEQUENCE :
[N,B,C]=pol2des(Ds)
PARAMETERS :
Ds : polynomial matrix
N, B, C : three real matrices
DESCRIPTION :
Given the polynomial matrix Ds=D 0 +D 1 s +D 2 s^2 +... ,
+D k s^k pol2des returns three
matrices N, B, C, with N nilpotent such that:
Ds = C (sN-Eye)^-1 B
See Also : ss2des , tf2des
Author : F.D.
8.0.562 pol2str polynomial matrix to string conversion
CALLING SEQUENCE :
[str]=pol2str(p)
PARAMETERS :
p : real polynomial
str : character string
DESCRIPTION :
converts polynomial to character string (utility function).
See Also : string, pol2tex

Scilab Group April 1993 267

rowcomprX Scilab Function
8.0.563 polfact minimal factors
CALLING SEQUENCE :
[f]=polfact(p)
PARAMETERS :
p : polynomial
f : vector [f0 f1 ... fn] such that p=prod(f)
f0 : constant
fi : polynomial

DESCRIPTION :
f=polfact(p) returns the minimal factors of p i.e. f=[f0 f1 ... fn] such that p=prod(f)
See Also : lcm , cmndred

8.0.564 residu residue

CALLING SEQUENCE :
[V]=residu(P,Q1,Q2)
PARAMETERS :
P, Q1, Q2 : polynomials or matrix polynomials with real or complex coecients.
DESCRIPTION :
V=residu(P,Q1,Q2) returns the matrix V such that V(i,j) is the sum of the residues of the
rational fraction P(i,j)/(Q1(i,j)*Q2(i,j)) calculated at the zeros of Q1(i,j).
Q1(i,j) and Q2(i,j) must not have any common root.
See Also : pfss, bdiag, roots, poly.
Author : F.D.
8.0.565 roots roots of polynomials
CALLING SEQUENCE :
[x]=roots(p)
PARAMETERS :
p : polynomial with real or complex coecients
DESCRIPTION :
x=roots(p) returns the complex vector x the roots of the polynomial p
See Also : poly.

8.0.566 routh t Routh's table

CALLING SEQUENCE :
r=routh_t(h [,k]).
PARAMETERS :
h : square rational matrix
DESCRIPTION :
r=routh t(h,k) computes Routh's table of denominator of the system described by transfer
matrix SISO h with the feedback by the gain k.
If k=poly(0,'k') we will have a polynomial matrix with dummy variable k, formal expression of
the Routh table.
Scilab Group April 1993 268
sylmX Scilab Function
8.0.567 rowcompr row compression of polynomial matrix
CALLING SEQUENCE :
[X,rk,Ac]=rowcompr(A)

PARAMETERS :
A : polynomial matrix
Y : square polynomial matrix (left unimodular basis)
rk : normal rank of A
Ac : Ac=X*A, polynomial matrix
DESCRIPTION :
row compression of polynomial matrix A .
X is a left polynomial unimodular basis wich row compresse thee rows of A. rk is the normal rank
of A.
Warning: elimination of "small" terms (use with care!).
See Also : colcompr
8.0.568 sfact discrete spectral factorization
CALLING SEQUENCE :
[F]=sfact(P)

PARAMETERS :
P : real polynomial matrix
DESCRIPTION :
Finds a spectral factor of P. P is a polynomial matrix assumed such that each root of P has a
mirror image w.r.t the unit circle.
sfact(P) returns a Hurwitz (stable) polynomial matrix such that
P = F(z)* F(1/z) *z^n
For scalar polynomials a specic algorithm is implemented. Algorithms are from Kucera's book.
See Also : fspec, fspecg.
8.0.569 simp rational simplication
CALLING SEQUENCE :
[N1,D1]=simp(N,D)
H1=simp(H)

PARAMETERS :
N,D : real polynomials or real matrix polynomials
H : rational matrix (i.e matrix with entries n/d ,n and d real polynomials)
DESCRIPTION :
[n1,d1]=simp(n,d) calculates two polynomials n1 and d1 such that n1/d1 = n/d.
If N and D are polynomial matrices the calculation is performed element-wise.
H1=simp(H) is also valid (each entry of H is simplied in H1).
Caution:
-no threshold is given i.e. simp cannot forces a simplication.
-For linear dynamic systems which include integrator(s) simplication changes the static gain.
(H(0) for continuuous systems or H(1) for discrete systems)
See Also : roots, trfmod, poly, clean
Scilab Group April 1993 269
systmat Scilab Function
8.0.570 sylm Sylvester matrix
CALLING SEQUENCE :
[S]=sylm(a,b)

PARAMETERS :
a,b : two polynomials
S : matrix
DESCRIPTION :
sylm(a,b) gives the Sylvester matrix associated to polynomials a and b, i.e. the matrix S such
that:
coeff( a*x + b*y )' = S * [coeff(x)';coeff(y)'] .
Dimension of is equal to
S degree(a)+degree(b) .
If and are coprime polynomials then
a b
rank(sylm(a,b))=degree(a)+degree(b)) and the instructions
u = sylm(a,b) \ eye(na+nb,1)
x = poly(u(1:nb),'z','coeff')
y = poly(u(nb+1:na+nb),'z','coeff')

compute Bezout factors x and y of minimal degree such that a*x+b*y = 1

8.0.571 systmat system matrix

CALLING SEQUENCE :
[Sm]=systmat(Sl);

PARAMETERS :
Sl : linear system (syslin list) or descriptor system
Sm : matrix pencil
DESCRIPTION :
System matrix of the linear system Sl (syslin list) in state-space form (utility function).
Sm = [-sI + A B;
[ C D]

For a descriptor system (Sl=list('des',A,B,C,D,E)), systmat returns:

Sm = [-sE + A B;
[ C D]

See Also : ss2des , sm2des , sm2ss

Scilab Group April 1993 270

Chapter 9

Linear Algebra

271
a2ab Scilab Function
9.0.572 a2ab linear (ane) function to A,b conversion
CALLING SEQUENCE :
[A,b]=aff2ab(afunction,dimX,D [,flag])

PARAMETERS :
afunction : a scilab function Y =fct(X,D) where X, D, Y are list of matrices
dimX : a p x 2 integer matrix (p is the number of matrices in X)
D :a list of real matrices (or any other valid Scilab object).
flag : optional parameter (flag='f' or flag='sp')
A : a real matrix
b : a real vector having same row dimension as A
DESCRIPTION :
aff2ab returns the matrix representation of an ane function (in the canonical basis).
afunction is a function with imposed syntax: Y=afunction(X,D) where X=list(X1,X2,...,Xp)
is a list of p real matrices, and Y=list(Y1,...,Yq) is a list of q real real matrices which depend
linearly of the Xi's. The (optional) input D contains parameters needed to compute Y as a function
of X. (It is generally a list of matrices).
dimX is a p x 2 matrix: dimX(i)=[nri,nci] is the actual number of rows and columns of matrix
Xi. These dimensions determine na, the column dimension of the resulting matrix A: na=nr1*nc1
+...+ nrp*ncp.
If the optional parameter flag='sp' the resulting A matrix is returned as a sparse matrix.
This function is useful to solve a system of linear equations where the unknown variables are
matrices.
EXAMPLE :
// Lyapunov equation solver (one unknown variable, one constraint)
deff('Y=lyapunov(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q)')
A=rand(3,3);Q=rand(3,3);Q=Q+Q';D=list(A,Q);dimX=[3,3];
[Aly,bly]=aff2ab(lyapunov,dimX,D);
[Xl,kerA]=linsolve(Aly,bly); Xv=vec2list(Xl,dimX); lyapunov(Xv,D)
Xm=Xv(:); A'*Xm+Xm*A-Q

// Lyapunov equation solver with redundant constraint X=X'

// (one variable, two constraints) D is global variable
deff('Y=ly2(X,D)','[A,Q]=D(:);Xm=X(:); Y=list(A''*Xm+Xm*A-Q,Xm''-Xm)')
A=rand(3,3);Q=rand(3,3);Q=Q+Q';D=list(A,Q);dimX=[3,3];
[Aly,bly]=aff2ab(ly2,dimX,D);
[Xl,kerA]=linsolve(Aly,bly); Xv=vec2list(Xl,dimX); ly2(Xv,D)

// Francis equations
// Find matrices X1 and X2 such that:
// A1*X1 - X1*A2 + B*X2 -A3 = 0
// D1*X1 -D2 = 0
deff('Y=bruce(X,D)','[A1,A2,A3,B,D1,D2]=D(:),...
[X1,X2]=X(:);Y=list(A1*X1-X1*A2+B*X2-A3,D1*X1-D2)')
A1=[-4,10;-1,2];A3=[1;2];B=[0;1];A2=1;D1=[0,1];D2=1;
D=list(A1,A2,A3,B,D1,D2);
[n1,m1]=size(A1);[n2,m2]=size(A2);[n3,m3]=size(B);
dimX=[[m1,n2];[m3,m2]];
[Af,bf]=aff2ab(bruce,dimX,D);
[Xf,KerAf]=linsolve(Af,bf);Xsol=vec2list(Xf,dimX)
bruce(Xsol,D)

Scilab Group April 1993 272

bdiag Scilab Function
// Find all X which commute with A
deff('y=f(X,D)','y=list(D(:)*X(:)-X(:)*D(:))')
A=rand(3,3);dimX=[3,3];[Af,bf]=aff2ab(f,dimX,list(A));
[Xf,KerAf]=linsolve(Af,bf);[p,q]=size(KerAf);
Xsol=vec2list(Xf+KerAf*rand(q,1),dimX);
C=Xsol(:); A*C-C*A

See Also : linsolve , vec2list

9.0.573 balanc matrix or pencil balancing

CALLING SEQUENCE :
[Ab,X]=balanc(A)
[Eb,Ab,X,Y]=balanc(E,A)

PARAMETERS :
A: a real square matrix
X: a real square invertible matrix
E: a real square matrix (same dimension as A)
Y: a real square invertible matrix.
DESCRIPTION :
Balance a square matrix to improve its condition number.
[Ab,X] = balanc(A) nds a similarity transformation X such that Ab = inv(X)*A*X has
approximately equal row and column norms.
For matrix pencils,balancing is done for improving the generalized eigenvalue problem.
[Eb,Ab,X,Y] = balanc(E,A) returns left and right transformations X and Y such that Eb=X*E*Y
Ab=X*A*Y
REMARK :
Balancing is made in the functions bdiag and spec.
See Also : bdiag
9.0.574 bdiag block diagonalization.
CALLING SEQUENCE :
[Ab [,X [,bs]]]=bdiag(A [,rmax])

PARAMETERS :
A : real or complex square matrix
rmax : real number
Ab : real or complex square matrix
X : real or complex non-singular matrix
bs : vector of integers
DESCRIPTION :
[Ab [,X [,bs]]]=bdiag(A [,rmax])

performs the block-diagonalization of matrix A. bs gives the structure of the blocks (respective sizes
of the blocks). X is the change of basis i.e Ab = inv(X)*A*X is block diagonal.
rmax controls the conditioning of X; the default value is the l1 norm of A.
To get a diagonal form (if it exists) choose a large value for rmax (rmax=1/%eps for example).
Generically (for real random A) the blocks are (1x1) and (2x2) and X is the matrix of eigenvectors.
EXAMPLE :
Scilab Group April 1993 273
colcomp Scilab Function
//Real case: 1x1 and 2x2 blocks
a=rand(5,5);[ab,x,bs]=bdiag(a);ab
//Complex case: complex 1x1 blocks
[ab,x,bs]=bdiag(a+%i*0);ab

See Also : schur , sylv.

9.0.575 chol Cholesky factorization

CALLING SEQUENCE :
[R]=chol(X)

PARAMETERS :
X : a symmetric positive denite real or complex matrix.
DESCRIPTION :
If is positive denite, then R = chol(X) produces an upper triangular matrix R such that R'*R
X
= X.
chol(X) uses only the diagonal and upper triangle of X. The lower triangular is assumed to be the
(complex conjugate) transpose of the upper.
See Also : qr, svd, bdiag, fullrf
9.0.576 co resolvent (cofactor method)
CALLING SEQUENCE :
[N,d]=coff(M [,var])

PARAMETERS :
M : square real matrix
var : character string
N : polynomial matrix (same size as M)
d : polynomial (characteristic polynomial poly(A,'s'))
DESCRIPTION :
coff computes R=(s*eye-M)^-1 for M a real matrix. R is given by N/d.
N = numerator polynomial matrix.
d = common denominator.
var character string ('s' if omitted)
EXAMPLE :
M=[1,2;0,3];
[N,d]=coff(M)

See Also : coffg , ss2tf , nlev

9.0.577 colcomp column compression, kernel, nullspace

CALLING SEQUENCE :
[W,rk]=colcomp(A [,flag,tol])

PARAMETERS :
A : real or complex matrix
Scilab Group April 1993 274
epsn Scilab Function
flag : character string
tol : real number
W : square non-singular matrix (change of basis)
rk : integer (rank of A)
DESCRIPTION :
Column compression of A: Ac = A*W is column compressed i.e
Ac=[0,Af] with Af full column rank, rank(Af) = rank(A) = rk.
flag and tol are optional parameters: flag = 'qr' or 'svd' (default is 'svd').
tol = tolerance parameter (of order %eps as default value).
The ma-rk rst columns of W span the kernel of A when size(A)=(na,ma)
See Also : rowcomp, fullrf, fullrfk, kernel
Author : F.D.
9.0.578 cond condition number
CALLING SEQUENCE :
cond(X)

PARAMETERS :
X : real or complex square matrix
DESCRIPTION :
Condition number in 2-norm. cond(X) is the ratio of the largest singular value of X to the
smallest.
See Also : rcond, svd
9.0.579 det determinant
CALLING SEQUENCE :
det(X)

PARAMETERS :
X : real or complex square matrix, polynomial or rational matrix.
DESCRIPTION :
det(X) is the determinant of the square matrix X.
For polynomial matrix det(X) is equivalent to determ(X).
For rational matrices det(X) is equivalent to detr(X).
See Also : detr, determ
9.0.580 epsn reduced pencil
CALLING SEQUENCE :
[Er,Ar,Q,Z]=epsfin(F)
[Er,Ar,Q,Z]=epsfin(E,A)

PARAMETERS :
F : real matrix pencil F=s*E-A
E,A : two real matrices of same dimensions
Q,Z : two orthogonal matrices (not necessarily square)
Scilab Group April 1993 275
fullrf Scilab Function
Er,Ar : two real matrices of same dimensions (reduced pencil)
DESCRIPTION :
Returns the epsilon + nite part of the pencil F=sE-A.
Er=Q*E*Z, Ar=Q*A*Z has only epsilon and nite Kronecker invariants and Er is full row rank.
Z : right subspace associated with epsilon and nite part of the pencil
For a regular pencil spans the right nite eigenspace.
Z
Author : F. D. & R. N.
See Also : kroneck, pencan, fineta
9.0.581 exp exponential, matrix exponential
CALLING SEQUENCE :
exp(X)

PARAMETERS :
X : a vector or a square matrix with real or complex entries.

DESCRIPTION :
If X is a vector (or a non-square matrix) exp(X) is the (element-wise) exponential of the entries
of X, e to the X.
If X is a square matrix exp(X) is the matrix
exp(X) = I + X + X 2 =2 + :::
The computation is performed by rst block-diagonalizing X and then applying a Pade approxi-
mation on each block.
See Also : bdiag, coff, log
9.0.582 neta reduced pencil
CALLING SEQUENCE :
[Er,Ar,Q,Z]=fineta(F)
[Er,Ar,Q,Z]=fineta(E,A)

PARAMETERS :
F : real matrix pencil F=s*E-A
E,A : two real matrices of same dimensions
Q,Z : two orthogonal matrices (not necessarily square)
Er,Ar : two real matrices of same dimensions (reduced pencil)
DESCRIPTION :
Returns the nite + eta part of the pencil F=sE-A.
Er=Q*E*Z, Ar=Q*A*Z has only nite and eta Kronecker invariants and Er is full column rank.
Q : left (row)-subspace associated with nite and eta part of the pencil
For a regular pencil spans the left nite eigenspace.
Q
Author : F. D & R. N.
See Also : kroneck, pencan, epsfin
Scilab Group April 1993 276
glever Scilab Function
9.0.583 fullrf full rank factorization
CALLING SEQUENCE :
[Q,M,rk]=fullrf(A,[tol])

PARAMETERS :
A : real or complex matrix
tol : real number (threshold for rank determination)
Q,M : real or complex matrix
rk : integer (rank of A)
DESCRIPTION :
Full rank factorization : fullrf returns Q and M such that A = Q*M with range(Q)=range(A) and
ker(M)=ker(A), Q full column rank , M full row rank, rk = rank(A) = #columns(Q) = #rows(M).
tol is an optional real parameter (default value is sqrt(%eps)). The rank rk of A is dened as
the number of singular values larger than norm(A)*tol.
See Also : svd, qr, fullrfk
Author : F.D.
9.0.584 fullrfk full rank factorization of A^k
CALLING SEQUENCE :
[Bk,Ck]=fullrfk(A,k)

PARAMETERS :
A : real or complex matrix
k : integer
Bk,Ck : real or complex matrices
DESCRIPTION :
This function computes the full rank factorization of A^k i.e. Bk*Ck=A^k where Bk is full column
rank and Ck full row rank. One has range(Bk)=range(A^k) and ker(Ck)=ker(A^k).
For k=1, fullrfk is equivalent to fullrf.
See Also : fullrf, range
Author : F.D (1990)
9.0.585 givens Givens transformation
CALLING SEQUENCE :
U=givens(xy)
U=givens(x,y)

PARAMETERS :
x,y : two real or complex numbers
xy : 1x2 real or complex matrix
U : 2x2 unitary matrix
DESCRIPTION :
U = givens(x, y) or U = givens(xy) with xy = [x;y] returns a 2x2 unitary matrix U such
that:
U*xy=[r;0] .
Note thatgivens(x,y) and givens([x;y]) are equivalent.
Scilab Group April 1993 277
gschur Scilab Function
9.0.586 glever inverse of matrix pencil
CALLING SEQUENCE :
[Bfs,Bis,chis]=glever(E,A [,s])

PARAMETERS :
E, A : two real square matrices of same dimensions
s : character string (default value 's')
Bfs,Bis : two polynomial matrices
chis : polynomial
DESCRIPTION :
Computation of (sE , A),1 by generalized Leverrier's algorithm for a matrix pencil.
(s*E-A)^-1 = (Bfs/chis) - Bis.

chis = characteristic polynomial (up to a multiplicative constant).

Bfs = numerator polynomial matrix.
Bis = polynomial matrix ( - expansion of (s*E-A)^-1 at innity).
Note the - sign before Bis.
CAUTION :
This function uses cleanp to simplify Bfs,Bis and chis.
Author : F. D. (1988)
See Also : shuffle , determ , invr , coffg , pencan , penlaur

9.0.587 gschur generalized Schur form (matrix pencils).

CALLING SEQUENCE :
[As,Es]=gschur(A,E)
[As,Es,Q,Z]=gschur(A,E)
[As,Es,Z,dim] = gschur(A,E,flag)
[As,Es,Z,dim]= gschur(A,E,extern)

PARAMETERS :
A, E : two real square matrices
flag : character string ('c' or 'd')
extern : Scilab \external" function (usual case). Could be also a list or a character string
As,Es : two real square matrices
Q, Z : two non-singular real matrices
dim : integer (dimension of subspace)
DESCRIPTION :
Schur form of matrix pencils (QZ algorithm)
[As,Es] = gschur(A,E)

produces a quasi triangular As matrix and a triangular Es matrix which are the generalized Schur
form of the pair A, E.
[As,Es,Q,Z] = gschur(A,E)

returns in addition two unitary matrices Q and Z such that As=Q*A*Z and Es=Q*E*Z.
Ordered stable form
[As,Es,Z,dim] = gschur(A,E,'c')

Scilab Group April 1993 278

im inv Scilab Function
returns the real generalized Schur form of the pencil s*E-A. In addition, the dim rst columns of
Z span a basis of the right eigenspace associated with eigenvalues with negative real parts (stable
"continuous time" generalized eigenspace).
[As,Es,Z,dim] = gschur(A,E,'d')

returns the real generalized Schur form of the pencil s*E-A. In addition, the dim rst columns of
Z make a basis of the right eigenspace associated with eigenvalues with magnitude lower than 1
(stable "discrete time" generalized eigenspace).
General subspace
[As,Es,Z,dim] = gschur(A,E,extern)

returns the real generalized Schur form of the pencil s*E-A. In addition, the dim rst columns of
Z make a basis of the right eigenspace associated with eigenvalues of the pencil which are selected
according to a rule which is given by the scilab function extern. (See schur for denition of this
function).
See Also : external, gspec, pencan, penlaur, coffg, balanc
9.0.588 gspec eigenvalues of matrix pencil
CALLING SEQUENCE :
[al,be]=gspec(A,E)
[al,be,Z]=gspec(A,E)

PARAMETERS :
A, E : real square matrices
al, be : real vectors
Z : real square non-singular matrix
DESCRIPTION :
[al,be] = gspec(A,E) returns the spectrum of the matrix pencil s E - A, i.e. the roots of
the polynomial matrix s E - A. The eigenvalues are given by al./be and if be(i) = 0 the ith
eigenvalue is at innity. (For E = eye(A), al./be is spec(A)).
[al,be,Z] = gspec(A,E) returns in addition the matrix Z of generalized right eigenvectors of
the pencil.
See Also : gschur, balanc, spec.
9.0.589 hess Hessenberg form
CALLING SEQUENCE :
H = hess(A)
[U,H] = hess(A)

PARAMETERS :
A : real or complex square matrix
H : real or complex square matrix
U : orthogonal or unitary square matrix
DESCRIPTION :
[U,H] = hess(A) produces a unitary matrix U and a Hessenberg matrix H so that A = U*H*U'
and U'*U = Identity. By itself, hess(A) returns H.
The Hessenberg form of a matrix is zero below the rst subdiagonal. If the matrix is symmetric
or Hermitian, the form is tridiagonal.
See Also : qr, contr.
Scilab Group April 1993 279
kroneck Scilab Function
9.0.590 im inv inverse image
CALLING SEQUENCE :
[X,dim]=im_inv(A,B [,tol])

PARAMETERS :
A,B : two real or complex matrices with equal number of columns
X : orthogonal or unitary square matrix of order equal to the number of columns of A
dim : integer (dimension of subspace)
DESCRIPTION :
[X,dim]=im_inv(A,B) computes A,1(B) i.e vectors whose image through A are in range(B)
The dim rst columns of span A,1 (B):
X
tol is a threshold used to test if subspace inclusion; default value is tol = 100*%eps.
See Also : rowcomp
Author : F. D.
9.0.591 inv matrix inverse
CALLING SEQUENCE :
inv(X)

PARAMETERS :
X : real or complex square matrix, polynomial matrix, rational matrix in transfer or state-space
representation.
DESCRIPTION :
inv(X) is the inverse of the square matrix X. A warning message is printed if X is badly scaled
or nearly singular.
For polynomial matrices or rational matrices in transfer representation, inv(X) is equivalent to
invr(X).
For linear systems in state-space representation (syslin list), invr(X) is equivalent to invsyslin(X).
See Also : slash , backslash , pinv , qr, lufact , lusolve , invr , coff , coffg

9.0.592 kernel kernel, nullspace

CALLING SEQUENCE :
W=kernel(A [,tol,[,flag])

PARAMETERS :
A : full real or complex matrix or real sparse matrix
flag : character string 'svd' (default) or 'qr'
tol : real number
W : full column rank matrix
DESCRIPTION :
W=kernel(A) returns the kernel of A.
flag and tol are optional parameters: flag = 'qr' or 'svd' (default is 'svd').
tol = tolerance parameter (of order %eps as default value).
See Also : colcomp, fullrf, fullrfk, linsolve
Author : F.D.
Scilab Group April 1993 280
leverrie Scilab Function
9.0.593 kroneck Kronecker form of matrix pencil
CALLING SEQUENCE :
[Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(F)
[Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(E,A)

PARAMETERS :
F : real matrix pencil F=s*E-A
E,A : two real matrices of same dimensions
Q,Z : two square orthogonal matrices
Qd,Zd : two vectors of integers
numbeps,numeta : two vectors of integers
DESCRIPTION :
Kronecker form of matrix pencil: kroneck computes two orthogonal matrices Q, Z which put
the pencil F=s*E -A into upper-triangular form:

| sE(eps)-A(eps) | X | X | X |
|----------------|----------------|------------|---------------|
| O | sE(inf)-A(inf) | X | X |
Q(sE-A)Z = |---------------------------------|----------------------------|
| | | | |
| 0 | 0 | sE(f)-A(f) | X |
|--------------------------------------------------------------|
| | | | |
| 0 | 0 | 0 | sE(eta)-A(eta)|

The dimensions of the four blocks are given by:

eps=Qd(1) x Zd(1), inf=Qd(2) x Zd(2), f = Qd(3) x Zd(3), eta=Qd(4)xZd(4)
The inf block contains the innite modes of the pencil.
The f block contains the nite modes of the pencil
The structure of epsilon and eta blocks are given by:
numbeps(1) = # of eps blocks of size 0 x 1
numbeps(2) = # of eps blocks of size 1 x 2
numbeps(3) = # of eps blocks of size 2 x 3 etc...
numbeta(1) = # of eta blocks of size 1 x 0
numbeta(2) = # of eta blocks of size 2 x 1
numbeta(3) = # of eta blocks of size 3 x 2 etc...
The code is taken from T. Beelen (Slicot-WGS group).
See Also : gschur, gspec, systmat, pencan, epsfin
9.0.594 leverrier Leverrier's algorithm
CALLING SEQUENCE :
[NUM,DEN]=leverrier(H,F,G)

PARAMETERS :
H,F,G : real matrices of appropriate dimensions
NUM : polynomial matrix
den : polynomial
Scilab Group April 1993 281
ludel Scilab Function
DESCRIPTION :
[NUM,den]=leverrier(H,F,G) computes the transfer matrix num./den such that:
NUM./den = H*(s*eye-F)^(-1)*G by Leverrier's algorithm.
REMARK :
Use preferably ss2tf.
See Also : glever, coff , coffg , detr , determ , nlev

9.0.595 linsolve linear equation solver

CALLING SEQUENCE :
[x0,kerA]=linsolve(A,b [,x0])

PARAMETERS :
A :ana x ma real matrix (possibly sparse)
b :ana x 1 vector (same row dimension as A)
x0 : a real vector
kerA :a
ma x k real matrix
DESCRIPTION :
linsolve computes all the solutions to A*x+b=0.
x0 is a particular solution (if any) and kerA= nullspace of A. Any x=x0+kerA*w with arbitrary w
satises
A*x+b=0 .
If compatible is given on entry, x0 is returned. If not a compatible x0, if any, is returned.
x0
EXAMPLE :
A=rand(5,3)*rand(3,8);
b=A*ones(8,1);[x,kerA]=linsolve(A,b);A*x+b //compatible b
b=ones(5,1);[x,kerA]=linsolve(A,b);A*x+b //uncompatible b
A=rand(5,5);[x,kerA]=linsolve(A,b), -inv(A)*b //x is unique

See Also : inv, pinv, colcomp , im_inv

9.0.596 lu LU factors of Gaussian elimination

CALLING SEQUENCE :
[L,U]= lu(A)

PARAMETERS :
A : real or complex square matrix (n x n)
L,U : two real or complex matrices (n x n)
DESCRIPTION :
[L,U]= lu(A) produces two matrices L and U such that A = L*U with U upper triangular and
E*L lower triangular for a permutation matrix E. If A has rank k, rows k+1 to n of U are zero.
REMARK :
E is not returned by LU: as such this primitive is not interesting (old stu)
See Also : lufact, lusolve, qr, svd.
Scilab Group April 1993 282
lufact Scilab Function
9.0.597 ludel utility function used with lufact
CALLING SEQUENCE :
ludel(hand)

PARAMETERS :
hand : handle to sparse lu factors (output of lufact)
DESCRIPTION :
This function is used in conjunction with lufact. It clears the internal memory space used to
store the result of lufact.
The sequence of commands [p,r]=lufact(A);x=lusolve(p,b);ludel(p); solves the sparse lin-
ear system A*x = b and clears p.
See Also : sparse, lufact, luget.
9.0.598 lufact sparse lu factorization
CALLING SEQUENCE :
[hand,rk]=lufact(A,prec)

PARAMETERS :
A : square sparse matrix
hand : handle to sparse lu factors
rk : integer (rank of A)
prec : a vector of size two prec=[eps,reps] giving the absolute and relative thresolds.
DESCRIPTION :
[hand,rk]=lufact(A) performs the lu factorization of sparse matrix A. hand (no display) is
used by lusolve (for solving linear system) and luget (for retrieving the factors). hand should
be cleared by the command: ludel(hand);
The A matrix needs not be full rank but must be square (since A is assumed sparse one may add
zeros if necessary to squaring down A).
eps : The absolute magnitude an element must have to be considered as a pivot candidate,
except as a last resort. This number should be set signicantly smaller than the smallest
diagonal element that is is expected to be placed in the matrix. the default value is %eps.
reps : This number determines what the pivot relative threshold will be. It should be between
zero and one. If it is one then the pivoting method becomes complete pivoting, which is very
slow and tends to ll up the matrix. If it is set close to zero the pivoting method becomes
strict Markowitz with no threshold. The pivot threshold is used to eliminate pivot candidates
that would cause excessive element growth if they were used. Element growth is the cause
of roundo error. Element growth occurs even in well-conditioned matrices. Setting the
reps large will reduce element growth and roundo error, but setting it too large will cause
execution time to be excessive and will result in a large number of ll-ins. If this occurs,
accuracy can actually be degraded because of the large number of operations required on
the matrix due to the large number of ll-ins. A good value seems to be 0.001 which is the
default value. The default is chosen by giving a value larger than one or less than or equal
to zero. This value should be increased and the matrix resolved if growth is found to be
excessive. Changing the pivot threshold does not improve performance on matrices where
growth is low, as is often the case with ill-conditioned matrices. reps was choosen for use with
nearly diagonally dominant matrices such as node- and modied-node admittance matrices.
For these matrices it is usually best to use diagonal pivoting. For matrices without a strong
diagonal, it is usually best to use a larger threshold, such as 0.01 or 0.1.
Scilab Group April 1993 283
lusolve Scilab Function
EXAMPLE :
a=rand(5,5);b=rand(5,1);A=sparse(a);
[h,rk]=lufact(A);
x=lusolve(h,b);a*x-b
ludel(h)

See Also : sparse , lusolve , luget

9.0.599 luget sparse lu factorization

CALLING SEQUENCE :
[P,L,U,Q]=luget(ptr)

PARAMETERS :
ptr : pointer, output of lufact
P : sparse permutation matrix
L : sparse matrix, lower triangular if ptr is obtained from a non singular matrix
U : square non singular upper triangular sparse matrix with ones along the main diagonal
Q : sparse permutation matrix
DESCRIPTION :
[P,L,U,Q]=luget(ptr) with ptr obtained by the command [ptr,rk]=lufact(A) with A a
sparse matrix returns four sparse matrices such that P*L*U*Q=A.
The A matrix needs not be full rank but must be square (since A is assumed sparse one may add
zeros if necessary to squaring down A).
If A is singular, the L matrix is column compressed (with rk independent nonzero columns): the
nonsingular sparse matrix Q'*inv(U) column compresses A.
EXAMPLE :
a=rand(5,2)*rand(2,5);A=sparse(a);
[ptr,rk]=lufact(A);[P,L,U,Q]=luget(ptr);
full(L), P*L*U*Q-A
clean(P*L*U*Q-A)
ludel(ptr)

See Also : sparse , lusolve , luget , spclean

9.0.600 lusolve sparse linear system solver

CALLING SEQUENCE :
lusolve(hand,b)
lusolve(A,b)

PARAMETERS :
b : full real matrix
A : real square sparse invertible matrix
hand : handle to a previously computed sparse lu factors (output of lufact)
DESCRIPTION :
x=lusolve(hand,b) solves the sparse linear system
A*x = b .
[hand,rk]=lufact(A) is the output of lufact.
x=lusolve(A,b) solves the sparse linear system \fVA*x = b\fR.
EXAMPLE :
Scilab Group April 1993 284
orth Scilab Function
non_zeros=[1,2,3,4];rows_cols=[1,1;2,2;3,3;4,4];
sp=sparse(rows_cols,non_zeros);
[h,rk]=lufact(sp);x=lusolve(h,[1;1;1;1]);ludel(h)
rk,sp*x

non_zeros=[1,2,3,4];rows_cols=[1,1;2,2;3,3;4,4];
sp=sparse(rows_cols,non_zeros);
x=lusolve(sp,-ones(4,1));
sp*x

See Also : sparse , lufact , slash , backslash.

9.0.601 lyap Lyapunov equation

CALLING SEQUENCE :
[X]=lyap(A,C,'c')
[X]=lyap(A,C,'d')

PARAMETERS :
A, C : real square matrices, C must be symmetric
DESCRIPTION :
X = lyap(A,C,flag) solves the continuous time or discrete time matrix Lyapunov matrix
equation:
A'*X + X*A = C ( flag='c' )
A'*X*A - X = C ( flag='d' )

See Also : sylv

9.0.602 nlev Leverrier's algorithm

CALLING SEQUENCE :
[num,den]=nlev(A,z [,rmax])

PARAMETERS :
A : real square matrix
z : character string
rmax : optional parameter (see bdiag)
DESCRIPTION :
[num,den]=nlev(A,z [,rmax]) computes: (zI , A),1by block diagonalization of A followed
by Leverrier's algorithm on each block.
REMARK :
This algorithm is better than leverrier but still not perfect!
See Also : leverrier, coff, coffg, glever, ss2tf
Author : F. D., S. S.
Scilab Group April 1993 285
pencan Scilab Function
9.0.603 orth orthogonal basis
CALLING SEQUENCE :
Q=orth(A)

PARAMETERS :
A : real or complex matrix
Q : real or complex matrix
DESCRIPTION :
returns Q, an orthogonal basis for the span of A. Range(Q) = Range(A) and Q'*Q=eye.
Q=orth(A)
The number of columns of Q is the rank of A as determined by the QR algorithm.
See Also : qr, rowcomp, colcomp
9.0.604 pbig eigen-projection
CALLING SEQUENCE :
[Q,M]=pbig(A,thres,flag)

PARAMETERS :
A : real square matrix
thres : real number
flag : character string ('c' or 'd')
Q,M : real matrices
DESCRIPTION :
Projection on eigen-subspace associated with eigenvalues with real part >= thres (flag='c') or
with magnitude >= thres (flag='d').
The projection is dened by Q*M, Q is full column rank, M is full row rank and M*Q=eye.
If flag='c', the eigenvalues of M*A*Q = eigenvalues of A with real part >= thres.
If flag='d', the eigenvalues of M*A*Q = eigenvalues of A with magnitude >= thres.
If flag='c' and if [Q1,M1] = full rank factorization (fullrf) of eye-Q*M then eigenvalues of
M1*A*Q1 = eigenvalues of A with real part < thres.
If flag='d' and if [Q1,M1] = full rank factorization (fullrf) of eye-Q*M then eigenvalues of
M1*A*Q1 = eigenvalues of A with magnitude < thres.
See Also : psmall, projspec, fullrf
Author : F. D. (1988)

9.0.605 pencan canonical form of matrix pencil

CALLING SEQUENCE :
[Q,M,i1]=pencan(Fs)
[Q,M,i1]=pencan(E,A)

PARAMETERS :
Fs : a regular pencil s*E-A
E,A : two real square matrices
Q,M : two non-singular real matrices
i1 : integer
Scilab Group April 1993 286
polar Scilab Function
DESCRIPTION :
Given the regular pencil Fs=s*E-A, pencan returns matrices Q and M such than M*(s*E-A)*Q is
in "canonical" form.
M*E*Q is a block matrix
[I,0;
0,N]
with N nilpotent and i1 = size of the I matrix above.
M*A*Q is a block matrix:
[Ar,0;
0,I]

See Also : glever , penlaur

Author : F. D.
9.0.606 penlaur Laurent coecients of matrix pencil
CALLING SEQUENCE :
[Si,Pi,Di,order]=penlaur(Fs)
[Si,Pi,Di,order]=penlaur(E,A)
PARAMETERS :
Fs : a regular pencil s*E-A
E, A : two real square matrices
Si,Pi,Di : three real square matrices
order : integer
DESCRIPTION :
penlaur computes the rst Laurent coecients of
(s*E-A)^-1 at innity.
(s*E-A)^-1 = ... + Si/s - Pi - s*Di + ... s at = innity.
order = order of the singularity (order=index-1).
The matrix pencil
Fs=s*E-A should be invertible.
For a index-zero pencil,
Pi, Di,... are zero and
Si=inv(E) .
For a index-one pencil (order=0), =0.
Di
For higher-index pencils, the terms
-s^2 Di(2), -s^3 Di(3),... are given by:
,
Di(2)=Di*A*Di Di(3)=Di*A*Di*A*Di (up to
Di(order) ).
REMARK :
Experimental version: troubles when bad conditioning of so*E-A
See Also : glever, pencan, rowshuff
Author : F. D. (1988,1990)
9.0.607 pinv pseudoinverse
CALLING SEQUENCE :
pinv(A,[tol])
PARAMETERS :
A : real or complex matrix
tol : real number
DESCRIPTION :
X = pinv(A) produces a matrix X of the same dimensions as A' such that:
A*X*A = A, X*A*X = X and both A*X and X*A are Hermitian .
The computation is based on SVD and any singular values lower than a tolerance are treated as
zero: this tolerance is accessed by X=pinv(A,tol).
See Also : rank, svd, qr
Scilab Group April 1993 287
psmall Scilab Function
9.0.608 polar polar form
CALLING SEQUENCE :
[Ro,Theta]=polar(A)

PARAMETERS :
A : real or complex square matrix
Ro, Theta : real matrices
DESCRIPTION :
[Ro,Theta]=polar(A) returns the polar form of A i.e.:
A=Ro*exp(%i*Theta) Ro symmetric >=0 and Theta hermitian >=0.
Author : F. D.

9.0.609 proj projection

CALLING SEQUENCE :
P = proj(X1,X2)

PARAMETERS :
X1,X2 : two real matrices with equal number of columns
P : real projection matrix (P^2=P)
DESCRIPTION :
P is the projection on X2 parallel to X1.
See Also : projspec
Author : F. D.

9.0.610 projspec spectral operators

CALLING SEQUENCE :
[S,P,D,index]=projspec(A)

PARAMETERS :
A : square matrix
S, P, D : square matrices
index : integer
DESCRIPTION :
Spectral characteristics of A at 0.
S = reduced resolvent at 0 (S = -Drazin inverse(A)).
P = spectral projection at 0.
D = nilpotent operator at 0.
index = index of the 0 eigenvalue.
Author : F. D.
Scilab Group April 1993 288
quaskro Scilab Function
9.0.611 psmall spectral projection
CALLING SEQUENCE :
[Q,M]=psmall(A,thres,flag)

PARAMETERS :
A : real square matrix
thres : real number
flag : character string ('c' or 'd')
Q,M : real matrices
DESCRIPTION :
Projection on eigen-subspace associated with eigenvalues with real part < thres (flag='c') or
with modulus < thres (flag='d').
The projection is dened by Q*M, Q is full column rank, M is full row rank and M*Q=eye.
If flag='c', the eigenvalues of M*A*Q = eigenvalues of A with real part < thres.
If flag='d', the eigenvalues of M*A*Q = eigenvalues of A with magnitude < thres.
If flag='c' and if [Q1,M1] = full rank factorization (fullrf) of eye-Q*M then eigenvalues of
M1*A*Q1 = eigenvalues of A with real part >= thres.
If flag='d' and if [Q1,M1] = full rank factorization (fullrf) of eye-Q*M then eigenvalues of
M1*A*Q1 = eigenvalues of A with magnitude >= thres.
See Also : pbig, proj, projspec
Author : F. D. (1988)

9.0.612 qr QR decomposition
CALLING SEQUENCE :
[Q,R]=qr(X)
[Q,R,E]=qr(X)
[Q,R,rk,E]=qr(X,tol)

PARAMETERS :
X : real or complex matrix
tol : nonnegative real number
Q : square orthogonal or unitary matrix
R : matrix with same dimensions as X
E : permutation matrix
rk : integer (QR-rank of X*E)
DESCRIPTION :
[Q,R] = qr(X) produces an upper triangular matrix R of the same dimension as X and a
unitary matrix Q so that X = Q*R.
[Q,R,E] = qr(X) produces a (column) permutation matrix E, an upper triangular R with de-
creasing diagonal elements and a unitary Q so that X*E = Q*R.
[Q,R,rk,E] = qr(X,tol) returns rk = rank estimate of X i.e. rk is the number of diagonal
elements in R which are larger than tol.
See Also : rank, svd, rowcomp, colcomp.
Scilab Group April 1993 289
rank Scilab Function
9.0.613 quaskro quasi-Kronecker form
CALLING SEQUENCE :
[Q,Z,Qd,Zd,numbeps,numbeta]=quaskro(F)
[Q,Z,Qd,Zd,numbeps,numbeta]=quaskro(E,A)
[Q,Z,Qd,Zd,numbeps,numbeta]=quaskro(F,tol)
[Q,Z,Qd,Zd,numbeps,numbeta]=quaskro(E,A,tol)
PARAMETERS :
F : real matrix pencil F=s*E-A (s=poly(0,'s'))
E,A : two real matrices of same dimensions
tol : a real number (tolerance, default value=1.d-10)
Q,Z : two square orthogonal matrices
Qd,Zd : two vectors of integers
numbeps : vector of integers
DESCRIPTION :
Quasi-Kronecker form of matrix pencil: quaskro computes two orthogonal matrices Q, Z wich
put the pencil F=s*E -A into upper-triangular form:
| sE(eps)-A(eps) | X | X |
|----------------|----------------|------------|
| O | sE(inf)-A(inf) | X |
Q(sE-A)Z = |=================================|============|
| | |
| O | sE(r)-A(r) |

The dimensions of the blocks are given by:

eps=Qd(1) x Zd(1), inf=Qd(2) x Zd(2), r = Qd(3) x Zd(3)
The inf block contains the innite modes of the pencil.
The f block contains the nite modes of the pencil
The structure of epsilon blocks are given by:
numbeps(1) = # of eps blocks of size 0 x 1
numbeps(2) = # of eps blocks of size 1 x 2
numbeps(3) = # of eps blocks of size 2 x 3 etc...
The complete (four blocks) Kronecker form is given by the function kroneck which calls quaskro
on the (pertransposed) pencil sE(r)-A(r).
The code is taken from T. Beelen
See Also : kroneck, gschur, gspec
9.0.614 range range (span) of A^k
CALLING SEQUENCE :
[X,dim]=range(A,k)

PARAMETERS :
A : real square matrix
k : integer
X : non-singular real matrix
dim : integer (dimension of subspace)
DESCRIPTION :
Computation of Range A^k ; the rst dim columns of X span the range of A^k.
See Also : fullrfk, rowcomp
Author : F. D.
Scilab Group April 1993 290
rowcomp Scilab Function
9.0.615 rank rank
CALLING SEQUENCE :
[i]=rank(X)
[i]=rank(X,tol)

PARAMETERS :
X : real or complex matrix
tol : nonnegative real number
DESCRIPTION :
rank(X) is the numerical rank of X i.e. the number of singular values of X that are larger
than norm(size(X),'inf') * norm(X) * %eps.
rank(X,tol) is the number of singular values of X that are larger than tol.
REMARK :
Note that the default value of tol is proportional to norm(X). As a consequence
rank([1.d-80,0;0,1.d-80]) is 2 !.
See Also : svd, qr, rowcomp, colcomp.
9.0.616 rcond inverse condition number
CALLING SEQUENCE :
rcond(X)

PARAMETERS :
X : real or complex square matrix
DESCRIPTION :
rcond(X) is an estimate for the reciprocal of the condition of X in the 1-norm.
If X is well conditioned, rcond(X) is close to 1. If not, rcond(X) is close to 0.
[r,z]=rcond(X) sets r to rcond(X) and returns z such that
norm(X*z,1) = r*norm(X,1)*norm(z,1) Thus, if rcond is small z is a vector in the kernel.
See Also : svd, cond, inv
9.0.617 rowcomp row compression, range
CALLING SEQUENCE :
[W,rk]=rowcomp(A, flag, tol)

PARAMETERS :
A : real or complex matrix
flag : character string
tol : real number
W : square non-singular matrix (change of basis)
rk : integer (rank of A)
DESCRIPTION :
Row compression of A. Ac = W*A is a row compressed matrix: i.e. Ac=[Af;0] with Af full row
rank.
flag and tol are optional parameters: flag='qr' or 'svd' (default 'svd').
tol is a tolerance parameter (of order %eps as default value).
The rk rst columns of W' span the range of A.
Scilab Group April 1993 291
schur Scilab Function
The rk rst (top) rows of W span the row range of A.
REMARK :
A non zero vector x belongs to range(A) i W*x is row compressed in accordance with Ac i.e the
norm of its last components is small w.r.t its rst components.
See Also : colcomp, fullrf, fullrfk
Author : F. D.
9.0.618 rowshu shue algorithm
CALLING SEQUENCE :
[Ws,Fs1]=rowshuff(Fs, [alfa])

PARAMETERS :
Fs : square real pencil Fs = s*E-A
Ws : polynomial matrix
Fs1 : square real pencil F1s = s*E1 -A1 with E1 non-singular
alfa : real number (alfa = 0 is the default value)
DESCRIPTION :
Shue algorithm: Given the pencil Fs=s*E-A , returns Ws=W(s) (square polynomial matrix)
such that:
Fs1 = s*E1-A1 = W(s)*(s*E-A) is a pencil with non singular E1 matrix.
This is possible i the pencil Fs = s*E-A is regular (i.e. invertible). The degree of Ws is equal to
the index of the pencil.
The poles at innity of Fs are put to alfa and the zeros of Ws are at alfa.
Note that (s*E-A)^-1 = (s*E1-A1)^-1 * W(s) = (W(s)*(s*E-A))^-1 *W(s)
See Also : pencan, glever, penlaur
Author : F. D.
9.0.619 schur [ordered] Schur decomposition
CALLING SEQUENCE :
[U,T] = schur(A)
[U,dim]=schur(A,flag)
[U,dim]=schur(A,macro)

PARAMETERS :
A : real or complex matrix. For ordered forms A is assumed real.
flag : character string ('c' or 'd')
macro : an \external" function (this parameter can also be a list or character string)
U : orthogonal or unitary square matrix
T : matrix
dim : integer
DESCRIPTION :
Schur forms, ordered Schur forms
USUAL SCHUR FORM :
[U,T] = schur(A) produces a Schur matrix T and a unitary matrix U so that A = U*T*U'
and U'*U = eye(U). By itself, schur(A) returns T. If A is complex, the Complex Schur Form is
returned in matrix T. The Complex Schur Form is upper triangular with the eigenvalues of A on
the diagonal. If A is real, the Real Schur Form is returned. The Real Schur Form has the real
eigenvalues on the diagonal and the complex eigenvalues in 2-by-2 blocks on the diagonal.
Scilab Group April 1993 292
spanplus Scilab Function
ORDERED STABLE FORM :
[T,dim]=schur(A,'c') returns an unitary matrix T which transforms A into schur form. In
addition, the dim rst columns of T make a basis of the eigenspace of A associated with eigenvalues
with negative real parts (stable "continuous time" eigenspace).
[T,dim]=schur(A,'d') returns an unitary matrix T which transforms A into schur form. In
addition, the dim rst columns of T span a basis of the eigenspace of A associated with eigenvalues
with magnitude lower than 1 (stable "discrete time" eigenspace).
GENERAL EIGENSPACE :
[T,dim]=schur(A,a_macro) returns an unitary matrix T which transforms A into schur form.
In addition, the dim rst columns of T span a basis of the eigenspace of A associated with the
eigenvalues which are selected by the function a macro.
This function must be of the following type (here a macro is "rule"):
function [flag]=rule(x)

flag=...
x is a vector with three components which characterizes either a real eigenvalue or a pair of complex
conjugate eigenvalues.
If x(1)=1, a real eigenvalue is considered and this eigenvalue is x(2)/x(3).
If x(1)=2, a pair of complex conjugate eigenvalues is considered. The sum of these two eigenvalues
(twice the real part) is x(2) and the product (squared magnitude) is x(3).
On return, ag should be 1 if the real eigenvalue is selected or the pair of eigenvalues is selected
and 0 otherwise.
EXAMPLE OF FUNCTION :
function [flag]=disc(x)
ls =x(1);flag=0;
select ls
case 1 then if abs(x(2)) < ro*abs(x(3)) then flag=1;end
case 2 then if x(3) < ro*ro then flag=1;end
end
The function disc selects the eigenvalues with magnitude lower than a given scalar ro. And for
ro=1 the calling sequence [T,dim]=schur(A,'d') and [T,dim]=schur(A,disc) are equivalent.
Another useful example is %choose (see function code in SCIDIR/macros/percent)
See Also : gschur, ricc, pbig, psmall
9.0.620 spaninter subspace intersection
CALLING SEQUENCE :
[X,dim]=spaninter(A,B [,tol])

PARAMETERS :
A, B : two real or complex matrices with equal number of rows
X : orthogonal or unitary square matrix
dim : integer, dimension of subspace range(A) inter range(B)
DESCRIPTION :
[X,dim]=spaninter(A,B) computes the intersection of range(A) and range(B).
The rst dim columns of X span this intersection i.e. X(:,1:dim) is an orthogonal basis for
R(A) \ R(B)
In the X basis A and B are respectively represented by:
X'*A and X'*B.
tol is a threshold (sqrt(%eps) is the default value).
See Also : spanplus, spantwo
Author : F. D.
Scilab Group April 1993 293
spantwo Scilab Function
9.0.621 spanplus sum of subspaces
CALLING SEQUENCE :
[X,dim,dima]=spanplus(A,B[,tol])

PARAMETERS :
A, B : two real or complex matrices with equal number of rows
X : orthogonal or unitary square matrix
dim, dima : integers, dimension of subspaces
tol : nonnegative real number
DESCRIPTION :
[X,dim,dima]=spanplus(A,B) computes a basis X such that:
the rst dima columns of X span Range(A) and the following (dim-dima) columns make a basis of
A+B relative to A.
The dim rst columns of X make a basis for A+B.
One has the following canonical form for [A,B]:
[*,*] (dima rows)
X'*[A,B]=[0,*] (dim-dima rows)
[0,0]

tol is an optional argument (see function code).

See Also : spaninter, im_inv, spantwo
Author : F. D.

9.0.622 spantwo sum and intersection of subspaces

CALLING SEQUENCE :
[Xp,dima,dimb,dim]=spantwo(A,B, [tol])

PARAMETERS :
A, B : two real or complex matrices with equal number of rows
Xp : square non-singular matrix
dima, dimb, dim : integers, dimension of subspaces
tol : nonnegative real number
DESCRIPTION :
Given two matrices A and B with same number of rows, returns a square matrix Xp (non singular
but not necessarily orthogonal) such that :
[*,0] (dim-dimb rows)
Xp*[A,B]=[*,*] (dima+dimb-dim rows)
[0,*] (dim-dima rows)
[0,0]

The rst dima columns of inv(Xp) span range(A).

Columns dim-dimb+1 to dima of inv(Xp) span the intersection of range(A) and range(B).
The dim rst columns of inv(Xp) span range(A)+range(B).
Columns dim-dimb+1 to dim of inv(Xp) span range(B).
EXAMPLE :
Scilab Group April 1993 294
sqroot Scilab Function
A=[1,0,0,4;
5,6,7,8;
0,0,11,12;
0,0,0,16];
B=[1,2,0,0]';C=[4,0,0,1];
Sl=ss2ss(syslin('c',A,B,C),rand(A));
[no,X]=contr(Sl(2),Sl(3));CO=X(:,1:no); //Controllable part
[uo,Y]=unobs(Sl(2),Sl(4));UO=Y(:,1:uo); //Unobservable part
[Xp,dimc,dimu,dim]=spantwo(CO,UO); //Kalman decomposition
Slcan=ss2ss(Sl,inv(Xp));

See Also : spanplus , spaninter

Author : F. D.

9.0.623 spclean sparse matrix utility

CALLING SEQUENCE :
Aclean=spclean(A [,tols])

PARAMETERS :
A : sparse matrix
Aclean : sparse matrix
tols : optional 1 x 2 matrix tols=[abstol,reltol]
DESCRIPTION :
Aclean=spclean(A,[abstol,reltol]) returns a sparse matrix Aclean where the small entries
of A are set to zero.
An entry Aij is small if abs(Aij) < abstol or abs(Aij) <reltol*norm(A,1)
EXAMPLE :
A=sparse([%eps,0.001;2,0.1])
//spclean(A,[0.002,0])

See Also : sparse, lusolve , luget , spclean

9.0.624 spec eigenvalues

CALLING SEQUENCE :
evals=spec(A)

PARAMETERS :
A : real or complex square matrix
evals : real or complex vector
DESCRIPTION :
evals=spec(A) returns in vector evals the eigenvalues of A.
Eigenvectors are obtained by bdiag.
See Also : poly, det, gspec, schur, bdiag, colcomp.
Scilab Group April 1993 295
sylv Scilab Function
9.0.625 sqroot square root
CALLING SEQUENCE :
sqroot(X)

PARAMETERS :
X : symmetric non negative denite real or complex matrix
DESCRIPTION :
W=sqroot(X) returns the square root of X (uses SVD).
See Also : sqrt

9.0.626 sva singular value approximation

CALLING SEQUENCE :
[U,s,V]=sva(A,k)
[U,s,V]=sva(A,tol)

PARAMETERS :
A : real or complex matrix
k : integer
tol : nonnegative real number
DESCRIPTION :
Singular value approximation.
[U,S,V]=sva(a,k) with k an integer >=1, returns U,S and V such that B=U*S*V' is the bast
L2 approximation of A with rank(B)=k.
[U,S,V]=sva(A,tol) with tol a real number, returns U,S and V such that B=U*S*V' such
that L2-norm of A-B is at most tol.
See Also : svd
9.0.627 svd singular value decomposition
CALLING SEQUENCE :
s=svd(X)
[U,S,V]=svd(X)
[U,S,V,rk]=svd(X [,tol])

PARAMETERS :
X : a real or complex matrix
s : real vector (singular values)
S : real diagonal matrix (singular values)
U,V : orthogonal or unitary square matrices (singular vectors).
tol : real number
DESCRIPTION :
[U,S,V] = svd(X) produces a diagonal matrix S , of the same dimension as X and with
nonnegative diagonal elements in decreasing order, and unitary matrices U and V so that X =
U*S*V'.
s = svd(X) by itself, returns a vector s containing the singular values.
[U,S,V,rk]=svd(X,tol) gives in addition rk, the numerical rank of X i.e. the number of
singular values larger than tol.
The default value of tol is the same as in rank.
See Also : rank, qr, colcomp, rowcomp.
Scilab Group April 1993 296
trace Scilab Function
9.0.628 sylv Sylvester equation.
CALLING SEQUENCE :
sylv(A,B,C,flag)

PARAMETERS :
A,B,C : three real matrices of appropriate dimensions.
flag character string ('c' or 'd')
DESCRIPTION :
X = sylv(A,B,C,'c') computes X, solution of the "continuous time" Sylvester equation
A*X+X*B=C

X=sylv(A,B,C,'d') computes X, solution of the "discrete time" Sylvester equation

A*X*B-X=C

See Also : lyap.

9.0.629 trace trace

CALLING SEQUENCE :
trace(X)

PARAMETERS :
X : real or complex square matrix, polynomial or rational matrix.
DESCRIPTION :
trace(X) is the trace of the matrix X.
Same as sum(diag(X)).
See Also : det

Scilab Group April 1993 297

trace Scilab Function

Scilab Group April 1993 298

Chapter 10

Metanet

299
circuit Scilab function
10.0.630 adj lists compute adjacency lists
CALLING SEQUENCE :
[lp,la,ls] = adj_lists(directed,n,tail,head)

PARAMETERS :
directed : integer, 0 or 1 according to the fact that the graph is undirected or directed
n : integer, the number of nodes of the graph
tail : the row vector of the numbers of the tail nodes of the graph (its size is the number of
edges of the graph)
head : the row vector of the numbers of the head nodes of the graph (its size is the number of
edges of the graph)
lp : row vector, pointer array of the adjacency lists description of the graph (its size is the
number of nodes of the graph + 1)
la : row vector, arc array of the adjacency lists description of the graph (its size is the number
of edges of the graph)
ls : row vector, node array of the adjacency lists description of the graph (its size is the number
of edges of the graph)
DESCRIPTION :
adj lists computes the row vectors of the adjacency lists description of the graph from the
description of the graph given by the number of nodes n and the row vectors tail and head.
EXAMPLE :
ta=[2 3 3 5 3 4 4 5 8];
he=[1 2 4 2 6 6 7 7 4];
gt=make_graph('foo',1,8,ta,he);
gt('node_x')=[129 200 283 281 128 366 122 333];
gt('node_y')=[61 125 129 189 173 135 236 249];
show_graph(gt,'rep');
[lp,la,ls]=adj_lists(1,gt('node_number'),ta,he)

10.0.631 check graph check a Scilab graph-list

CALLING SEQUENCE :
check_graph(g)

PARAMETERS :
g : graph-list to check
DESCRIPTION :
check graph checks its argument g to see if it is a graph-list. The checking is not only syntactic
(number of elements of the list, compatible sizes of the vectors), but also semantic in the sense that
check graph checks that node number, tail and head elements of the list can really represent a
graph.
See Also : graph-list
10.0.632 circuit nd a circuit or the rank function in a directed
graph
CALLING SEQUENCE :
[p,r] = circuit(g)

Scilab Group September 1995 300

connex Scilab function
PARAMETERS :
g : graph-list
p : row vector of integer numbers of the arcs of the circuit if it exists
r : row vector of rank function if there is no circuit
DESCRIPTION :
circuit tries to nd a circuit for the directed graph g. It returns the circuit p as a row vector
of the corresponding arc numbers if it exists and it returns the empty vector [] otherwise. If the
graph has no circuit, the rank function is returned in r, otherwise its value is the empty vector [].
EXAMPLE :
g=make_graph('foo',1,3,[1 2 3],[2 3 1]);
circuit(g)
g=make_graph('foo',1,4,[1 2 2 3],[2 3 4 4]);
[p,r]=circuit(g)

10.0.633 con nodes set of nodes of a connected component

CALLING SEQUENCE :
[ns] = con_nodes(i,g)

PARAMETERS :
i : integer, number of the connected component
g : graph-list
ns : row vector, node numbers of the connected component
DESCRIPTION :
con nodes returns the row vector ns of the numbers of the nodes which belong to the connected
component number i.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 7 7 9 10 12 12 13 13 14 15];
he=[2 6 3 4 5 1 3 5 1 8 9 8 11 10 11 11 15 13 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[197 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[76 181 276 278 276 83 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
con_nodes(2,gt)
x_message('Displaying the nodes of component #2');
g1=gt; n=gt('node_number');
nodecolor=0*ones(1,n);
nodecolor(1,con_nodes(2,gt))=11*ones(con_nodes(2,gt));
g1('node_color')=nodecolor;
nodediam=20.*ones(1,n);
nodediam(1,con_nodes(2,gt))=30*ones(con_nodes(2,gt));
g1('node_diam')=nodediam;
show_graph(g1,'rep');

See Also : connex , is_connex , strong_connex , strong_con_nodes

Scilab Group September 1995 301

graph-list Scilab type
10.0.634 connex connected components
CALLING SEQUENCE :
[nc,ncomp] = connex(g)

PARAMETERS :
g : graph-list
nc : integer, number of connected components
ncomp : row vector of connected components
DESCRIPTION :
connex returns the number nc of connected components for the graph g and a row vector ncomp
giving the number of the connected component for each node. For instance, if i is a node number,
ncomp[i] is the number of the connected component to which node number i belongs.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 7 7 7 8 9 10 12 12 13 13 14 15];
he=[2 6 3 4 5 1 3 5 1 7 5 8 9 5 8 11 10 11 11 15 13 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[197 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[76 181 276 278 276 83 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
[nc,ncomp]=connex(gt)
g1=gt;
g1('node_color')=10+ncomp;
g1('node_diam')=10+10*ncomp;
x_message('Displaying the connected components of this graph');
show_graph(g1,'rep');

See Also : con_nodes , is_connex , strong_connex , strong_con_nodes

10.0.635 nd path nd a path between two nodes

CALLING SEQUENCE :
[p] = find_path(i,j,g)

PARAMETERS :
i : integer, number of start node
j : integer, number of end node
g : graph-list
p : row vector of integer numbers of the arcs of the path if it exists
DESCRIPTION :
find path returns the path p from node number i to node number j if it exists, and the empty
vector [] otherwise.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
p=find_path(1,14,gt);
edgecolor=1*ones(ta); edgecolor(p)=11*ones(p); gt('edge_color')=edgecolor;
show_graph(gt,'rep'); show_arcs(p);

See Also : nodes_2_path , shortest_path

Scilab Group September 1995 302

graph-list Scilab type
10.0.636 graph-list description of graph
DESCRIPTION :
A graph in Scilab is represented by a Scilab typed list with 34 elements. We call it a graph-list.
You will nd below the complete description of the list. Each element is described by one or
more lines. The rst line gives the order of the element in the list, its name and its denition.
Additional informations, such as the default for elements that can have one, are given in the other
lines. Indeed, only the 6 rst elements must have a value in the list, all the others can be given the
empty vector [] as a value, and then the default is used. For instance, you can dene a graph-list
by
g=make_graph('min',1,1,1,1);

which is the simplest graph you can create in Metanet (it is directed, has one node and one loop
arc on this node).
The name of the element in the list is very important because it is used to access the elements
of the list. For instance, if g is a graph-list, to get the name of the graph, you only have to do:
g('name')

and if you want to change the name of the graph to 'toto', you have to do:
g('name')='toto';

The elements of a graph-list are given below:

1 type : - the type of the list

- it must always be 'graph'

2 name : - the name of the graph

- it is a string with a maximum of 80 characters

3 directed : - ag giving the type of the graph

- it is equal to 1 (graph directed) or equal to 0 (graph undirected)

4 node number : - number of nodes
5 tail : - row vector of the tail node numbers
6 head : - row vector of the head node numbers
7 node name : - row vector of node names

- the names of the nodes must be unique

- default is the node numbers as node names
8 node type : - row vector of the node types

- the type is an integer from 0 to 2, default is 0 (plain node):

- 0 = plain node
- 1 = sink node
- 2 = source node
9 node x : - row vector of the x coordinate of the nodes

- default is computed
10 node y : - row vector of the y coordinate of the nodes

- default is computed
11 node color : - row vector of the node colors

- the color is an integer from 0 to 16, default is 0 (default foreground):

- 0 = default foreground

Scilab Group September 1995 303

graph-list Scilab type
- 1 = navyblue
- 2 = blue
- 3 = skyblue
- 4 = aquamarine
- 5 = forestgreen
- 6 = green
- 7 = lightcyan
- 8 = cyan
- 9 = orange
- 10 = red
- 11 = magenta
- 12 = violet
- 13 = yellow
- 14 = gold
- 15 = beige
- 16 = background
12 node diam : - row vector of the size of the node diameters in pixels

- a node is drawn as a circle

- default is the value of element default node diam
13 node border : - row vector of the size of the node borders in pixels

- a node is drawn as a circle

- default is the value of element default node border
14 node font size : - row vector of the size of the font used to draw the name of the node

- you can choose 8, 10, 12, 14, 18 or 24

- default is the value of element default font size
15 node demand : - row vector of the node demands

- default is 0
16 edge name : - row vector of the edge names

- the edge names must be unique

- default is the edge numbers as edge names
17 edge color : - row vector of the edge colors

- the color is an integer from 0 to 16 (see node color)

- default is 0 (black)
18 edge width : - row vector of the size of the edge widths in pixels

- default is the value of element default edge width

19 edge hi width : - row vector of the size of the highlighted edge widths in pixels

- default is the value of element default edge hi width

20 edge font size : - row vector of the size of the font used to draw the name of the edge

- you can choose 8, 10, 12, 14, 18 or 24

- default is the value of element default font size
21 edge length : - row vector of the edge lengths

- default is 0
22 edge cost : - row vector of the edge costs

- default is 0

Scilab Group September 1995 304

is connex Scilab function
23 edge min cap : - row vector of the edge minimum capacities
- default is 0
24 edge max cap : - row vector of the edge maximum capacities
- default is 0
25 edge q weight : - row vector of the edge quadratic weights
- default is 0
26 edge q orig : - row vector of the edge quadratic origins
- default is 0
27 edge weight : - row vector of the edge weights
- default is 0
28 default node diam : - default size of the node diameters of the graph
- default is 20 pixels
29 default node border : - default size of the node borders of the graph
- default is 2 pixels
30 default edge width : - default size of the edge widths of the graph
- default is 1 pixel
31 default edge hi width : - default size of the highlighted edge widths of the graph
- default is 3 pixels
32 default font size : - default size of the font used to draw the names of nodes and edges
- default is 12
33 node label : - row vector of node labels
34 edge label : - row vector of edge labels

EXAMPLE :
g=load_graph(SCI+'/demos/metanet/mesh100');
g('node_color')=int(rand(1:g('node_number'))*16);
g('edge_color')=int(rand(1:g('edge_number'))*16);
show_graph(g,'rep')

10.0.637 graph 2 mat node-arc incidence matrix from graph

CALLING SEQUENCE :
[a] = graph_2_mat(g)

PARAMETERS :
g : graph-list
a : sparse node-arc incidence matrix
DESCRIPTION :
graph 2 mat computes the node-arc incidence matrix corresponding to the graph g.
EXAMPLE :
g=load_graph(SCI+'/demos/metanet/colored');
a=graph_2_mat(g)

See Also : mat_2_graph

Scilab Group September 1995 305

make graph Scilab function
10.0.638 is connex connectivity test
CALLING SEQUENCE :
[res] = isconnex(g)

PARAMETERS :
g : graph-list
res : integer, result of the test
DESCRIPTION :
is connex returns 1 if the graph g is connected and 0 otherwise.
EXAMPLE :
g=make_graph('foo',1,3,[1,2,3,1],[2,3,1,3]);
is_connex(g)
g=make_graph('foo',1,4,[1,2,3,1],[2,3,1,3]);
is_connex(g)

See Also : con_nodes , strong_connex

10.0.639 load graph load a graph

CALLING SEQUENCE :
[g]=load_graph(path)

PARAMETERS :
name : string, the path of the graph to load
g : graph-list
DESCRIPTION :
path is the name of a graph le which contains the ASCII description of a graph. Such a le must
have the "graph" extension. path can be the name or the pathname of the le ; if the "graph"
extension is missing in path, it is assumed. load graph returns the corresponding graph-list.
EXAMPLE :
g=load_graph(SCI+'/demos/metanet/mesh100.graph');
show_graph(g,'rep');
g=load_graph(SCI+'/demos/metanet/colored');
show_graph(g,'new');

See Also : save_graph

10.0.640 make graph make a graph-list

CALLING SEQUENCE :
[g] = make-graph(name,directed,n,tail,head)

PARAMETERS :
name : string, the name of the graph
directed : integer, 0 or 1 according to the fact that the graph is undirected or directed
n : integer, the number of nodes of the graph
tail : row vector of the numbers of the tail nodes of the graph (its size is the number of edges
of the graph)
Scilab Group September 1995 306
max cap path Scilab function
head : row vector of the numbers of the head nodes of the graph (its size is the number of edges
of the graph)
DESCRIPTION :
make graph makes a graph-list according to its arguments which are respectively the name of the
graph, a ag for directed or undirected, the number of nodes and the row vectors tail and head.
These are the minimal data needed or a graph.
EXAMPLE :
// creating a directed graph with 3 nodes and 4 arcs.
g=make_graph('foo',1,3,[1,2,3,1],[2,3,1,3]);

See Also : graph-list

10.0.641 mat 2 graph graph from node-arc incidence matrix

CALLING SEQUENCE :
[g] = mat_2_graph(a,directed)

PARAMETERS :
a : sparse node-arc incidence matrix
directed : integer, 0 or 1 according to the fact that the graph is undirected or directed
g : graph-list
DESCRIPTION :
mat 2 graph computes the graph g correspponding to the node-arc incidence matrix a. Note that
a checking is made to insure that a is a sparse node-arc incidence matrix of a directed (directed=1)
or undirected (directed=0) graph.
EXAMPLE :
g=load_graph(SCI+'/demos/metanet/colored');
show_graph(g,'rep');
a=graph_2_mat(g)
g1=mat_2_graph(a,1)
g1('node_x')=g('node_x'); g1('node_y')=g('node_y');
show_graph(g1,'new');

See Also : graph_2_mat

10.0.642 max cap path maximum capacity path

CALLING SEQUENCE :
[p,cap] = max_cap_path(i,j,g)

PARAMETERS :
i,j : integers, node numbers
g : graph-list
p : row vector of integer numbers of the arcs of the path if it exists
cap : value of the capacity of the path
DESCRIPTION :
max cap path returns the path with maximum capacity from node i to node j for the graph g
if it exists and returns the empty vector [] otherwise.
The capacities of the edges are given by the element edge max cap of the graph-list. If its
value is not given (empty vector []), max cap path returns the empty vector []. The capacities
must be strictly positive, i.e negative capacities are considered as equal to 0 (no capacity at all).
EXAMPLE :
Scilab Group September 1995 307
max ow Scilab function
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
ma=gt('edge_number');
gt('edge_max_cap')=int(rand(1,ma)*16)+5;
[p,cap]=max_cap_path(1,14,gt);
edgecolor=1*ones(1,ma); edgecolor(p)=11*ones(p); gt('edge_color')=edgecolor;
x_message(['The maximum capacity is: '+string(cap);
'Showing the corresponding path']);
show_graph(gt,'rep'); show_arcs(p);

10.0.643 max ow maximum ow between two nodes

CALLING SEQUENCE :
[v,phi] = maxflow(i,j,g,[p])

PARAMETERS :
i : integer, number of start node
j : integer, number of end node
g : graph-list
p : row vector of a compatible initial ow
v : value of the maximum ow it is exists
phi : row vector of the value of the ow on the arcs
DESCRIPTION :
max flow returns the value of maximum ow v from node number i to node number j if it
exists, and the value of the ow on each arc as a row vector phi. All the computations are made
with integer numbers. The graph must be directed.
The bounds of the ow are given by the elements edge min cap and edge max cap of the
graph-list. The value of the maximum capacity must be greater than or equal to the value of the
minimum capacity. If the value of edge min cap or edge max cap is not given (empty row vector
[]), it is assumed to be equal to 0 on each edge.
p is a compatible ow for initializing the algorithm. It is an optional argument. If it is not
given, it is considered as equal to null vector. If given, checking is made to see if it is really a
compatible ow.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 181 276 278 276 103 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
g1=gt; ma=g1('edge_number'); n=g1('node_number');
g1('edge_min_cap')=0*ones(1,ma);
rand('uniform');
g1('edge_max_cap')=20*rand(1,ma)+ones(1,ma);
source=15; sink=1;
[v,phi]=max_flow(source,sink,g1);
x_message(['The maximum flow is: '+string(v);
'Showing the flow on the arcs']);

Scilab Group September 1995 308

min lcost c ow Scilab function
nodetype=0*ones(1,n); nodetype(source)=2; nodetype(sink)=1;
g1('node_type')=nodetype;
nodecolor=0*ones(1,n); nodecolor(source)=11; nodecolor(sink)=11;
g1('node_color')=nodecolor;
ii=find(phi<>0); edgecolor=phi; edgecolor(ii)=11*ones(ii);
g1('edge_color')=edgecolor;
edgefontsize=8*ones(1,ma); edgefontsize(ii)=18*ones(ii);
g1('edge_font_size')=edgefontsize;
g1('edge_label')=string(phi);
show_graph(g1,'rep');

10.0.644 metanet open a Metanet window

CALLING SEQUENCE :
[window] = metanet([path])

PARAMETERS :
path : string, directory where graph les are searched
window : integer, window number
DESCRIPTION :
This function is used to open a Metanet window from Scilab. path is an optional argument; it is
the directory where graph les are searched. By default, path is the working directory. Usually,
show graph is used and metanet is seldom used.
Each time metanet is executed, a new window is created and its number is incremented by 1.
See Also : netwindow, netwindows, show_graph
10.0.645 min lcost c ow minimum linear cost constrained ow
CALLING SEQUENCE :
[c,phi,v,flag] = min_lcost_cflow(i,j,cv,g)

PARAMETERS :
i : integer, number of source node
j : integer, number of sink node
cv : scalar, value of constrained ow
g : graph-list
c : value of cost
phi : row vector of the value of ow on the arcs
v : value of ow from source to sink
flag : feasible constrained ow ag (0 or 1)
DESCRIPTION :
min lcost cflow computes the minimum cost ow in the network g, with the value of the ow
from source node i to sink node j constrained to be equal to cv.
min lcost cflow returns the total cost of the ows on the arcs c, the row vector of the ows
on the arcs phi and the value of the ow v on the virtual arc from sink to source. If v is less than
cv, a message is issued, but the computation is done: in this case flag is equal to 0, otherwise it
is equal to 1.
The bounds of the ows are given by the elements edge min cap and edge max cap of the
graph-list. The value of the minimumcapacity must be equal to zero, and the value of the maximum
capacity must be non negative and must be integer numbers. If the value of edge min cap or
edge max cap is not given (empty row vector []), it is assumed to be equal to 0 on each edge.

Scilab Group September 1995 309

min lcost ow1 Scilab function
The costs on the edges are given by the element edge cost of the graph-list. The costs must
be non negative. If the value of edge cost is not given (empty row vector []), it is assumed to
be equal to 0 on each edge.
The demands, element node demand of the graph list, must be equal to zero.
This function uses the algorithm of Busacker and Goven.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 181 276 278 276 103 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
g1=gt; ma=g1('arc_number'); n=g1('node_number');
g1('edge_min_cap')=0*ones(1,ma);
rand('uniform');
g1('edge_max_cap')=round(20*rand(1,ma))+ones(1,ma);
g1('edge_cost')=10*rand(1,ma)+ones(1,ma);
source=15; sink=1; cv=5;
[c,phi,v]=min_lcost_cflow(source,sink,cv,g1);
x_message(['The cost is: '+string(c);
'Showing the flow on the arcs']);
nodetype=0*ones(1,n); nodetype(source)=2; nodetype(sink)=1;
g1('node_type')=nodetype;
ii=find(phi<>0); edgecolor=phi; edgecolor(ii)=11*ones(ii);
g1('edge_color')=edgecolor;
edgefontsize=8*ones(1,ma); edgefontsize(ii)=18*ones(ii);
nodecolor=0*ones(1,n); nodecolor(source)=11; nodecolor(sink)=11;
g1('node_color')=nodecolor;
g1('edge_font_size')=edgefontsize;
g1('edge_label')=string(phi);
show_graph(g1,'rep');

See Also : min_lcost_flow1 , min_lcost_flow2 , min_qcost_flow

10.0.646 min lcost ow1 minimum linear cost ow

CALLING SEQUENCE :
[c,phi,flag]=min_lcost_flow1(g)

PARAMETERS :
g : graph-list
c : value of cost
phi : row vector of the value of ow on the arcs ag : feasible problem ag (0 or 1)
DESCRIPTION :
min lcost flow1 computes the minimum linear cost ow in the network g. It returns the total
cost of the ows on the arcs c and the row vector of the ows on the arcs phi. If the problem is
not feasible (impossible to nd a compatible ow for instance), flag is equal to 0, otherwise it is
equal to 1.
The bounds of the ow are given by the elements edge min cap and edge max cap of the
graph-list. The value of the minimumcapacity and of the maximum capacity must be non negative
and must be integer numbers. The value of the maximum capacity must be greater than or equal
to the value of the minimum capacity. If the value of edge min cap or edge max cap is not given
(empty row vector []), it is assumed to be equal to 0 on each edge.
Scilab Group September 1995 310
min lcost ow2 Scilab function
The costs on the edges are given by the element edge cost of the graph-list. The costs must
be non negative. If the value of edge cost is not given (empty row vector []), it is assumed to
be equal to 0 on each edge.
The demands, element node demand of the graph list, must be equal to zero.
This function uses the out-of-kilter algorithm.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10 1 8];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1 12 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 221 316 318 316 143 214 321 217 126 215 80 330 437 439];
show_graph(gt,'rep');
g1=gt;ma=g1('arc_number');
rand('uniform');
while %T then
g1('edge_min_cap')=round(20*rand(1,ma));
g1('edge_max_cap')=round(20*rand(1,ma))+g1('edge_min_cap')+33*ones(1,ma);
g1('edge_cost')=round(10*rand(1,ma))+ones(1,ma);
[c,phi,flag]=min_lcost_flow1(g1);
if flag==1 then break; end;
end;
x_message(['The cost is: '+string(c);
'Showing the flow on the arcs ']);
ii=find(phi<>0); edgecolor=phi; edgecolor(ii)=11*ones(ii);
g1('edge_color')=edgecolor;
edgefontsize=8*ones(1,ma); edgefontsize(ii)=18*ones(ii);
g1('edge_font_size')=edgefontsize;
g1('edge_label')=string(phi);
show_graph(g1,'rep');

See Also : min_lcost_cflow , min_lcost_flow2 , min_qcost_flow

10.0.647 min lcost ow2 minimum linear cost ow

CALLING SEQUENCE :
[c,phi,flag]=min_lcost_flow2(g)

PARAMETERS :
g : graph-list
c : value of cost
phi : row vector of the value of ow on the arcs ag : feasible problem ag (0 or 1)
DESCRIPTION :
min lcost flow2 computes the minimum linear cost ow in the network g. It returns the total
cost of the ows on the arcs c and the row vector of the ows on the arcs phi. If the problem is
not feasible (impossible to nd a compatible ow for instance), flag is equal to 0, otherwise it is
equal to 1.
The bounds of the ow are given by the elements edge min cap and edge max cap of the
graph-list. The value of the minimum capacity must be equal to zero. The values of the maximum
capacity must be non negative and must be integer numbers. If the value of edge min cap or
edge max cap is not given (empty row vector []), it is assumed to be equal to 0 on each edge.
The costs on the edges are given by the element edge cost of the graph-list. The costs must
be non negative and must be integer numbers. If the value of edge cost is not given (empty row
vector []), it is assumed to be equal to 0 on each edge.
Scilab Group September 1995 311
min qcost ow Scilab function
The demand on the nodes are given by the element node demand of the graph-list. The demands
must be integer numbers. Note that the sum of the demands must be equal to zero for the problem
to be feasible. If the value of node demand is not given (empty row vector []), it is assumed to be
equal to 0 on each node.
This functions uses a relaxation algorithm due to D. Bertsekas.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10 1 8];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1 12 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 221 316 318 316 143 214 321 217 126 215 80 330 437 439];
show_graph(gt,'rep');
g1=gt; ma=g1('arc_number'); n=g1('node_number');
g1('edge_min_cap')=0.*ones(1,ma);
while %T then
rand('uniform');
g1('edge_max_cap')=round(20*rand(1,ma))+20*ones(1,ma);
g1('edge_cost')=round(10*rand(1,ma)+ones(1,ma));
rand('normal');
dd=20.*rand(1,n)-10*ones(1,n);
dd=round(dd-sum(dd)/n*ones(1,n));
dd(n)=dd(n)-sum(dd);
g1('node_demand')=dd;
[c,phi,flag]=min_lcost_flow2(g1);
if flag==1 then break; end;
end;
x_message(['The cost is: '+string(c);
'Showing the flow on the arcs and the demand on the nodes']);
ii=find(phi<>0); edgecolor=phi; edgecolor(ii)=11*ones(ii);
g1('edge_color')=edgecolor;
edgefontsize=8*ones(1,ma); edgefontsize(ii)=18*ones(ii);
g1('edge_font_size')=edgefontsize;
g1('edge_label')=string(phi);
g1('node_label')=string(g1('node_demand'));
show_graph(g1,'rep');

See Also : min_lcost_cflow , min_lcost_flow1 , min_qcost_flow

10.0.648 min qcost ow minimum quadratic cost ow

CALLING SEQUENCE :
[c,phi,flag]=min_qcost_flow(eps,g)

PARAMETERS :
eps : scalar, precision
g : graph-list
c : value of cost
phi : row vector of the value of ow on the arcs ag : feasible problem ag (0 or 1)
DESCRIPTION :
min qcost flow computes the minimum quadratic cost ow in the network g. It returns the total
cost of the ows on the arcs c and the row vector of the ows on the arcs phi. eps is the precision
of the iterative algorithm. If the problem is not feasible (impossible to nd a compatible ow for
instance), flag is equal to 0, otherwise it is equal to 1.
Scilab Group September 1995 312
metanet Scilab function
The bounds of the ow are given by the elements edge min cap and edge max cap of the
graph-list. The value of the maximum capacity must be greater than or equal to the value of the
minimum capacity. If the value of edge min cap or edge max cap is not given (empty row vector
[]), it is assumed to be equal to 0 on each edge.
The costs on the edges are given by the elements edge q orig and edge q weight of the
graph-list. The cost on arc u is given by:
(1/2)*edge q weight[u](phi[u]-edge q orig[u])^2 The costs must be non negative. If the
value of edge q orig or edge q weight is not given (empty row vector []), it is assumed to be
equal to 0 on each edge.
This function uses an algorithm due to M. Minoux.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10 1 8];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1 12 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 221 316 318 316 143 214 321 217 126 215 80 330 437 439];
show_graph(gt,'rep');
g1=gt; ma=g1('arc_number');
rand('uniform');
while %T then
g1('edge_min_cap')=round(5*rand(1,ma));
g1('edge_max_cap')=round(20*rand(1,ma))+30*ones(1,ma);
g1('edge_q_orig')=0*ones(1,ma);
g1('edge_q_weight')=ones(1,ma);
[c,phi,flag]=min_qcost_flow(0.001,g1);
if flag==1 then break; end;
end;
x_message(['The cost is: '+string(c);
'Showing the flow on the arcs']);
ii=find(phi<>0); edgecolor=phi; edgecolor(ii)=11*ones(ii);
g1('edge_color')=edgecolor;
edgefontsize=8*ones(1,ma); edgefontsize(ii)=18*ones(ii);
g1('edge_font_size')=edgefontsize;
g1('edge_label')=string(phi);
show_graph(g1,'rep');

See Also : min_lcost_cflow , min_lcost_flow1 , min_lcost_flow2

10.0.649 min weight tree minimum weight spanning tree

CALLING SEQUENCE :
[t] = min_weight_tree([i],g)

PARAMETERS :
i : integer, node number of the root of the tree
g : graph-list
t : row vector of integer numbers of the arcs of the tree if it exists
DESCRIPTION :
min weight tree tries to nd a minimum weight spanning tree for the graph g. The optional
argument i is the number of the root node of the tree ; its default value is node number 1. This
node is meaningless for an undirected graph.
The weights are given by the element edge weight of the graph-list. If its value is not given
(empty vector []), it is assumed to be equal to 0 on each edge. Weigths can be positive, equal to
Scilab Group September 1995 313
nodes 2 path Scilab function
0 or negative. To compute a spanning tree without dealing with weights, give to weights a value
of 0 on each edge or the empty vector [].
min weight tree returns the tree t as a row vector of the arc numbers (directed graph) or
edge numbers (undirected graph) if it exists or the empty vector [] otherwise. The numbers in
this vector are in random order.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
t=min_weight_tree(1,gt);
g1=gt; ma=g1('arc_number'); n=g1('node_number');
nodetype=0*ones(1,n); nodetype(1)=2; g1('node_type')=nodetype;
edgecolor=1*ones(1,ma); edgecolor(t)=11*ones(t); g1('edge_color')=edgecolor;
edgewidth=1*ones(1,ma); edgewidth(t)=4*ones(t); g1('edge_width')=edgewidth;
x_message('Minimum weight tree from node 1');
show_graph(g1,'rep');

10.0.650 netwindow choose a Metanet window

CALLING SEQUENCE :
netwindow(window)

PARAMETERS :
window : integer, window number
DESCRIPTION :
This function is used to change the Metanet window. Each Metanet window has a window
number returned by the metanet function. To use the Metanet window associated to window
number window, use netwindow(window). The numbers of existing windows are given by the
function netwindows.
See Also : metanet, netwindows
10.0.651 netwindows get the numbers of Metanet windows
CALLING SEQUENCE :
[l] = netwindows()

PARAMETERS :
l : list
DESCRIPTION :
This function returns a list l. Its rst element is the row vector of all the Metanet windows and
the second element is the number of the current Metanet window. This number is equal to 0 if no
current Metanet window exists.
See Also : metanet, netwindow
Scilab Group September 1995 314
path 2 nodes Scilab function
10.0.652 nodes 2 path path from a set of nodes
CALLING SEQUENCE :
[p] = nodes_2_path(ns,g)

PARAMETERS :
ns : row vector of integer numbers of the set of nodes
g : graph-list
p : row vector of integer numbers of the arcs of the path if it exists
DESCRIPTION :
nodes 2 path returns the path p corresponding to the node sequence ns given by its node num-
bers if it exists ; it returns the empty vector [] otherwise.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
ns=[1 10 15 16 17 14 11 12 13 9 7 8 6];
g1=gt; nodecolor=1*ones(gt('node_x')); nodecolor(ns)=11*ones(ns);
g1('node_color')=nodecolor;
show_graph(g1,'rep'); show_nodes(ns);
p=nodes_2_path(ns,gt);
g1=gt; edgecolor=1*ones(ta); edgecolor(p)=11*ones(p);
g1('edge_color')=edgecolor;
show_graph(g1,'rep'); show_arcs(p);
show_nodes(ns,'sup');

See Also : path_2_nodes

10.0.653 path 2 nodes set of nodes from a path

CALLING SEQUENCE :
[ns]=path_2_nodes(p,g)

PARAMETERS :
p : row vector of integer numbers of the arcs of the path
g : graph-list
ns : row vector of integer numbers of the set of nodes
DESCRIPTION :
path 2 nodes returns the set of nodes ns corresponding to the path p given by its arc numbers
; if p is not a path, the empty vector [] is returned.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');

Scilab Group September 1995 315

plot graph1 Scilab Function
p=[2 16 23 25 26 22 17 18 19 13 10 11];
g1=gt; edgecolor=1*ones(ta); edgecolor(p)=11*ones(p);
g1('edge_color')=edgecolor;
show_graph(g1,'rep'); show_arcs(p);
ns=path_2_nodes(p,gt);
g1=gt; nodecolor=1*ones(g1('node_number')); nodecolor(ns)=11*ones(ns);
g1('node_color')=nodecolor;
show_graph(g1,'rep');show_nodes(ns);
show_arcs(p,'sup');

See Also : nodes_2_path

10.0.654 plot graph plot a graph

CALLING SEQUENCE :
plot_graph(g,[orx,ory,w,h])

PARAMETERS :
g : graph-list
orx,ory,w,h : real values dening the plotting rectangle
DESCRIPTION :
Simple plot of a graph with only simple nodes and arcs (without arrows, loops and multiple
arcs). The size of the plot is automatically computed with the coordinates of the nodes. The
optional parameters [orx,ory,w,h] (upper-left point, width, height) dene a rectangle for a better
denition of the window or for zooming on a part of the graph
EXAMPLE :
// simple graph for comparing plot_graph, plot_graph1 and plot_graph2
ta=[2 2 1 1 2 4 3 3 4];
he=[2 2 3 2 3 2 1 2 1];
g=make_graph('foo',1,4,ta,he);
g('node_type')=[1 1 1 2];
g('node_x')=[73 737 381 391]; g('node_y')=[283 337 458 142];
g('node_color')=[3 3 3 11];
g('node_diam')=[30 30 30 60];
g('edge_color')=[10 0 2 6 11 11 0 0 11];
xbasc();
plot_graph(g);
x_message('plot_graph');
xbasc();
plot_graph1(g);
x_message('plot_graph1');
xbasc();
plot_graph2(g);
x_message('plot_graph2');
xbasc();
plot_graph2(g,200,-470,350,450);

See Also : plot_graph1 , plot_graph2

Scilab Group September 1995 316

plot graph2 Scilab Function
10.0.655 plot graph1 plot a graph
CALLING SEQUENCE :
plot_graph1(g,[orx,ory,w,h])

PARAMETERS :
g : graph-list
orx,ory,w,h : real values dening the plotting rectangle
DESCRIPTION :
Plot of a graph with dierent types of nodes, multiple arcs and loops (without arrows). The size
of the plot is automatically computed with the coordinates of the nodes. The optional parameters
[orx,ory,w,h] (upper-left point, width, height) dene a rectangle for a better denition of the
window or for zooming on a part of the graph
EXAMPLE :
// simple graph for comparing plot_graph, plot_graph1 and plot_graph2
ta=[2 2 1 1 2 4 3 3 4];
he=[2 2 3 2 3 2 1 2 1];
g=make_graph('foo',1,4,ta,he);
g('node_type')=[1 1 1 2];
g('node_x')=[73 737 381 391]; g('node_y')=[283 337 458 142];
g('node_color')=[3 3 3 11];
g('node_diam')=[30 30 30 60];
g('edge_color')=[10 0 2 6 11 11 0 0 11];
xbasc();
plot_graph(g);
x_message('plot_graph');
xbasc();
plot_graph1(g);
x_message('plot_graph1');
xbasc();
plot_graph2(g);
x_message('plot_graph2');
xbasc();
plot_graph2(g,200,-470,350,450);

See Also : plot_graph , plot_graph2

10.0.656 plot graph2 plot a graph

CALLING SEQUENCE :
plot_graph2(g,[orx,ory,w,h])

PARAMETERS :
g : graph-list
orx,ory,w,h : real values dening the plotting rectangle
DESCRIPTION :
Plot of a graph. The size of the plot is automatically computed with the coordinates of the nodes.
The optional parameters [orx,ory,w,h] (upper-left point, width, height) dene a rectangle for a
better denition of the window or for zooming on a part of the graph
EXAMPLE :
Scilab Group September 1995 317
shortest path Scilab function
// simple graph for comparing plot_graph, plot_graph1 and plot_graph2
ta=[2 2 1 1 2 4 3 3 4];
he=[2 2 3 2 3 2 1 2 1];
g=make_graph('foo',1,4,ta,he);
g('node_type')=[1 1 1 2];
g('node_x')=[73 737 381 391]; g('node_y')=[283 337 458 142];
g('node_color')=[3 3 3 11];
g('node_diam')=[30 30 30 60];
g('edge_color')=[10 0 2 6 11 11 0 0 11];
xbasc();
plot_graph(g);
x_message('plot_graph');
xbasc();
plot_graph1(g);
x_message('plot_graph1');
xbasc();
plot_graph2(g);
x_message('plot_graph2');
xbasc();
plot_graph2(g,200,-470,350,450);

See Also : plot_graph , plot_graph1

10.0.657 save graph save a graph

CALLING SEQUENCE :
save_graph(g,path)

PARAMETERS :
g : graph-list
name : string, the path of the graph to save
DESCRIPTION :
save graph saves the graph g in a graph le. path is the name of the graph le where the graph
will be saved. path can be the name or the pathname of the le ; if the "graph" extension is
missing in path, it is assumed. If path is the name of a directory, the name of the graph is used
as the name of the le.
EXAMPLE :
g=load_graph(SCI+'/demos/metanet/mesh100');
show_graph(g,'rep');
unix('rm mymesh100.graph')
save_graph(g,'mymesh100.graph');
g=load_graph('mymesh100');
show_graph(g,'new');

See Also : load_graph

10.0.658 shortest path shortest path

CALLING SEQUENCE :
[p,lp] = shortest_path(i,j,g,[typ])

PARAMETERS :
Scilab Group September 1995 318
show arcs Scilab function
i : integer, number of start node
j : integer, number of end node
g : graph-list
typ : string, type of shortest path
p : row vector of integer numbers of the arcs of the shortest path if it exists
lp : length of shortest path
DESCRIPTION :
shortest path returns the shortest path p from node i to node j if it exists, and the empty
vector [] otherwise. The optional argument typ is a string which denes the type of shortest
path, 'arc' for the shortest path with respect to the number of arcs and 'length' for the shortest
path with respect to the length of the edges edge length.
For the shortest path with respect to the length of the edges, the lengths are given by the
element edge length of the graph-list. If its value is not given (empty vector []), it is assumed
to be equal to 0 on each edge. Lengths can be positive, equal to 0 or negative.
When a shortest path exists, lp is the length of this path.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15 14 9 11 10];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14 4 6 9 1];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[194 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[56 181 276 278 276 103 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
g1=gt;ma=prod(size(g1('head')));
rand('uniform');
g1('edge_length')=int(20*rand(1,ma));
[p,lp]=shortest_path(13,1,g1,'length');
p
x_message(['Showing the arcs of the shortest path ';
'Choose ""Display arc names"" in the Graph menu to see arc names']);
g1('edge_name')=string(g1('edge_length'));
edgecolor=ones(1:ma);edgecolor(p)=11*ones(p);
g1('edge_color')=edgecolor;
edgefontsize=12*ones(1,ma);edgefontsize(p)=18*ones(p);
g1('edge_font_size')=edgefontsize;
show_graph(g1,'rep');

See Also : find_path , nodes_2_path

10.0.659 show arcs highlight a set of arcs

CALLING SEQUENCE :
show_arcs(p,[sup])

PARAMETERS :
p : row vector of arc numbers (directed graph) or edge numbers (undirected graph)
sup : string, superposition ag
DESCRIPTION :
show arcs highlights the set of arcs or edges p of the displayed graph in the current Metanet
window. If the optional argument sup is equal to the string 'sup', the highlighting is superposed
on the previous one.
EXAMPLE :
Scilab Group September 1995 319
show nodes Scilab function
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
t=min_weight_tree(1,gt); g1=gt; ma=g1('edge_number');
edgecolor=1*ones(1,ma); g1('edge_color')=edgecolor;
edgewidth=1*ones(1,ma); edgewidth(t)=4*ones(t); g1('edge_width')=edgewidth;
for i=8:12,
edgecolor(t)=i*ones(t); g1('edge_color')=edgecolor;
unix('sleep 2'); show_graph(g1,'rep');
show_arcs(t);
end;

See Also : show_nodes

10.0.660 show graph display a graph

CALLING SEQUENCE :
show_graph(g,[mode,scale])

PARAMETERS :
g : graph-list
mode : string, mode value
scale : real value, scale factor
DESCRIPTION :
show graph displays the graph g in the current Metanet window. If there is no current Metanet
window, a Metanet window is created. If there is already a graph displayed in the current Metanet
window, the optional argument mode must be equal to the string 'rep' to display the new graph
instead. If the optional argument mode is equal to the string 'new', a new Metanet window is
created. The optional argument scale is the value of the scale factor when drawing the graph.
The default value is 1.
The labels of the nodes and edges, if they exist, are displayed.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep',2);
show_graph(gt,'rep',0.5);
show_graph(gt,'rep',1);

10.0.661 show nodes highlight a set of nodes

CALLING SEQUENCE :
show_nodes(nodes,[sup])

PARAMETERS :
nodes : row vector of node numbers
Scilab Group September 1995 320
strong connex Scilab function
sup : string, superposition ag
DESCRIPTION :
show nodes highlights the set of nodes nodes of the displayed graph in the current Metanet
window. If the optional argument sup is equal to the string 'sup', the highlighting is superposed
on the previous one.
EXAMPLE :
ta=[1 1 2 2 2 3 4 5 5 7 8 8 9 10 10 10 11 12 13 13 13 14 15 16 16 17 17];
he=[2 10 3 5 7 4 2 4 6 8 6 9 7 7 11 15 12 13 9 10 14 11 16 1 17 14 15];
gt=make_graph('foo',1,17,ta,he);
gt('node_x')=[283 163 63 57 164 164 273 271 339 384 504 513 439 623 631 757 642];
gt('node_y')=[59 133 223 318 227 319 221 324 432 141 209 319 428 443 187 151 301];
show_graph(gt,'rep');
for i=2:3:gt('node_number'), show_nodes([i]); end;
for i=1:3:gt('node_number'), show_nodes([i],'sup'); end;

See Also : show_arcs

10.0.662 strong con nodes set of nodes of a strong connected

component
CALLING SEQUENCE :
[ns] = strong_con_nodes(i,g)

PARAMETERS :
i : integer, number of the strong connected component
g : graph-list
ns : row vector, node numbers of the strong connected component
DESCRIPTION :
strong con nodes returns the row vector ns of the numbers of the nodes which belong to the
strong connected component number i.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[197 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[76 181 276 278 276 83 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
ncomp=strong_con_nodes(3,gt);
n=gt('node_number');
nodecolor=0*ones(1,n); nodecolor(ncomp)=11*ones(ncomp);
gt('node_color')=nodecolor;
nodediam=20*ones(1,n); nodediam(ncomp)=40*ones(ncomp);
gt('node_diam')=nodediam;
x_message('Set of nodes of the strong connected component #3');
show_graph(gt,'rep');

See Also : connex , con_nodes , strong_connex

Scilab Group September 1995 321

trans closure Scilab function
10.0.663 strong connex strong connected components
CALLING SEQUENCE :
[nc,ncomp] = strong_connex(g)

PARAMETERS :
g : graph-list
nc : integer, number of strong connected components
ncomp : row vector of strong connected components
DESCRIPTION :
strong connex returns the number nc of strong connected components for the graph g and a row
vector ncomp giving the number of the strong connected component for each node. For instance,
if i is a node number, ncomp[i] is the number of the strong connected component to which node
i belongs.
EXAMPLE :
ta=[1 1 2 2 2 3 4 4 5 6 6 6 7 7 7 8 9 10 12 12 13 13 13 14 15];
he=[2 6 3 4 5 1 3 5 1 7 10 11 5 8 9 5 8 11 10 11 9 11 15 13 14];
gt=make_graph('foo',1,15,ta,he);
gt('node_x')=[197 191 106 194 296 305 305 418 422 432 552 550 549 416 548];
gt('node_y')=[76 181 276 278 276 83 174 281 177 86 175 90 290 397 399];
show_graph(gt,'rep');
[nc,ncomp]=strong_connex(gt);
g1=gt; g1('node_color')=8+ncomp; g1('node_diam')=10+5*ncomp;
x_message('Connected components of the graph');
show_graph(g1,'rep');

See Also : ,
connex con_nodes , strong_con_nodes

10.0.664 trans closure transitive closure

CALLING SEQUENCE :
g1 = trans_closure(g)

PARAMETERS :
g : graph-list
g1 : graph-list
DESCRIPTION :
trans closure returns as a new graph-list g1 the transitive closure of the graph g. This graph
must be directed and connected. If <name> if the name of graph g, <name> trans closure is
the name of the transitive closure.
EXAMPLE :
ta=[2 3 3 5 3 4 4 5 8];
he=[1 2 4 2 6 6 7 7 4];
gt=make_graph('foo',1,8,ta,he);
gt('node_x')=[129 200 283 281 128 366 122 333];
gt('node_y')=[61 125 129 189 173 135 236 249];
show_graph(gt,'rep');
g1=trans_closure(gt);
vv=1*ones(ta); aa=sparse([ta' he'],vv');
ta1=g1('tail'); he1=g1('head');

Scilab Group September 1995 322

trans closure Scilab function
ww=1*ones(ta1); bb=sparse([ta1' he1'],ww');
dif=bb-aa; lim=size(ta1); edgecolor=0*ones(ta1);
for i=1:lim(2)
if dif(ta1(i),he1(i))==1 then edgecolor(i)=11; end;
end;
g1('edge_color')=edgecolor;
x_message('Transitive closure of the graph');
show_graph(g1,'rep');

Scilab Group September 1995 323

trans closure Scilab function

Scilab Group September 1995 324

Chapter 11

Scicos

325
CLKOUT f Scicos Block
11.0.665 ABSBLK Scicos abs block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. This xes the number of inputs and outputs.
DESCRIPTION :
This block realizes vector absolute value operation.

11.0.666 ANIMXY Scicos visualization block

DESCRIPTION :
This block realizes the visualization of the evolution of the two regular input signals by drawing
the second input as a function of the rst at instants of events on the event input port.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Curve colors : an integer. It is the color number (<0) or marker type (>0) used to draw the
evolution of the input port signal. See plot2d for color (dash type) denitions.
Line or mark size : an integer.
Output window number : The number of graphic window used for the display. It is often good
to use high values to avoid con ict with palettes and Super Block windows. If you have more
than one scope, make sure they don't have the same window numbers (unless superposition
of the curves is desired).
Xmin, Xmax : Minimum and maximum values of the rst input; used to set up the X-axis of the
plot in the graphics window.
Ymin, Ymax : Minimum and maximum values of the second input; used to set up the Y-axis of
the plot in the graphics window.
Buffer size : an integer. The number of points visible at any time.

See Also : SCOPE_f EVENTSCOPE_f SCOPXY_f

11.0.667 CLINDUMMY Scicos dummy continuous system with state

DESCRIPTION :
This block should be placed in any block diagram that contains a treshold block but no continuous
system with state. The reason for that is that it is the ode solver that nd zero crossing surfaces.

11.0.668 CLKIN Scicos Super Block event input port

DESCRIPTION :
This block must only be used inside Scicos Super Blocks to represent an event input port.
In a Super Block, the event input ports must be numbered from 1 to the number of event input
ports.
DIALOG PARAMETERS :
Input name : A string dening the block label. This label is placed under the block.
Port number : an integer dening the port number.
See Also : IN_f OUT_f CLKOUT_f

Scilab Group Janvier 1996 326

CLSS f Scicos Block
11.0.669 CLKOUT Scicos Super Block event output port
DESCRIPTION :
This block must only be used inside Scicos Super Blocks to represent an event output port.
In a Super Block, the event output ports must be numbered from 1 to the number of event output
ports.
DIALOG PARAMETERS :
Output name : A string dening the block label. This label is placed under the block.
Port number : an integer giving the port number.
See Also : IN_f OUT_f CLKIN_f

11.0.670 CLKSOM Scicos event addition block

DESCRIPTION :
This block is a clock sum with up to three inputs. The output reproduces the events on all
the input ports. Strictly speaking, CLKSOM is not a Scicos block because it is discarded at the
compilation phase. The inputs and output of CLKSOM are synchronized (this is impossible for
other basic blocks in Scicos).
11.0.671 CLOCK Scicos event clock
DESCRIPTION :
This block is a Super Block constructed by feeding back the output of an event delay block into
its input event port. The unique output of this block generates a regular train of events.
DIALOG PARAMETERS :
Period : scalar. One over the frequency of the clock. Period is the time that separates two
output events.
See Also : EVTDLY_f

11.0.672 CLR Scicos continuous-time linear system (transfer

function)
DESCRIPTION :
This block realizes a SISO linear system represented by its rational transfer function (in the
symbolic variable s). The rational function must be proper.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Numerator : a polynomial in s.
Denomiator : a polynomial in s.
See Also : CLSS_f INTEGRAL_f

11.0.673 CLSS Scicos continuous-time linear state-space system

DESCRIPTION :
This block realizes a continuous-time linear state-space system. The system is dened by the
(A,B,C,D) matrices and the initial state x0. The dimensions must be compatible.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
A : square matrix. The A matrix
Scilab Group Janvier 1996 327
DLSS f Scicos Block
B : the B matrix
C : the C matrix
D : the D matrix
x0 : vector. The initial state of the system.
See Also : CLR_f INTEGRAL_f

11.0.674 CONST Scicos constant value(s) generator

DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
constants : a real vector. The vector size gives the number of output ports. The value
constants(i) is assigned to the ith port. Note that output ports are numbered from top to
bottom.
DESCRIPTION :
This block is a constant value(s) generator.
11.0.675 COSBLK Scicos cosine block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. This xes the number of inputs and outputs.
DESCRIPTION :
This block realizes vector cosine operation.
11.0.676 TANBLK Scicos delay block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Register initial condition : a vector. The initial condition of the regsiter used to store past
values of the input.
Period : a scalar. The period of the clock which coresponds to the discretization step.

DESCRIPTION :
This block realizes an approximate delay operation. The output at t is a discretized (piecewise
constant with discretization step equal to Period) version of the input at t-dt where dt equals
Period times the size of the Register.
11.0.677 DLR Scicos discrete-time linear system (transfer function)
DESCRIPTION :
This block realizes a SISO linear system represented by its rational transfer function (in the sym-
bolic variable z). The rational function must be proper. If it is not proper, the direct feedthrough
make the output depend continuously on the input, so if the input is not the output of a discrete
block, it may not be piece-wise constant.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Numerator : a polynomial in z.
Denomiator : a polynomial in z.
See Also : DLSS_f REGISTER_f

Scilab Group Janvier 1996 328

EVTGEN f Scicos Block
11.0.678 DLSS Scicos discrete-time linear state-space system
DESCRIPTION :
This block realizes a discrete-time linear state-space system. The system is dened by the
(A,B,C,D) matrices and the initial state x0. The dimensions must be compatible. At the ar-
rival of an input event on the unique input event port, the state is updated. If D is not zero, the
the output depends directly on the input, so if the input is not the output of a discrete block, it
may not be piecewise constant.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
A : square matrix. The A matrix
B : the B matrix
C : the C matrix
x0 : vector. The initial state of the system.
See Also : CLR_f INTEGRAL_f
11.0.679 EVENTFSCOPE Scicos visualization block
DESCRIPTION :
This block allows the visualization of event signals on its event input port(s).
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Number of inputs : an integer, the number of event input ports.
Curve colors : a vector of integers. The i-th element is the color number (<0) or dash type
(>0) used to draw the evolution of the i-th input port signal. See plot2d for color (dash
type) denitions.
Output window number : The number of graphic window used for the display. It is often good
to use high values to avoid con ict with palettes and Super Block windows. If you have more
than one scope, make sure they don't have the same window numbers (unless superposition
of the curves is desired).
Refresh period : Maximum value on the X-axis (time). The plot is redrawn when time reaches
a multiple of this value.
See Also : SCOPXY_f SCOPE_f ANIMXY_f
11.0.680 EVTDLY Scicos event delay block
DESCRIPTION :
One event is generated dt after an event enters the unique input event port. The output can be
initially red or not.
DIALOG PARAMETERS :
Block label : string. The block label is placed under the block.
Delay: scalar. dt.
Auto-exec : 0 or 1. 1 if initially red.
See Also : CLOCK_f
11.0.681 EVTGEN Scicos event ring block
DESCRIPTION :
One event is generated on the unique output event port. The time of this event is t if t is larger
tan equal to zero, if not, no event is generated.
DIALOG PARAMETERS :
Scilab Group Janvier 1996 329
STOP f Scicos Block
Block label : string. The block label is placed under the block.
Event time : scalar. t.
See Also : CLOCK_f

11.0.682 GAIN Scicos gain block

DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Gain : a matrix.
DESCRIPTION :
This block is a gain block. The output is the Gain times the regular input (vector). The dimensions
of Gain determines the number of inputs and outputs.

11.0.683 GENERAL Scicos general zero crossing detector

DESCRIPTION :
Depending on the sign (just before the crossing) of the inputs and the input numbers of the inputs
that have crossed zero, an event is programmed (or not) with a given delay, for each output. The
number of combinations grows so fast that this becomes unusable for blocks having more than 2
or 3 inputs. For the moment this block is not documented.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Number of regular inputs : integer.
Number of output events : integer.
the routing matrix : matrix. number of rows is the number of output events. The columns
correspond to each possible combination of signs and zero crossings of the inputs. The entries
of the matrix give the delay for generating the output event (<0 no event is generated).
See Also : NEGTOPOS_f POSTONEG_f ZCROSS_f

11.0.684 GENSIN Scicos sinusoid generator

DESCRIPTION :
This block is a sine wave generator: M*sin(F*t+P)
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Magnitude : a scalar. The magnitude M.
Frequency : a scalar. The frequency F.
Phase : a scalar. The phase P.
See Also : GENSQR_f RAND_f SAWTOOTH_f

11.0.685 GENSQR Scicos square wave generator

DESCRIPTION :
This block is a square wave generator: output takes values 0 and M. Everytime an event is received
on the input event port, the output switches from 0 to M, or M to 0.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Scilab Group Janvier 1996 330
MCLOCK f Scicos Block
dt : a scalar. If 0, no ouput event port exists. If dt>0, an output event port exists. This port
is initially red and an event is generated dt after every input event. By feeding back this
event output to the event input, a self clocked square wave generator can be costructed.
Amplitude : a scalar M.

See Also : GENSIN_f SAWTOOTH_f RAND_f

11.0.686 CLOCK Scicos Stop block

DIALOG PARAMETERS :
Block label : string. Label to be placed under the block.
State on halt : scalar. A value to be placed in the state of the block. For debugging purposes
this allows to distinguish between dierent halts.
DESCRIPTION :
This block has a unique input event port. Upon the arrival of an event, the simulation is stoped
and the main Scicos window is activated. Simulation can be restarted or continued (Run button).
11.0.687 IFTHEL Scicos if then else block
DIALOG PARAMETERS :
Block label : string. The block label is placed under the block.
DESCRIPTION :
One event is generated on one of the output event ports when an input event arrives. Depending
on the sign of the regular input, the event is generated on the rst or second output.
11.0.688 INTEGRAL Scicos simple integrator
DESCRIPTION :
This block is an integrator. The output is the integral of the input.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Initial state : a scalar. The initial condition of the integrator.
See Also : CLSS_f CLR_f

11.0.689 OUT Scicos Super Block regular output port

DESCRIPTION :
This block must only be used inside Scicos Super Blocks to represent a regular output port.
In a Super Block, regular output ports must be numbered from 1 to the number of regular output
ports.
DIALOG PARAMETERS :
Output name : A string dening the block label. This label is placed under the block.
Port number : an integer giving the port number.
See Also : CLKIN_f IN_f CLKOUT_f

11.0.690 LOOKUP Scicos Lookup table with graphical editor

DESCRIPTION :
This block realizes a non-linear function dened using a graphical editor.
Scilab Group Janvier 1996 331
RAND f Scicos Block
11.0.691 MCLOCK Scicos 2 frequency event clock
DESCRIPTION :
This block is a Super Block constructed by feeding back the outputs of an MFCLCK block into its
input event port. The two outputs of this block generate regular train of events, the frequency of
the rst input being equal to that of the second output diveided by an integer n. The two outputs
are synchronized (this is impossible for standard blocks; this is a Super Block).
DIALOG PARAMETERS :
Block label : This has no eect on this Super Block
Basic period : scalar. equals 1/f, f being the highest frequency.
n : an intger >1. the frequency of the rst output event is f/n.
See Also : MFCLCK_f CLOCK_f

11.0.692 MFCLCK Scicos basic block for frequency division of event

clock
DESCRIPTION :
This block is used in the Super Block MCLOCK. The input event is directed once evry n times to
output 1 and the rest of the time to output 2. There is a delay of "Basic period" in the transmission
of the event. If this period >0 then the second output is initially red. It is not if this period=0.
In the latter case, the input is driven by an event clock and in the former case, feedback can be
used.
DIALOG PARAMETERS :
Block label : This has no eect on this Super Block
Basic period : scalar.
n : an intger >1.
See Also : MCLOCK_f CLOCK_f

11.0.693 NEGTOPOS Scicos negative to positive detector

DESCRIPTION :
An output event is generated when the unique input crosses zero with a positive derivative.
See Also : POSTONEG_f ZCROSS_f GENERAL_f

11.0.694 POSTONEG Scicos positive to negative detector

DESCRIPTION :
An output event is generated when the unique input crosses zero with a negative derivative.
See Also : NEGTOPOS_f ZCROSS_f GENERAL_f

11.0.695 PROD Scicos product blocl

DESCRIPTION :
The output is the product of the two inputs.
Scilab Group Janvier 1996 332
SAT f Scicos Block
11.0.696 RAND Scicos random wave generator
DESCRIPTION :
This block is a random wave generator: output takes piecewise constant random values. Everytime
an event is received on the input event port, the output takes a new independent random value.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
flag : 0 or 1. 0 for uniform distribution on [A,A+B] and 1 for normal distribution N(A,B*B).
A : scalar
B : scalar
dt : a scalar. If 0, no ouput event port exists. If dt>0, an output event port exists. This port
is initially red and an event is generated dt after every input event. By feeding back this
event output to the event input, a self clocked random wave generator can be constructed.
Amplitude : a scalar M.

See Also : GENSIN_f SAWTOOTH_f GENSQR_f

11.0.697 REGISTER Scicos shift register block

DESCRIPTION :
This block realizes a shift register. At every input event, the register is shifted one step.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Initial condition : a column vector. It contains the initial state of the register.
See Also : DLSS_f DLR_f

11.0.698 RFILE Scicos "read from le" block

DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Time record Selection : an empty matrix or a positive integer. If an integer i is given the
ith element of the read record is assumed to be the date of the output event. If empty no
output event exists.
Output record selection : a vector of positive integer. [k1,..,kn],The kith element of the
read record gives the value of ith output.
number of inputs : a scalar. This xes the number of "value" output
Input file name : a character string dening the path of the le
Input Format : a character string dening the Fortran format to use or nothing for an unfor-
matted (binary) write
Buffer size : To improve eciency it is possible to buer the input data. read on the le is
only done after each Buffer size call to the block.
DESCRIPTION :
This block allows user to read datas in a le, in formatted or binary mode. Output record
selection and Time record Selection allows the user to select data among le records.
Each call to the block advance one record in the le.
See Also : WFILE_f
Scilab Group Janvier 1996 333
SCOPXY f Scicos Block
11.0.699 SAT Scicos Saturation block
DESCRIPTION :
This block realizes the non-linear function: saturation.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
Min : a scalar. Lower saturation bound
Max : a scalar. Upper saturation bound
Slope : a scalar. The slope of the line going through the origin and describing the behavior of
the function around zero.
See Also : LOOKUP_f

11.0.700 SAWTOOTH Scicos sawtooth wave generator

DESCRIPTION :
This block is a sawtooth wave generator: output is (t-t i) from ti to t (i+1) where t i and t (i+1)
denote the times of two successive input events.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
dt : a scalar. If 0, no ouput event port exists. If dt>0, an output event port exists. This port
is initially red and an event is generated dt after every input event. By feeding back this
event output to the event input, a self clocked sawtooth wave generator can be costructed.
See Also : GENSIN_f GENSQR_f RAND_f

11.0.701 SCOPE Scicos visualization block

DESCRIPTION :
This block realizes the visualization of the evolution of the signals on the standard input port(s)
at instants of events on the event input port.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Number of inputs : an integer, the number of input ports
Curve colors : a vector of integers. The i-th element is the color number (<0) or dash type
(>0) used to draw the evolution of the i-th input port signal. See plot2d for color (dash
type) denitions.
Output window number : The number of graphic window used for the display. It is often good
to use high values to avoid con ict with palettes and Super Block windows. If you have more
than one scope, make sure they don't have the same window numbers (unless superposition
of the curves is desired).
Ymin, Ymax : Minimum and maximum values of the input; used to set up the Y-axis of the plot
in the graphics window.
Refresh period : Maximum value on the X-axis (time). The plot is redrawn when time reaches
a multiple of this value.
Buffer size : To improve eciency it is possible to buer the input data. The drawing is only
done after each Buffer size call to the block.
dt : If dt is 0, time is used for the X-axis (normal operation). If dt is not zero, the x-axis advances
by dt everytime an event arrives at the event input port.
See Also : SCOPXY_f EVENTSCOPE_f ANIMXY_f

Scilab Group Janvier 1996 334

STOP f Scicos Block
11.0.702 SCOPXY Scicos visualization block
DESCRIPTION :
This block realizes the visualization of the evolution of the two regular input signals by drawing
the second input as a function of the rst at instants of events on the event input port.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Curve colors : an integer. It is the color number (<0) or dash type (>0) used to draw the
evolution of the input port signal. See plot2d for color (dash type) denitions.
Line or mark size : an integer.
Output window number : The number of graphic window used for the display. It is often good
to use high values to avoid con ict with palettes and Super Block windows. If you have more
than one scope, make sure they don't have the same window numbers (unless superposition
of the curves is desired).
Xmin, Xmax : Minimum and maximum values of the rst input; used to set up the X-axis of the
plot in the graphics window.
Ymin, Ymax : Minimum and maximum values of the second input; used to set up the Y-axis of
the plot in the graphics window.
Buffer size : To improve eciency it is possible to buer the input data. The drawing is only
done after each Buffer size call to the block.
See Also : SCOPE_f EVENTSCOPE_f ANIMXY_f
11.0.703 SELECT Scicos select block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. Number of regular and event inputs.
initial connected input : a integer. It must be between 1 and the number of inputs.
DESCRIPTION :
The blocks routes one of the regular inputs to the unique regular output. the choice of which
input is to be routed is done, initially by the "initial connected input" parameter. Then, everytime
an input event arrives on the i-th input event port, the i-th regular input port is routed to the
regular output.
11.0.704 SINBLK Scicos sine block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. This xes the number of inputs and outputs.
DESCRIPTION :
This block realizes vector sine operation.
11.0.705 SOM Scicos addition block
DESCRIPTION :
This block is a sum. The output is the sum of the inputs.
DIALOG PARAMETERS :
Number of inputs : a scalar. Safe to leave at three even if you connect less inputs. More than
3 is not allowed. Use Gain for more inputs.
Input signs : a (1x3) vector of +1 and -1. If -1, the corresponding input is multipled by -1
before addition.
See Also : GAIN_f
Scilab Group Janvier 1996 335
TRASH f Scicos Block
11.0.706 CLOCK Scicos Stop block
DIALOG PARAMETERS :
Block label : string. Label to be placed under the block.
State on halt : scalar. A value to be placed in the state of the block. For debugging purposes
this allows to distinguish between dierent halts.
DESCRIPTION :
This block has a unique input event port. Upon the arrival of an event, the simulation is stoped
and the main Scicos window is activated. Simulation can be restarted or continued (Run button).
11.0.707 SUPER Scicos Super block
DESCRIPTION :
This block opens up a new Scicos window for editing a new block diagram. This diagram de-
scribes the internal functions of the super block. The number of inputs and outputs are adjusted
automatically based on the number of inputs and outputs blocks in the diagram.
11.0.708 TANBLK Scicos sine block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. This xes the number of inputs and outputs.
DESCRIPTION :
This block realizes vector tangent operation.
11.0.709 TCLSS Scicos jump continuous-time linear state-space
system
DESCRIPTION :
This block realizes a continuous-time linear state-space system with the possibility of jumps in
the state. The number of inputs to this block equals the number of inputs of the linear system
plus n the number of states of the linear system. When an event arrives at the unique event input
port of this block, the state of the system jumps to the value present on the last n inputs of the
block. The system is dened by the (A,B,C,D) matrices and the initial state x0. The dimensions
must be compatible. The number of inputs and outputs are adjusted automatically.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
A : square matrix. The A matrix
B : the B matrix
C : the C matrix
D : the D matrix
x0 : vector. The initial state of the system.
See Also : CLSS_f CLR_f
11.0.710 TIME Scicos time generator
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is placed under the block.
DESCRIPTION :
This block is a time generator. The unique regular output is the current time.
Scilab Group Janvier 1996 336
scicos Scicos GUI
11.0.711 TRASH Scicos Trash block
DIALOG PARAMETERS :
Block label : string. Label to be placed under the block.
Number of inputs : integer. The number of regular inputs. There is always one event input.
DESCRIPTION :
This block does nothing. It simply allows to safely connect the ouputs of other blocks which
should be ignored. This happens mostly for event outputs that should produce no action.
11.0.712 WFILE Scicos "write to le" block
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
number of inputs : a scalar. This xes the number of inputs
Output file name : a character string dening the path of the le
Output Format : a character string dening the Fortran format to use or nothing for an unfor-
matted (binary) write
Buffer size : To improve eciency it is possible to buer the input data. write on the le is
only done after each Buffer size call to the block.
DESCRIPTION :
This block allows user to save datas in a le, in formatted or binary mode. Each call to the block
corresponds to a record in the le. Each record has the following form: [t,V1,...,Vn] where t
is the value of time when block is called and Vi is the ith input value
See Also : RFILE_f
11.0.713 ZCROSS Scicos zero crossing detector
DESCRIPTION :
An output event is generated when all inputs (if more than one) cross zero simultaneously.
DIALOG PARAMETERS :
Block label : A string dening the block label. This label is written under the block.
Number of inputs : integer.
See Also : POSTONEG_f ZCROSS_f GENERAL_f

11.0.714 scicos Block diagram editor and GUI to hybrid simulator

scicosim
CALLING SEQUENCE :
sys=scicos([sys])
PARAMETERS :
sys : a Scicos data structure
DESCRIPTION :
scicos is a visual editor for constructing models of hybrid dynamical systems. Invoking scicos with
no argument opens up an empty scicos window. Models can then be assembled, loaded, saved,
compiled, simulated, using GUI of scicos. The input and ouput arguments are only useful for
debugging purposes. scicos serves as an interface to the various block diagram compilers and the
hybrid simulator scicosim. Here is a list of operations available in scicos:
Help : To get help on an object or menu buttons, click rst on Help button and then on the
selected object or menu item.
Scilab Group Janvier 1996 337
scicos Scicos GUI
Edit : Click on the Edit button to open the Edit menu.
Simulate.. : Click on the Simulate.. button to open the compilation/execution menu.
File.. : Click on the File.. button to open the le management menu.
View : To shift the diagram to left, right, up or down, click rst on the View button, then on a
point in the diagram where you want to appear in the middle of the graphics window.
Exit : Click on the Exit button to leave scicos and return to Scilab session. Save your diagram
before leaving Scicos or it will be lost.
Palettes : Click on the Palettes button to open a new palette.
Move : To move a block in main Scicos window, click rst on the Move button, then click on
the selected block, drag the mouse to the desired new block position and click again to x
the position. The lower left corner of the block is placed at the selected point.
Copy : To copy a block in main Scicos window Click rst on the Copy button, then click on the
to-be-copied block (in Scicos window or in a palette) , and nally click where you want the
copy to be placed in the Scicos window. The lower left corner of the block is placed at the
selected point.
Align : To obtain nice diagrams, you can align ports of dierent blocks, vertically and horizon-
tally. Click rst on the Align button, then on the rst port and nally on the second port.
The block corresponding to the second port is moved. A connected block cannot be aligned.
Link : To connect an output port to an input port, click rst on the Link button, then on the
output port and nally on the input port. To split a link, click rst on the Link button, then
on the link where the split should be placed, and nally on an input port. Only one link can
go from and to a port. Link color can be changed directly by clicking on the link.
Delete : To delete a block or a link, click rst on the Delete button, then on the selected object.
If you delete a block all links connected to it are deleted as well.
Flip : To reverse the positions of the (regular) inputs and outputs of a block placed on its sides,
click on the Flip button rst and then on the selected block. This does not aect the order,
nor the position of the input and output event ports which are numbered from left to right.
A connected block cannot be ipped.
Undo : Click on the Undo button to undo the last edit operation.
Replot : Click on the Replot button to replot the content of the graphics window. Graphics
window stores complete history of the editing session in memory.
Replot is usefull for cleaning this memory.
Back : Click on the Back button to go back to the main menu.
Compile : Click on the Compile button to compile the block diagram. This button need never
be used since compilation is performed automatically, if necessary, before the beginning of
every simulation (Run button).
Normally, a new compilation is not needed if only system parameters and internal states
are modied. In some cases howeever modications are not correctly updated and a manual
compilation may be needed before a Restart or a Continue. Please report if you encounter
such a case.
Run : Click on the Run button to start the simulation. If the system has already been simulated,
a dialog box appears where you can choose to Continue, Restart or End the simulation.
You may interrupt the simulation by clicking on the ""stop"" button, change any of the
block parameters and continue the simulation with the new values.
Save : Click on the save button to save the block diagram in a binary le already selected by a
previous click on the Save As button. If you click on this button and you have never clicked
on the Save As button, the diagram is saved in the current direcotry as <window name>.cos
where <window name> is the name of the window appearing on top of the window (usually
Untitled or Super Block).
Save As : Click on the Save As button to save the block diagram in a binary le. A dialog box
allows choosing the le which must have a .cos extension. The diagram takes the name of
the le (without the extension).
FSave : Click on the FSave button to save the diagram in a formatted ascii le. A dialog box
allows choosing the le which must have a .cosf extension.
Scilab Group Janvier 1996 338
scifunc block Scicos Block
Formatted save is slower than regular save but has the advantage that the generated le is
system independent (usefull for exchanging data on dierent computers.
Newblkn : Click on the Newblk button to save the Super Block as a new Scicos block. A Scilab
function is generated and saved in a le <window name>.sci in a user palette directory.
<window name> is the name of the Super Block appearing on top of the window. A dialog
allows choosing the palette directory. To make Scicos recognize your palettes, you should
dene the Scilab variable user pal dir as a column vector of strings containing the paths to
your palette directories. This can, for example, be done in your .scilab (user initialization)
le. You should also make sure the functions included in your palettes exists in Scilab
environment before using Scicos (lib or getf).
Load : Click on the Load button to load an ascii or binary le containing a saved block diagram.
A dialog box allows choosing the le.
Setup : In the main Scicos window, clicking on the Setup button invokes a dialog box that
allows you to change window dimensions, integration parameters: absolute and relative error
tolerances and the time tolerance (the smallest time interval for which the ode solver is used
to update continuous states), and the simulation mode (1 or 2). In a Super Block window,
clicking on this button invokes a dialog box that allows changing the window name (Super
Block name) and window dimensions.
New : Clicking on the New button loads an empty diagram in the main Scicos window. If the
previous content of the window is not saved, it will be lost.
See Also : scicosim
11.0.715 scifunc block Scicos block dened interactively
DESCRIPTION :
This block can realize any type of Scicos block. The function of the block is dened interactively
using dialog boxes and in Scilab language. During simulation, these instructions are interpreted by
Scilab; the simulation of diagrams that include these types of blocks is slower. For more information
see Scicos reference manual.
DIALOG PARAMETERS :
number of inputs : a scalar. Number of regular input ports
number of outputs : a scalar. Number of regular output ports
number of input events : a scalar. Number of input event ports
number of output events : a scalar. Number of output event ports
Initial continuous state : a column vector.
Initial discrete state : a column vector.
System type : a string: z if the block is zero crossing; anything else if it is a regular block (c or
d for example to specify continuous or discrete).
System parameter : column vector. Any parameters used in the block can be dened here a
column vector.
initial firing : vector. Size of this vector corresponds to the number of event outputs. The
value of the i-th entry species the time of the preprogrammed event ring on the i-th output
event port. If less than zero, no event is preprogrammed.
See Also : Sci_Block_f
11.0.716 scifunc block Scicos block dened interactively
DESCRIPTION :
This block can realize any type of Scicos block. The function of the block is dened interactively
using dialog boxes and in Scilab language. During simulation, these instructions are interpreted by
Scilab; the simulation of diagrams that include these types of blocks is slower. For more information
see Scicos reference manual.
DIALOG PARAMETERS :
Scilab Group Janvier 1996 339
scifunc block Scicos Block
number of inputs : a scalar. Number of regular input ports
number of outputs : a scalar. Number of regular output ports
number of input events : a scalar. Number of input event ports
number of output events : a scalar. Number of output event ports
Initial continuous state : a column vector.
Initial discrete state : a column vector.
System type : a string: z if the block is zero crossing; anything else if it is a regular block (c or
d for example to specify continuous or discrete).
System parameter : column vector. Any parameters used in the block can be dened here a
column vector.
initial firing : vector. Size of this vector corresponds to the number of event outputs. The
value of the i-th entry species the time of the preprogrammed event ring on the i-th output
event port. If less than zero, no event is preprogrammed.
See Also : Sci_Block_f

Scilab Group Janvier 1996 340

Chapter 12

Tools for dynamical systems

341
boucle Scilab Function
12.0.717 artest arnold dynamical system
CALLING SEQUENCE :
artest(f_l,[odem,xdim,npts])
arnold(t,x)
iarf([a])

PARAMETERS :
f l : can be "arnold" or arnold. It is the name of the external for the arnold system. If f l
is set to "arnold" a Fortran coded version of the arnold system where a(1:6)=1 will be used
and if f l is set to arnold a Scilab coded version will be used . arnold is a Scilab macro
coding the Arnold system. This macro is loaded when calling artest.
iarf : is used to x the values of a in the Scilab coded case. a is a vector of size 6.
odem,xdim,npts : are optional arguments. Their meaning and syntax can be found in the
portr3d help

DESCRIPTION :
A call to the function artest() will interactively display a phase portrait of a the following
dynamical system :
ydot(1)=a(1)*cos(y(2)) +a(2)*sin(y(3))
ydot(2)=a(3)*cos(y(3)) +a(4)*sin(y(1))
ydot(3)=a(5)*cos(y(1)) +a(6)*sin(y(2))

See Also : , ,
portr3d ode chaintest lotest ,
12.0.718 bish shows a bifurcation diagram in a sh population
discrete time model
CALLING SEQUENCE :
bifish([f_ch])

PARAMETERS :
f ch : can be one of fish, fishr and fishr2. This option selects the population model.
DESCRIPTION :
The dynamical system fish is the following :
y=b*exp(-0.1*(x(k)_1+x(k)_2));
x(k+1)=[ y 2*y ; s 0.0]*x(k);

and the parameters s evolves to show the bifurcation diagram. fishr and fishr2 are constructed
as above but with added white noises.
fishr
y=b*exp(-0.1*(xk(1)+xk(2)))
xkp1=[ y 2*y ; s*(1+0.1*(rand-0.5)) 0.0]*xk

fishr2
z=exp(-0.1*(xk(1)+xk(2)))
xkp1=[ b*z**(1+0.1*(rand-0.5)) 2*b*z**(1+0.1*(rand-0.5)) ; s 0.0]*xk

The three macros fish, fishr, fishr2 are loaded in Scilab when calling bifish.
See Also : ode
Scilab Group April 1993 342
gpeche Scilab Function
12.0.719 boucle phase portrait of a dynamical system with observer
CALLING SEQUENCE :
[]=boucle(fch,[abruit,xdim,npts,farrow])

PARAMETERS :
fch : Scilab macro. fch is supposed to be an observed-controlled system with noisy output of
state dimension 4 ( [x;xchap] is of dimension 4). fch can be created with the macro obs cont
or can be set to one of the two following string which gives pre computed examples
"bcomp": for a non-linear competition model.
"lcomp": for a linear example.
abruit : give the noise variance.
xdim,npts,farrow : See portrait

DESCRIPTION :
Phase portrait of dynamical systems.
See Also : portrait, ode, obs_cont
12.0.720 chaintest a three-species food chain model
CALLING SEQUENCE :
chaintest([f_l,b1,odem,xdim,npts])
[xdot]=chain(t,x)
[z1]=ch_f1(u)
[z2]=ch_f2(u)

PARAMETERS :
f l : the name of the macro which code the three-species food chain model (default value chain).
odem,xdim,npts : are optional arguments. Their meaning and syntax can be found in the
portr3d help
DESCRIPTION :
A call to the function chaintest() will interactively display a phase portrait of a three-species
food chain model given by:
ff1= f1(x(1))
ff2= f2(x(2))

xdot1= x(1)*(1-x(1)) - ff1*x(2)

xdot2= ff1*x(2) - ff2*x(3) - 0.4*x(2)
xdot3= ff2*x(3) - 0.01*x(3)

and
f1(u)=5*u/(1+b1*u)
f2(u)z2=0.1*u/(1+2*u)

The default value for b1 is 3.0.

The Scilab macros chain(t,x),f1(u),f2(u) code the dynamical system
See Also : portr3d, ode
Scilab Group April 1993 343
fusee Scilab Function
12.0.721 gpeche a shing program
CALLING SEQUENCE :
[xk,ukp1]=gpeche(uk,pasg)
[ut]=peche(t)
[pdot]=pechep(t,p)

DESCRIPTION :
gpeche Iterates a gradient method on a shing problem Computes the trajectory associated to
the command law uk prints the cost value and computes a new control.
12.0.722 fusee a set of Scilab macro for a landing rocket problem
FUSEE :
[xdot]=fusee(t,x)

Dynamical motion equation for the rocket

FINIT :
finit()

Initialises the following parameters for rocket landing.

k : The acceleration of the rocket engines
gamma : The moon gravity acceleration.
umax : the gaz ejection ow out.
mcap : the mass of the space capsule.
cpen : penalisation in the cost function of the nal state.

FUSEEGRAD :
[ukp1]=fuseegrad(niter,ukp1,pasg)

niter : number of gradient iteration steps.

ukp1 : initial control value ( vector of sie 135 )
pasg : the gradient step value.
DESCRIPTION :
Iterate a gradient method and returns the computed control.
FUSEEP :
[pdot]=fuseep(t,p)

DESCRIPTION :
adjoint equation for the landing rocket problem.
POUSSE :
[ut]=pousse(t)

return the value of a piece wise constant control build on the discrete control uk
UBANG :
[uk]=ubang(tf,tcom)

returns a bang-bang control, 0 form time 0 to tcom and 1 form tcom to tf.
FCOUT :
Scilab Group April 1993 344
mine Scilab Function
[c,xk,pk,ukp1]=fcout(tf,uk,pasg)

DESCRITION :
optimise the following cost function by gradient iterations.
c = -m(tf) + C*( h(tf)**2 + v(tf)**2)

SFUSEE :
[]=sfusee(tau,h0,v0,m0,Tf)

DESCRIPTION :
computes the rocket trajectory when a bang-bang control is used tau is the commutation time.
h0 : The initial position (high)
v0 : The initial speed ( negative if the rocket is landing )
m0 : The total initial mass ( capsule and fuel).
Tf : Time horizon.

EQUAD :
DESCRIPTION :
[xk,pk]=equad(tf,uk)
Computes the state and adjoint state of the rocket system for a given control ur.
TRAJ :
[xt]=traj(t)
returns a piece wise value of the mass evolution.
12.0.723 lotest demo of the Lorenz attractor
CALLING SEQUENCE :
[]=lotest([f_l,odem,xdim,npts,pinit])
[y]=lorenz(t,x)
[]=ilo(sig,ro,beta)
[]=ilof(sig,ro,beta)

PARAMETERS :
f l : can be "loren" or lorenz. it is the name of the external for the Lorenz system. "loren"
will use a Fortran coded version of the lorenz system and arnold will and loren will use a
Scilab coded version.lorentz is the Scilab macro which code the lorenz system. This macro
is loaded when calling lotest.
ilof, ilo :are used to x the parameters of the Fortran and Scilab code version of the Lorenz
system.
odem,xdim,npts : are optional arguments. Their meaning and syntax can be found in the
portr3d help

DESCRIPTION :
A call to the function lotest() will interactively display a phase portrait of a the following
dynamical system
y(1)=sig*(x(2)-x(1));
y(2)=ro*x(1) -x(2)-x(1)*x(3);
y(3)=-beta*x(3)+x(1)*x(2);

See Also : , ,
portr3d ode chaintest lotest ,
Scilab Group April 1993 345
obs cont Scilab Function
12.0.724 mine a mining problem
CALLING SEQUENCE :
[cout,feed]=mine(n1,n2,uvect)

PARAMETERS :
n1 : Number of discrete point for the state.
n2 : Number of time step
uvect : a row vector which gives the possible control value ( integer values ). for example
u=[-1,0,1] means that at each step we come down one step or stay at the same level or
rise one step ).
cout(n1,n2) : The Bellman values.
feed(n1,n2) : The feedback Law.

DESCRIPTION :
Dynamic programmingapplied to an optimal extraction of ore in an opencast mine. The extraction
is done as follows : the steam shovel move forward for (k=1,2,...,n2) at each step it takes the ore,
then move up or down (or stay at the same level) according to the control value to reach another
level at next step. The extraction process must maximise the following cost :
-- n2-1
\
/ f(x(k),k) + V_F(x,n2)
-- k=1

with x(k+1)=x(k) + u. x(k) is the trajectory depth at step k (x=1 is the ground level).
The instantaneous cost f(i,k) stands for the benefit of digging at depth i at position
k. It must be given as a Scilab macro ff o

[y]=ff_o(x,k)

and for eciency ff o must accept and return column vectors for x and y.
V F(i,n2) is a nal cost which is set so as to impose the steam shovel to be at ground level at
position n2
FF O :
SHOWCOST :
CALLING SEQUENCE :
[]=showcost(n1,n2,teta,alpha)

DESCRIPTION :
Shows a 3D representation of the instantaneous cost.
12.0.725 obs cont a controlled-observed system
CALLING SEQUENCE :
[macr]=obs_cont(sysn)

PARAMETERS :
sysn : A Scilab string which gives the name of the controlled system.
gaincom,gainobs : column vectors giving the requested gains
macr : a new Scilab function which simulates the controlled observed system.
Scilab Group April 1993 346
portrait Scilab Function
[x1dot]=macr(t,x1,abruit,pas,n)
x1=[x;xchap],

DESCRIPTION :
This macros return a new function which computes the controlled observed version of a linearised
system around the (xe,ue) point.
before calling this function, a noise vector br should be created. the equilibrium point (xe,ue)
should be given as a global Scilab. the linearised system $f,g,h$ and the two gain matrices l,k
are returned as global Scilab data.
12.0.726 portr3d 3 dimensional phase portrait.
CALLING SEQUENCE :
[]=portr3d(f,[odem,xdim,npts,pinit])

PARAMETERS :
f : a Scilab external which gives the eld of the dynamical system. Hence it can be a macro
name which computes the eld at time t and point x [y]=f(t,x,[u]) or a list list(f1,u1) where
f1 is a macro of type [y]=f1(t,x,u) or a character string
rest : The other parameters are optional. If omitted they will be asked interactively

odem : gives the integration method to use. The value "default" can be used, otherwise see
ode for a complete set of possibilities
npts : a vector of size (2,10) [number-of-points,step] gives the step for integration and the
number of requested points. The solution will be calculated and drawn for time=0:step:(step*[number-
of-points])
xdim : [xmin,xmax,ymin,ymax,zmin,zmax] the boundaries of the graphic frame.
pinit : initial values for integration. A set of initial points can be given in a matrix

pinit = [x0(1), x1(1),...., xn(1)

x0(2), x1(2),...., xn(2)
x0(3), x1(3),...., xn(3)].

DESCRIPTION :
Interactive integration and display of a 3 dimensional phase portrait of a dynamical system
dx/dt=f(t,x,[u]) (where u is an optional parameter )
See Also : ode
12.0.727 portrait 2 dimensional phase portrait.
CALLING SEQUENCE :
[]=portrait(f,[odem,xdim,npts,pinit])

PARAMETERS :
f : a Scilab external which gives the eld of the dynamical system. Hence it can be a macro
name which computes the eld at time t and point x [y]=f(t,x,[u]) or a list list(f1,u1) where
f1 is a macro of type [y]=f1(t,x,u) or a character string. The macro can be used to simulate
a continuous or discrete system and in case of discrete system the second parameter must be
set to 'discrete'
rest : The other parameters are optional. If omitted they will be asked interactively

odem : gives the integration method to use. The value "default" can be used, otherwise see
ode for a complete set of possibilities
Scilab Group April 1993 347
systems Scilab Function
npts : a vector of size (2,10) [number-of-points,step] gives the step for integration and the
number of requested points. The solution will be calculated and drawn for time=0:step:(step*[number-
of-points])
xdim : [xmin,xmax,ymin,ymax,zmin,zmax] the boundaries of the graphic frame.
pinit : initial values for integration. A set of initial points can be given in a matrix
pinit = [x0(1), x1(1),...., xn(1)
x0(2), x1(2),...., xn(2)
x0(3), x1(3),...., xn(3)].

DESCRIPTION :
Interactive integration and display of a 2 dimensional phase portrait of a dynamical system
dx/dt=f(t,x,[u]) (where u is an optional parameter )
EXAMPLE :
a=rand(2,2)
deff('[ydot]=l_s(t,y)','ydot=a*y')
portrait(l_s)

See Also : ode

12.0.728 recur a bilinear recurrent equation

CALLING SEQUENCE :
[y]=recur(x0,var,k,n)
[integr]=logr(k,var)

DESCRIPTION :
computes solutions of a bilinear recurrent equation
x(i+1)=-x(i)*(k + sqrt(var)*br(i))

with initial value x0 and driven by a white noise of variance var.

Trajectories are drawn and the empirical Lyapunov exponent is returned ( x(i) is not to much
dierent from exp(y*i) )
A theorical computation of the Lyapunov exponent is given by
[integr]=logr(k,var)

12.0.729 systems a collection of dynamical system

CALLING SEQUENCE :
[]=systems()

DESCRIPTION :
A call to this function will load into Scilab a set of macros which describes dynamical systems.
Their parameters can be initiated by calling the routine tdinit().
BIOREACT :
[ydot]=biorecat(t,x)

a bioreactor model,
x(1) is the biomass concentration
x(2) is the sugar concentration

xdot(1)=mu_td(x(2))*x(1)- debit*x(1);
xdot(2)=-k*mu_td(x(2))*x(1)-debit*x(2)+debit*x2in;

Scilab Group April 1993 348

systems Scilab Function
where mu td is given by
mu_td(x)=x/(1+x);

COMPET :
[xdot]=compet(t,x [,u])

a competition model. x(1),x(2) stands for two populations which grows on a same resource. 1/u
is the level of that resource ( 1 is the default value).
xdot=0*ones(2,1);
xdot(1) = ppr*x(1)*(1-x(1)/ppk) - u*ppa*x(1)*x(2) ,
xdot(2) = pps*x(2)*(1-x(2)/ppl) - u*ppb*x(1)*x(2) ,

The macro [xe]=equilcom(ue) computes an equilibrium point of the competition model and a
xed level of the resource ue ( default value is 1)
The macro [f,g,h,linsy]=lincomp([ue]) gives the linearisation of the competition model (
with output y=x) around the equilibrium point xe=equilcom(ue). This macro returns [f,g,h]
the three matrices of the linearised system. and linsy which is a Scilab macro [ydot]=linsy(t,x)
which computes the dynamics of the linearised system
CYCLLIM :
[xdot]=cycllim(t,x)

a model with a limit cycle

xdot=a*x+qeps(1-||x||**2)x

LINEAR :
[xdot]=linear(t,x)

a linear system
BLINPER :
[xdot]=linper(t,x)

a linear system with quadratic perturbations.

POP :
[xdot]=pop(t,x)

a sh population model
xdot= 10*x*(1-x/K)- peche(t)*x

PROIE :
a Predator prey model with external insecticide.
[xdot]=p_p(t,x,[u]

x(1) The prey ( that we want to kill )

x(2) the predator ( that we want to preserve )
u mortality rate due to insecticide which destroys both prey and predator ( default value u=0)
xdot(1) = ppr*x(1)*(1-x(1)/ppk) - ppa*x(1)*x(2) - u*x(1);
xdot(2) = -ppm*x(2) + ppb*x(1)*x(2) - u*x(2);

Scilab Group April 1993 349

tdinit Scilab Function
The macro [xe]=equilpp([ue]) computes the equilibrium point of the p p system for the
value ue of the command. The default value for ue is 0.
xe(1) = (ppm+ue)/ppb;
xe(2) = (ppr*(1-xe(1)/ppk)-ue)/ppa;

LINCOM :
[xdot]=lincom(t,x,k)

linear system with a feedback

xdot= a*x +b*(-k*x)

See Also : tdinit.

12.0.730 tangent linearization of a dynamical system at an

equilibrium point
CALLING SEQUENCE :
[f,g,newm]=tangent(ff,xe,[ue])

PARAMETERS :
ff : a string which gives the name of the Scilab macro which codes the system
xe : column vector which gives the equilibrium point for the value ue of the parameter
ue : real value.
f, g : two matrices for the linearised system dxdot=f.dx + g.du
newm : A new macro of type [y]=newm(t,x,u) which computes the eld of the linearised system
(newm(t,xe,ue)=0)
DESCRIPTION :
linearises around the equilibrium point (xe,ue) the vector eld of the dynamical system given
by a Scilab macro ff, xdot=ff(t,x,[u]). The dynamical system is supposed to be autonomous.
12.0.731 tdinit interactive initialisation of the tdcs dynamical
systems
CALLING SEQUENCE :
tdinit()

DESCRIPTION :
This macro can be used to interactively dene the parameters needed by the dynamical systems
described in systems
bioreactor model
competition model
system with limit cycle
linear system
quadratic model
linear system with a feedback
prey predatory model
See Also : portrait , systems

Scilab Group April 1993 350

Index
Symbols armac, 253
<, 29 armap, 254
', 42 armax, 254
(, 36 armax1, 255
*, 54 arsimul, 255
+, 38 arspec, 256
,, 10 artest, 342
-, 34 asin, 112
/, 50 asinh, 112
:, 10 atan, 113
;, 49 atanh, 113
=, 13 augment, 184
[, 29
[,], 8 B
[], 13 balanc, 273
%, 37 balreal, 152
%K, 226 bdiag, 273
%asn, 226 bezout, 260
%sn, 226 bish, 342
^, 38 black, 65
^,exp, 26 bloc2exp, 113
n, 7 bloc2ss, 115
~, 56 bode, 66
boucle, 343
A break, 8
abcd, 150 bstap, 184
abinv, 150 buttmag, 229
abs, 110
ABSBLK, 326 C
acos, 110 c link, 116
acosh, 110 cainv, 152
addf, 110 calerf, 117
addinter, 6 calfrq, 153
addmenu, 111 canon, 154
adj lists, 300 casc, 229
a2ab, 272 case, 8
amell, 112 ccontrg, 184
analpf, 228 ceil, 9
and, 6 chaintest, 343
ANIMXY, 326 champ, 67
ans, 6 chart, 67
apropos, 6 cheb1mag, 229
argn, 7 Cheb2mag, 230
arhnk, 151 check graph, 300
arl2, 151 chepol, 230
arma, 253 chol, 274
351
tdinit Scilab Function
circuit, 300 degree, 11
clean, 260 delbpt, 12
clear, 9 delip, 119
clearfun, 9 delmenu, 119
CLINDUMMY, 326 demos, 119
CLKIN, 326 denom, 261
CLKOUT, 327 derivat, 262
CLKSOM, 327 des2ss, 186
CLOCK, 327, 331, 336 des2tf, 158
CLR, 327 det, 275
cls2dls, 154 determ, 262
CLSS, 327 detr, 262
cmb lin, 117 dft, 232
cmndred, 260 diag, 120
code2str, 9 diary, 12
coe, 10 diophant, 263
co, 274 disp, 12
cog, 261 dispbpt, 12
colcomp, 274 DLR, 328
colcompr, 261 DLSS, 329
colinout, 185 driver, 68
colnew, 202 dscr, 158
colregul, 155 dsimul, 158
comments, 10 dt ility, 159
comp, 11 dtsi, 186
con nodes, 301
cond, 275 E
conj, 117 edit, 120
connex, 302 ell1mag, 233
CONST, 328 else, 12
cont frm, 155 elseif, 12
cont mat, 155 emptystr, 121
contour, 68 end, 13
contr, 156 epsn, 275
contrss, 156 eqr, 233
convol, 230 eqiir, 233
convstr, 118 equil, 159
copfac, 185 equil1, 160
corr, 231 erf, 121
cos, 118 erfc, 121
COSBLK, 328 erfcx, 122
cosh, 118 errbar, 69
cotg, 118 errcatch, 13
coth, 118 errclear, 14
csim, 156 error, 14
cspect, 231 eval, 122
ctr gram, 157 eval3d, 69
czt, 232 eval3dp, 70
evans, 70
D EVENTFSCOPE, 329
dasrt, 205 evstr, 14
dassl, 207 EVTDLY, 329
dcf, 186 EVTGEN, 329
debug, 119 exar1, 256
de, 11 exar2, 256
Scilab Group April 1993 352
tdinit Scilab Function
exar3, 256 gainplot, 74
exec, 15 gamitg, 188
execstr, 122 gbruit, 257
exists, 15 gcare, 188
exit, 15 gcd, 263
exp, 276 GENERAL, 330
external, 15 genfac3d, 74
eye, 16 GENSIN, 330
GENSQR, 330
F geom3d, 75
fac3d, 70 getenv, 25
factors, 263 getf, 26
faurre, 234 getpid, 26
fchamp, 71 getvalue, 123
fcontour, 71 gfare, 189
feedback, 160 givens, 277
feval, 16 glever, 278
lt, 234 gpeche, 344
t, 234 gr menu, 75
fgrayplot, 72 graduate, 76
le, 17 graph-list, 303
lter, 235 graph 2 mat, 305
nd, 18 Graphic, 64
nd freq, 235 grayplot, 76
nd path, 302 group, 237
ndm, 236 gschur, 278
neta, 276 gspec, 279
x, 18 gtild, 189
oor, 19
ts, 161 H
for, 19 h2norm, 190
format, 19 h cl, 190
fort, 20 h inf, 190
fourplan, 187 H inf st, 191
fplot2d, 72 H norm, 191
fplot3d, 73 halt, 123
fplot3d1, 73 hank, 237
frep2tf, 162 hankelsv, 192
freq, 162 havewindow, 124
freson, 162 help, 27
frmag, 236 hermit, 264
fsrlin, 236 hess, 279
fsolve, 209 hilb, 238
fspecg, 187 hist3d, 77
fstabst, 187 histplot, 77
full, 122 horner, 264
fullrf, 277 host, 27
fullrfk, 277 hrmt, 265
funptr, 25 htrianr, 265
fusee, 344
fwiir, 237 I
if, 27
G IFTHEL, 331
g margin, 163 iir, 238
GAIN, 330 iirgroup, 239
Scilab Group April 1993 353
tdinit Scilab Function
iirlp, 239 linpro, 212
im inv, 280 linsolve, 282
imag, 28 linspace, 126
impl, 209 lmisolver, 214
imrep2ss, 163 lmitool, 214
input, 124 load, 32
int, 28 load graph, 306
intc, 211 locate, 78
intdec, 239 log, 127
INTEGRAL, 331 logspace, 127
integrate, 124 LOOKUP, 331
interp, 125 lotest, 345
interpln, 125 lqe, 164
intg, 211 lqg, 165
intl, 211 lqg2stan, 165
inv, 280 lqg ltr, 195
invr, 266 lqr, 166
invsyslin, 163 ltitr, 167
is connex, 306 lu, 282
isdef, 126 ludel, 283
iserror, 28 lufact, 283
isoview, 77 luget, 284
lusolve, 284
J lyap, 285
jmat, 240
M
K m circle, 78
kalm, 240 mac2for, 128
karmarkar, 212 Macglov, 195
kernel, 280 macr2lst, 128
keyboard, 28 macrovar, 129
kron, 126 make graph, 306
kroneck, 281 manedit, 129
markp2ss, 167
L mat 2 graph, 307
lattn, 240 matrix, 33
lattp, 241 max, 33
lcf, 192 max cap path, 307
lcm, 266 max ow, 308
ldiv, 266 maxi, 34
ldivf, 126 MCLOCK, 332
length, 29 mese, 243
leqr, 192 metanet, 309
lev, 241 MFCLCK, 332
leverrier, 281 mt, 243
levin, 241 milk drop, 79
lft, 193 min, 34
lgt, 242 min lcost c ow, 309
lib, 30 min lcost ow1, 310
lin, 163 min lcost ow2, 311
lindquist, 242 min qcost ow, 312
lines, 30 min weight tree, 313
linf, 194 mine, 346
linfn, 194 mini, 34
link, 31 minreal, 167
Scilab Group April 1993 354
tdinit Scilab Function
minss, 168 plot2d, 81
mode, 34 plot2d1, 82
modulo, 129 plot2d2, 83
mulf, 129 plot2d3, 83
plot2d4, 83
N plot3d, 84
narsimul, 257 plot3d1, 84
NEGTOPOS, 332 plot graph, 316
nehari, 196 plot graph1, 317
netwindow, 314 plot graph2, 317
netwindows, 314 plotframe, 85
newfun, 35 plzr, 85
nlev, 285 pol2des, 267
nodes 2 path, 315 pol2str, 267
norm, 130 pol2tex, 131
null, 35 polar, 288
numer, 267 polfact, 268
nyquist, 79 poly, 38
portr3d, 347
O portrait, 347
obs cont, 346 POSTONEG, 332
obs gram, 168 ppol, 172
obscont, 168 prbs a, 257
observer, 169 predef, 39
obsv mat, 170 print, 39
obsvss, 170 printf,fprintf,sprintf, 21, 39, 50
ode, 215 printing, 86
odedc, 218 PROD, 332
odedi, 257 prod, 131
odeoptions, 219 proj, 288
ones, 35 projsl, 172
optim, 219 projspec, 288
or, 36 psmall, 289
orth, 286 pspect, 244
OUT, 331
Q
P qr, 289
p margin, 171 quapro, 221
param3d, 80 quaskro, 290
param3di, 80 quit, 42
parrot, 196
part, 37 R
path 2 nodes, 315 RAND, 333
pause, 37 rand, 42
pbig, 286 range, 290
pdiv, 267 rank, 291
pen2ea, 130 rat, 43
pencan, 286 rcond, 291
penlaur, 287 rdivf, 131
pertrans, 130 read, 43
pfss, 171 readb, 44
phasemag, 171 readc , 131
phc, 243 real, 45
pinv, 287 recur, 348
plot, 81 REGISTER, 333
Scilab Group April 1993 355
tdinit Scilab Function
reglin, 257 shortest path, 318
remez, 244 show arcs, 319
remezb, 244 show graph, 320
repfreq, 173 show nodes, 320
residu, 268 sign, 49
resume, 45 Signal, 227
return, 45 simp, 269
RFILE, 333 sin, 133
ric desc, 196 SINBLK, 335
ricc, 173 sinc, 246
riccati, 197 sincd, 246
roots, 268 sinh, 133
rotate, 87 size, 49
round, 45 sm2des, 175
routh t, 268 sm2ss, 175
rowcomp, 291 smooth, 133
rowcompr, 269 solve, 134
rowinout, 198 SOM, 335
rowregul, 174 sort, 134
rowshu, 292 spaninter, 293
rpem, 245 spanplus, 294
rtitr, 174 spantwo, 294
sparse, 134
S spclean, 295
SAT, 334 spec, 295
save, 45 specfact, 175
save graph, 318 speye, 135
SAWTOOTH, 334 spget, 135
scaling, 87 splin, 135
scanf,, 23, 46, 53 sprand, 136
schur, 292 spzeros, 136
sci2exp, 132 sqroot, 296
sci2map, 132 sqrt, 136
scicos, 337 square, 88
scifunc block, 339 srfaur, 247
scilab, 47 srkf, 247
Scilab object: boolean, 7 ss2des, 176
Scilab object: list, 31 ss2ss, 176
Scilab object: matrix, 32 ss2tf, 177
Scilab object: tlist, 56 sskf, 247
Scilab object:string, 55 ssprint, 137
Scilab object : function, 25 ssrand, 137
Scilab object : macro, 32 st ility, 177
Scilab object : rationals, 43 stabil, 178
scilink, 48 stacksize, 54
SCOPE, 334 startup, 54
SCOPXY, 335 str2code, 55
secto3d, 87 strcat, 138
SELECT, 335 string, 55
select, 48 strong con nodes, 321
semidef, 222 strong connex, 322
sensi, 198 subf, 138
setbpt, 49 sum, 139
setmenu, 132 SUPER, 336
sfact, 269 sva, 296
Scilab Group April 1993 356
tdinit Scilab Function
svd, 296 where, 59
svplot, 178 whereami, 60
sylm, 270 whereis, 60
sylv, 297 while, 60
sysconv, 139 who, 61
sysdiag, 140 wiener, 249
syslin, 140 wigner, 249
system, 248 window, 250
systems, 348 writb, 61
systmat, 270 write, 61
T X
tan, 141 x choices, 144
TANBLK, 328, 336 x choose, 145
tangent, 350 x dialog, 145
tanh, 141 x matrix, 145
TCLSS, 336 x mdialog, 146
tdinit, 350 x message, 146
texprint, 142 xarc, 88
tf2des, 199 xarcs, 89
tf2ss, 179 xarrows, 89
TIME, 336 xaxis, 90
time id, 179 xbasc, 91
timer, 142 xbasimp, 91
titlepage, 88 xbasr, 91
toeplitz, 142 xchange, 91
trace, 297 xclea, 92
trans, 248 xclear, 92
trans closure, 322 xclick, 92
TRASH, 337 xclip, 93
trfmod, 142 xdel, 94
trianfml, 142 xend, 94
tril, 143 xfarc, 94
trisolve, 143 xfarcs, 95
triu, 143 xfpoly, 95
trzeros, 179 xfpolys, 95
type, 56 xfrect, 96
typeof, 143 xget, 96
U xgetech, 97
unix, 57 xgetle, 147
unix g, 57 xgetmouse, 98
unix s, 58 xgrid, 98
unix w, 58 xinfo, 99
unix x, 58 xinit, 99
unobs, 180 xlfont, 99
unsetmenu, 144 xload, 100
user, 59 xnumb, 100
xpause, 100
V xpoly, 101
varn, 59 xpolys, 101
xrect, 101
W xrects, 102
WFILE, 337 xrpoly, 102
wr, 248 xs2g, 102
what, 59 xsave, 103
Scilab Group April 1993 357
tdinit Scilab Function
xsegs, 103
xselect, 104
xset, 104
xsetech, 105
xstring, 106
xstringb, 106
xstringl, 107
xtape, 107
xtitle, 108
Y
yulewalk, 250
Z
ZCROSS, 337
zeropen, 180
zeros, 147
zgrid, 108
zpbutt, 250
zpch1, 251
zpch2, 251
zpell, 252

Scilab Group April 1993 358