Negative error codes describe fatal errors, whereas positive error codes are warnings only. In case of fatal error, the function output arguments have undefined values. If a function has no output arguments, it typically has only positive return codes.
The error code descriptions do normally not appear in the Tela help messages. If an error occurs, Tela will however find and display the proper textual message.
[y] = BatchMode()
BatchMode() returns 1 if this Tela process is in batch mode
(command line switch -b), otherwise 0.
See also:
SilentMode
,
VerboseMode
,
UsingReadline
.
[;y] = CheckReadOnlyMode(;x)
CheckReadOnlyMode() returns 1 if this Tela process checks that function
input arguments are not modified by the function. The check is done by
default, but if it causes problems (bugs in Tela) you can turn it off
using CheckReadOnlyMode(off).
CheckReadOnlyMode returns the old mode setting.
See also:
SilentMode
,
BatchMode
,
VerboseMode
.
Error codes:
1: Argument not integer
[;y] = DebugQueryMode(;x)
DebugQueryMode() returns 1 if the debug query mode
has been set, otherwise 0.
DebugQueryMode(on) and DebugQueryMode(off) change
the current setting.
If debug query mode is on, the program will ask whether
the user wants to enter debug mode if control-C is
pressed (INT signal sent). Otherwise the program simply
stops on pressing control-C.
Error codes:
1: Argument not integer
[f] = FFT(u; dim)
FFT(u) gives the complex Fast Fourier Transform of u.
If u's rank is more than one, the transform is computed
only along the first dimension (many independent 1D
transforms).
FFT(u,dim) computes the FFT along the specified dimension.
The first dimension is labeled 1 and so on.
For vector u, f=FFT(u) is equivalent with
n = length(u); f = czeros(n);
for (j=1; j<=n; j++)
f[j] = sum(u*exp(-(j-1)*(0:n-1)*2i*pi/n));
All Fourier transform functions in Tela can take the transform
along any dimension in a multidimensional array, and the transform
length is not restricted. The function FFT should be used only in
case of complex input data. Use realFFT for real input array.
Functions FFT, realFFT, sinqFFT, cosFFT and their inverses
are the most efficient when the transform length n is a product
of small primes.
Functions sinFFT and invsinFFT are efficient when n+1 is
a product of small primes
Functions cosFFT and invcosFFT are efficient when n-1 is
a product of small primes
See also:
invFFT
,
realFFT
,
sinFFT
,
cosFFT
,
sinqFFT
,
cosqFFT
.
Error codes:
-1: First argument not a numeric array
-2: Second argument not integer
-3: Second argument out of range
[Ninstructions,Noperations] = GetInstructionData(p,mnemo)
[Ninstr,Nops] = GetInstructionData(p,"mnemonic") returns
the number of specific instructions executed when p=perf() was
gathered, and the number of (floating point) operations associated
with the instruction.
The mnemonic must be a string, and it may be any of the names
that appear in the disasm(f) listing. In addition, mnemonic may
be "flop", which includes all instructions that may perform floating
point arithmetic, or it may be "*", which includes all instructions.
Error codes:
-1: Bad first argument, must be obtained from perf()
-2: Second arg not a string
-3: Second arg not a recognized string
[y] = HeavisideTheta(x)
y = HeavisideTheta(x) returns 1 if x>=0 and 0 if x<0.
x must be real. If x is array, the operation is applied componentwise.
See also:
sign
.
Error codes:
-1: Complex or nonnumeric input argument
[y] = Im(x)
y = Im(x) takes the imaginary part of a complex quantity x.
If x is real or integer, the result is zero.
If x is an array, the operation is applied componentwise.
See also:
Re
,
conj
,
arg
.
Error codes:
-1: Nonnumeric input argument
[L;U,P] = LU(A)
[L,U,P] = LU(A) computes the LU factorization of matrix A.
The factorization is A = P**L**U, where P is a permutation
matrix, L is lower triangular with unit diagonal and U is
upper triangular.
[lu] = LU(A) leaves the factors L and U packed in one matrix.
[lu,p] = LU(A) returns also the pivoting info vector p.
(Notice that this p is related to the permutation matrix P
but is not the same. You need this form of LU if you want to
use LUbacksubst later on.)
See also:
LUbacksubst
,
linsolve
,
inv
,
chol
,
SVD
.
Error codes:
1: Singular matrix (==> zero in U's diagonal)
-1: Input arg not an array
-2: Input arg not a rank-2 array (matrix)
[x] = LUbacksubst(lu,p,b)
LUbacksubst(lu,p,b) solves the linear system A**x == b,
where A has been previously LU-decomposed using LU:
[lu,p] = LU(A).
See also:
linsolve
,
LU
.
Error codes:
-1: First input arg is not an array
-2: First input arg is not a square matrix
-3: Second input arg is not an integer vector
-4: Third input arg is not an array
-5: Third input arg is not a vector or matrix
-6: Incompatible dimensions in first/third args
-7: Singular matrix
-8: Incompatible dimensions in first/second args
-9: Internal error
[y] = Re(x)
y = Re(x) takes the real part of a complex quantity x.
If x is real or integer, it is returned as such.
If x is an array, the operation is applied componentwise.
See also:
Im
,
conj
,
arg
.
Error codes:
-1: Nonnumeric input argument
[U;S,V] = SVD(A)
[U,S,V] = SVD(A) computes the singular value
decomposition of matrix A: A = U**S**V'.
U and V are unitary and S is diagonal.
SVD(A) as such returns the vector of singular values.
See also:
LU
,
chol
.
Error codes:
1: No convergence
-1: Input arg not an array
-2: Input array is not a matrix
-3: Internal error
-4: Two output arg case not supported (must be 1 or 3)
[y] = SilentMode()
SilentMode() returns 1 if this Tela process is in silent mode
(command line switch -s), otherwise 0.
See also:
BatchMode
,
VerboseMode
,
CheckReadOnlyMode
.
[y] = UsingReadline()
UsingReadline() returns 1 if this Tela was compiled
to use the GNU readline library, otherwise 0.
See also:
BatchMode
,
SilentMode
,
VerboseMode
.
[;y] = VerboseMode(;x)
VerboseMode() returns 1 if this Tela process is in verbose mode
(command line switch -v), otherwise 0.
VerboseMode(on) and VerboseMode(off) set the verbose mode on
and off, respectively. They return the old mode setting.
See also:
SilentMode
,
BatchMode
.
Error codes:
1: Argument not integer
[y] = abs2(x)
y = abs2(x) computes the square of the absolute value of x.
If x is real or integer, the result is just the square of x.
If x is complex, the result is equal to x*conj(x), except that
the latter would produce a complex result with zero or tiny
(because of possible roundoff error) imaginary part.
If x is an array, the operation is applied componentwise.
Error codes:
-1: Nonnumeric input argument
[y] = acos(x)
y = acos(x) computes the arc cosine of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[y] = all(x)
all(x) returns 1 if all elements of x are nonzero,
and 0 otherwise.
x must be an integer array or scalar.
Conditional statements (if, while, for, until) assume
implicit all, for example saying
if (A > 0) ...
is equivalent of saying
if (all(A > 0)) ... ,
thus you will need all less frequently than you need any.
See also:
any
.
Error codes:
1: Argument not integer or IntArray
[] = annotate(primitive...)
annotate("primitive"[,options]) adds MTV annotations to the previous
graph. The plot command(s) and the annotate command(s) must appear
inside hold(on) ... hold(off) in order to work correctly.
--------------------------------------------
Here may be the proper place to list the most frequently used
PlotMTV options. These are used by giving them as optional args
(option-value pairs) to graphics functions.
Option name(s) Possible value(s) Explanation
"xlabel" string X-axis label
"ylabel" string Y-axis label
"zlabel" string Z-axis label
"toplabel" string Plot title
"subtitle" string Text below title
"comment" string Text on right corner
"xmin","xmax" real number X-axis scale
"ymin","ymax" real number Y-axis scale
"zmin","zmax" real number Z-axis scale
"cmin","cmax" real number Contour min/max
"nsteps" integer Number of contours
"cstep" real number Contour spacing
"contstyle" 1: normal contours, 2: colored (pcolor),
3: 3D surface
"hiddenline" "true": colored 3D surface, "false": wireframe
"linecolor" color value (integer)
"linewidth" integer
"linestyle" solid,dashed etc.; integers; 0 is no line
"markertype" integers; 0 is no marker (the default)
"markersize" real number
"markercolor" color value (integer)
Some color (red,green,blue,pink etc.) names have been defined
in telainit.t. Use them for clarity if possible.
The most usual PlotMTV command line options (always start with
minus sign):
-3d Initially view in 3D
-colorps Produce color PostScript
-landscape Produce landscape (rotated) PostScript
-scale s PostScript scale factor, default 1
-nodate Drop the date from PostScript figure
-title 'my title' PlotMTV window title
For an example in using the annotations, see e.g. the file
"3windows.t", usual location is /usr/local/lib/tela/t/.
See also:
plotopt
,
hold
,
plot
,
pcolor
,
mesh
,
contour
,
vplot
.
Error codes:
1: Could not open temporary MTV file
2: First argument not a string
3: Syntax error in graph options
[y] = any(x)
any(x) returns 1 if at least one element of x is nonzero,
and 0 otherwise.
x must be a integer array or scalar.
Conditional statements (if, while, for, until) default
to implicit all, thus you sometimes need to use any
with these statements.
See also:
all
.
Error codes:
1: Argument not integer or IntArray
[phi] = arg(z)
arg(z) returns the argument of a complex quantity
(in radians). The result is between -pi and pi.
If z is a complex array, the operation is applied
componentwise.
See also:
Re
,
Im
,
conj
.
Error codes:
-1: Argument has undefined value
1: Nonnumeric argument
[y] = asin(x)
y = asin(x) computes the arc sine of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[y] = atan(x)
y = atan(x) computes the arc tangent of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
See also:
atan2
.
[z] = atan2(y,x)
z = atan2(y,x) computes the arcus tangent of y/x using the signs
of both arguments to determine the quadrant of the return value.
The input argument must be integer or real scalars and the
return value is real.
See also:
atan
.
Error codes:
-1: Bad input argument
[y] = autoglobal(...)
autoglobal("sym1","sym2",...) sets the 'autoglobal' attribute
to given symbols. The symbols are then globally accessible
from inside packages and functions without need to explicitly
declaring them global. Constants such as pi carry the autoglobal
attribute automatically, but with this function it is possible
for the user to define more autoglobal symbols.
Warning: This function is for experts only. It is not advisable
to say autoglobal("x"), for instance, because many existing code
may then break down.
See also:
hide
.
Error codes:
1: Argument not a string
[] = autosource(fn...)
autosource("file.t","name1","name2",...) tags symbols
name1, name2,... such that the command source("file.t")
is effectively executed when any of the symbols name
is used. This is load-on-demand.
See also:
source
.
Error codes:
1: Argument not a string
[] = bar(x,y,z...)
bar(grouplabels,data,barnames[,options]) produces a bar chart.
Example 1:
bar(strmat("DEC","HP"),#(111,150.6),"Speed")
See also:
plot
,
hist
.
Error codes:
1: First argument not int nor real array
2: First argument not a vector nor matrix
3: Second argument not int nor real array
4: Second argument not a vector nor matrix
5: Dimension mismatch between first and second arg
6: If second arg is vector, third arg must be a string
7: Third arg must be a string or a string matrix
8: If second arg is matrix, third arg must be a string matrix
9: Dimension mismatch between second and third arg
10: Syntax error in graph options
11: First arg must not be real matrix
12: Could not open temporary MTV file
[] = cd(fn)
cd("pathname") will change the current directory to "pathname".
cd("") will change to home directory.
cd("~/my/dir") will change to directory "my/dir" in the
home directory.
See also:
getenv
.
Error codes:
1: Input argument not a string
2: Directory not found
3: This system does not support cd
[y] = ceil(x)
ceil(x) returns the smallest integer which is larger than x.
x must be integer or real scalar or array. If it is an array,
the operation is applied componentwise.
See also:
floor
.
Error codes:
-1: Complex or nonnumeric input argument
[B] = chol(A)
B=chol(A) returns the Cholesky decomposition of a
positive definite square matrix A: B'**B == A.
A may be integer, real or complex valued.
Only the upper half of A is referenced, the lower half
is assumed to be Hermitian symmetric.
See also:
linsolve
,
LU
,
matprod
,
det
,
eig
,
inv
.
Error codes:
-1: Input arg is not a matrix
-2: Input matrix is not square
-3: Input matrix is not positive definite
[] = closefig(n)
closefig(n) (n>1) closes the nth graphics window.
The active window is not changed, so if n is the active
window, subsequent plot commands will reopen it.
If the window has never been opened or has already been
closed, closefig is silent about it.
See also:
figure
.
Error codes:
1: Argument not an integer
2: Argument not positive
3: This Tela installation does not support the closefig command
4: No n>1 figures are currently open (and X11 initialization has failed)
[y] = conj(x)
y = conj(x) computes the complex conjugate of x.
Real and integer arguments are returned as such.
If x is an array, the operation is applied componentwise.
See also:
Re
,
Im
,
arg
.
[] = contour(z...)
contour(z[,options]) plots the matrix z as a filled contour plot.
See also:
contour3
,
annotate
,
plot
,
mesh
,
pcolor
,
vplot
.
Error codes:
1: Could not open temporary MTV file
2: First argument is not a numeric 2D array
3: Syntax error in graph options
4: Write error in MTV file - file system full?
[] = contour3(z...)
contour3(z[,options]) plots the 3D array as a
"volume" plot. Currently this only means that all
six faces of the volume are contoured and colored
according to options.
See also:
annotate
,
plot
,
mesh
,
pcolor
,
vplot
.
contour.
Error codes:
1: Could not open temporary MTV file
2: First argument is not a real 3D array
3: Syntax error in graph options
4: Write error in MTV file - file system full?
[y] = cos(x)
y = cos(x) computes the cosine function of x.
If x is complex, the result is complex, otherwise real.
The argument must be in radians.
If x is an array, the operation is applied componentwise.
[f] = cosFFT(u; dim)
cosFFT(u) gives the cosine Fast Fourier Transform of array u.
If u's rank is more than one, the transform is computed
only along the first dimension (many independent 1D
transforms).
cosFFT(u,dim) computes the FFT along the specified dimension.
The first dimension is labeled 1 and so on.
For vector u, f=cosFFT(u) is equivalent with
n = length(u); f = zeros(n);
for (j=1; j<=n; j++)
f[j] = u[1] - (-1)^j*u[n] + 2*sum(u[2:n-1]*cos((1:n-2)*(j-1)*pi/(n-1)));
Note that cosFFT is most efficient when n-1 is a product of small
primes, where n is the transform length.
See also:
invcosFFT
,
sinFFT
,
cosqFFT
,
sinqFFT
,
realFFT
,
FFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[y] = cosh(x)
y = cosh(x) computes the hyperbolic cosine function of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[f] = cosqFFT(u; dim)
cosqFFT computes the quarter-wave cosine Fourier transform.
Except for the quarter-wave cosine character, it works similarly to cosFFT.
For vector u, f=cosqFFT(u) is equivalent with
n = length(u); f = zeros(n);
for (j=1; j<=n; j++)
f[j] = u[1] + 2*sum(u[2:n]*cos((2*j-1)*(1:n-1)*pi/(2*n)));
cosqFFT is most efficient when the transform length is a product
of small primes.
See also:
invcosqFFT
,
realFFT
,
sinqFFT
,
FFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[y] = cot(x)
y = cot(x) is the cotangent function
cot(x) = 1/tan(x) = cos(x)/sin(x).
[t] = cputime(;p)
cputime() returns the CPU time in seconds used by the current
tela session. cputime(p) returns CPU time from performance data
array p, previously obtained from perf().
See also:
tic
,
toc
,
perf
.
Error codes:
-1: Bad argument, must be obtained from perf()
[y] = csc(x)
y = csc(x) is the cosecant function
csc(x) = 1/sin(x).
[y] = cumprod(x)
y = cumprod(x) forms an array of partial products
y = #(x[1],x[1]*x[2],...,prod(x[1:n]),...).
The result y has the same size and type as x. Unlike
prod, cumprod does not try to avoid integer overflows.
The array x is logically flattened, to apply
along a specified dimension use map(cumsum,...).
If x is scalar, it is returned as such.
See also:
prod
,
cumsum
,
map
.
Error codes:
-1: Nonnumeric input arg
[y] = cumsum(x)
y = cumsum(x) forms an array of partial sums
y = #(x[1],x[1]+x[2],...,sum(x[1:n]),...).
The result y has the same size and type as x.
The array x is logically flattened, to apply
along a specified dimension use map(cumsum,...).
If x is scalar, it is returned as such.
See also:
sum
,
cumprod
,
map
.
Error codes:
-1: Nonnumeric input arg
[d] = det(A)
det(A) returns the determinant of a square matrix A.
A may be integer, real or complex valued.
If A is scalar, it is returned as such.
Error codes:
-1: Nonnumeric input arg
-2: Input array is not a matrix
-3: Input matrix is not square
-4: Singular matrix
[y] = diag(x)
diag(V) (V is a vector) returns a square diagonal matrix,
whose diagonal elements are given by V.
diag(M) (M is a matrix) returns the main diagonal of M
as a vector. M need not necessarily be square.
Error codes:
-1: Input array not vector or matrix
[] = disasm(fn)
disasm(f) produces disassembly listing of function f.
Error codes:
1: Argument not a Tela function
[D;V] = eig(A)
eig(A) returns the eigenvalues of a square matrix A.
[D,V] = eig(A) returns the eigenvalues in D and the
right eigenvectors as columns of V. The eigenvectors
satisfy A**V == D*V.
See also:
inv
,
LU
.
Error codes:
1: Failed to converge
-1: Input arg is not an array
-2: Input array is not a matrix
-3: Input matrix is not square
-4: Internal error
[] = eval(s)
eval("string") executes string as a Tela command, as it had been
typed from the keyboard.
The evaluation is done in global context. The symbols appearing
in the string refer to the global ones.
See also:
evalexpr
.
Error codes:
1: Argument not a string
[y] = evalexpr(s)
evalexpr("expression") executes string as a Tela command,
returning its value in y.
The evaluation is done in global context. The symbols appearing
in the string refer to the global ones.
See also:
eval
.
Error codes:
1: Argument not a string
[] = exit()
exit() stops Tela. quit() is synonym for exit().
[y] = exp(x)
y = exp(x) computes the exponent function of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[] = export_PBM(fn,r;g,b)
export_PBM("file.pbm",x) writes integer matrix x in
binary PBM (actually PGM) file "file.pbm". Matrix elements
are truncated to the range 0..255. If all elements are
equal to 0 or 1 a black and white PBM file will be written.
export_PBM("file.pbm",r,g,b) creates a 24-bit PBM file.
The integer matrices r,g and b represent the red, green
and blue values. They must have equal dimensions.
See also:
import_PBM
.
Error codes:
1: First arg not a string
2: Argument is not integer matrix
3: export_PBM must be called with 2 or 4 input args
4: Dimensions of R,G,B matrices must be equal
[] = export_RIS8(fn,x)
export_RIS8("file.hdf",x) writes (appends) integer matrix x
to HDF file "file.hdf" as a raster-8 image (Raster Image Set, RIS).
When the file is opened with default settings using the usual
HDF viewers such as Spyglass products, the first dimension grows
vertically downward and the second dimension grows from left to
right.
The RIS8 HDF files can be read back using import.
See also:
export_matlab
,
save
,
import
.
Error codes:
1: First argument not a string
2: Second argument not an integer matrix
[] = export_matlab(fn...)
export_matlab("file") saves all variables in Tela
workspace in "file". Any previous contents of "file"
are overwritten. The data are written in MATLAB
binary format. Hidden Tela variables are not saved.
export_matlab("file","var1","var2"...) saves only the
specified variables. Notice that you have to give the
variable names as strings.
The resulting MAT-file can be read using the
MATLAB 'load' command.
Limitations (bugs): It is not possible to export
local variables. If you try, the global ones will
be written, if they have numeric values. Use
export_matlab2 to achieve this, and to have explicit
control of variable naming.
See also:
export_matlab2
,
save
,
load
,
import
.
Error codes:
1: Too few arguments
2: Argument not a string
3: Write error on file
[] = export_matlab2(fn...)
export_matlab2("file", var1,"name1", var2,"name2"...)
saves objects var1,var2... in MATLAB binary format in "file".
The objects will be named "name1", "name2"... .
Any previous contents of "file" are overwritten.
workspace in "file". Any previous contents of "file"
is overwritten.
The resulting MAT-file can be read using the
MATLAB 'load' command.
See also:
export_matlab
,
save
,
load
,
import
.
Error codes:
1: First arg not a string
2: Even number of arguments
3: Write error on file
4: The 'name' argument is not a string
[A] = eye(n)
eye(n) returns the (integer) unit matrix of order n.
n must be a non-negative scalar integer.
eye(V) where V is a two-element integer vector with
both elements equal and positive works also, thus
you can also use eye(size(A)).
See also:
ones
,
inv
.
Error codes:
-1: Argument not an integer or IntArray
-2: Negative dimension
-3: IntArray rank not 1
-4: IntArray length not 2
-5: Integer vector elements are unequal
[] = fclose(fnum)
fclose(fnum) closes file with given identification number.
The fnum must have been previously obtained from fopen.
See also:
fopen
,
fformat
.
Error codes:
-1: Bad argument: not integer
-2: Bad argument: outside range
3: File was not open
[] = fformat(fnum,str...)
fformat(fnum,"format-string",arg1,arg2,...) is similar to format,
except that it does not output to stdout but to opened file.
See also:
format
,
sformat
,
fopen
.
Error codes:
-1: First argument not integer
-2: First argument not a valid file number
-3: Second argument not a string or char
4: File is not open
[] = figure(n)
figure(n) causes subsequent plot commands to use
window (figure) number n (n=1,2,...). Figures with
n>1 are drawn over by each new plot command.
figure(-1) restores the default behavior, which is
to create standalone windows. These plots are never
replaced by new graphics and are quit only by the user.
Using this command for n>1 requires that you use the
Tela-compatible PlotMTV version.
See also:
closefig
.
Error codes:
1: Argument is not an integer
2: Figure number zero is reserved, don't use it
3: This Tela installation does not support the figure command
4: Failed X11 initialization, cannot synchronize with PlotMTV
[y] = find(x)
I=find(V) returns the index vector I=(i) for which
V[i] is nonzero. V must be an integer array. The length
of I is equal to the number of nonzeros in V.
If V is multidimensional, it is used in flattened form.
Example: If V=#(1,-2.3,4,5,-8.2), find(V < 0) returns
#(2, 5).
See also:
any
,
all
,
flatten
.
Error codes:
1: Argument not integer vector
[y] = flatten(;x)
flatten(x) returns the array x flattened to a vector.
If x is not an array, it is returned as is.
Example: flatten(#(1,2; 3,4)) returns #(1,2,3,4).
x = flatten() flattens x "in place". This is much faster
(it works in constant time) than to do x = flatten(x),
since no data movement is involved.
[y] = flip(x;d)
flip(A) reverses the first dimension of array A.
flip(A,d) reverses the d'th dimension. For example,
flip(#(1,6,2; 7,9,2.3),2) returns #(2,6,1; 2.3,9,7).
If A is non-array it is returned as such, regardless of d.
See also:
transpose
.
Error codes:
-1: Second argument not an integer scalar
-2: Second argument out of range
[y] = floor(x)
floor(x) returns the largest integer which is smaller than x.
x must be integer or real scalar or array. If it is an array,
the operation is applied componentwise.
See also:
ceil
.
Error codes:
-1: Complex or nonnumeric input argument
[fnum] = fopen(name,mode)
fopen("filename",mode) opens a file and returns
its identifier (integer). The mode parameter can be
"r" or "w" for reading and writing, respectively.
If the open is not succesful, -1 is returned.
See also:
fformat
,
fclose
.
Error codes:
-1: First arg not a string
-2: Second arg not a string
-3: Too many open files
-4: Bad string for second arg
[] = format(str...)
format("format-string",arg1,arg2,...) prints "format-string"
to standard output, replacing occurrences of `format-spec`
with consecutive args. `Format-spec` is either empty, i.e. ``,
or of the form
`[-]w[.d]`.
Here w is the field width (unsigned integer) and d is the number
of significant digits, also unsigned integer. By default the
argument is printed left-justified, but the optional minus sign
dictates right justification. The backquote character ` can be
produced by writing it three times: ```.
Hint: You can add any number of spaces before the closing backquote,
for example `20.7 `.
These spaces do not affect the output. This feature can be used
to justify source code lines.
See also:
fformat
,
sformat
.
Error codes:
1: First argument not a string or char
[] = fprintf(fnum,formatstr...)
fprintf(fnum,"format-string",arg1,arg2,...) is an interface to the C
fprintf function. The format string should have a percent slot
for every arg. The args may be integer or real scalars or strings.
The file identifier fnum must have been obtained from fopen.
Notice: The stream is not flushed after every fprintf operation,
but a flush occurs whenever you switch from using fprintf to
fformat on the same file. Therefore avoid mixing fprintf and fformat
on the same file if performance is an issue for you!
See also:
fopen
,
printf
,
sprintf
,
format
.
Error codes:
1: Bad argument type
2: Second arg not a string
3: First argument not an integer
4: Bad file identifier: out of range
5: File is not open
6: Internal error: fdopen failed
[y] = getenv(varname)
getenv("envvar") returns the value of environment variable
"envvar", or VOID if such variable is not defined in
the UNIX environment.
For example, getenv("LOGNAME") returns the login name of
the owner of the Tela prcess.
(If Unix functions are not available, getenv will always
return VOID.)
See also:
getpid
,
cd
.
Error codes:
-1: Argument not a string
[y] = getpid()
getpid() returns the process ID of the Tela process.
This can be used e.g. to generate unique temporary
file names. If Unix functions are not available,
getpid() returns 0.
[X,Y] = grid(x,y)
[X,Y] = grid(x,y) produces matrices X,Y that are formed from vectors x,y
such that X[i,j] = x[i] for all j, and Y[i,j] = y[j] for all i.
See also:
grid3
.
Error codes:
-1: Input argument is array but not a vector
-2: Input argument is not real array
[X,Y,Z] = grid3(x,y,z)
[X,Y,Z] = grid3(x,y,z) produces 3D arrays X,Y,Z that ar
formed from vectors x,y,z such that
X[i,j,k] = x[i] for all j,k,
Y[i,j,k] = y[j] for all i,k, and
Z[i,j,k] = z[k] for all i,j.
See also:
grid
.
Error codes:
-1: Input arg is array but not a vector
-2: Input arg not a real array
[] = help(;fn)
help(function-name) or help("help-item") displays the help information
associated with a given function or a given help item. On command line
you may use the abbreviation
?help-item
or
help help-item
These forms are translated to help("help-item") before parsing.
First tries:
help operators
help special
help if
help for
help function
...
Error codes:
1: Item not found
2: Cannot open help file
[B] = herm(A; P)
herm(A) is the same as conj(transpose(A)).
herm(A,P) is the same as conj(transpose(A,P)).
You can abbreviate "herm(A)" as "A'".
See also:
transpose
,
flip
,
conj
.
Error codes:
-1: Permutation argument not integer array
-2: Permutation argument of bad rank or size
-3: Permutation argument contains invalid integers
[] = hide(...)
hide("sym-name",...) sets the 'hidden' attribute to
specified symbols.
See also:
whos
,
unhide
,
autoglobal
.
Error codes:
1: Argument not a string
2: Argument does not name a symbol
[;ndata,xdata] = hist(x...)
hist(x) produces a histogram of vector x.
The range min(x)..max(x) is divided in bins, and the
number of x values in each bin is counted. The count determines
the height of each bin.
hist(x) uses 10 bins, hist(x,n) uses n bins.
hist(x,n,a) starts from x=a.
hist(x,n,a,b) ignores x values outside interval a..b.
Rest of the args may contain other MTV options.
[ndata,xdata] = hist(args) returns the count and abscissa vectors
but does not draw anything. bar(xdata,ndata,"lab") can be used to draw
the histogram later. Graphics options are ignored in this case.
See also:
plot
,
bar
.
Error codes:
1: First argument not a (real) vector
2: Second arg not a positive integer
3: Third arg not a (real) scalar
4: Fourth arg not a (real) scalar
5: Third arg greater of equal than fourth arg
6: Could not open temporary MTV file
7: Syntax error in graph options
[] = hold(flag)
hold(on) and hold(off) set the graphics hold mode on and off.
When hold is on, all graphics commands will be accumulated and
performed only until hold(off).
If hold(on) is called many times in succession, also hold(off)
must be called as many times until the plots are produced.
For example, if
function f() {hold(on); plot1(); plot2(); hold(off)};
and it is called as
hold(on); f(); plot3(); hold(off);
then all three plots are actually combined in one plot.
hold(-1) can be used to reset the internal counter.
Use it in emergency.
See also:
plot
,
holdmode
.
Error codes:
1: Argument not an integer
[result] = holdmode(;flag)
holdmode(overlay) causes held plots to be combined in same figure.
holdmode(paging) shows them as sequential pages in one window.
holdmode(stacking) draws them as subplots in one window.
holdmode() returns the current setting.
See also:
hold
.
Error codes:
1: Argument not an integer
2: Bad value for argument
[] = import(filename; appendix)
import("file") tries to load the contents of "file" in
Tela workspace. All files accepted by load are also accepted
by import. In addition, import accepts more general HDF files
(SDS and 8-bit raster image files) as well as MATLAB binary
files (MAT-files).
import("file","app") appends the string "app" to the name
of every variable imported.
Restrictions:
1) Only MATLAB files created on a similar architecture can be
correctly imported. If this rule is not followed, the imported
data will be garbage!
2) MATLAB4.0 and higher saves arrays with more than 10000 elements
as various integer formats, if all elements are whole numbers.
Tela cannot read these files. A workaround is to perturb one element
in MATLAB before saving so that it is not exactly integer.
3) If file is HDF-file, import first tries to read all SDSs.
Only if none was found, it tries to read all RIS8 datasets.
The variable names are taken from the HDF labels, if the labels
have been set. If there are no labels, the variables are named
"Dataset1", "Dataset2", ... and "Image1", "Image2",... for
SDS and RIS8 imports, respectively.
For filename conventions, see load.
See also:
load
,
save
,
import1
,
export_matlab
,
export_RIS8
,
import_PBM
.
(The difference between import and import1 is that import1 reads
only one object and returns it, whereas import reads several
objects and assigns them directly to workspace variables.)
Error codes:
1: First arg not string or char
2: First arg is not an HDF file
3: File not found
4: Cannot import file
5: Unused error message
6: Cannot import this Matlab file (O(letter'Oh) != 0, (can even Matlab?))
7: Cannot import this Matlab file (P != 0). Is your array size >10000 and all integer? Try perturbing it
8: Cannot import this Matlab file (T != 0, 1). Is it a sparse matrix? Make it full
10: Bad Matlab binary file, premature end of file
11: Second argument not a string
[x] = import1(filename; label)
import1("file") reads one object from "file". The imported
object is returned. "File" can be one of the following:
1) HDF file, in which case the first Scientific Data Set (SDS)
is imported. The form import1("file.hdf","label") reads SDS
with label "label", which is not necessarily the first one.
2) D-style ASCII file of the following format:
(line 1) D=Nt dim1 dim2 ... dimN
(any number M of blank lines or lines starting with '#')
(line M+2) data1 data2 ....
where N is the rank of the dataset and t is an optionial
type specification letter: t may be either 'r', 'i', or 'c'
for real, integer and complex data, respectively. If t is
missing, real data are asssumed.
3) Plain ASCII file of nrows x ncols real numbers. If nrows or
ncols is 1, it will be returned as a vector, otherwise as a
matrix. Missing entries are treated as zeros. This format
is similar to Matlab's load for ASCII, except that '#'
comments are accepted in the beginning.
See also:
import
,
load
,
save
.
See import for a difference between import and import1.
For filename conventions, see load.
Error codes:
-1: Input arg not a char or string
-2: File not found
-3: Unknown format in ASCII file
-4: Unknown format in ASCII file
-5: Too high rank ASCII data
-6: Syntax error in ASCII file dimension specification
-7: Syntax error when reading D-style ASCII data
-8: Internal error
-9: Cannot import file
-10: Second arg not a string
-11: Specified label not found
-12: Premature end of file in D-style ASCII
-13: Syntax error when reading plain ASCII data
[r;g,b] = import_PBM(fn)
x = import_PBM("file.pbm") reads PBM format image file.
x will become integer matrix.
[r,g,b] = import_PBM("file.pbm") reads a color image
and assigns the red, green and blue components to
matrices r,g,b.
All six PBM formats (P1-P6) are recognized. If a color
image (P3 or P6) is loaded using only one output argument,
the average of color components is computed and assigned
to x. If a greyscale image is loaded using three output
args, only the first (r) output arg will be filled,
g and b are assigned the VOID value. You might use
a code like
[r,g,b] = import_PBM("file.pbm");
if (isvoid(g)) {g=r; b=r};
to continue processing in 24-bit mode.
See also:
import
,
export_PBM
.
Error codes:
-1: First arg not a string
-2: Could not open input file
-3: Input file is not PBM file
-4: Width or height not positive - improper PBM file
-5: Color range not in 1..255
-6: Two output args, give 1 or 3
-7: Error when rading ASCII data
-8: Pixel not 0 or 1 in 1-bit image
-9: Pixel out of range 0..255
-10: Could not read all binary data
[] = info()
info() shows information about various class sizes for this Tela implementation.
It also prints the total counts of Tnode, Tprg and Tobject objects at the moment.
[s] = input_string(;prompt)
input_string() waits for an input line from the keyboard
and returns it as a string. The newline is not included
in the result.
If the string is enclosed in double quotes, they are removed.
input_string("prompt") displays prompt first.
Error codes:
-1: EOF encountered.
[y] = intpol(A...)
intpol(A,index1,index2...) is a general interpolation
function. A must be an array from which values are interpolated.
The rank of A must equal the number of index arguments.
Each index argument may be a real scalar or real array.
All index arguments must mutually agree in type and rank.
The array A may also be complex. The result y is of same
rank and size as each of the index arguments.
intpol(A,i,j,...) is a generalization of mapped indexing
A<[i,j,...]> for non-integral indices. The function benefits
from vectorization even more than most other Tela functions.
Currently intpol uses linear interpolation.
Error codes:
-1: First arg not a numerical array
-2: Rank of first arg does not match number of index args
-3: Non-real index arg
-4: Dissimilar index args
-6: Range overflow
[B] = inv(A)
inv(A) returns the inverse of a square matrix A.
A may be integer, real or complex valued.
A may also be a scalar, in which case its reciprocal
is returned.
See also:
linsolve
,
LU
,
chol
,
matprod
,
det
,
eig
.
Error codes:
-1: Nonnumeric input arg
-2: Input array is not a matrix
-3: Input matrix is not square
-4: Singular matrix
-5: Singular matrix
[f] = invFFT(u; dim)
invFFT() is the inverse of FFT().
For vector f, u=invFFT(f) is equivalent with
n = length(f); u = czeros(n);
for (j=1; j<=n; j++)
u[j] = (1/n)*sum(f*exp((j-1)*(0:n-1)*2i*pi/n));
Differences with FFT: sign of i is plus, scale factor 1/n.
See also:
FFT
.
Error codes:
-1: First argument not a numeric array
-2: Second argument not integer
-3: Second argument out of range
[f] = invcosFFT(u; dim)
invcosFFT() is the inverse of cosFFT().
Actually invcosFFT differs from cosFFT only by normalization,
but it is provided as a separate function for convenience.
For vector f, u=invcosFFT(f) is equivalent with
n = length(f); u = zeros(n);
for (j=1; j<=n; j++)
u[j] = (f[1] - (-1)^j*f[n] + 2*sum(f[2:n-1]*cos((1:n-2)*(j-1)*pi/(n-1))))/(2*n-2)
See also:
cosFFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[f] = invcosqFFT(u; dim)
invcosqFFT() is the inverse of cosqFFT()
(inverse quarter-wave cosine Fourier transform).
For vector f, u=invcosqFFT(f) is equivalent with
n = length(f); u = zeros(n);
for (j=1; j<=n; j++)
u[j] = (1/n)*sum(f*cos((2*(1:n)-1)*(j-1)*pi/(2*n)));
See also:
cosqFFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[f] = invrealFFT(u; dim,oddevenspec)
invrealFFT() is the inverse of realFFT().
invrealFFT(u,dim,"even") and invrealFFT(u,dim,"odd") specifies
even or odd transform length, respectively.
invrealFFT(u,dim,N) uses the same evenness as the integer N has.
If the evenness is not specified explicitly, the imaginary parts
of the highest frequency components are tested. If they are all zero
the transform length is even, otherwise odd. However, this automatic
method will fail if the imaginary parts are not EXACTLY zero. If you
use multiple FFTs to solve a PDE, for example, you should probably
specify the evenness explicitly.
See also:
realFFT
.
Error codes:
-1: First argument not a complex array
-2: Second argument not integer
-3: Second argument out of range
-4: Third argument not "even", "odd" or an integer
[f] = invsinFFT(u; dim)
invsinFFT() is the inverse of sinFFT().
Actually invsinFFT differs from sinFFT only by normalization,
but it is provided as a separate function for convenience.
For vector f, u=invsinFFT(f) is equivalent with
n = length(f); u = zeros(n);
for (j=1; j<=n; j++)
u[j] = (1/(n+1))*sum(f*sin((1:n)*j*pi/(n+1)));
See also:
sinFFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[f] = invsinqFFT(u; dim)
invsinqFFT() is the inverse of sinqFFT()
(inverse quarter-wave sine Fourier transform).
For vector f, u=invsinqFFT(f) is equivalent with
n = length(f); u = zeros(n);
for (j=1; j<=n; j++)
u[j] = (1/n)*sum(f*sin((2*(1:n)-1)*j*pi/(2*n)));
See also:
sinqFFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[y] = isCfunction(x)
isCfunction(x) returns 1 if x is a C-tela function.
and 0 otherwise.
See also:
isfunction
,
isTfunction
.
[y] = isTfunction(x)
isTfunction(x) returns 1 if x is a function written in Tela
and 0 otherwise.
See also:
isfunction
,
isCfunction
.
[y] = isarray(x)
isarray(x) returns 1 if x is an array and 0 if it is not.
See also:
isscalar
,
isvector
,
ismatrix
.
[y] = ischar(x)
ischar(x) returns 1 if x is a character and 0 otherwise.
See also:
isstring
,
isstr
.
[y] = iscomplex(x)
iscomplex(x) returns 1 if x is a complex array or scalar,
and 0 if it is real or integer or a nonnumeric object.
See also:
isreal
,
isfloat
,
isint
.
[y] = isdefined(x)
isdefined(x) returns 1 if x is not undefined and 0 if
it is undefined. Optional function arguments are undefined
if not assigned by the caller; isdefined can be used
inside the function to test whether this is the case.
See also:
isundefined
.
[y] = isfinite(x)
isfinite(x) returns 1 if x is a finite number and 0 otherwise.
If x is array, the operation is applied componentwise.
If x is non-numeric it is considered not finite.
Integer and consequently strings and chars are always finite.
[y] = isfloat(x)
isfloat(x) returns 1 if x is a floating point array
or scalar, and 0 otherwise. Notice the difference between
isfloat and isreal. isreal(x) is 1 for integer objects,
while isfloat(x) is 0.
See also:
isreal
,
isint
,
iscomplex
.
[y] = isfunction(x)
isfunction(x) returns 1 if x is a function
(Tela-function, C-tela function or intrinsic function)
and 0 otherwise.
See also:
isCfunction
,
isTfunction
.
[y] = isint(x)
isint(x) returns 1 if x is integer scalar or array
and 0 if it is not.
See also:
isreal
,
isfloat
,
iscomplex
.
[y] = ismatrix(x)
ismatrix(x) returns 1 if x is a matrix (2D array)
and 0 if it is not.
See also:
isscalar
,
isvector
,
isarray
.
[y] = isreal(x)
isreal(x) returns 1 if x is numerical non-complex
array or scalar, and 0 otherwise.
See also:
isfloat
,
isint
,
iscomplex
.
[y] = isscalar(x)
isscalar(x) returns 1 if x is scalar and 0 if it is not.
See also:
isvector
,
ismatrix
,
isarray
.
[y] = isstr(x)
isstr(x) returns 1 if x is a character or string
and 0 otherwise.
See also:
isstring
,
ischar
.
[y] = isstring(x)
isstring(x) returns 1 if x is a string and 0 otherwise.
See also:
ischar
,
isstr
.
[y] = isundefined(x)
isundefined(x) returns 1 if x is not undefined and 0 if
it is undefined. Optional function arguments are undefined
if not assigned by the caller; isdefined can be used
inside the function to test whether this is the case.
See also:
isdefined
.
[y] = isvector(x)
isvector(x) returns 1 if x is a vector and 0 if it is not.
See also:
isscalar
,
ismatrix
,
isarray
.
[y] = isvoid(x)
isvoid(x) returns 1 if x is a void value and 0 otherwise.
[L] = length(x)
length(x) returns the total number of elements in array x.
If x is scalar, length(x) is 1. If x is undefined, an error
results. Notice that if x is e.g. a matrix, its length is
equal to the product of the row and column dimensions,
which is different from e.g. the Matlab convention.
See also:
size
,
rank
.
Error codes:
-1: Argument has undefined value
[] = link(filename)
link("file.o") makes C-tela functions in "file.o" available
to Tela. "file.o" must be compiled from a C-tela file
(usually "file.ct").
Error codes:
1: Cannot initialize DLD
2: Cannot link-load file
3: Argument not string or char
4: Cannot find fninfo pointer
5: Internal inconsistency
6: Undefined symbols remain
7: main function returned error code
8: Could not dlclose the previous linkage
9: Too many dynamically linked modules
10: File not found
[x] = linsolve(A,b)
linsolve(A,b) solves the linear system A**x == b.
If A is square, the result x is roughly the same as
computing inv(A)**b (however, using linsolve is
faster and numerically more accurate). If A is not
square, a least-square problem is solved. If the system
is overdetermined, the solution x minimizes the quantity
|A**x - b|. If the system is underdetermined, the
solution x minimizes |x| among all x that satisfy
A**x==b.
The second argument may be a vector or a matrix.
If it is a matrix, several linear systems are effectively
solved simultaneously.
See also:
inv
,
LU
,
eig
,
SVD
.
Error codes:
-1: First input arg is not an array
-2: First input arg is not a matrix
-3: Second input arg is not an array
-4: Second input arg is not a vector or matrix
-5: Incompatible dimensions in first/second args
-6: Matrix must be square
-7: Singular matrix
-8: Internal error
[] = load(filename)
load("file") loads the contents of "file"
in Tela workspace.
"file" must have been previously created using
the 'save' command; it must be in a certain
HDF format.
Filename conventions:
If the filename starts with "/", "./" or "..",
it is considered absolute. Otherwise it is searched
along TELAPATH. This applies to other file
operations as well.
The counterpart of load is save.
To read more general HDF files and ASCII files,
see import1.
To load more general HDF files and MATLAB binary
files, see import.
See also:
save
,
import
,
import1
,
export_matlab
.
Error codes:
1: Argument not string or char
2: Argument is not an HDF file
3: File not found
[y] = log(x)
y = log(x) computes the natural logarithm of x.
If x is complex, the result is complex. If x is real or
integer, but negative, the result is complex (purely
imaginary). If x is real or integer and non-negative,
the result is real.
If x is an array, the operation is applied componentwise.
If some of the components are negative, all components
of the result are complex.
[B] = map(fn,A,darg)
[B] = map(fn,A,d) maps function fn along d'th dimension
in array A. Fn is a functional argument. It must return a scalar
or a vector when called with one vector argument. The type and length
of the returned value must not change from call to call.
For example, map(mean,A,1) computes the columnwise means
of matrix A, returning a vector. map(sort,A,2) sorts all rows
of matrix A in ascending order. Notice than many standard
functions, including mean, have a builtin mapping capabability;
using map in these cases is unnecessary.
See also:
mapmin
,
mapmax
,
flip
.
Error codes:
-1: First arg not a function
-2: Second arg not a numerical array
-3: Third arg not an integer scalar
-4: Third arg (the dimension) out of range
-5: First arg (function) did not return a numerical object
-6: First arg (function) unexpectedly changed its return type
-7: First arg is an intrinsic function; it is no good
-8: Function returned rank>1 array when first called
[y;P] = mapmax(x;d)
mapmax(x,d) finds maximum along d'th dimension in array x.
The result is an array with rank one less than rank(x).
The array may not be complex.
[M,p] = mapmax(x,d) returns the maximum positions p along with
the maximums m. The array p is of the same shape as M, but is
integer-valued.
mapmax(x) is a flattened form which returns a scalar result.
It is equivalent to max(x). [M,p] = mapmax(x) also works.
Using mapmax is faster than using map and max together.
In the latter case you would also have to define another function:
function y=max1(x) {y=max(x)}
because being intrinsic function, max can not be passed
to map directly.
See also:
mapmin
,
map
.
Error codes:
-1: First arg not a numerical array
-2: Second arg not an integer scalar
-3: Second arg (the dimension) out of range
-4: First arg is complex
[y;P] = mapmin(x;d)
mapmin(x,d) finds minimum along d'th dimension in array x.
The result is an array with rank one less than rank(x).
The array x may not be complex.
[m,p] = mapmin(x,d) returns the minimum positions p along with
the minimum values m. The array p is of the same shape as m,
but is integer-valued.
mapmin(x) is a flattened form which returns a scalar result.
It is equivalent to min(x). [m,p] = mapmin(x) also works.
Using mapmin is faster than using map and min together.
In the latter case you would also have to define another function:
function y=min1(x) {y=min(x)}
because being intrinsic function, min can not be passed
to map directly.
See also:
mapmax
,
map
.
Error codes:
-1: First arg not a numerical array
-2: Second arg not an integer scalar
-3: Second arg (the dimension) out of range
-4: First arg is complex
[...] = matlab_call(fname...)
[a,b,c,...] = matlab_call("fname",d,e,f,...)
calls a Matlab function in a currently running background
Matlab process. Input arguments (any number) d,e,f,...
are sent to Matlab prior to call, and output arguments
(any number) a,b,c,... are collected and returned to Tela
after the function has completed.
See also:
matlab_start
,
matlab_eval
,
matlab_put
,
matlab_get
.
Error codes:
1: Unknown error when sending input argument
2: Function call unsuccessful
3: Internal error: No such output argument in Matlab workspace
4: Output argument is of unsupported type (not double)
5: Output argument is of unsupported type (not full matrix)
-1: Internal error: matlab_put or matlab_get first argument not a string
-2: No Matlab process running, use matlab_start first
-3: Input argument not interpretable as a matrix
-4: Input argument has too high (> 2) rank
-5: First argument not a string
[retval] = matlab_eval(str)
matlab_eval("command") sends "command" to currently
running Matlab background process. It returns 1
if succesful 0 if an error occurred.
See also:
matlab_start
,
matlab_put
,
matlab_call
.
Error codes:
-1: Argument not a string
-2: No Matlab process running, use matlab_start first
[y] = matlab_get(name)
matlab_get("MatrixName") asks a currently running background
Matlab process for a variable named "MatrixName", and returns
its value.
See also:
matlab_start
,
matlab_put
,
matlab_eval
.
Error codes:
-1: Argument not a string
-2: No Matlab process running, use matlab_start first
3: No such variable in Matlab workspace
4: The variable is of unsupported type (not double)
5: The variable is of unsupported type (not full matrix)
[] = matlab_put(name,value)
matlab_put("MatrixName",x) tries to interpret x as
a Matlab matrix and sends it to currently running
background Matlab process. The matrix is assigned to
variable "MatrixName" in Matlab side.
matlab_put returns 1 if successful and 0 if not.
See also:
matlab_start
,
matlab_get
,
matlab_eval
.
Error codes:
1: Unknown error
-1: First argument not a string
-2: No Matlab process running, use matlab_start first
-3: Second argument not interpretable as a matrix
-4: Second argument has too high (> 2) rank
[] = matlab_start(;startcmd)
matlab_start() starts a new Matlab process on background.
You can send to it commands with matlab_eval.
matlab_start("startcmd") uses "startcmd" to start up
Matlab. The default "startcmd" is "matlab".
If matlab_start() has already been called, a new call
is harmless and does nothing.
See also:
matlab_eval
,
matlab_call
,
matlab_stop
.
Error codes:
1: Could not start Matlab
-1: Argument not a string
[] = matlab_stop()
matlab_stop() stops a currently running Matlab process.
See also:
matlab_start
,
matlab_eval
.
Error codes:
1: No Matlab process running; none to be stopped
2: Unknown error occurred when trying to stop Matlab process
[C] = matprod(A,B; Aflag,Bflag)
matprod(A,B) returns the matrix product of A and B.
If at least one of A and B is scalar, matprod(A,B) is the
same as their ordinary product A*B. If both A and B
are arrays, their "inner" dimensions must agree.
That is, the last dimension of A must equal the first
dimension of B.
You can abbreviate matprod(A,B) as A**B.
Optional args: matprod(A,B,aflag,bflag) can be used to
transpose or Hermitian-conjugate the factors before the
product. 'n' means no operation, 't' means transpose and
'h' means Hermitian conjugate. For example,
matprod(A,B,'h') = A'**B = herm(A)**B
matprod(A,B,'n','t') = A**B.' = A**transpose(B)
Normally you need not use matprod explicitly, but you
can use the operator **, which is internally translated
to matprod. Hermitian conjugates and transposes in
connection with ** produce the corresponding 'h' and
't' options in matprod. For example,
A'**B generates matprod(A,B,'h')
A.'**B' generates matprod(A,B,'t','h')
A**B.' generates matprod(A,B,'n','t')
and so on. The runtime is optimal for all these operations.
See also:
inv
.
Error codes:
-1: Inner dimensions do not agree
-2: Resulting array would have too high rank
-3: Third arg not one of 'n', 't', 'h'
-4: Fourth arg not one of 'n', 't', 'h'
[result] = menu(title...)
choice = menu("title","choice1","choice2",...) displays
a menu of choices and returns the number entered by
the user.
See also:
smenu
.
Error codes:
-1: Less than two input args
[] = mesh(z...)
mesh(z[,options]) plots the matrix z as a 3D mesh.
See also:
annotate
,
plot
,
contour
,
pcolor
,
vplot
.
Error codes:
1: Could not open temporary MTV file
2: First argument is not a numeric 2D array
3: Syntax error in graph options
4: Write error in MTV file - file system full?
[y] = ones(...)
ones(n,m...) returns an integer array with all elements
equal to 1 of size n x m x ... .
ones(V) where V is an integer vector, and thus
ones(size(A)), works also.
See also:
rand
,
eye
.
Error codes:
-1: Input argument not an integer or IntVector
-2: Rank of requested tensor array exceeds MAXRANK
-3: Non-positive input argument
-4: Negative input argument
-5: Integer array rank not 1
[] = pause(;seconds)
pause() will wait for a keypress on keyboard.
pause(n) will pause for n seconds and then continue.
The argument n may be integer or real.
Note: some systems implicitly round a real argument
to nearest whole number.
Error codes:
1: Argument not a real scalar
2: Argument is negative
3: This system does not support pausing for n seconds
[] = pcolor(z...)
pcolor(z[,options]) plots the matrix z as a pseudocolor density plot.
See also:
annotate
,
plot
,
contour
,
mesh
,
vplot
.
Error codes:
1: Could not open temporary MTV file
2: First argument is not a numeric 2D array
3: Syntax error in graph options
4: Write error in MTV file - file system full?
[v] = perf()
perf() returns an array containing all maintained operation
counters. To measure performance of a code segment, do
p0=perf(); mycode(); p=perf()-p0;
Now you can apply various performance-related functions to p:
for example cputime(p), Mflops(p).
[] = pixmap(flag)
pixmap(off) tells PlotMTV not to use pixmaps for faster redraw.
pixmap(on) turns the pixmap mode on, which is the default.
If your X server uses backing store, you can save memory
by turning pixmap(off) without hurting performance.
Error codes:
1: Argument is not an integer
[] = plot(...)
plot(x1,y1,[options1], x2,y2,[options2],...) is the basic 2D plot function.
Each vector yi is plotted versus the corresponding xi. All curves yi are
displayed in the same figure. The option sequences must consist of keyword-
value pairs. Example:
x = 0:0.1:4*pi;
plot(x,sin(x), "linewidth",3,"linecolor",2);
The abscissa x may be missing, in which case the default of 1:length(y)
is used. The ordinates y may be matrices; then each row produces one
curve. If also abscissa x is matrix, the x-value may be different for each
curve.
See also:
plot3
,
annotate
,
plotopt
,
mesh
,
contour
,
pcolor
,
vplot
.
Error codes:
1: Could not open temporary MTV file
2: Nonnumeric or complex data argument
3: Syntax error in graph options
4: The abscissa ("x") must be a vector or a matrix
5: The ordinate ("y") must be a vector or a matrix
6: x and y dimensions disagree
[] = plot3(x,y,z...)
plot3(x,y,z[,options]) produces parametric space curves.
The quantities x,y,z must have equal ranks, and they can
be either vectors or matrices. If they are vectors, only
one space curve is drawn. If they are matrices, the number
of curves produces equals the number of rows.
See also:
plot
,
annotate
.
Error codes:
1: Could not open temporary MTV file
2: y dimensionality disagrees with x dimensionality
3: z dimensionality disagrees with x dimensionality
4: Input arrays must be integer or real arrays
5: Input arrays must have rank equal to 1 or 2
6: Syntax error in graph options
[] = plotopt(s)
plotopt("-3d -colorps -landscape...") sets a set of PlotMTV command
line options for subsequent graphics commands (global setting).
See also:
plot
,
annotate
.
NOTICE: plotopt is usually not required. You can pass the option string
to all plot commands directly, for example:
plot(x,sin(x),"-3d -landscape");
These options affect only the current (or next outputted, if hold is used)
plot. All graphics function optional string args which start with minus sign
are assumed to be PlotMTV command line options.
Error codes:
1: Argument not a string
[] = printf(formatstr...)
printf("format-string",arg1,arg2,...) is an interface to the C
printf function. The format string should have a percent slot
for every arg. The args may be integer or real scalars or strings.
See also:
fprintf
,
sprintf
,
format
.
Error codes:
1: Bad argument type
2: First arg not a string
[y] = prod(x;d)
prod(x) multiplies all the elements of x, if x is an array.
prod(x,d) takes the product along d'th dimension only, returning
an array of rank one less than rank(x).
If x is scalar, it is returned as such.
If I is integer array, prod(I) will be of type real if the product
would cause integer overflow. In all other cases, including prod(I,d),
the type of y equals the component type of x.
See also:
sum
,
cumprod
.
Error codes:
-1: Nonnumeric input arg
-2: Second argument not an integer
-3: Second argument (dimension spec) out of range
[] = quit()
quit() stops Tela. quit() is synonym for exit().
[x] = rand(...)
rand() returns a random real x, 0<=x<1.
rand(N) (N positive integer) returns a real random vector of length N.
rand(N,M) returns a random matrix, and so on.
See also:
srand
.
Error codes:
-1: Tried to create too high rank array
-2: Argument not an integer
-3: Non-positive integer argument
[y] = rank(x)
rank(A) returns the number of dimensions of array A.
The rank of a scalar is 0. The rank of a nonnumeric
object, including undefined value, is -1. The rank function
never generates an error.
See also:
length
,
size
.
[f] = realFFT(u; dim)
realFFT(u) gives the Fast Fourier Transform of real array u.
If u's rank is more than one, the transform is computed
only along the first dimension (many independent 1D
transforms).
realFFT(u,dim) computes the FFT along the specified dimension.
The first dimension is labeled 1 and so on.
The result of realFFT() is the same as FFT() except that only
nonnegative frequency components are returned. The result is
always complex array. The first component (0 frequency) has always
zero imaginary part. If the transform length is even, the last
component has zero imaginary part as well. Notice that these
conventions are different from some generally used C and Fortran
library routines, which return a real array force-fitted
in the same space as the input array by not storing the zero
imaginary parts. The Tela convention allows you to manipulate the
result in k-space more easily because it is already complex.
realFFT is the most efficient when the transform length is
a product of small primes.
See also:
invrealFFT
,
FFT
,
sinFFT
,
cosFFT
,
sinqFFT
,
cosqFFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[] = remove(fn)
remove("file") removes the named file.
If the file does not exist or some other error occurs,
no warning or error message is given.
Error codes:
1: Argument not a string
[B] = reshape(A...)
reshape(A,n,m,...) returns the data in array A rearranged
to have dimensionality n x m x ... . The product of the indices
must equal the length of A.
reshape(A,#(n,m...)) works also.
Example: reshape(#(1,2,3,4,5,6), 2,3) returns
#(1, 2, 3;
4, 5, 6)
Error codes:
-1: First argument not an array
-2: Later argument not an integer
-3: Product of dimensions does not equal the length of first argument
-4: Number of input arguments exceeds MAXRANK
-5: Second arg is array but not integer vector
[y] = round(x)
round(x) returns the nearest integer.
x must be integer or real scalar or array. If it is an array,
the operation is applied componentwise.
See also:
floor
,
ceil
.
Error codes:
-1: Complex or nonnumeric input argument
[output] = run(cmd; input)
run("cmd","input") runs operating system (Unix) command
"cmd", using contents of the second argument string as
standard input. It returns the standard output of "cmd"
as a string.
The form run("cmd") may be used if the command does not
read standard input. The command is executed by /bin/sh.
Error codes:
-1: First argument not a string
-2: Second argument not a string
-3: Error with temporary file
-4: Error with internal pipe
-5: run not supported: OS does not provide unistd.h nor popen()
-7: wait(2) returned error
-8: pipe(2) returned error
-9: cannot fork(2) a child process
[] = save(fn...)
save("file") saves all variables in Tela workspace
in "file". Any previous contents of "file" is
overwritten. The data are written as Scientific
Data Sets in HDF format. Hidden variables are not saved.
save("file","var1","var2"...) saves only the
specified variables. Notice that you have to give
the variable names as strings.
Limitations (bugs): It is not possible to save
local variables, since they are not bound to
symbols. If you try, the global one, if any,
will be saved.
See also:
load
,
export_matlab
.
Error codes:
1: Too few arguments
2: Argument not a string or char
3: Unexpected HDF error
[y] = sec(x)
y = sec(x) is the secant function
sec(x) = 1/cos(x).
[s] = sformat(formatstr...)
sformat("format-string",arg1,arg2,...) is similar to format,
except that it does not output to stdout but returns a string
variable.
See also:
format
,
fformat
,
sprintf
.
Error codes:
-1: First argument not a string or char
[] = showcompiled(filename...)
showcompiled("filename.ct",f1,f2,...) compiles functions
f1,f2,... to C-tela code, creating "filename.ct".
If no suffix is given in "filename", the suffix
".ct" will be assumed.
showcompiled(f1,f2,...) displays on standard output.
See also:
t2ct
.
NOTE: STILL UNDER DEVELOPMENT
Error codes:
1: One of the args is not a Tela-function
2: Cannot open output file
[y] = sign(x)
y = sign(x) returns 1 if x>0, 0 if x==0, and -1 if x<0.
x must be real. If x is array, the operation is applied componentwise.
See also:
HeavisideTheta
.
Error codes:
-1: Complex or nonnumeric input argument
[y] = sin(x)
y = sin(x) computes the sine function of x.
If x is complex, the result is complex, otherwise real.
The argument must be in radians.
If x is an array, the operation is applied componentwise.
[f] = sinFFT(u; dim)
sinFFT(u) gives the sine Fast Fourier Transform of array u.
If u's rank is more than one, the transform is computed
only along the first dimension (many independent 1D
transforms).
sinFFT(u,dim) computes the FFT along the specified dimension.
The first dimension is labeled 1 and so on.
For vector u, f=sinFFT(u) is equivalent with
n = length(u); f = zeros(n);
for (j=1; j<=n; j++)
f[j] = 2*sum(u*sin((1:n)*j*pi/(n+1)));
Note that sinFFT is the most efficient when n+1 is a product of
small primes, where n is the transform length.
See also:
invsinFFT
,
cosFFT
,
sinqFFT
,
cosqFFT
,
realFFT
,
FFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[y] = sinh(x)
y = sinh(x) computes the hyperbolic sine function of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[f] = sinqFFT(u; dim)
sinqFFT computes the quarter-wave sine Fourier transform of array u.
Except for the quarter-wave sine character, it works similarly to sinFFT.
For vector u, f=sinqFFT(u) is equivalent with
n = length(u); f = zeros(n);
for (j=1; j<=n; j++)
f[j] = (-1)^(j-1)*u[n] + 2*sum(u[1:n-1]*sin((2*j-1)*(1:n-1)*pi/(2*n)));
sinqFFT is most efficient when the transform length is a product
of small primes.
See also:
invsinqFFT
,
realFFT
,
cosqFFT
,
FFT
.
Error codes:
-1: First argument not a real array
-2: Second argument not integer
-3: Second argument out of range
[...] = size(x)
[n,m,...] = size(A) finds out the dimensions of array A.
The number of n,m... must not exceed rank(A). If rank(A)==0
(that is, A is scalar), n=size(A) sets 1 to n.
V = size(A) assigns the dimension vector [n,m,..] to V.
If A is scalar, V is set to 1, if A is vector, V becomes
a one-element vector.
See also:
length
,
rank
.
Error codes:
-1: No output arguments
-2: Argument has undefined value
1: More than one output arg but non-array input arg
2: Too many output args relative to input arg rank
[result] = smenu(title...)
choice = smenu("title","choice1","choice2",...) displays
a menu of choices and returns the "choice" string corresponding
to the number entered by the user.
See also:
menu
.
Error codes:
-1: Less than two input args
[y;I] = sort(x)
sort(x) returns array x sorted in ascending order.
If x is complex, it is sorted by the real parts.
If x is not an array, it is returned as is.
[y,I] = sort(x) returns also an index vector I such that
y == x[I].
To sort with user-defined comparisons, do the following.
For example, if you want to sort a complex vector z by
absolute value as Matlab does, first sort a vector of
absolute values saving the index information:
[y,I] = sort(abs(z));
Then y=z[I] is the wanted result.
If x is multidimensional, it is implicitly flattened.
Use the map function to get around this problem.
[] = source(fn)
source("file.t") loads the tela code from given file.
See also:
source_silent
,
autosource
,
load
.
Error codes:
1: Operation did not succeed
2: Argument not a string
[] = source_silent(fn)
source_silent("file.t") is similar to source("file.t"),
but it does not complain if e.g. the file does not exist.
See also:
source
,
autosource
,
load
.
Error codes:
1: Argument not a string
[s] = sprintf(formatstr,arg)
sprintf("format-string",arg1,arg2,...) is an interface to the C
sprintf function. The format string should have a percent
slot for every arg. The args may be integer or real scalars
or strings.
See also:
sformat
.
LIMITATIONS:
This implementation allows only one arg (arg1).
The resulting string may not become larger than
500 chars or Tela may crash.
Error codes:
-1: First arg not a string
-2: Args may only be scalar ints or reals, or strings
[y] = sqrt(x)
y = sqrt(x) computes the square root of x.
If x is complex, the result is complex. If x is real or
integer, but negative, the result is complex (purely
imaginary). If x is real or integer and non-negative,
the result is real.
If x is an array, the operation is applied componentwise.
If some of the components are negative, all components
of the result are complex.
[] = srand(seed)
srand(seed) seeds the random number generator.
The same seed will always produce the same random
number sequence. The argument must be an integer.
See also:
rand
.
Error codes:
1: Argument not an integer
[y] = str2num(s)
str2num(s) converts a string to a number.
The string must represent a scalar. If an error
occurs, str2num returns a void value.
Error codes:
1: Argument not a string
[y] = streq(s1,s2)
streq("string1","string2") returns 1 if the argument
strings are exactly equal and 0 otherwise. If one of
the args is not a string, the result is also 0.
See also:
strstarteq
.
[x] = strmat(...)
strmat("string1","string2",...) makes a string matrix
ouf of individual strings. The strings need not be same length,
they are padded with zeros (invisible) if they are not.
See also:
strmat2
.
Error codes:
-1: Argument not a string
[x] = strmat2(str; sep)
strmat2("string") creates a string matrix from "string"
interpreting the newline character as row ending marker.
strmat2("string",sep) uses separator sep instead of
newline char; sep may be either character or string.
If sep is a string, any character that is a member of sep
is taken to be a separator. If the rows have unequal lengths,
they are padded with zeros.
See also:
strmat
.
Error codes:
-1: First arg not a string
-2: Second arg not a char or string
[y] = strstarteq(s1,s2)
strstarteq("string1","string2") returns 1 if the argument
strings are equal on the first min(length(s1),length(s2))
characters and 0 otherwise.
If one of the the args is not a string, the result is also 0.
See also:
streq
.
[y] = sum(x;d)
sum(x) sums all the elements of x, if x is an array.
The result type is always the same as the component type
of x. If x is scalar, it is returned as such.
sum(x,d) sums only along d'th dimension, returning array
of rank one less than rank(x).
See also:
cumsum
,
prod
,
map
.
Error codes:
-1: Nonnumeric input arg
-2: Second argument not an integer
-3: Second argument (dimension spec) out of range
[] = system(s)
system("string") executes string as an external
operating system command.
Error codes:
1: Argument not a string
[] = t2ct(fn)
t2ct("filename.t") translates t-code to ct-code.
Error codes:
1: Operation did not succeed
2: Argument not a string
3: Could not open output file
[y] = tan(x)
y = tan(x) computes the tangent function of x.
If x is complex, the result is complex, otherwise real.
The argument must be in radians.
If x is an array, the operation is applied componentwise.
[y] = tanh(x)
y = tanh(x) computes the hyperbolic tangent function of x.
If x is complex, the result is complex, otherwise real.
If x is an array, the operation is applied componentwise.
[s] = telapath()
telapath() returns the currently set effective Tela path
as a string.
[] = tic()
tic() marks the CPU time at which it was invoked.
To measure CPU time, use tic() and toc().
See also:
cputime
,
toc
.
Example:
a = rand(100,100); tic(); b=inv(a); toc()
This would measure the CPU time in inverting a 100x100
random real matrix. See also: toc.
[t] = toc()
toc() gives the CPU seconds used since the last call to tic().
See also:
tic
,
cputime
.
[y] = tostring(x)
tostring(x) converts an integer vector to a string.
Transfer of characters is stopped if zero element
is encountered.
tostring(A) where A is geneeral integer array copies
A and sets the string flag.
Error codes:
-1: Argument not an integer array
[B] = transpose(A; P)
B = transpose(A) returns a transpose of array A: B[i,j,k...l] = A[l...k,j,i].
B = transpose(A,P) where P is integer vector transposes the indices according
to the permutation defined by P.
For example if A has rank 3, B = transpose(A,[2,1,3]) causes the assignment
B[j,i,k] = A[i,j,k] to be carried out. B = transpose(A) would in this case
correspond to B[k,j,i] = A[i,j,k].
The second argument is meaningful only if rank(A) is greater than 2.
You can abbreviate "transpose(A)" by "A.'".
See also:
herm
,
flip
.
Error codes:
-1: Permutation argument not integer array
-2: Permutation argument of bad rank or size
-3: Permutation argument contains invalid integers
[] = unhide(...)
hide("sym-name",...) unsets the 'hidden' attribute to
specified symbols.
See also:
whos
,
hide
.
Error codes:
1: Argument not a string
2: Argument does not name a symbol
[x] = version()
version() returns the Tela version number (real) currently
in use.
[] = vplot(x,y,vx,vy...)
vplot(x,y,vx,vy[,options]) produces a 2D vector plot of the vector
field (vx,vy). All arguments x,y,vx and vy must be 2D integer or
real arrays and of the same size. Each 2D vector will be positioned
at (x[i,j],y[i,j]) and its direction will be (vx[i,j],vy[i,j]) where
(i,j) run over rows and columns of the matrices.
See also:
annotate
,
plot
,
mesh
,
contour
,
pcolor
.
Error codes:
1: Could not open temporary MTV file
2: One of first four args is not a numeric array
3: One of first four args has rank not equal to 2
4: Dimensions of first four args disagree
5: Syntax error in graph options
[] = whos(;hidden)
whos() displays names of variables together with their
types and values, if short. 'Hidden' symbols are not shown.
whos("hidden") shows also hidden symbols.
See also:
hide
,
unhide
.
Error codes:
1: Bad argument
Next Chapter, Previous Chapter
Table of contents of this chapter, General table of contents
Top of the document, Beginning of this Chapter