ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / maths / rlab / docs / RLEF41~1 < prev next >

Wrap

Text File | 1997-03-09 | 107.6 KB | 3,846 lines

<HTML> <HEAD> <TITLE> Rlab2 Reference Manual: Builtin Functions</TITLE> </HEAD> <BODY> <A HREF="rlab-ref-6.html"><IMG SRC="prev.gif" ALT="Previous"></A> <A HREF="rlab-ref-8.html"><IMG SRC="next.gif" ALT="Next"></A> <A HREF="rlab-ref.html#toc7"><IMG SRC="toc.gif" ALT="Contents"></A> <HR> <H2><A NAME="s7">7. Builtin Functions</A></H2> This chapter covers the built-in functions. Normally, no distinction is made between the built-in, and the user-functions. However, they are documented separately because custom installations, and program execution options make it possible for Rlab to run with many of the user-functions missing. The documentation for each built-in function is nearly the same as the online help. In fact, the printed documentation is the source of the online help files. <H2><A NAME="ss7.1">7.1 abs </A></H2> <DL> <DT> Synopsis <DD>Compute the absolute value. <DT> Syntax <DD>abs ( A ) <DT> Description <DD>abs returns the absolute value of it's input, A. abs is a scalar function. For complex values abs returns the square root of the sum of the squares of the real and imaginary parts. </DL> <H2><A NAME="ss7.2">7.2 acos </A></H2> <DL> <DT> Synopsis <DD>Compute the arc-cosine. <DT> Syntax <DD>acos ( A ) <DT> Description <DD>The trigonometric functions are scalars functions. The return value is the result of the trigonometric operation performed on the input, element-by-element. All the trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.3">7.3 all </A></H2> <DL> <DT> Synopsis <DD>Check if all elements are non-zero. <DT> Syntax <DD>all ( A ) <DT> Description <DD>When A is a vector (row or column): <BLOCKQUOTE> all returns TRUE (1) if all of the elements of A are non-zero. all returns zero otherwise. </BLOCKQUOTE> When A is a matrix: <BLOCKQUOTE> all operates on the columns of A, returning a row-vector of ones and zeros. </BLOCKQUOTE> <DT>See Also<DD>any </DL> <H2><A NAME="ss7.4">7.4 any </A></H2> <DL> <DT> Synopsis <DD>Check if any elements are non-zero. <DT> Syntax <DD>any ( A ) <DT> Description <DD>When A is a vector (row or column): <BLOCKQUOTE> any returns TRUE (1) if any of the elements of A are non-zero. any returns FALSE (0) otherwise. </BLOCKQUOTE> When A is a matrix: <BLOCKQUOTE> any operates on the columns of A, returning a row-vector of ones and zeros. </BLOCKQUOTE> <DT>See Also<DD>all </DL> <H2><A NAME="ss7.5">7.5 asin </A></H2> <DL> <DT> Synopsis <DD>Compute the arc-sin. <DT> Syntax <DD>asin ( A ) <DT> Description <DD>RLaB trigonometric functions are designed to take scalars, and matrices as arguments. The return value is the input argument with the trigonometric operation performed element by element. The trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.6">7.6 atan </A></H2> <DL> <DT> Synopsis <DD>Compute the arc-tangent. <DT> Syntax <DD>atan ( A ) <DT> Description <DD>RLaB trigonometric functions are designed to take scalars, and matrices as arguments. The return value is the input argument with the trigonometric operation performed element by element. The trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.7">7.7 atan2 </A></H2> <DL> <DT> Synopsis <DD>Compute the arc-tangent. <DT> Syntax <DD>atan2 ( y , x ) <DT> Description <DD>RLaB trigonometric functions are designed to take scalars, and matrices as arguments. The return value is the input argument with the trigonometric operation performed element by element. atan2 takes two arguments, which are the y, and x values used to form the tangent. All the trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. Atan2 does not operate on complex arguments. </DL> <H2><A NAME="ss7.8">7.8 backsub </A></H2> <DL> <DT> Synopsis <DD>Solution of <CODE>Ax = B</CODE> by backsubstitution. <DT> Syntax <DD>backsub ( LIST, B ) <DT> Description <DD>The backsub function computes the solution to the set of linear equations described by: <BLOCKQUOTE> A * X = B </BLOCKQUOTE> The 1st argument to backsub (LIST) is the result from `factor(A)'. The second argument to backsub is the matrix B. B can contain multiple right hand sides. Backsub returns a matrix X which contains the solution(s) to the aforementioned equations. Backsub utilizes the LAPACK subroutines DGETRS or ZGETRS if LIST contains LU factors or LAPACK subroutins DSYTRS or ZHETRS if LIST contains the LDL factors. Example: <BLOCKQUOTE><CODE> <PRE> > A = [1,2,3;4,5,6;7,8,0] 1 2 3 4 5 6 7 8 0 > B = [1;2;3] 1 2 3 > X = backsub(factor(A), B) -0.333 0.667 -3.52e-18 > A*X - B 0 0 0 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>factor, inv, lu, solve </DL> <H2><A NAME="ss7.9">7.9 balance </A></H2> <DL> <DT> Synopsis <DD>Balance a matrix for equal row and column norms. <DT> Syntax <DD>balance ( A ) <DT> Description <DD>Balance uses the LAPACK subroutines DGEBAL and ZGEBAL to balance the input matrix so that the row and column norms are approximately equal. balance returns a list with elements t and ab. Example: <BLOCKQUOTE><CODE> <PRE> > a 0 0 1 0 0 0 0 1 11 10 0 0 10 11 0 0 > </ ab ; t /> = balance(a); > inv(t)*a*t - ab 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 </PRE> </CODE></BLOCKQUOTE> Only square matrices are allowed. </DL> <H2><A NAME="ss7.10">7.10 ceil </A></H2> <DL> <DT> Synopsis <DD>Smallest integer not less than argument. <DT> Syntax <DD>ceil ( a ) <DT> Description <DD>Ceil returns the smallest integer not less than the argument. If the argument is a MATRIX then the ceil operation is performed on an element-by-element basis. <DT>See Also<DD>floor, int </DL> <H2><A NAME="ss7.11">7.11 chol </A></H2> <DL> <DT> Synopsis <DD>Cholesky factorization. <DT> Syntax <DD>chol( A ) <DT> Description <DD>Chol computes the Cholesky factorization of the input matrix. The input matrix must be real symmetric positive definite, or complex Hermitian positive definite. chol() produces an upper triangular matrix U, such that <CODE>U'*U</CODE> and A (the input) are equal. chol use the LAPACK subroutine DPOTRF and ZPOTRF. </DL> <H2><A NAME="ss7.12">7.12 class </A></H2> <DL> <DT> Synopsis <DD>Identify the class of an object. <DT> Syntax <DD>class ( A ) <DT> Description <DD>Class returns a string which identifies the type of the object that A represents. Valid classes are: <UL> <LI> num</LI> <LI> string</LI> <LI> list</LI> <LI> function</LI> </UL> It is often useful to: <BLOCKQUOTE><CODE> <PRE> if(class(m) == "num") { # Perform numerical computation on m } </PRE> </CODE></BLOCKQUOTE> The class of a variable can also be determined by using the class member reference (except for LISTs), like: <BLOCKQUOTE><CODE> <PRE> > zeros.class function </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>show, type </DL> <H2><A NAME="ss7.13">7.13 clear </A></H2> <DL> <DT> Synopsis <DD>Delete a variable. <DT> Syntax <DD>clear ( A ) <DT> Description <DD>Clear effectively deletes a variables object from the symbol table. The effect is the variable does not show up when who() is used. The memory associated with the variable is freed. Clear accepts up to 32 arguments, the return value is the number of objects that have been successfully cleared. </DL> <H2><A NAME="ss7.14">7.14 close </A></H2> <DL> <DT> Synopsis <DD>Close a file. <DT> Syntax <DD>close ( filename ) <DT> Description <DD>close takes a string (filename) as input, and attempts to close the output stream associated with filename. close returns TRUE (1) if the output stream was successfully closed, FALSE (0) if the output stream could not be closed. If you want to read the contents of a file that you have created with the write function in the present session, then be sure to close the file before using the read function. Example: <BLOCKQUOTE><CODE> <PRE> write( "eig_output", a , vec , val ); close( "eig_output" ); read( "eig_output" ); </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>printf, fprintf, getline, open, read, readb, readm, write, writeb, writem </DL> <H2><A NAME="ss7.15">7.15 conj </A></H2> <DL> <DT> Synopsis <DD>Complex conjugate. <DT> Syntax <DD>conj ( A ) <DT> Description <DD>Conj returns the complex conjugate of its input argument. For MATRIX arguments the conjugate is performed element by element. <DT>See Also<DD>imag, real </DL> <H2><A NAME="ss7.16">7.16 cos </A></H2> <DL> <DT> Synopsis <DD>Compute the cosine. <DT> Syntax <DD>cos ( A ) <DT> Description <DD>The trigonometric functions are scalars functions. The return value is the result of the trigonometric operation performed on the input, element-by-element. All the trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.17">7.17 cumprod </A></H2> <DL> <DT> Synopsis <DD>Cumulative product. <DT> Syntax <DD>cumprod ( A ) <DT> Description <DD>cumprod computes the running, or cumulative product of the input, A. If the input is a rectangular matrix, then the cumulative product is performed over the columns of the matrix. Example: <BLOCKQUOTE><CODE> <PRE> > a=1:4 a = 1 2 3 4 > cumprod (a) 1 2 6 24 > a = [1,2,3;4,5,6;7,8,9] a = 1 2 3 4 5 6 7 8 9 > cumprod (a) 1 2 3 4 10 18 28 80 162 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>cumsum, prod, sum </DL> <H2><A NAME="ss7.18">7.18 cumsum </A></H2> <DL> <DT> Synopsis <DD>Cumulative sum. <DT> Syntax <DD>cumsum ( A ) <DT> Description <DD>cumsum computes the running, or cumulative sum of a vector or matrix. The return object is a matrix the same size as the input, A. If A is a rectangular matrix, then the cumulative sums are performed over the columns of the matrix. Example: <BLOCKQUOTE><CODE> <PRE> > a = 1:4 a = 1 2 3 4 > cumsum(a) 1 3 6 10 > a= [1,2,3;4,5,6;7,8,9] a = 1 2 3 4 5 6 7 8 9 > cumsum (a) 1 2 3 5 7 9 12 15 18 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>cumprod, prod, sum </DL> <H2><A NAME="ss7.19">7.19 det </A></H2> <DL> <DT> Synopsis <DD>Matrix determinant. <DT> Syntax <DD>det ( A ) <DT> Description <DD>Det computes the determinant of the matrix argument. Det uses the LAPACK functions to factor the input, and the LINPACK algorithm to calculate the determinant. See Also inv, lu, rcond </DL> <H2><A NAME="ss7.20">7.20 diag </A></H2> <DL> <DT> Synopsis <DD>Diagnonal matrix. <DT> Syntax <DD>diag ( A ) diag ( A, K ) <DT> Description <DD>If the 1st argument, A is a 1xN matrix construct a diagonal matrix from the input. Optionally if K (scalar) is specified then create a matrix with the vector as the Kth diagonal. If the 1st argument is a MxN matrix, construct a 1xN matrix from the diagonal elements of the input matrix. Optionally if K is specified return the vector from the Kth diagonal of the input matrix. <BLOCKQUOTE> K < is below the main diagonal. </BLOCKQUOTE> <BLOCKQUOTE> K > is above the main diagonal. </BLOCKQUOTE> <DT>See Also<DD>tril, triu </DL> <H2><A NAME="ss7.21">7.21 diary</A></H2> <DL> <DT> Synopsis <DD>Log commands (program statements) to a file. <DT> Syntax <DD>diary ( ) diary ( FILENAME ) <DT> Description <DD>The diary function echoes all input commands and Rlab output to a diary file. If FILENAME is not specified, then a file named: <CODE>DIARY</CODE> is opened. The diary, used without any arguments will turn on statement logging, or turn off statement logging if a diary file is already open. </DL> <H2><A NAME="ss7.22">7.22 dlopen </A></H2> <DL> <DT> Synopsis <DD>Dynamically link a function. <DT> Syntax <DD>dlopen ( FILENAME , FUNCTION_NAME ) <DT> Description <DD>dlopen opens a shared object, FILENAME, and creates a builtin function that points to FUNCTION_NAME. dlopen returns the newly created builtin function. For information on how to write and compile functions that can be linked with dlopen, consult the RLaB Programmer's Guide and Reference Manual. dlopen only exists for those platforms that support dynamic linking. As of this writing support exists for Solaris 2.x and Linux/ELF platforms. </DL> <H2><A NAME="ss7.23">7.23 eig </A></H2> <DL> <DT> Synopsis <DD>Eigensolver. <DT> Syntax <DD>eig ( A ) <DT> Description <DD> <DL> <DT>eig ( A )<DD>Computes the eigenvectors, and values of matrix A. eig() returns a LIST with elements `val' and `vec' which are the eigenvalues and eigenvectors. Eig checks for symmetry in A, and uses the appropriate solver. <DT>eig ( A , B )<DD>Computes the eigenvectors, and values of A, and B. Where <CODE>A*x = lambda*B*x</CODE>. The values and vectors are returned in a list with element names val and vec. Eig checks for symmetry in A and B and uses the appropriate solver. </DL> Uses the LAPACK subroutines DSYEV/ZHEEV or DGEEV/ZGEEV. Example: The generalized eigenvalue problem arises quite regularly in structures. From the second order differential equations describing a lumped mass system arise $M$ and $K$, coefficient matrices representing the mass and stiffness of the various physical degress of freedom. The equations are formulated as follows: <BLOCKQUOTE><CODE> <PRE> M*dx^2/dt^2 + K*x = F </PRE> </CODE></BLOCKQUOTE> Which leads to the eigenvalue problem: <BLOCKQUOTE><CODE> <PRE> K*v = w^2*M*v </PRE> </CODE></BLOCKQUOTE> For a two degree of freedom system we might have: <BLOCKQUOTE><CODE> <PRE> > m = eye(2,2) > k = [5,1;1,5] > </ val ; vec /> = eig(k, m); > // Test the solution > k * vec[;1] -2.83 2.83 > val[1] * m * vec[;1] -2.83 2.83 > // Properties of the solution > vec' * m * vec 1 -4.27e-17 -4.27e-17 1 > vec' * k * vec 4 -1.71e-16 1.23e-16 6 </PRE> </CODE></BLOCKQUOTE> The eigenvalues and vectors are sometimes obtained by converting the generalized problem into a standard eigenvalue problem (this is only feasible under certain conditions). <BLOCKQUOTE><CODE> <PRE> > a = m\k a = 5 1 1 5 > eig(a).val val = 4 6 > eig(a).vec vec = -0.707 0.707 0.707 0.707 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>svd, schur </DL> <H2><A NAME="ss7.24">7.24 entinfo </A></H2> <DL> <DT> Synopsis <DD>Return entity information. <DT> Syntax <DD>entinfo ( VAR ) <DT> Description <DD>Entinfo returns the internal address, and reference count of VAR. This function is not intended for general use... so no explanation of the function's purpose, or guarentees regarding its future availability will be made. </DL> <H2><A NAME="ss7.25">7.25 error </A></H2> <DL> <DT> Synopsis <DD>Error handling / reporting. <DT> Syntax <DD>error ( STRING ) <DT> Description <DD>The error function allows user-functions to jump back to the prompt when some sort of error has occurred. The nature of the error is up to the user. When an error is detected the user simply calls error(). If no argument is supplied, error() will print the default message. Otherwise, error prints the string supplied as an argument, and jumps back to the prompt. Jumping "back to the prompt" means execution of the current loop or function is terminated immediately and execution of any prompt-level statements is performed. </DL> <H2><A NAME="ss7.26">7.26 eval </A></H2> <DL> <DT> Synopsis <DD>Evaluate expressions. <DT> Syntax <DD>eval ( S ) <DT> Description <DD>The eval function evaluates the statement contained in the string argument S. eval returns the result of the statement in S. eval can be used within functions and can distinguish local and argument variables from global. Before we go any further, we should note that eval is not really a necessary part of RLaB. Users should defintely not use it a a crutch as with some other matrix programming languages. The RLaB concept of variables, and the list class are more efficient ways of dealing with function evaluations and variable variable names than eval. Examples: <BLOCKQUOTE><CODE> <PRE> > // Evaluate a simple string. > // Demonstrate the ability to work with function > // arguments. > > x=function(s,a){return eval(s);} <user-function> > str = "yy = 2 + x(\"2*a\", 3.5)" str = yy = 2 + x("2*a", 3.5) > z = eval(str) z = 9 > whos(); Name Class Type Size NBytes eps num real 1 1 16 pi num real 1 1 16 str string string 1 1 22 yy num real 1 1 16 z num real 1 1 16 Total MBytes = 0.129062 > // First create a function that will eval a matrix. > > evalm = function ( m ) > { > local (mnew, i) > > mnew = zeros (size (m)); > for (i in 1:m.n) > { > mnew[i] = eval (m[i]); > } > > return mnew; > }; > > // Then create a string matrix... > > mstr = ["x + 1", "x + sqrt(x)" ; > "cos(2*x)", "sin(sqrt(x))" ] > x = 2 x = 2 > > m = evalm(mstr) m = 3 3.41 -0.654 0.988 > > // Define a second function that does eval twice > > eval2m = function ( m ) > { > local (mnew, i) > > mnew = zeros (size (m)); > for (i in 1:m.n) > { > mnew[i] = eval (eval (m[i])); > } > > return mnew; > }; > > mstr = [ "E1", "E2" ; > "E2", "E3" ] mstr = E1 E2 E2 E3 > E1 = "cos(2*x) + 3"; > E2 = "tan(x)"; > E3 = "exp(x)"; > m = eval2m(mstr) m = 2.35 -2.19 -2.19 7.39 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.27">7.27 exist </A></H2> <DL> <DT> Synopsis <DD>Check the existence of a variable. <DT> Syntax <DD>exist ( VAR ) <DT> Description <DD>The exist function returns TRUE (1) if VAR exists, and FALSE (0), if VAR does not exist. VAR is any valid variable name. If you need to know if a variable exists, and if it is a function or data, then use the exist function in conjunction with the class or type functions. <DT>See Also<DD>class, type, who, what </DL> <H2><A NAME="ss7.28">7.28 exp </A></H2> <DL> <DT> Synopsis <DD>Exponential function. <DT> Syntax <DD>exp ( X ) <DT> Description <DD>Exp returns the value of e (the base of natural logarithms) raised to the power of X. If the argument to exp is a matrix then an element-by-element operation is performed. </DL> <H2><A NAME="ss7.29">7.29 factor </A></H2> <DL> <DT> Synopsis <DD>Factor a square matrix. <DT> Syntax <DD>factor ( A ) <DT> Description <DD>The factor function computes the LU factorization of the input matrix A. Factor returns a list with 3 elements: if A is a general matrix: <DL> <DT>lu<DD>a matrix containing the LU factors <DT>pvt<DD>a vector containing the pivot indices <DT>rcond<DD>the inverse of the condition estimate </DL> Factor utilizes the LAPACK subroutines DGETRF, DGECON or ZGETRF, ZGECON. if A is a symmetric matrix: <DL> <DT>ldl<DD>a matrix containing the block diagonal matrix D, and the multipliers used to obtain L. <DT>pvt<DD>a vector containing the pivot indices <DT>rcond<DD>the inverse of the condition estimate </DL> Factor utilizes the LAPACK subroutines DSYTRF, DSYCON or ZHETRF, ZHECON. The user can overide factor's choice of solution type with the optional argument TYPE. <BLOCKQUOTE> TYPE = "g" or "G" The general solution is used. </BLOCKQUOTE> <BLOCKQUOTE> TYPE = "s" or "S" the symmetric solution is used. </BLOCKQUOTE> Factor returns the results in the above format, so that they may be conveniently used with backsub for repetitive solutions. The user-function lu will separate the results from factor into separate L and U matrices. <DT>See Also<DD>backsub, inv, lu, solve </DL> <H2><A NAME="ss7.30">7.30 fft </A></H2> <DL> <DT> Synopsis <DD>Discrete Fourier Transform. <DT> Syntax <DD>fft ( X ) fft ( X, N ) <DT> Description <DD>Fft utilizes the FFTPACK subroutine CFFTF to compute a discrete forward Fourier transform of the input. If fft is used with a second argument, N, then the matrix X is either padded with zeros, or truncated till it is of length N (if X is a vector), or has row dimension N (if it is a matrix). Subroutine CFFTF computes the forward complex discrete Fourier transform (the Fourier analysis). equivalently , CFFTF computes the Fourier coefficients of a complex periodic sequence. <BLOCKQUOTE><CODE> <PRE> for j=1,...,n c(j)=the sum from k=1,...,n of c(k)*exp(-i*(j-1)*(k-1)*2*pi/n) where i=sqrt(-1) </PRE> </CODE></BLOCKQUOTE> The argument X must be a matrix. If X is a row, or column matrix then a vector fft is performed. If X is a MxN matrix then the N columns of X are fft'ed. <DT>See Also<DD>ifft </DL> <H2><A NAME="ss7.31">7.31 filter</A></H2> <DL> <DT> Synopsis <DD>Discrete time recursive filter. <DT> Syntax <DD>filter ( B, A, X ) filter ( B, A, X, Zi ) <DT> Description <DD>Filter is an implementation of the standard difference equation: <BLOCKQUOTE><CODE> <PRE> y[n] = b(1)*x[n] + b(2)*x[n-1] + ... b(nb+1)*x[n-nb] - a(2)*y[n-1] - ... a(na+1)*y[n-na] </PRE> </CODE></BLOCKQUOTE> The filter is implemented using a method described as a "Direct Form II Transposed" filter. More for information see Chapter 6 of "Discrete-Time Signal Processing" by Oppenheim and Schafer. The inputs to filter are: <DL> <DT>B<DD>The numerator coefficients, or zeros of the system transfer function. The coefficients are specified in a vector like: <BLOCKQUOTE><CODE> <PRE> [ b(1) , b(2) , ... b(nb) ] </PRE> </CODE></BLOCKQUOTE> <DT>A<DD>The denominator coefficients, or the poles of the system transfer function. the coefficients are specified in a vector like: <BLOCKQUOTE><CODE> <PRE> [ a(1) , a(2) , ... a(na) ] </PRE> </CODE></BLOCKQUOTE> <DT>X<DD>A vector of the filter inputs. <DT>Zi<DD>[Optional] The initial delays of the filter. </DL> The filter outputs are in a list with element names: <DL> <DT>y<DD>The filter output. y is a vector of the same dimension as X. <DT>zf<DD>A vector of the final values of the filter delays. </DL> The A(1) coefficient must be non-zero, as the other coefficients are divided by A(1). Below is an implementation of filter() in a r-file - it is provided for informational usage only. <HR> <PRE> # # Simplistic version of RLaB's builtin function filter() # Y = filter ( b, a, x ) # Y = filter ( b, a, x, zi ) # rfilter = function ( b , a , x , zi ) { local ( b , a , x , zi ) ntotal = x.nr * x.nc; M = b.nr * b.nc; N = a.nr * a.nc; NN = max ([ M, N ]); y = zeros (x.nr, x.nc); # Fix up pole and zero vectors. # Make them the same length, this makes # filter's job much easier. if (N < NN) { a[NN] = 0; } if (M < NN) { b[NN] = 0; } # Adjust filter coefficients if (a[1] == 0) { error ("rfilter: 1st A term must be non-zero"); } a[2:NN] = a[2:NN] ./ a[1]; b = b ./ a[1]; # Create delay vectors and load inital delays. # Add an extra term to vi[] to make filter's # job a little easier. This extra term will # always be zero. v = zeros (NN, 1); vi = zeros (NN+1, 1); if (exist (zi)) { vi[1:NN] = zi; } # # Do the work... # for (n in 1:ntotal) { v[1] = b[1]*x[n] + vi[2]; y[n] = v[1]; for (k in 2:NN) { v[k] = b[k]*x[n] - a[k]*v[1] + vi[k+1]; vi[k] = v[k]; } } return << y = y; zf = v >>; }; </PRE> <HR> </DL> <H2><A NAME="ss7.32">7.32 find </A></H2> <DL> <DT> Synopsis <DD>Find non-zeros. <DT> Syntax <DD>find ( A ) <DT> Description <DD>Find returns a matrix that contains the indices of the non-zero elements of the input matrix A. A common usage for find, is the selection of matrix elements that meet certain criteria. Example: <BLOCKQUOTE><CODE> <PRE> > a = rand(4,4) a = matrix columns 1 thru 4 0.647 0.665 0.655 0.299 0.333 0.0847 0.129 0.265 0.0369 0.204 0.91 0.7 0.162 0.167 0.112 0.95 > x = a[ find( a < .1 ) ] x = matrix columns 1 thru 2 0.0369 0.0847 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.33">7.33 findstr </A></H2> <DL> <DT> Synopsis <DD>Find a string within another string. <DT> Syntax <DD>findstr ( STR1, STR2 ) <DT> Description <DD>Findstr finds the starting point(s) of one string within another. The return value is a row vector of offsets into the longer string. Example: <BLOCKQUOTE><CODE> <PRE> > s = "now is the time for all good men to come to the aid of their country" now is the time for all good men to come to the aid of their country > findstr(s, "all") 21 > findstr(s, "aid") 49 > findstr(s, "the") 8 45 56 > findstr(s, " ") matrix columns 1 thru 6 4 7 11 16 20 24 matrix columns 7 thru 12 29 33 36 41 44 48 matrix columns 13 thru 15 52 55 61 </PRE> </CODE></BLOCKQUOTE> <DT>See also<DD>strsplt </DL> <H2><A NAME="ss7.34">7.34 finite </A></H2> <DL> <DT> Synopsis <DD>Test variable for finite values. <DT> Syntax <DD>finite ( A ) <DT> Description <DD>finite returns a matrix, the same size as the input (A), consisting of ones and zeros. The elements of the return matrix are 1 if the corresponding value of A is finite, or zero if the corresponding element of A is an Inf or a NaN. Example: <BLOCKQUOTE><CODE> <PRE> > a = [1, inf(), 3; 4, 5, 6; inf(), 8, nan()] a = 1 inf 3 4 5 6 inf 8 nan0x80000000 > finite (a) 1 0 1 1 1 1 0 1 0 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>isinf, isnan </DL> <H2><A NAME="ss7.35">7.35 floor </A></H2> <DL> <DT> Synopsis <DD>Largest integral value not greater than X <DT> Syntax <DD>floor ( X ) <DT> Description <DD>Floor returns the largest integer not greater than the argument. If the argument is a MATRIX then the floor operation is performed on an element-by-element basis. <DT>See Also<DD>ceil, int </DL> <H2><A NAME="ss7.36">7.36 format </A></H2> <DL> <DT> Synopsis <DD>Set the printing format. <DT> Syntax <DD>format ( ) format ( PRECISION ) format ( WIDTH, PRECISION ) format ( [ WIDTH, PRECISION ] ) <DT> Description <DD>Format sets the output print format for all numeric output. If no arguments are supplied, then the output print formats are reset to the default values. <DL> <DT>PRECISION<DD>represents the precision with which numbers will be printed. For instance, if PRECISION has a value of 4, then 4 significant digits will be printed for numeric values. <DT>WIDTH<DD>represents the minimum field width of the formatted output. </DL> Format returns a 2-element matrix contains the previous width and precision values. Subsequently, this matrix can be used to reset format. Example: <BLOCKQUOTE><CODE> <PRE> > 123456789.123456789 1.235e+08 > format(10); > 123456789.123456789 123456789.1 > format(); > a = rand(3,3) a = matrix columns 1 thru 3 1 0.3331 0.6646 0.9745 0.03694 0.08467 0.6475 0.1617 0.2041 > format(10); > a a = matrix columns 1 thru 3 0.9999996424 0.3330855668 0.6646450162 0.9745196104 0.03694454208 0.08467286825 0.6474838853 0.1617118716 0.2041363865 > format(15,10); > a a = matrix columns 1 thru 3 0.9999996424 0.3330855668 0.6646450162 0.9745196104 0.03694454208 0.08467286825 0.6474838853 0.1617118716 0.2041363865 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.37">7.37 fprintf </A></H2> <DL> <DT> Synopsis <DD>Formatted printing to a file. <DT> Syntax <DD>fprintf ( filestring, formatstring, VARi ... ) <DT> Description <DD>The RLaB fprintf is a limited feature version of the C-language fprintf. The features are limited because RLaB does not support all of the data types the C-language does. <DL> <DT>filestring<DD>The 1st string argument determines the file to which the output is sent. If the filename starts with a <CODE>|</CODE> then a pipe is opened to the process following the <CODE>|</CODE> and the output is written to the pipe. For example: <BLOCKQUOTE><CODE> <PRE> > fprintf("|gnuplot"; "set term X11\n plot sin(x)\n"); </PRE> </CODE></BLOCKQUOTE> will create the sub-process gnuplot, and pipe the command string to it. <DT>formatstring<DD>A valid fprintf format string. <DT>VARi<DD>Are any number of constants or variables that match the format string. fprintf cannot print out vector, matrix, or list objects as a whole. Valid print objects are strings, constants, and scalars. </DL> Example: <BLOCKQUOTE><CODE> <PRE> > for (i in 1:a.n) { fprintf("stdout", "element %i: %20.10g\n", i, a[i]); } element 1: 1.414213562 element 2: 4.242640687 element 3: 2.828427125 element 4: 5.656854249 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>printf, sprintf, write, read </DL> <H2><A NAME="ss7.38">7.38 fread </A></H2> <DL> <DT> Synopsis <DD>Binary stream input. <DT> Syntax <DD>fread ( FILENAME, NITEMS, TYPE, SWAPB ) <DT> Description <DD>fread reads NITEMS of type TYPE from FILENAME (a string) and returns the result in a numeric matrix. Allowable arguments are: <DL> <DT>NITEMS<DD>Number of objects of type TYPE to read from FILENAME. If NITEMS is inf(), then fread will read from FILENAME until end-of-file is reached. <DT>TYPE<DD> <BLOCKQUOTE> "char" </BLOCKQUOTE> <BLOCKQUOTE> "unsigned char" </BLOCKQUOTE> <BLOCKQUOTE> "short int" </BLOCKQUOTE> <BLOCKQUOTE> "unsigned int" </BLOCKQUOTE> <BLOCKQUOTE> "int" </BLOCKQUOTE> <BLOCKQUOTE> "float" </BLOCKQUOTE> <BLOCKQUOTE> "double" </BLOCKQUOTE> <DT>SWAPB<DD> <BLOCKQUOTE> 0 Do not swap bytes in a word (default). </BLOCKQUOTE> <BLOCKQUOTE> 1 Do swap the bytes in each word. </BLOCKQUOTE> </DL> <DT>See Also<DD>FILES, fseek, fwrite, close, open, write </DL> <H2><A NAME="ss7.39">7.39 frexp </A></H2> <DL> <DT> Synopsis <DD>Convert floating-point number to fractional and integral components <DT> Syntax <DD>frexp ( A ) <DT> Description <DD>Frexp returns a list with elements f and e Frexp splits A into a normalized fraction in the interval: <BLOCKQUOTE><CODE> <PRE> 0.5 <= abs(f) <= 1 </PRE> </CODE></BLOCKQUOTE> which is returned in f, and a power of 2, which is returned in e. If A is zero, then both e and f are zero. Frexp operates on REAL matrices of any dimension. <DT>See Also<DD>log, log10, log2, exp, mod </DL> <H2><A NAME="ss7.40">7.40 fseek </A></H2> <DL> <DT> Synopsis <DD>Reposition a stream. <DT> Syntax <DD>fseek ( FILENAME, OFFSET ) fseek ( FILENAME, OFFSET, OFFSET ) <DT> Description <DD>fseek sets the current position in FILENAME. a subsequent read will access data beginning at the new position. fseek is an interface to the C library function of the same name. OFFSET is specified in bytes. <DL> <DT>ORIGIN<DD> <BLOCKQUOTE> "SEEK_SET" beginning of file (default) </BLOCKQUOTE> <BLOCKQUOTE> "SEEK_CUR" current position </BLOCKQUOTE> <BLOCKQUOTE> "SEEK_END" end of file </BLOCKQUOTE> </DL> <DT>See Also<DD>FILES, fread, open, close </DL> <H2><A NAME="ss7.41">7.41 full </A></H2> <DL> <DT> Synopsis <DD>Convert sparse storage to full (dense) storage. <DT> Syntax <DD>full( A ) <DT> Description <DD>full converts its argument from the sparse storage format to the full, or dense, storage format. Example: <BLOCKQUOTE><CODE> <PRE> > d = [1, 1, 10; > 2, 4, 20; > 3, 1, 12; > 5, 2, 13; > 1, 4, 3]; > s = spconvert(d) (1, 1) 10 (1, 4) 3 (2, 4) 20 (3, 1) 12 (5, 2) 13 > f = full(s) 10 0 0 3 0 0 0 20 12 0 0 0 0 0 0 0 0 13 0 0 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>sparse, spconvert </DL> <H2><A NAME="ss7.42">7.42 fwrite</A></H2> <DL> <DT> Synopsis <DD>Binary stream output. <DT> Syntax <DD>fwrite ( FILENAME, TYPE, DATA ) <DT> Description <DD>fwrite writes DATA to the file identified by FILENAME. DATA is cast, or converted to the data type identified in TYPE. fwrite roughly mimincs the C programming language's fwrite library function. DATA can either be a dense numeric matrix, or a string matrix. The size of the matrix does not need to be specified because the entire matrix is written. If DATA is a string matrix, then the first character of each element is written to FILENAME, after being coerced to type TYPE. Allowable arguments are: <DL> <DT>TYPE<DD> <BLOCKQUOTE> "char" </BLOCKQUOTE> <BLOCKQUOTE> "unsigned char" </BLOCKQUOTE> <BLOCKQUOTE> "short int" </BLOCKQUOTE> <BLOCKQUOTE> "unsigned int" </BLOCKQUOTE> <BLOCKQUOTE> "int" </BLOCKQUOTE> <BLOCKQUOTE> "float" </BLOCKQUOTE> <BLOCKQUOTE> "double" </BLOCKQUOTE> </DL> <DT>See Also<DD>FILES, fread, fseek, close, open, write </DL> <H2><A NAME="ss7.43">7.43 getenv </A></H2> <DL> <DT> Synopsis <DD>Get an environment variable <DT> Syntax <DD>getenv ( NAME ) <DT> Description <DD>Getenv searches the current environment for a variable with name NAME. The value of the environment variable is returned as a string. Exactly how getenv behaves is depends upon the underlying operating system implementation. On UNIX system getenv will return a NULL string if the environment variable does not exist. <DT>See Also<DD>putenv </DL> <H2><A NAME="ss7.44">7.44 getline </A></H2> <DL> <DT> Synopsis <DD>Get a line of input. <DT> Syntax <DD>getline ( FN ) getline ( FN, LL ) <DT> Description <DD>Getline returns an N-element list which contains all of the tokens from a line in the file described by FN. The tokens are delimited by whitespace. Numbers are installed in the list as numeric scalars, everything else is installed as scalar strings. The list elements have numeric indices, and are numbered from 1 to N. The 1st element containing the 1st token on the line, and the Nth element containing the last token on the line. The newline is not returned as a token. Getline will also recognize everything enclosed within a pair of <CODE>"</CODE> as a string, including escape characters. Getline will always return a list-object. When an empty-line has been read, getline returns an empty list. Getline will terminate on an End-Of-File (EOF). The filename can be a string that specifies a sub-process (see <CODE>help FILES</CODE>), in which case getline will run the sub-process, and read from the process's standard output. The second, and optional argument, LL, forces getline to return the entire line (including the newline) as a string, without any parsing. If LL is <= 0, then getline will read lines as long as 512 characters. If LL > 0, then getline will read lines as long as LL characters. The return value is a single string, not a list, when LL is used. If getline encounters and EOF, while LL is being used, a numeric value of 0 is returned. Examples: To get input interactively: <BLOCKQUOTE><CODE> <PRE> > printf( "Enter a string and a number: " ); x = getline( "stdin" ); Enter a string and a number: test-string 1.234e5 > show(x) name: x class: list n: 2 > x.[1] test-string > x.[2] 2 = 1.23e+05 </PRE> </CODE></BLOCKQUOTE> Given a file named `test', which contains the following lines: <BLOCKQUOTE><CODE> <PRE> jcool 259 4 1075 822 vt01 S Dec 29 9:32 X :0 -p 1 -s 5 jcool 256 0 21 0 console S Dec 29 0:00 startx jcool 261 0 338 88 console S Dec 29 0:16 twm jcool 288 8 635 333 ? S Dec 29 2:00 emacs jcool 287 0 408 65 console S Dec 29 0:01 xclock </PRE> </CODE></BLOCKQUOTE> <BLOCKQUOTE><CODE> <PRE> > tmp = getline( "test" ); </PRE> </CODE></BLOCKQUOTE> would produce a list variable named `tmp' with 16 elements: tmp.<F>1</F> would be the string "jcool" and tmp.<F>16</F> would be the number 5. The next call to getline() would read the second line in the file, and create a new list containing those elements. The above could also have been done with: <BLOCKQUOTE><CODE> <PRE> > tmp = getline( "|ps -aux | grep jcool" ); </PRE> </CODE></BLOCKQUOTE> Which would open a readable pipe to the "ps -aux | grep jcool" command and grab a line at a time from the process. To read the entire contents of a file: <BLOCKQUOTE><CODE> <PRE> if (length (ans = getline("stdin"))) { // do something with ans else // finish up } </PRE> </CODE></BLOCKQUOTE> Since getline returns an empty list when there is no input, we can tell when to terminate the input loop by checking the length of the returned list. Using the optional second arguemnt to getline we can get old-style Fortran formattted output. For example, we have a file filled with: <BLOCKQUOTE><CODE> <PRE> 0.1285186E+000.1463163E+000.0000000E+000.0000000E+000.0000000E+000.0000000E+00 0.0000000E+000.0000000E+000.0000000E+000.0000000E+000.7322469E-010.5245288E-01 0.0000000E+00-.9399651E-010.2397120E-01-.6551484E-010.2616772E+020.5796479E-01 0.0000000E+000.2500000E+000.7788281E-010.2121489E-010.0000000E+00-.1345507E+00 0.1516225E-01-.1284981E+000.1136876E+020.3010250E-010.0000000E+00-.2500000E+00 </PRE> </CODE></BLOCKQUOTE> we can do: <BLOCKQUOTE><CODE> <PRE> > lv = strtod (getline (FN, 13)); </PRE> </CODE></BLOCKQUOTE> and get a vector with the numeric values for each line. <DT>See Also<DD>strsplt </DL> <H2><A NAME="ss7.45">7.45 help </A></H2> <DL> <DT> Synopsis <DD>Online Help <DT> Syntax <DD>help help NAME <DT> Description <DD> <DL> <DT>help<DD>Prints a list of available help files. Help first prints out the help files in the default help file directory. Next, the directories identified in the environment variable <CODE>RLAB_SEARCH_PATH</CODE> are searched for files ending in `.r' -- rfiles. A list of each directory's rfiles is printed on the standard output. <DT>help NAME<DD>Prints out the help file identified by NAME. If NAME matches a file in the default help directory, that file is paged to the standard output. If no match is found, the directories identified in the environment variable <CODE>RLAB_SEARCH_PATH</CODE> are searched for matches. The first match is paged to the standard output. The rfile extension (`.r') is not considered when checking for matches. </DL> If the user's environment does not contain <CODE>RLAB_SEARCH_PATH</CODE>, then the default search-path is used. The default is set at compile time. Normally the default is ".", the current working directory. Help is a command, not an expression or statement. Therefore, it must be issued on a line by itself, and cannot occur in the midst of another statement or expression. <DT>See Also<DD>rfile </DL> <H2><A NAME="ss7.46">7.46 hess </A></H2> <DL> <DT> Synopsis <DD>Find the Hessenberg form of a matrix. <DT> Syntax <DD>hess( A ) <DT> Description <DD>Hess finds the Hessenberg from of a matrix. Hess takes a single matrix, A, as input, and returns a list with two elements, h, and p. <BLOCKQUOTE> A = p * h * p' where A is the input </BLOCKQUOTE> Hess uses the LAPACK subroutines DGEHRD, DORGHR, and ZGEHRD, ZUNGHR. </DL> <H2><A NAME="ss7.47">7.47 ifft </A></H2> <DL> <DT> Synopsis <DD>Inverse Discrete Fourier Transform <DT> Syntax <DD>ifft ( X ) ifft ( X, N ) <DT> Description <DD>Ifft utilizes the FFTPACK subroutine CFFTB to compute a discrete Fourier transform of the input. The output is scaled by 1/N, so that a call to fft() followed by a call to ifft() will reproduce the original input. If ifft is used with a second argument, N, then the matrix X is either padded with zeros, or truncated till it is of length N (if X is a vector), or has row dimension N (if it is a matrix). Subroutine CFFTB computes the backward complex discrete Fourier transform (the Fourier synthesis). equivalently, CFFTB computes a complex periodic sequence from its Fourier coefficients. <BLOCKQUOTE><CODE> <PRE> for j=1,...,n c(j)=the sum from k=1,...,n of c(k)*exp(i*(j-1)*(k-1)*2*pi/n) where i=sqrt(-1) </PRE> </CODE></BLOCKQUOTE> The argument X must be a matrix. If X is a row, or column matrix then a vector ifft is performed. If X is a MxN matrix then the N columns of X are ifft'ed. <DT>See Also<DD>fft </DL> <H2><A NAME="ss7.48">7.48 imag </A></H2> <DL> <DT> Synopsis <DD>Imaginary part <DT> Syntax <DD>imag ( A ) <DT> Description <DD>Imag returns the imaginary part of an A. Example: <BLOCKQUOTE><CODE> <PRE> > z = pi + 3*pi*1j 3.14 + 9.42i > imag(z) 9.42 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>conj, real </DL> <H2><A NAME="ss7.49">7.49 inf </A></H2> <DL> <DT> Synopsis <DD>Create a variable with value of infinity. <DT> Syntax <DD>inf ( ) <DT> Description <DD>Inf returns a scalar whose value is infinity, according to IEEE-754. Unlike NaN, inf == inf should return TRUE (1). <DT>See Also<DD>nan </DL> <H2><A NAME="ss7.50">7.50 int </A></H2> <DL> <DT> Synopsis <DD>Return an integer. <DT> Syntax <DD>int ( A ) <DT> Description <DD>Int returns its argument after it has been "cast" to an integer. If the argument is a MATRIX then the int operation is performed on an element-by-element basis. int has the effect of truncating the input, for example: <BLOCKQUOTE><CODE> <PRE> > int(1.1) 1 > int(1.5) 1 > int(1.999) 1 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>ceil, floor </DL> <H2><A NAME="ss7.51">7.51 isinf </A></H2> <DL> <DT> Synopsis <DD>Test for values of infinity. <DT> Syntax <DD>isinf ( A ) <DT> Description <DD>isinf returns TRUE (1) if A is Infinity (according to IEEE-754). If A is a vector or a matrix the test is performed element-by-element, and a matrix the same size as A is returned. Infs can usually be created by attempting to divide by zero, or using the builtin inf function. Example: <BLOCKQUOTE><CODE> <PRE> > a = [1, 2, 3; 4, 5, inf(); 7, 8, 9] a = 1 2 3 4 5 inf 7 8 9 > isinf (a) 0 0 0 0 0 1 0 0 0 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>isnan, finite </DL> <H2><A NAME="ss7.52">7.52 isnan </A></H2> <DL> <DT> Synopsis <DD>Test for NaN values. <DT> Syntax <DD>isnan ( A ) <DT> Description <DD>isnan returns TRUE (1) if A is a NaN (Not A Number). If A is a vector or a matrix the test is performed element-by-element, and a matrix the same size as A is returned. NaNs can be create by the 0/0 operation on most computers. Example: <BLOCKQUOTE><CODE> <PRE> > a = [1, 2, 3; 4, 5, nan(); 7, 8, 9] a = 1 2 3 4 5 nan0x80000000 7 8 9 > isnan (a) 0 0 0 0 0 1 0 0 0 </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>inf, isinf, finite, nan </DL> <H2><A NAME="ss7.53">7.53 issymm </A></H2> <DL> <DT> Synopsis <DD>Test matrix for symmetry <DT> Syntax <DD>issymm ( A ) <DT> Description <DD>Issymm returns TRUE (1) if the argument A is a symmetric (or Hermitian) matrix, and FALSE (0) if A is not symmetric (Hermitian). </DL> <H2><A NAME="ss7.54">7.54 length </A></H2> <DL> <DT> Synopsis <DD>Return the length of an object. <DT> Syntax <DD>length ( A ) <DT> Description <DD>The length function returns the length of vector A. It is equivalent to <CODE>max (size (A))</CODE>, when A is numeric. To summarize: <DL> <DT>NUMERIC:<DD><CODE>max (size (A))</CODE> <DT>STRING:<DD>number of characters in a string. <DT>LIST:<DD>number of elements in list. </DL> <DT>See Also<DD>show, size </DL> <H2><A NAME="ss7.55">7.55 load </A></H2> <DL> <DT> Synopsis <DD>Load / execute the instructions in a file. <DT> Syntax <DD>load( filename ) <DT> Description <DD>Load opens the file named filename and reads its contents as though a user were typing the contents at the command line. Thus a user can use load to enter data, user-functions, or execute repetitive commands saved in a file. there is no limit to the number of functions, or regular statements that can exist in a file called by load. Immediately after the the input is read, load closes the file, so that subsequent calls to load will re-open the file. Load requires that a complete file specification be provided. If the file is in the present working directory, then only the filename is necessary otherwise, a complete path is required. In most cases the rfile command is simpler to use. Example: <BLOCKQUOTE><CODE> <PRE> // load the roots() function into memory > load( "roots.r" ) </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>rfile </DL> <H2><A NAME="ss7.56">7.56 log </A></H2> <DL> <DT> Synopsis <DD>Logarithmic function. <DT> Syntax <DD>log ( A ) <DT> Description <DD>Log returns the natural logarithm of it's argument. If the argument is a VECTOR or MATRIX an element-by-element log operation is performed. </DL> <H2><A NAME="ss7.57">7.57 log10 </A></H2> <DL> <DT> Synopsis <DD>Base-10 logarithm. <DT> Syntax <DD>log10 ( A ) <DT> Description <DD>Log10 returns the base-10 logarithm of it's argument. If the argument is a MATRIX, an element-by-element log10 operation is performed. log10 is not implemented yet for COMPLEX data. </DL> <H2><A NAME="ss7.58">7.58 logb </A></H2> <DL> <DT> Synopsis <DD>Unbiased exponent. <DT> Syntax <DD>logb ( A ) <DT> Description <DD>Logb returns the unbiased exponent of its REAL argument. This function depends upon operating system support. Logb is part of the IEEE-754 standard, and should be available on most machines that implement this standard in one form or another. <DT>See Also<DD>frexp </DL> <H2><A NAME="ss7.59">7.59 max </A></H2> <DL> <DT> Synopsis <DD>Maximum function <DT> Syntax <DD>max ( A ) max ( A, B ) <DT> Description <DD>Max returns the maximum value(s) contained in the matrix A. If the argument is a vector, then the largest value is returned. If A is a MxN matrix, then a row-vector of N columns is returned containing the maximum value from each column of A. If max is used with two arguments, then max returns a matrix the same size as A and B filled with the largest elements from A and B. When matrix elements are complex the absolute value is used for comparison purposes. <DT>See Also<DD>maxi, min, mini </DL> <H2><A NAME="ss7.60">7.60 maxi </A></H2> <DL> <DT> Synopsis <DD>Maximum value indices <DT> Syntax <DD>maxi ( A ) <DT> Description <DD>Maxi returns the index of the maximum value contained in matrix. If the input argument (A) is a vector, then the index of the largest value is returned. If A is a MxN matrix, then a row-vector of the column indices of the largest column values of A is returned. <DT>See Also<DD>max, min, mini </DL> <H2><A NAME="ss7.61">7.61 members </A></H2> <DL> <DT> Synopsis <DD>Return an object's member names. <DT> Syntax <DD>members ( L ) <DT> Description <DD>The members function takes a variable as an argument (L), and returns a string-vector containing the object's member names. For example: <CODE>x = members ($$)</CODE> will create a row-vector and assign it to x. The row-vector will contain the names of all the elements in the global-symbol-table. The members function is probably most useful when used in conjunction with for-loops. The result of members can be used as the loop index, allowing users to operate on the elements of an object. For example: <BLOCKQUOTE><CODE> <PRE> ll = << a = rand(3,3); b = rand(3,3); c = rand(3,3) >>; for (i in members (ll)) { ll.[i] = diag(ll.[i]); } </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.62">7.62 min </A></H2> <DL> <DT> Synopsis <DD>Minimum function. <DT> Syntax <DD>min ( A ) min ( A, B ) <DT> Description <DD>Min returns the minimum value(s) contained in the matrix A. If the argument is a vector, then the smallest value is returned. If A is a MxN matrix, then a row-vector of N columns is returned containing the minimum value from each column of A. If min is used with two arguments, then min returns a matrix the same size as A and B filled with the smallest elements from A and B. When matrix elements are complex the absolute value is used for comparison purposes. <DT>See Also<DD>mini, max, maxi </DL> <H2><A NAME="ss7.63">7.63 mini </A></H2> <DL> <DT> Synopsis <DD>Minimum value indices. <DT> Syntax <DD>mini ( A ) <DT> Description <DD>Mini returns the index of the minimum value contained in matrix. If the input argument (A) is a vector, then the index of the smallest value is returned. If A is a MxN matrix, then a row-vector of the column indices of the smallest column values of A is returned. <DT>See Also<DD>max, maxi, min </DL> <H2><A NAME="ss7.64">7.64 mnorm</A></H2> <DL> <DT> Synopsis <DD>Compute the matrix norm. <DT> Syntax <DD>mnorm ( A ) mnorm ( A , TYPE ) <DT> Description <DD>The first form defaults to computing the 1-norm of the input matrix. The second form allows the user to specify the desired type of matrix norm with a string argument. <DL> <DT><CODE>M</CODE> or <CODE>m</CODE><DD>returns <CODE>max(abs( A ))</CODE> <DT> <CODE>1</CODE>, <CODE>O</CODE> or <CODE>o</CODE> <DD>return the 1-norm (default), the largest column sum (max(sum(abs(A)))). <DT> <CODE>2</CODE> <DD>returns the matrix 2-norm (largest singular value) <DT> <CODE>I</CODE> or <CODE>i</CODE> <DD>returns the infinity-norm, the largest row sum (max(sum(abs(A')))). <DT> <CODE>F</CODE>, <CODE>f</CODE>, <CODE>E</CODE> or <CODE>e</CODE> <DD>returns the Frobenius norm. </DL> LAPACK subroutines DLANGE and ZLANGE are used to compute all norms, except the 2-norm. Obscure feature: If TYPE is Inf (the output from <CODE>inf()</CODE>, for example), then norm will compute the Infinity norm of the matrix A. Example: <BLOCKQUOTE><CODE> <PRE> > a = magic(4) 16 2 3 13 5 11 10 8 9 7 6 12 4 14 15 1 > mnorm ( a ) 34 > mnorm ( a , "m" ) 16 > mnorm ( a , "1" ) 34 > mnorm ( a , "2" ) 34 > mnorm ( a , "i" ) 34 > mnorm ( a , inf() ) 34 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.65">7.65 mod </A></H2> <DL> <DT> Synopsis <DD>Floating point remainder <DT> Syntax <DD>mod( A, B ) <DT> Description <DD>The mod routine returns the floating point remainder of the division of A by B: zero if B is zero or if A/B would overflow; otherwise the number F with the same sign as A, such that A = iB + F for some integer i, and |f| < |B|. When the arguments to mod are two matrices, then an element by element mod is performed. Mod works on complex number also. mod(x,y) is equivalent to: <BLOCKQUOTE> n = int( x/y ) </BLOCKQUOTE> <BLOCKQUOTE> mod(x,y) = x - y.*n </BLOCKQUOTE> mod is implemented via libm.a fmod function. </DL> <H2><A NAME="ss7.66">7.66 nan </A></H2> <DL> <DT> Synopsis <DD>Return a NaN (Not a Number) <DT> Syntax <DD>nan ( ) <DT> Description <DD>Nan returns a NaN (Not a Number) according to IEEE-754. One way to determine if a variable contains a NaN is to test it against itself. <BLOCKQUOTE> NaN == NaN </BLOCKQUOTE> Should always return FALSE (0). <DT>See Also<DD>inf </DL> <H2><A NAME="ss7.67">7.67 ode </A></H2> <DL> <DT> Synopsis <DD>Integrate Ordinary Differential Equations. <DT> Syntax <DD>ode ( rhsf, tstart, tend, ystart, dtout, relerr, abserr, uout ) <DT> Description <DD>ode integrates a system of N first order ordinary differential equations of the form: <BLOCKQUOTE><CODE> <PRE> dy(i)/dt = f(t,y(1),y(2),...,y(N)) y(i) given at t . </PRE> </CODE></BLOCKQUOTE> The arguments to ode are: <DL> <DT>rhsf<DD>A function that evaluates <CODE>dy(i)/dt</CODE> at <CODE>t</CODE>. The function takes two arguments and returns <CODE>dy/dt</CODE>. An example that generates <CODE>dy/dt</CODE> for Van der Pol's equation is shown below. <BLOCKQUOTE><CODE> <PRE> vdpol = function ( t , x ) { xp = zeros(2,1); xp[1] = x[1] * (1 - x[2]^2) - x[2]; xp[2] = x[1]; return xp; }; </PRE> </CODE></BLOCKQUOTE> <DT>ystart<DD>The initial values of <CODE>y, y(tstart)</CODE>. <DT>tstart<DD>The initial value of the independent variable. <DT>tend<DD>The final value of the independent variable. <DT>dtout<DD>The output interval. The vector <CODE>y</CODE> will be saved at tstart, increments of tstart + dtout, and tend. If dtout is not specified, then the default is to store output at 101 values of the independent variable. <DT>relerr<DD>The relative error tolerance. Default value is 1.e-6. <DT>abserr<DD>The absolute error tolerance. At each step, ode requires that: <BLOCKQUOTE> abs(local error) <= abs(y)*relerr + abserr </BLOCKQUOTE> For each component of the local error and solution vectors. The default value is 1.e-6. <DT>uout<DD>Optional. A user-supplied function that computes an arbitrary output during the integration. uout must return a row-matrix at each dtout during the integration. It is entirely up to the user what to put in the matrix. The matrix is used to build up a larger matrix of the output, with one row for each dtout. The resulting matrix is returned by ode when the integration is complete. </DL> The Fortran source code for ode is completely explained and documented in the text, "Computer Solution of Ordinary Differential Equations: The Initial Value Problem" by L. F. Shampine and M. K. Gordon. Example: <BLOCKQUOTE><CODE> <PRE> // // Integrate the Van der Pol equation, and measure the effect // of relerr and abserr on the solution. // vdpol = function ( t , x ) { xp = zeros(2,1); xp[1] = x[1] * (1 - x[2]^2) - x[2]; xp[2] = x[1]; return xp; }; t0 = 0; tf = 10; x0 = [0; 0.25]; dtout = 0.05; relerr = [1e-6, 1e-5, 1e-4, 1e-3, 1e-2, 1e-1]; abserr = relerr; // // Baseline // xbase = ode( vdpol, 0, 20, x0, 0.05, 1e-9, 1e-9); results = zeros (relerr.n, abserr.n); elapse = zeros (relerr.n, abserr.n); // // Now loop through the combinations of relerr // and abserr, saving the results, and computing // the maximum difference. // "start testing loop" for (i in 1:abserr.n) { xode.[i] = <<>>; for (j in 1:relerr.n) { printf("\t%i %i\n", i, j); tic(); xode.[i].[j] = ode( vdpol, 0, 20, x0, 0.05, relerr[j], abserr[i]); elapse[i;j] = toc(); // Save results results[i;j] = max (max (abs (xode.[i].[j] - xbase))); } } > results results = matrix columns 1 thru 6 1.97e-05 0.000297 0.000634 0.00815 0.078 1.44 0.000128 7.89e-05 0.000632 0.00924 0.0732 1.61 0.000647 0.000625 0.00112 0.0147 0.0995 1.46 0.00355 0.00352 0.00271 0.0118 0.0883 0.862 0.0254 0.0254 0.0254 0.104 0.218 1.72 0.513 0.513 0.513 0.589 0.467 1.82 </PRE> </CODE></BLOCKQUOTE> Each row of results is a function of the absolute error (abserr) and each column is a function of the relative error (relerr). <DT>See Also<DD>ode4 </DL> <H2><A NAME="ss7.68">7.68 ones </A></H2> <DL> <DT> Synopsis <DD>Create a matrix filled with ones. <DT> Syntax <DD>ones ( M , N ) ones ( A ) <DT> Description <DD>Create a matrix of ones. If the input is two scalars, then create a matrix of 1s with dimensions NxM. If the input is a 2 element matrix, then create a matrix with row and column dimensions equal to A[1] and A[2] respectively. This is useful when used in conjunction with size(): <BLOCKQUOTE><CODE> <PRE> ones( size( X ) ) </PRE> </CODE></BLOCKQUOTE> will return a matrix of ones the same size as <CODE>X</CODE>. <DT>See Also<DD>zeros </DL> <H2><A NAME="ss7.69">7.69 open </A></H2> <DL> <DT> Synopsis <DD>Open a file for reading. <DT> Syntax <DD>open ( FILENAME, MODE ) open ( FILENAME, MODE, BUFFSIZE ) <DT> Description <DD>Open will open a file or a pipe for read or write operations. Open allows the user to specify the mode of operation, and optionally a buffer-size for I/O. The "normal" UNIX modes are: <DL> <DT>r<DD>read access <DT>w<DD>write access <DT>a<DD>append: open for writing at end of file, or create for writing <DT>BUFFSIZE<DD>Buffersize is specified in bytes. If BUFFSIZE is not specified the system defaults are used. </DL> Other operating systems may have different mode keys. Look at the API documentation for fopen on your system to find what mode values are acceptable. <DT>See Also<DD>close, printf, fprintf, read, readb, readm, write, writeb, writem </DL> <H2><A NAME="ss7.70">7.70 printf </A></H2> <DL> <DT> Synopsis <DD>Formatted printing. <DT> Syntax <DD>printf ( formatstring , VARi ... ) <DT> Description <DD>The RLaB printf is a limited feature version of the C-language printf(). The features are limited because RLaB does not support all of the data type the C-language does. <DL> <DT>formatstring<DD>must be a valid printf format string <DT>VARi<DD>are any number of constants or variables that match the format string. printf cannot print out vector, matrix, or list objects as a whole. Valid print objects are strings, constants, and scalars. </DL> The following shows how one might print out the annotated contents of a matrix. <BLOCKQUOTE><CODE> <PRE> for(i in 0:size(a)[0]-1) { for(j in 0:size(a)[1]-1) { printf("a[%i;%i] = %f\n", i, j, a[i;j]); } } </PRE> </CODE></BLOCKQUOTE> However, it would be more efficient to use: <BLOCKQUOTE><CODE> <PRE> > writem("stdout", a); </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>fprintf, sprintf, write, read </DL> <H2><A NAME="ss7.71">7.71 prod </A></H2> <DL> <DT> Synopsis <DD>Product. <DT> Syntax <DD>prod ( A ) <DT> Description <DD>Compute the product of the elements of A (if A is a vector). If A is a matrix return a row vector containing the product of each column. </DL> <H2><A NAME="ss7.72">7.72 putenv </A></H2> <DL> <DT> Synopsis <DD>Change or add an environment variable. <DT> Syntax <DD>putenv ( STRING ) <DT> Description <DD>putenv takes a single argument, STRING, of the form: <BLOCKQUOTE><CODE> <PRE> "NAME=VALUE" </PRE> </CODE></BLOCKQUOTE> putenv make the value of the environment variable <CODE>NAME</CODE> equal to <CODE>VALUE</CODE> by altering an existing variable or creating a new one. Exactly how putenv behaves is depends upon the underlying operating system implementation. On most Unix systems putenv will return non-zero if an error occurred, and zero otherwise. <DT>See Also<DD>getenv </DL> <H2><A NAME="ss7.73">7.73 qr </A></H2> <DL> <DT> Synopsis <DD>QR decomposition <DT> Syntax <DD>qr ( A ) qr ( A, <CODE>"p"</CODE> ) <DT> Description <DD> Qr computes the QR decomposition of the input matrix A such that: <BLOCKQUOTE> A = Q * R </BLOCKQUOTE> or <BLOCKQUOTE> A*p = Q * R </BLOCKQUOTE> Qr returns a list containing elements q and r. Optionally, qr can take a second argument, <CODE>"p"</CODE> which tells qr to perform column pivoting when computing q and r. The permutation matrix p is returned in the same list as q and r. Qr utilizes LAPACK subroutines DGEQRF and DORGQR for REAL inputs, and ZGEQRF and ZUNGQR for COMPLEX inputs. When column pivoting is requested the LAPACK subroutines DGEQPF, and ZGEQPF are used. </DL> <H2><A NAME="ss7.74">7.74 quit </A></H2> <DL> <DT> Synopsis <DD>Quit, terminate an Rlab session. <DT> Syntax <DD>quit <DT> Description <DD>The statement <CODE>quit</CODE> causes RLaB to stop execution immediately. Quit is an executable statement, that is, it is not built into the parser, it only takes effect when executed. This allows users to embed a quit statement in a branch of a conditional statement. RLaB can also be stopped by a ctrl-d (hold down the control key while typing `d'). </DL> <H2><A NAME="ss7.75">7.75 rand </A></H2> <DL> <DT> Synopsis <DD>Random number generator. <DT> Syntax <DD>rand ( ) rand ( nrow, ncol ) rand ( DTYPE, D1 ) rand ( DTYPE, D1, D2 ) <DT> Description <DD> <DL> <DT>rand()<DD>produces a random scalar. <DT>rand ( X , Y )<DD>produces a randomly generated MATRIX with row dimension X, and column dimension Y. <DT>rand ( DTYPE , ... )<DD>changes the distribution used when generating random numbers. The value of DTYPE determines the subsequent parameters. </DL> Types of distributions: <DL> <DT><CODE>rand ( "beta" , A , B )</CODE><DD>Sets the generator to return a random deviate from the beta distribution with parameters <CODE>A</CODE> and <CODE>B</CODE>. The density of the beta is <BLOCKQUOTE><CODE> <PRE> x^(a-1) * (1-x)^(b-1) / B(a,b) for 0 < x < 1 </PRE> </CODE></BLOCKQUOTE> <DT><CODE>rand ( "chi" , DF )</CODE><DD>Sets the generator to return a random deviate from the distribution of a chi-square with <CODE>DF</CODE> degrees of freedom random variable. <DT><CODE>rand ( "exp" , AV )</CODE><DD>Sets the generator to return a random deviate from an exponential distribution with mean <CODE>AV</CODE>. <DT><CODE>rand ( "f" , DFN DFD )</CODE><DD>Sets the generator to return a random deviate from the F (variance ratio) distribution with <CODE>DFN</CODE> degrees of freedom in the numerator and <CODE>DFD</CODE> degrees of freedom in the denominator. <DT><CODE>rand ( "gamma" , A , R )</CODE><DD>Sets the generator to return a random deviate from the gamma distribution whose density is: <BLOCKQUOTE><CODE> <PRE> (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X) </PRE> </CODE></BLOCKQUOTE> <DT><CODE>rand ( "nchi" , DF , XNONC )</CODE><DD>Sets the generator to return a random deviate from the distribution of a noncentral chi-square with <CODE>DF</CODE> degrees of freedom and noncentrality parameter <CODE>XNONC</CODE>. <DT><CODE>rand ( "nf" , DFN , DFD, XNONC )</CODE><DD>Sets the generator to return a random deviate from the noncentral F (variance ratio) distribution with <CODE>DFN</CODE> degrees of freedom in the numerator, and <CODE>DFD</CODE> degrees of freedom in the denominator, and noncentrality parameter <CODE>XNONC</CODE>. <DT><CODE>rand ( "normal" , AV , SD )</CODE><DD>Sets the generator to return a random deviate from a normal distribution with mean, AV, and standard deviation, SD. <DT><CODE>rand ( "uniform" , LOW , HIGH )</CODE><DD>Sets the generator to return a uniform double between <CODE>LOW</CODE> and <CODE>HIGH</CODE>. <DT><CODE>rand ( "bin" , N , P )</CODE><DD>Returns a single random deviate from a binomial distribution whose number of trials is <CODE>N</CODE> and whose probability of an event in each trial is <CODE>P</CODE>. <DT><CODE>rand ( "poisson" , AV )</CODE><DD>Sets the generator to return a random deviate from a Poisson distribution with mean <CODE>AV</CODE>. <DT><CODE>rand ( "default" )</CODE><DD>Resets the random number generator to the default generator, which generates a distributed random variable in the interval 0 -> 1. The interval endpoints are not returned. </DL> Examples: <BLOCKQUOTE><CODE> <PRE> > rand() 0.368 > rand(4) vector elements 1 thru 4 0.983 0.535 0.766 0.646 > rand(3,3) matrix columns 1 thru 3 0.767 0.152 0.347 0.78 0.625 0.917 0.823 0.315 0.52 > rand("norm", 10.0, 2.0 ); > rand(10) vector elements 1 thru 5 9.86 11.8 12.1 7.35 8.76 vector elements 6 thru 10 10.5 7.44 11.1 6.93 9.87 </PRE> </CODE></BLOCKQUOTE> rand uses the RANLIB library, authored by B. W. Brown and J. Lovato under grant CA-16672 from the National Cancer Institute. <DT>See Also<DD>srand </DL> <H2><A NAME="ss7.76">7.76 rcond </A></H2> <DL> <DT> Synopsis <DD>Condition number. <DT> Syntax <DD>rcond( A ) <DT> Description <DD>Rcond computes an estimate of the condition number of the input matrix, A. rcond() uses the LAPACK routines DGECON, or ZGECON. Probably the most published way to compute the condition of a matrix is: <BLOCKQUOTE><CODE> <PRE> Kcond = ||A|| * ||inv(A)|| </PRE> </CODE></BLOCKQUOTE> Another method is to use the 1st and last singular values of A: <BLOCKQUOTE><CODE> <PRE> Kcond = sigma(1)/sigma(n) </PRE> </CODE></BLOCKQUOTE> rcond computes an ESTIMATE of the condition number without computing all of the columns of inv(A). For more information see the LAPACK User's Guide. See Also inv, det, lu </DL> <H2><A NAME="ss7.77">7.77 read </A></H2> <DL> <DT> Synopsis <DD>Read data from a file. <DT> Syntax <DD>read ( FILENAME ) read ( FILENAME, LIST ) <DT> Description <DD>read reads the file identified by the FILENAME. The file is opened with read access, and all of the contents are read. The file identified by the 1st argument must contain data that is in RLaB binary format. The entities in the file are installed in the global symbol table, overwriting any existing entities. Upon completion the file is closed. Example: <BLOCKQUOTE><CODE> <PRE> read ("bunch_of_data_in_a_file"); </PRE> </CODE></BLOCKQUOTE> The second form of the read function allows the data in the file to be read into list variable LIST. The global-symbol-table is untouched (except for LIST). Example: <BLOCKQUOTE><CODE> <PRE> read ("bunch_of_data", X); </PRE> </CODE></BLOCKQUOTE> The contents of the file <CODE>bunch_of_data</CODE> are read and stored in the list variable <CODE>X</CODE>. Except for the creation/modification of the variable <CODE>X</CODE>, the global-symbol-table is unchanged. Read will read most numeric matrices written by MATLAB's save command. Read will not read MATLAB text matrices, or sparse matrices, or matrices written with reduced precision (integer format). Read will not read Cray, or VAX binaries. Read will read big and little endian binaries - this includes binaries written from PCs, DEC Risc, Macintosh, Sun, and Apollo. <DT>See Also<DD>FILES, close, getline, read, readm, writem </DL> <H2><A NAME="ss7.78">7.78 readm </A></H2> <DL> <DT> Synopsis <DD>Read ASCII matrices from a file. <DT> Syntax <DD>readm ( FILENAME ) readm ( FILENAME, [ NR,NC ] ) readm ( FILENAME, NROW ) <DT> Description <DD>Readm reads a generic matrix of data from the file denoted by the string argument FILENAME. The return value is the newly created matrix. The second, and optional, argument is a two-element matrix that specifies the size of the matrix to read. If the matrix size is not specified, then the matrix is filled row-wise with the input data. Otherwise (if the size is specified), the matrix if filled column-wise, as the input is read. The file format is generic ASCII. The rows of the matrix are separated by newlines, and the columns are separated by whitespace. Unnecessary newlines, either before, or after the data will confuse readm, and will probably result in an error message. Only one matrix can be stored in a file. If you need to store more than one matrix in a file, use write, and read. Readm can only read in numeric matrices. The result of reading in string matrices is undefined. Example: <BLOCKQUOTE><CODE> <PRE> 1 2 3 4 5 6 7 8 9 10 11 12 </PRE> </CODE></BLOCKQUOTE> The above values in a file called "test" would be read in like: <BLOCKQUOTE><CODE> <PRE> > a = readm("test") a = matrix columns 1 thru 4 1 2 3 4 5 6 7 8 9 10 11 12 </PRE> </CODE></BLOCKQUOTE> Readm exists to read in data from other programs. In many cases a simple awk script will filter the other programs output into one or more columns of data. readm will read the data into the matrix, then the matrix can be reshaped if necessary. Notes: Readm has no idea how many rows are in the matrix it is reading. This is because readm can work with pipes and process output where it gets the matrix as a stream. Readm uses a heuristic to guess how many rows of the matrix to allocate at one time. A second, optional argument, NROW can be specified if the heuristic does not yield the performance you desire. The heuristic is purposely memory conservative. <BLOCKQUOTE><CODE> <PRE> readm ( "filename" , NROW ) </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>reshape, getline, open, read, write, writem </DL> <H2><A NAME="ss7.79">7.79 require </A></H2> <DL> <DT> Synopsis <DD>Specify program dependencies/requirements. <DT> Syntax <DD>require NAME <DT> Description <DD>The require command takes Rfile names as operands, and checks the workspace for a function variable called NAME. If that function exists, then no action is taken. If the function does not exist, then the file <CODE>NAME.r</CODE> is loaded. More than one NAME can be given on the same line. Continuations are not allowed. NAME can contain the `.r' extension that distinguishes Rfiles (by convention), or NAME can omit the `.r' extension. In either case a workspace variable without the `.r' extension is checked for. Example: <BLOCKQUOTE><CODE> <PRE> > require roots poly.r bode </PRE> </CODE></BLOCKQUOTE> The require command syntax is identical to the rfile command, with the obvious exception of the initial keyword. The rules for searching the user's <CODE>RLAB2_PATH</CODE> are the same as those used with the rfile command. <DT>See Also<DD>rfile, load </DL> <H2><A NAME="ss7.80">7.80 reshape </A></H2> <DL> <DT> Synopsis <DD>Reshape a matrix <DT> Syntax <DD>reshape ( A, nrow, ncol ) <DT> Description <DD>Reshape does what its name implies, it reshapes the input matrix so that the return value has the number of rows and columns specified by the last two arguments. Reshape will not reshape the matrix if the product of the new row and column dimensions does not equal the product of the existing row and column dimensions. Examples: <BLOCKQUOTE><CODE> <PRE> m = [1,2,3;4,5,6;7,8,9]; mrow = reshape(m, 1, 9); // converts m to a row matrix mcol = reshape(m, 9, 1); // converts m to a column matrix </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.81">7.81 rfile </A></H2> <DL> <DT> Synopsis <DD>Load an rfile. <DT> Syntax <DD>rfile rfile NAME <DT> Description <DD> <DL> <DT>rfile<DD>Prints a list of all the files with a `.r' suffix. The list is compiled by searching the directories contained in the environment variable <CODE>RLAB2__PATH</CODE>. <DT>rfile NAME<DD>Loads the contents of the file denoted by NAME into the workspace. The NAME argument is NOT a string, and does not have to include the `.r' suffix. Allowable names for rfiles are filenames that start with: <BLOCKQUOTE> A digit, or a letter (a-z or A-Z). </BLOCKQUOTE> and contain: <BLOCKQUOTE> digits, letters, and/or <CODE>-</CODE>, <CODE>_</CODE>, <CODE>.</CODE> </BLOCKQUOTE> You may not be able to use all the possible filenames allowed by the host operating system. </DL> If the user's environment does not contain <CODE>RLAB2_PATH</CODE>, then the default search-path is used. The default is set at compile time. Normally the default is ".", the current working directory. Rfile is a command, not an expression or statement. Therefore, it must be issued on a line by itself, and cannot occur in the midst of another statement or expression. The rfile command cannot be continued across lines (no continuations). The command `rfile NAME' can be used more than once. Each time the command is issued the file `NAME.r' is loaded. The rfile command tries to be friendly. If you give it a string without the `.r' extension, it will automatically add one for you. If you give is a string with the `.r' extension, it will leave it alone. The contents of the named file can be any valid RLaB commands or functions. There is no limit to the number of functions that a file can contain. Additionally, a mixture of commands, and function definitions can be included in the same file. Example: <BLOCKQUOTE><CODE> <PRE> > rfile roots.r poly bode </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>help, load, require </DL> <H2><A NAME="ss7.82">7.82 round </A></H2> <DL> <DT> Synopsis <DD>Round to the nearest integer. <DT> Syntax <DD>round ( A ) <DT> Description <DD>Round returns the nearest integer value to its floating point argument X as a double-precision floating point number. The returned value is rounded according to the currently set machine rounding mode. If round-to-nearest (the default mode) is set and the difference between the function argument and the rounded result is exactly 0.5, then the result will be rounded to the nearest even integer. Round uses the libm.a function rint. If your machine does not have rint, then the supplied rint is used. <DT>See Also<DD>ceil, int, floor </DL> <H2><A NAME="ss7.83">7.83 schur </A></H2> <DL> <DT> Synopsis <DD>Schur decomposition. <DT> Syntax <DD>schur ( A ) <DT> Description <DD>The schur function returns a list containing elements t and z, such that: <BLOCKQUOTE> A = z * t * z' </BLOCKQUOTE> If A is real, the t is in "Real-Schur" form. The "Real-Schur" form is block upper-triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2 diagonal block has its diagonal elements equal and its off-diagonal elements of opposite sign. The eigenvalues of the 2-by-2 block: <CODE>[a, b; c, a]</CODE> are: <CODE>a +/- sqrt(b*c)</CODE> schur uses the LAPACK subroutines DGEES, and ZGEES. </DL> <H2><A NAME="ss7.84">7.84 sign </A></H2> <DL> <DT> Synopsis <DD>Return the sign of A <DT> Syntax <DD>sign ( A ) <DT> Description <DD> For real scalar argument, sign returns: <BLOCKQUOTE> 1 if A > 0 </BLOCKQUOTE> <BLOCKQUOTE> 0 if A == 0 </BLOCKQUOTE> <BLOCKQUOTE> -1 if A < 0 </BLOCKQUOTE> For a complex scalar sign returns: <BLOCKQUOTE> A ./ abs (A) </BLOCKQUOTE> sign performs its operation on real and complex matrices in an element by element fashion. </DL> <H2><A NAME="ss7.85">7.85 trig </A></H2> <DL> <DT> Synopsis <DD>Compute the sin. <DT> Syntax <DD>sin ( A ) <DT> Description <DD>RLaB trigonometric functions are designed to take scalars, and matrices as arguments. The return value is the input argument with the trigonometric operation performed element by element. All the trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.86">7.86 size </A></H2> <DL> <DT> Synopsis <DD>Return the size of an object. <DT> Syntax <DD>size ( A ) <DT> Description <DD>The size function returns the size of the argument. <DL> <DT>NUMERIC<DD>size returns a matrix whose 1st element is the number of rows, and whose 2nd element is the number of columns. <DT>STRING<DD>size returns a matrix whose 1st element is the number of rows, and whose 2nd element is the number of columns. If the length of a particular string is desired, then the length function must be used. <DT>LIST<DD>size returns the number of elements in the list. </DL> <DT>See Also<DD>length, show </DL> <H2><A NAME="ss7.87">7.87 sizeof </A></H2> <DL> <DT> Synopsis <DD>Return the size of an object in bytes. <DT> Syntax <DD>sizeof ( A ) <DT> Description <DD>The sizeof function returns the number of bytes of data in the argument A. <DT>See Also<DD>size, who, whos </DL> <H2><A NAME="ss7.88">7.88 solve </A></H2> <DL> <DT> Synopsis <DD>Solve linear equations. <DT> Syntax <DD>solve ( A, B ) solve ( A, B, TYPE ) <DT> Description <DD>Solve solves a system of linear equations: <BLOCKQUOTE> A * X = B </BLOCKQUOTE> <DL> <DT>A<DD>is the coefficient matrix. <DT>B<DD>is the right hand side. <DT>X<DD>is the solution. </DL> B can contain multiple right-hand-sides, one in each column. Solve returns a matrix of the solutions, X, where each column of the solution corresponds to a column of B. Solve uses the LAPACK subroutines DGETRF, and ZGETRF if A is general. Solve uses the LAPACK subroutines DSYTRF, and ZHETRF if A is symmetric. The third and optional argument, TYPE allows the user to overide the symmetry check, and force the solve to use either the general or the symmetric solver. <BLOCKQUOTE> TYPE = "g" or "G": The general solution is used. </BLOCKQUOTE> <BLOCKQUOTE> TYPE = "s" or "S": The symmetric solution is used. </BLOCKQUOTE> <DT>See Also<DD>backsub, inv, factor, lu, rcond </DL> <H2><A NAME="ss7.89">7.89 sort </A></H2> <DL> <DT> Synopsis <DD>Sort an object. <DT> Syntax <DD>sort ( A ) <DT> Description <DD>If A is a vector (either row or column): <BLOCKQUOTE> Then sort returns a list, containing the sorted values and indices. List element names are `val' and `ind'. </BLOCKQUOTE> If A is a matrix (m > 2): <BLOCKQUOTE> Then sort returns a list, containing a matrix with the sorted columns of A, and a matrix containing the sorted indices of A. </BLOCKQUOTE> Numerical matrices are sorted in ascending numerical value. Complex matrices are sorted by absolute value. String matrices are sorted alphabetically (using strcmp()). The sort function uses a simplistic version of qsort. </DL> <H2><A NAME="ss7.90">7.90 sparse </A></H2> <DL> <DT> Synopsis <DD>Convert full (dense) storage to sparse storage <DT> Syntax <DD>sparse ( A ) <DT> Description <DD>sparse converts its argument from a dense storage format to the sparse storage format. If the argument is already sparse, then it is condensed (any non-zeros are removed). The sparse storage format is commonly referred to as sparse row-wise storage. Only the non-zero elements of the matrix are stored in a row-wise fashion. Row-wise storage is used for several reasons: <UL> <LI> The matrix vector product <CODE>A*x</CODE> is a very common operation, efficiently performed with row-wise storage. </LI> <LI> Row-wise (and column-wise) storage is a very general storage scheme that works well for general non-symmetric matrices. There is a penalty to pay for storing symmetric matrices in this fashion, but it is small. </LI> </UL> Rlab does not attempt to out-smart the user by automatically converting sparse matrices to dense matrices, or vice-versa. Even if the user explicitly fills the a sparse matrix so that the number of non-zeros is equal to the full size of the matrix, the sparse storage format is retained. Certain operations on sparse matrices will return dense matrices. For instance, the cosine operation on a sparse matrix will create a dense matrix with ones where there used to be zeros. Sparse matrices are printed differently than full, or dense matrices. Only the non-zero elements are printed, along with their row and column values. For example: <BLOCKQUOTE><CODE> <PRE> > a = [0, 1, 0; > 2, 0, 0; > 0, 0, 3]; > s = sparse(a) (1, 2) 1 (2, 1) 2 (3, 3) 3 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.91">7.91 spconvert </A></H2> <DL> <DT> Synopsis <DD>Convert a full column matrix to sparse storage. <DT> Syntax <DD>spconvert ( A ) <DT> Description <DD>spconvert converts its argument to, or from, the sparse storage format. If the argument is a 3 (or 4) column full matrix, the argument is converted to sparse storage format. The 1st two columns are taken as the row and column indices for the elements in the third column. The rows of the input matrix do not have to be in any particular order. If there are duplicate elements (same row and column number), then they are summed. If the argument is a sparse matrix, then it is converted to a full matrix with 3 columns. The first two columns being the row and column indices of each non-zero element, and the third column in the element value (columns 3 and 4 if the matrix is complex). Example: Create a sparse matrix of zeros with 1000 rows, and 1000 columns <BLOCKQUOTE><CODE> <PRE> > s = spconvert ([ 1000, 1000, 0 ]) (1000, 1000) 0 > show(s); nr : 1000 nc : 1000 n : 1e+06 nnz : 1 class : num type : real storage : sparse </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.92">7.92 sprintf </A></H2> <DL> <DT> Synopsis <DD>Formatted printing to a string. <DT> Syntax <DD>sprintf ( stringvar, formatstr, VARi ... ) <DT> Description <DD>The RLaB sprintf is a limited feature version of the C-language sprintf. The features are limited because RLaB does not support all of the data types the C-language does. <DL> <DT>stringvar<DD>The output of sprintf is written to this variable. <DT>formatstr<DD>A valid sprintf format string. <DT>VARi<DD>Are any number of constants or variables that match the format string. sprintf cannot print out vector, matrix, or list objects as a whole. Valid print objects are strings, constants, and scalars. </DL> <DT>See Also<DD>printf, fprintf, write, read </DL> <H2><A NAME="ss7.93">7.93 spsolve </A></H2> <DL> <DT> Synopsis <DD>Solve sparse linear equations. <DT> Syntax <DD>spsolve ( A, B, DIAG_PIVOT, PERMV ) <DT> Description <DD>Solve solves a system of sparse linear equations: <BLOCKQUOTE> A * X = B </BLOCKQUOTE> <DL> <DT>A<DD>is the coefficient matrix. <DT>B<DD>is the right hand side. <DT>DIAG_PIVOT<DD>specifies the diagonal-pivoting threshold. <DT>PERMV<DD>is the permutation vector. <DT>X<DD>is the solution vector/matrix. </DL> To be finished later... <DT>See Also<DD>solve, backsub, factor </DL> <H2><A NAME="ss7.94">7.94 spwrite </A></H2> <DL> <DT> Synopsis <DD>Write a sparse matrix to file. <DT> Syntax <DD>spwrite ( FILENAME , SPM ) <DT> Syntax <DD>spwrite ( FILENAME , SPM , FORMAT ) <DT> Description <DD>The spwrite function takes at least two arguments. The 1st argument is the string that identifies the file to write to. The file is opened with write permission, destroying any pre-existing contents. The file closed after the matrix is written. The default format for the sparse matrix is the internal storage format: compressed row-wise storage. See the Rlab Reference Manual for more explanation of this storage format. A third, and optional argument, is a string specifying either the default, or an optional output format. The value of the string can be either <CODE>"sparse"</CODE> (default) or <CODE>"graph"</CODE>. The graph output is a file suitable for use with the Metis or Chaco graph partitioning/re-ordering software. <DT>See Also<DD>write </DL> <H2><A NAME="ss7.95">7.95 sqrt </A></H2> <DL> <DT> Synopsis <DD>Compute the square root. <DT> Syntax <DD>sqrt ( A ) <DT> Description <DD>Sqrt returns the square-root of it's argument. If the argument is a matrix, then an element-by-element square-root operation is performed. <CODE>sqrt(-1)</CODE> will produce <CODE>1i</CODE>. </DL> <H2><A NAME="ss7.96">7.96 srand </A></H2> <DL> <DT> Synopsis <DD>Seed the random number generator. <DT> Syntax <DD>srand ( ) srand ( A ) srand ( SEED ) <DT> Description <DD>Srand sets the seed for the random number generator. <CODE>srand()</CODE> sets the seed to the original value (the last value given to srand, or the default value, 1). <CODE>srand( "clock" )</CODE>' sets the seed based upon the machines clock value. This provides users a way of picking a unique seed each time. Srand uses the RANLIB subroutine SETALL. <DT>See Also<DD>rand </DL> <H2><A NAME="ss7.97">7.97 strsplt </A></H2> <DL> <DT> Synopsis <DD>Split a string. <DT> Syntax <DD>strsplt ( STR ) strsplt ( STR, FW ) <DT> Description <DD>Strsplt returns a row matrix that contains a single character string as each element. The resulting matrix has as many columns as the input argument had characters. Example: <BLOCKQUOTE><CODE> <PRE> > smat = strsplt( "string" ) smat = s t r i n g > show(smat) name: smat class: matrix type: string nr: 1 nc: 6 </PRE> </CODE></BLOCKQUOTE> The second, and optional, argument to strsplt, FW forces strsplt to split STR into FW length strings. FW can also be a string, or a string matrix, specifying the field separators that strsplt will use: <BLOCKQUOTE><CODE> <PRE> > str = "this;is;a;sem-colon;separated string;with numbers;1.234" this;is;a;sem-colon;separated string;with numbers;1.234 > strsplt(str,";") this is a sem-colon separated string with numbers 1.234 </PRE> </CODE></BLOCKQUOTE> <DT>See also<DD>getline </DL> <H2><A NAME="ss7.98">7.98 strtod </A></H2> <DL> <DT> Synopsis <DD>String to decimal conversion. <DT> Syntax <DD>strtod ( STR ) <DT> Description <DD>The strtod functions converts its argument, STR, from string class to numeric class. Strtod stands for STRing TO Decimal. Strtod will return a NaN (Not a Number) if it cannot recognize a string, or an element of a string matrix, as a number. </DL> <H2><A NAME="ss7.99">7.99 sum </A></H2> <DL> <DT> Synopsis <DD>Sum the elements of a matrix. <DT> Syntax <DD>sum ( A ) <DT> Description <DD>Sum computes the sum of a matrix. The return object is a row matrix which contains the sum of each column of the input. If the input is a vector (row-matrix) then the sum of the elements is returned. </DL> <H2><A NAME="ss7.100">7.100 svd </A></H2> <DL> <DT> Synopsis <DD>Singular Value Decomposition <DT> Syntax <DD>svd ( A ) svd ( A, TYPE ) <DT> Description <DD>Computes the singular values of the input matrix A, as well as the right and left singular vectors in various forms. Where: <BLOCKQUOTE><CODE> <PRE> A = U * diag (sigma) * Vt </PRE> </CODE></BLOCKQUOTE> The output is a list containing the three afore-mentioned objects (u, sigma, vt). Various forms of the right and left singular vectors can be computed, depending upon the value of the second, optional, string argument TYPE: <DL> <DT><CODE>S</CODE><DD>A minimal version of <CODE>U</CODE>, and <CODE>Vt</CODE> are returned. This is the default. <DT><CODE>A</CODE><DD>The full <CODE>U</CODE>, and <CODE>Vt</CODE> are returned. <DT><CODE>N</CODE><DD><CODE>U</CODE> and <CODE>Vt</CODE> are not computed, empty <CODE>U</CODE> and <CODE>Vt</CODE> are returned. </DL> The LAPACK subroutine DGESVD, or ZGESVD is used to perform the computation. Example: <BLOCKQUOTE><CODE> <PRE> > A = [0.96, 1.72; 2.28, 0.96]; > Asvd = svd(A) sigma u vt > Asvd.vt matrix columns 1 thru 2 -0.8 -0.6 0.6 -0.8 > Asvd.u matrix columns 1 thru 2 -0.6 -0.8 -0.8 0.6 > Asvd.sigma vector elements 1 thru 2 3 1 > check = Asvd.u * diag(Asvd.sigma) * Asvd.vt check = matrix columns 1 thru 2 0.96 1.72 2.28 0.96 </PRE> </CODE></BLOCKQUOTE> </DL> <H2><A NAME="ss7.101">7.101 system </A></H2> <DL> <DT> Synopsis <DD>Execute operating system commands. <DT> Syntax <DD>system ( COMMAND ) <DT> Description <DD>The system function behaves like the the UNIX system call. The string argument to system, COMMAND, is passed directly to the bourne-shell for execution. The program waits until the system call is finished. Example: <BLOCKQUOTE><CODE> <PRE> > system( "vi test.r" ) </PRE> </CODE></BLOCKQUOTE> will allow the user to edit (create) the file <CODE>test.r</CODE>. When the vi process is finished the user will be back at the RLaB prompt. <BLOCKQUOTE><CODE> <PRE> > rfile test </PRE> </CODE></BLOCKQUOTE> will then load the result of the vi process. </DL> <H2><A NAME="ss7.102">7.102 trig </A></H2> <DL> <DT> Synopsis <DD>Compute the tangent. <DT> Syntax <DD>tan ( A ) <DT> Description <DD>RLaB trigonometric functions are designed to take scalars, and matrices as arguments. The return value is the input argument with the trigonometric operation performed element by element. All the trigonometric functions use the C language math library functions, so details about the ranges and error conditions can be found by examining the appropriate man pages on your system. </DL> <H2><A NAME="ss7.103">7.103 tic </A></H2> <DL> <DT> Synopsis <DD>Start the timer. <DT> Syntax <DD>tic ( ) <DT> Description <DD>Tic internally marks the time at which it was invoked. To measure elapsed time, use tic in conjunction with toc. Example: <BLOCKQUOTE><CODE> <PRE> tic(); a = rand(100,100); eig(a); toc() </PRE> </CODE></BLOCKQUOTE> The above would measure the time spent generating the 100x100 random matrix, and calculating the eigenvectors and values. <DT>See Also<DD>toc </DL> <H2><A NAME="ss7.104">7.104 tmpnam </A></H2> <DL> <DT> Synopsis <DD>Generate temporary file name. <DT> Syntax <DD>tmpnam ( ) <DT> Description <DD>tmpnam returns a string that is not the name of an existing file. tmpnam generates a different name each time it is called. The string tmpnam returns can be used a a filename with RLaB's file I/O functions. <DT>See Also<DD>open, close, read, write, fprintf </DL> <H2><A NAME="ss7.105">7.105 toc </A></H2> <DL> <DT> Synopsis <DD>Measure time elapsed since tic. <DT> Syntax <DD>toc ( ) <DT> Description <DD>Toc reports the time (in seconds) elapsed since the last call to tic. See also: tic </DL> <H2><A NAME="ss7.106">7.106 type </A></H2> <DL> <DT> Synopsis <DD>Return the type of an object. <DT> Syntax <DD>type ( A ) <DT> Description <DD>Type returns a string that describes the type of element contained in object A. The valid types for an object vary according to the class of the object If a list object has a string member with name <CODE>type</CODE>, then the type function will report the contents of that member. <DT>See Also<DD>class, show </DL> <H2><A NAME="ss7.107">7.107 vpnorm</A></H2> <DL> <DT> Synopsis <DD>Compute the vector P norm. <DT> Syntax <DD>vpnorm ( V , P ) <DT> Description <DD><CODE>vpnorm</CODE> computes the vector P-norm of V. The second argument is required, and specifies the value of P. A small Rlab program demonstrating the P-norm computation is provided below. However, <CODE>vpnorm</CODE> is implemented as a builtin function for maximum efficiency. <HR> <PRE> pnorm = function ( V , P ) { return (sum ( V.^P )).^(1/P); } </PRE> <HR> </DL> <H2><A NAME="ss7.108">7.108 writeb </A></H2> <DL> <DT> Synopsis <DD>Write object(s) to file. <DT> Syntax <DD>write ( FILENAME , A , b , ... ) <DT> Description <DD>The write function takes at least two arguments. The 1st argument is the string that identifies the file to write to. The file is opened with write permission, destroying any pre-existing contents. The file is left open so that subsequent writes will append to the file, and not destroy the contents. The arguments after the file name are the objects that will be written. All objects are written in RLaB binary format. Example: <BLOCKQUOTE><CODE> <PRE> writeb ( "filename", a , b , c ); </PRE> </CODE></BLOCKQUOTE> Will open the file named <CODE>filename</CODE> in write mode, and write the contents of the variables <CODE>a</CODE>, <CODE>b</CODE>, and <CODE>c</CODE>. The matrix format that write uses is compatible with MATLAB's matrix format. As long as the file only contains matrices, MATLAB should be able to read RLaB binary output. <DT>See Also<DD>close, readb </DL> <H2><A NAME="ss7.109">7.109 writem </A></H2> <DL> <DT> Synopsis <DD>Write a matrix in ASCII format. <DT> Syntax <DD>writem ( <CODE>"filename"</CODE> , A ) <DT> Description <DD> Writem is the counterpart to readm. Writem writes the matrix A to the file denoted by the 1st argument in a generic format. The format used is: <BLOCKQUOTE><CODE> <PRE> line 1: value[1;1] ... value[1;ncol] \n line nrow: value[nrow;1] ... value[nrow;ncol] \n </PRE> </CODE></BLOCKQUOTE> Writem will write real and complex numeric matrices, as well as string matrices even though readm can only read real numeric matrices. Writem does not close the file after writing A. The file is left open for further writes if necessary. Close can be called to explicitly close the file. <DT>See Also<DD>close, getline, open, readm, write </DL> <H2><A NAME="ss7.110">7.110 zeros </A></H2> <DL> <DT> Synopsis <DD>Create a matrix of zeros <DT> Syntax <DD>zeros ( nrow, ncol ) zeros ( [ nrow, ncol ] ) <DT> Description <DD>Zeros returns a matrix with all zero elements. If the arguments are two scalars, then zeros returns a matrix with dimensions nrowxncol. If the argument is a MATRIX, then zeros returns a matrix with dimensions m<F>1</F> by m<F>2</F>. Examples: <BLOCKQUOTE><CODE> <PRE> > Z = zeros( 3 , 3 ); > A = rand([10,4]); > B = zeros( size(A) ) </PRE> </CODE></BLOCKQUOTE> <DT>See Also<DD>size </DL> <HR> <A HREF="rlab-ref-6.html"><IMG SRC="prev.gif" ALT="Previous"></A> <A HREF="rlab-ref-8.html"><IMG SRC="next.gif" ALT="Next"></A> <A HREF="rlab-ref.html#toc7"><IMG SRC="toc.gif" ALT="Contents"></A> </BODY> </HTML>