  Builtin Tela functions
  Pekka	Janhunen, Pekka.Janhunen@fmi.fi
  Version 1.23,	Thu Sep	14 13:45:17 EDT	1995

  This document	has been automatically generated from the online help
  messages of builtin Tela functions.

  1.  INTRODUCTION

  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.


  2.  std.ct

  This section describes functions from	file std.ct.


  2.1.	BatchMode



       [y] = BatchMode()
	BatchMode() returns 1 if this Tela process is in batch mode
	  (command line	switch -b), otherwise 0.


       See also: ``SilentMode'', ``VerboseMode'', ``UsingReadline''.


  2.2.	CheckReadOnlyMode



       [;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




  2.3.	DebugQueryMode









  [;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




  2.4.	GetInstructionData



       [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





  2.5.	HeavisideTheta



       [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




  2.6.	Im



       [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




  2.7.	Re



       [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




  2.8.	SilentMode



       [y] = SilentMode()
	SilentMode() returns 1 if this Tela process is in silent mode
	  (command line	switch -s), otherwise 0.


       See also: ``BatchMode'',	``VerboseMode'', ``CheckReadOnlyMode''.


  2.9.	UsingReadline



       [y] = UsingReadline()
	UsingReadline()	returns	1 if this Tela was compiled
	  to use the GNU readline library, otherwise 0.


       See also: ``BatchMode'',	``SilentMode'',	``VerboseMode''.


  2.10.	 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

  2.11.	 abs2



       [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




  2.12.	 acos



       [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.




  2.13.	 all



       [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




  2.14.	 any










  [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




  2.15.	 arg



       [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




  2.16.	 asin



       [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.




  2.17.	 atan



       [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''.




  2.18.	 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




  2.19.	 autoglobal



       [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




  2.20.	 autosource



       [] = 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







  2.21.	 cd



       [] = 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




  2.22.	 ceil



       [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




  2.23.	 conj



       [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''.


  2.24.	 cos



       [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.





  2.25.	 cosh



       [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.




  2.26.	 cot



       [y] = cot(x)
	y = cot(x) is the cotangent function
	  cot(x) = 1/tan(x) = cos(x)/sin(x).




  2.27.	 cputime



       [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()




  2.28.	 csc



       [y] = csc(x)
	y = csc(x) is the cosecant function
	  csc(x) = 1/sin(x).




  2.29.	 cumprod



       [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




  2.30.	 cumsum



       [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




  2.31.	 diag



       [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





  2.32.	 disasm



       [] = disasm(fn)
	disasm(f) produces disassembly listing of function f.
	  Error	codes:
	  1: Argument not a Tela function




  2.33.	 eval








  [] = 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




  2.34.	 evalexpr



       [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




  2.35.	 exit



       [] = exit()
	exit() stops Tela. quit() is synonym for exit().




  2.36.	 exp



       [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.




  2.37.	 find









  [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




  2.38.	 flatten



       [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.




  2.39.	 flip



       [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




  2.40.	 floor



       [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




  2.41.	 getenv



       [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





  2.42.	 getpid



       [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.




  2.43.	 help




















  [] = 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




  2.44.	 herm



       [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




  2.45.	 hide



       [] = 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






  2.46.	 info



       [] = 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.




  2.47.	 input_string



       [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.




  2.48.	 isCfunction



       [y] = isCfunction(x)
	isCfunction(x) returns 1 if x is a C-tela function.
	  and 0	otherwise.


       See also: ``isfunction'', ``isTfunction''.


  2.49.	 isTfunction



       [y] = isTfunction(x)
	isTfunction(x) returns 1 if x is a function written in Tela
	  and 0	otherwise.


       See also: ``isfunction'', ``isCfunction''.


  2.50.	 isarray



       [y] = isarray(x)
	isarray(x) returns 1 if	x is an	array and 0 if it is not.


       See also: ``isscalar'', ``isvector'', ``ismatrix''.





  2.51.	 ischar



       [y] = ischar(x)
	ischar(x) returns 1 if x is a character	and 0 otherwise.


       See also: ``isstring'', ``isstr''.


  2.52.	 iscomplex



       [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''.


  2.53.	 isdefined



       [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''.


  2.54.	 isfinite



       [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.




  2.55.	 isfloat



       [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''.




  2.56.	 isfunction



       [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''.


  2.57.	 isint



       [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''.


  2.58.	 ismatrix



       [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''.


  2.59.	 isreal



       [y] = isreal(x)
	isreal(x) returns 1 if x is numerical non-complex
	  array	or scalar, and 0 otherwise.


       See also: ``isfloat'', ``isint'', ``iscomplex''.


  2.60.	 isscalar



       [y] = isscalar(x)
	isscalar(x) returns 1 if x is scalar and 0 if it is not.


       See also: ``isvector'', ``ismatrix'', ``isarray''.


  2.61.	 isstr





  [y] =	isstr(x)
   isstr(x) returns 1 if x is a	character or string
     and 0 otherwise.


  See also: ``isstring'', ``ischar''.


  2.62.	 isstring



       [y] = isstring(x)
	isstring(x) returns 1 if x is a	string and 0 otherwise.


       See also: ``ischar'', ``isstr''.


  2.63.	 isundefined



       [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''.


  2.64.	 isvector



       [y] = isvector(x)
	isvector(x) returns 1 if x is a	vector and 0 if	it is not.


       See also: ``isscalar'', ``ismatrix'', ``isarray''.


  2.65.	 isvoid



       [y] = isvoid(x)
	isvoid(x) returns 1 if x is a void value and 0 otherwise.




  2.66.	 length



       [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




  2.67.	 limit



       [y] = limit(x,a,b)
	limit(x,a,b) limits x to the range [a,b].
	  x may	be an integer or real array or scalar,
	  the a	and b arguments	must be	integer	or real
	  scalars. The result type is integer only
	  if all x,a,b are integers, otherwise it is real.
	  limit(x,a,b) is equivalent to	min(b,max(x,a)).

	  Notice: limit	is builtin function in >=1.23
	  version. Before 1.23 it was a	t-file function.

	  (Usually a<=b, if a>b	then limit(x,a,b) has the
	  value	of b but this behavior should not be trusted.)
	  Error	codes:
	  -1: First arg	not int	or real
	  -2: Second arg not int or real scalar
	  -3: Third arg	not int	or real	scalar




  2.68.	 log



       [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.




  2.69.	 map



       [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




  2.70.	 mapmax



       [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'', ``limit''.

	  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




  2.71.	 mapmin
















  [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'', ``limit''.

     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




  2.72.	 menu



       [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




  2.73.	 ones



       [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





  2.74.	 pause



       [] = 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




  2.75.	 perf



       [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).




  2.76.	 prod



       [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




  2.77.	 quit



       [] = quit()
	quit() stops Tela. quit() is synonym for exit().




  2.78.	 rand



       [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




  2.79.	 rank



       [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''.


  2.80.	 reshape













  [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





  2.81.	 round



       [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




  2.82.	 run



       [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






  2.83.	 sec



       [y] = sec(x)
	y = sec(x) is the secant function
	  sec(x) = 1/cos(x).




  2.84.	 showcompiled



       [] = 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





  2.85.	 sign



       [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




  2.86.	 sin



       [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.






  2.87.	 sinh



       [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.




  2.88.	 size



       [...] = 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




  2.89.	 smenu



       [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




  2.90.	 sort











  [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.




  2.91.	 source



       [] = 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




  2.92.	 source_silent



       [] = 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




  2.93.	 sqrt









  [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.




  2.94.	 srand



       [] = 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




  2.95.	 str2num



       [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




  2.96.	 streq



       [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''.


  2.97.	 strmat







  [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.

     Usage example:
     S = strmat("string1","longer_string");
     s = tostring(S[1,:]);
     after which streq(s,"string1") will return	true (1).
     The function tostring is needed to	get rid	of possible
     extra zeros at the	end of the string.



  See also: ``strmat2'', ``tostring'', ``streq''.

     Error codes:
     -1: Argument not a	string




  2.98.	 strmat2



       [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





  2.99.	 strstarteq



       [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''.


  2.100.  sum





  [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




  2.101.  system



       [] = system(s)
	system("string") executes string as an external
	  operating system command.
	  Error	codes:
	  1: Argument not a string




  2.102.  t2ct



       [] = 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





  2.103.  tan



       [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.




  2.104.  tanh






  [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.




  2.105.  telapath



       [s] = telapath()
	telapath() returns the currently set effective Tela path
	  as a string.




  2.106.  tic



       [] = 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.




  2.107.  toc



       [t] = toc()
	toc() gives the	CPU seconds used since the last	call to	tic().


       See also: ``tic'', ``cputime''.


  2.108.  tostring



       [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



  2.109.  transpose



       [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




  2.110.  unhide



       [] = 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





  2.111.  version



       [x] = version()
	version() returns the Tela version number (real) currently
	  in use.




  2.112.  whos



       [] = 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






  3.  files.ct

  This section describes functions from	file files.ct.


  3.1.	export_PBM



       [] = 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




  3.2.	export_RIS8



       [] = 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





  3.3.	export_matlab



       [] = 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





  3.4.	export_matlab2



       [] = 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






  3.5.	import



       [] = 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





  3.6.	import1










  [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





  3.7.	import_PBM















  [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





  3.8.	load



       [] = 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





  3.9.	save



       [] = 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






  4.  plotmtv.ct

  This section describes functions from	file plotmtv.ct.


  4.1.	annotate


















  [] = 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




  4.2.	bar




  [] = 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





  4.3.	closefig



       [] = 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)




  4.4.	contour



       [] = 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?




  4.5.	contour3



       [] = 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?




  4.6.	figure



       [] = 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




  4.7.	grid





  [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




  4.8.	grid3



       [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




  4.9.	hist



       [;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


  4.10.	 hold



       [] = 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




  4.11.	 holdmode



       [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




  4.12.	 mesh



       [] = 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?




  4.13.	 pcolor



       [] = 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?




  4.14.	 pixmap



       [] = 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




  4.15.	 plot



       [] = 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





  4.16.	 plot3



       [] = 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





  4.17.	 plotopt



       [] = 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





  4.18.	 vplot



       [] = 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





  5.  la.ct

  This section describes functions from	file la.ct.


  5.1.	LU



       [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)





  5.2.	LUbacksubst



       [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




  5.3.	SVD



       [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)





  5.4.	axpy



       [y] = axpy(a,x)
	[y] = axpy(a,x)	is the equivalent of y = y + a*x
	  for scalar a and (real or complex) arrays x and y.
	  axpy calls a fast BLAS-1 routine if available.
	  Error	codes:
	  -1: Input/output arg y is not	real/complex array
	  -2: First input arg a	is not a scalar
	  -3: Second input arg x is not	real/complex array
	  -4: Second input arg x has size incompatible with y
	  -5: If y is real a and x must	also be	real
	  -6: If y is complex x	must also be complex




  5.5.	chol






  [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




  5.6.	det



       [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




  5.7.	eig



       [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





  5.8.	eye





  [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





  5.9.	inv



       [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




  5.10.	 linsolve



       [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





  5.11.	 matprod



       [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'






  6.  fft.ct

  This section describes functions from	file fft.ct.

  6.1.	FFT



       [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'', ``sin-
       qFFT'', ``cosqFFT''.

	  Error	codes:
	  -1: First argument not a numeric array
	  -2: Second argument not integer
	  -3: Second argument out of range





  6.2.	cosFFT

















  [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





  6.3.	cosqFFT



       [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





  6.4.	invFFT



  [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





  6.5.	invcosFFT



       [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





  6.6.	invcosqFFT



       [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





  6.7.	invrealFFT



       [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





  6.8.	invsinFFT



       [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


  6.9.	invsinqFFT



       [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





  6.10.	 realFFT



       [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'', ``sin-
       qFFT'', ``cosqFFT''.

	  Error	codes:
	  -1: First argument not a real	array
	  -2: Second argument not integer
	  -3: Second argument out of range



  6.11.	 sinFFT



       [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





  6.12.	 sinqFFT



       [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





  7.  dld.ct

  This section describes functions from	file dld.ct.


  7.1.	link



       [] = 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






  8.  fileio.ct

  This section describes functions from	file fileio.ct.


  8.1.	fclose



       [] = 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




  8.2.	feof



       [result]	= feof(fnum)
	feof(fnum) checks whether end of file has been reached
	  on previously	opened file with identification	number fnum.
	  Return value is 1 in case of EOF and 0 otherwise.
	  Return value is -1 if	the file is not	open.



  See also: ``fgetc'', ``fgets'', ``fopen''.

     Error codes:
     -1: Bad argument: not integer
     -2: Bad argument: outside range




  8.3.	fformat



       [] = 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





  8.4.	fgetc



       [ch] = fgetc(fnum)
	fgetc(fnum) returns the	next character from previously
	  opened file with identification number fnum, or VOID
	  value	if end of file has been	reached.


       See also: ``fgets'', ``fopen'', ``feof''.

	  Error	codes:
	  -1: Bad argument: not	integer
	  -2: Bad argument: outside range
	  -3: File was not open




  8.5.	fgets



       [s;endletter] = fgets(fnum;endletters)
	s=fgets(fnum) reads a string from previously opened
	  file with identification number fnum.	The string
	  is terminated	with a newline,	which is removed from
	  the stream but not returned.
	  s=fgets(fnum,t) where	t is a string uses characters
	  in t as terminators, the default for t is "\n".
	  [s,t1]=fgets(..) also	returns	the terminating	character
	  in t1.



  See also: ``fgetc'', ``fopen'', ``feof''.

     Error codes:
     -1: Bad first argument: not integer
     -2: Bad first argument: outside range
     -3: File was not open
     -4: Bad second argument: not a string





  8.6.	fopen



       [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'', ``fgetc'', ``fgets''.

	  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




  8.7.	format



       [] = 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




  8.8.	fparse



       [n...] =	fparse(fnum,controlstr)
	[n,a,b,c,...] =	fparse(fnum,"contolstring") scans input	file
	  with identification number fnum (obtained with fopen).
	  Occurrences of `` in "controlstring" denote objects to be
	  read and placed to output variables a,b,c,...	in order.
	  The number of	objects	succesfully read added by one is
	  placed in n in the normal case.
	  The notation `i`, `r`, `z` and `c` can be used to read
	  integer, real	or complex numbers, or single characters.

	  For example,

	  fnum = fopen("inputfile","r");
	  [n,c,i,z] = fparse(fnum,"N`c`	= `i`, a = `z`;");
	  if (n	!= 4) error("...");

	  would	accept the input

	  N3=  35,a   =3.4;

	  after	which c	would be '3', i	would be 35 and	z would
	  be 3.4. White	space characters in controlstring are special,
	  they match any number	(including zero) of whitespace characters
	  in input. Other characters in	controlstring must appear
	  literally in input. The variable n would be assigned the value
	  4 in this case. Every	time an	object is succesfully read,
	  the return value is incremented. If the end of the control string
	  after	the last `` item matches the input, the	return value is
	  incremented once more. Thus, in the above example, n==1 would
	  mean that error occurred between `c` and `i``, n==1 would
	  indicate error between `i` and `z` and n==3 would indicate a
	  missing semicolon after `z`. Perfectly correct input always
	  produced n equal to the total	number of output arguments,
	  four in the above example.

	  Currently there is no	way to quote the ` character
	  in control string. To	read `,	read it	as `c` and later
	  check	that it	really was a backquote.



       See also: ``fopen'', ``feof'', ``fgets'', ``fgetc''.

	  Error	codes:
	  -1: First input arg not an integer
	  -2: Second input arg not a string
	  -3: Bad first	argument: outside range
	  -4: File is not open
	  -5: Unended `` item in control string
	  -6: Too few output arguments as compared to control string
	  -7: Bad `` item: must	be `c`,	`i`, `r` or `z`
	  -8: `x` item does not	end with backquote character




  8.9.	fprintf





  [] = 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





  8.10.	 printf



       [] = 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





  8.11.	 remove



       [] = 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





  8.12.	 sformat



  [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




  8.13.	 sprintf



       [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






  9.  numerics.ct

  This section describes functions from	file numerics.ct.


  9.1.	intpol



















  [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




  9.2.	stencil2d_4



       [Lu] = stencil2d_4(u,ap0,am0,a0p,a0m)
	stencil2d_4(u,ap0,am0,a0p,a0m) computes	the two-dimensional
	  five-point "molecule"	where the coefficient of the central
	  term is unity:

	  Lu = u[i,j]
	     + ap0*u[i+1,j] + am0*u[i-1,j]
		 + a0p*u[i,j+1]	+ a0m*u[i,j-1];

	  where	the indices i and j run	from 2..nx and 2..ny where
	  [nx,ny] = size(u). The size of ap0,am0,a0p,a0m must be two
	  less than the	size of	u in both directions.
	  Error	codes:
	  -1: One of the arguments is not a real matrix
	  -2: One of the coefficient args has bad size





  10.  matlabeng.ct

  This section describes functions from	file local/matlabeng.ct.


  10.1.	 matlab_call



       [...] = 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'', ``mat-
  lab_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





  10.2.	 matlab_eval



       [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





  10.3.	 matlab_get



       [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)





  10.4.	 matlab_put



  [] = 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





  10.5.	 matlab_start



       [] = 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





  10.6.	 matlab_stop



       [] = 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









  11.  tsyganenko.ct

  This section describes functions from	file local/tsyganenko.ct.


  11.1.	 T87



       [Bx,By,Bz] = T87(Kp,x,y,z)
	[Bx,By,Bz] = T87(Kp,x,y,z) computes the	Tsyganenko-87 model
	  magnetic field. The non-truncated version of the model is used.
	  Inputs: Kp, the Kp index; x,y,z, GSM coordinates
	  in Earth radii. Outputs: total magnetic field	in nanotesla in
	  GSM coordinates.


       See also: ``T89'', ``m2i'', ``geotomag''.

	  Error	codes:
	  -1: Bad type of input	arg




  11.2.	 T89



       [Bx,By,Bz] = T89(Kp,x,y,z)
	[Bx,By,Bz] = T89(Kp,x,y,z) computes the	Tsyganenko-89 model
	  magnetic field. Inputs: Kp, the Kp index; x,y,z, GSM coordinates
	  in Earth radii. Outputs: total magnetic field	in nanotesla in
	  GSM coordinates.


       See also: ``T87'', ``m2i'', ``geotomag''.

	  Error	codes:
	  -1: Bad type of input	arg




  11.3.	 ecctogeo



       [lat,longit] = ecctogeo(latmag,longmag)
	[lat,long] = ecctogeo(latecc,longecc) transforms eccentric
	  geomagnetic latitude and longitude to	geographic latitude and	longitude.
	  All angles in	degrees.


       See also: ``geotoecc'', ``ecctogeoXYZ'',	``geotomag'', ``magtogeo''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg







  11.4.	 ecctogeoXYZ



       [x1,y1,z1] = ecctogeoXYZ(x,y,z)
	[x1,y1,z1] = ecctogeoXYZ(x,y,z)	transforms eccentric dipole
	  point	(x,y,z)	to geographic coordinates (x1,y1,z1).


       See also: ``ecctogeo'', ``geotoeccXYZ'',	``magtogeoXYZ''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg
	  -3: Bad third	arg





  11.5.	 geotoecc



       [latmag,longmag]	= geotoecc(lat,longit)
	[latmag,longmag] = geotoecc(lat,long) transforms geographic
	  latitude and longitude to eccentric geomagnetic latitude and longitude.
	  All angles in	degrees.


       See also: ``ecctogeo'', ``geotoeccXYZ'',	``geotomag'', ``magtogeo''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg





  11.6.	 geotoeccXYZ



       [x1,y1,z1] = geotoeccXYZ(x,y,z)
	[x1,y1,z1] = geotoeccXYZ(x,y,z)	transforms geographic
	  point	(x,y,z)	to eccentric dipole coordinates	(x1,y1,z1).


       See also: ``geotomagXYZ'', ``ecctogeoXYZ'', ``geotoecc''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg
	  -3: Bad third	arg





  11.7.	 geotomag





  [latmag,longmag] = geotomag(lat,longit)
   [latmag,longmag] = geotomag(lat,long) transforms geographic
     latitude and longitude to geomagnetic dipole latitude and longitude.
     All angles	in degrees.


  See also: ``geotomagXYZ'', ``magtogeo'', ``ecctogeo'', ``geotoecc''.

     Error codes:
     -1: Bad first arg
     -2: Bad second arg





  11.8.	 geotomagXYZ



       [x1,y1,z1] = geotomagXYZ(x,y,z)
	[x1,y1,z1] = geotomagXYZ(x,y,z)	transforms geographic
	  point	(x,y,z)	to geomagnetic dipole coordinates (x1,y1,z1).


       See also: ``geotomag'', ``magtogeoXYZ''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg
	  -3: Bad third	arg





  11.9.	 m2i



       [theta,phi] = m2i(Kp,x,y)
	[theta,phi] = m2i(Kp,x,y) maps the equatorial plane point (x,y,z=0)
	  to the northern ionosphere. Inputs: Kp, the Kp index;	x,y,z, GSM
	  coordinates in Earth radii. Outputs: colatitude and longitude	in
	  magnetic coordinates in degrees.


       See also: ``T89'', ``geotomag''.

	  Error	codes:
	  -1: Bad type of input	arg




  11.10.  magtogeo



       [lat,longit] = magtogeo(latmag,longmag)
	[lat,long] = magtogeo(latmag,longmag) transforms geomagnetic
	  latitude and longitude to geographic latitude	and longitude.
	  All angles in	degrees.



  See also: ``geotomag'', ``magtogeoXYZ'', ``geotoecc'', ``ecctogeo''.

     Error codes:
     -1: Bad first arg
     -2: Bad second arg





  11.11.  magtogeoXYZ



       [x1,y1,z1] = magtogeoXYZ(x,y,z)
	[x1,y1,z1] = magtogeoXYZ(x,y,z)	transforms geomagnetic dipole
	  point	(x,y,z)	to geographic coordinates (x1,y1,z1).


       See also: ``magtogeo'', ``geotomagXYZ''.

	  Error	codes:
	  -1: Bad first	arg
	  -2: Bad second arg
	  -3: Bad third	arg






  12.  gnuplot.ct

  This section describes functions from	file local/gnuplot.ct.


  12.1.	 gnuplot



       [] = gnuplot(x)
	gnuplot(x) calls GNUPLOT on vector x.
	  Error	codes:
	  -1: Cannot open command pipe to gnuplot
	  -2: Cannot open data pipe





















