M 2014-09-07 ______________________________________________________________________________ M is an interactive matrix calculator with C-style syntax. It has features of C, Matlab, and APL. The main data type in M is a `matrix', i.e. a dynamically sized two-dimensional array of double. Data types `vector' for one-dimensional arrays, and `string' for arrays of characters are also supported. M includes all of the C control statements except goto, i.e. if, else, switch, case, default, while, do, for, break, continue, return. In M, functions that return void are called procedures. A set of useful built- in functions and procedures is provided. Also built-in is a set of `commands' whose syntax is similar to a Unix command line, e.g. save a b >"ab.save" The associativity and precedence of operators in M are the same as in C. Usage: m [files...] M first loads the file .mrc from your current directory, or, if not found there, from your home directory if it can find it there. Then it loads any files specified on the command line. M Operators and Associativity in decreasing order of precedence --------------------------------------------------------------- OPERATORS ASSOCIATIVITY () [] left to right ' left to right ^ right to left ! - ++ -- (type) right to left * / % .* left to right + - left to right < <= > >= left to right == != left to right && left to right || left to right : left to right ?: right to left = += -= *= /= %= ^= .*= +/ -/ */ // +\ *\ right to left , left to right ^ is exponentiation. For help on ' see help topic transpose, for .* .*= see array, for : see vector, for +/ -/ */ // +\ *\ see reduce. Unless otherwise noted, all operators may be applied to any combination of scalars, matrices, and vectors. Operators in C which are not available in M: bit operators: ~ << >> & ^ | &= ^= |= <<= >>= struct, pointer operators: -> . & * unary plus: + Operators in M which are not available in C: matrix transpose: ' exponentiation: ^ ^= array product: .* .*= vector generator: : reduction operators: +/ -/ */ // cumulative operators: +\ *\ `sizeof' is available in M as a function which returns a two-element vector containing the numbers of rows and columns in its argument. The single quote character ' is used for matrix transpose. If A is m-by-n then A' is n-by-m. In M, [brackets] are not used for indexing, they are used to create matrices and vectors similar to Matlab, with either a comma or blank space separating elements in a row, and a semicolon or new-line separating rows, e.g. a = [ 1 2; 3, 4; d+e/f] In M, parentheses are used for indexing variables. Vector elements can be referred to with 1 index; matrix elements can be refered to with 2 indices. Rows of a matrix are selected if only 1 index is used. A range, e1:e2, may be used as a row or column index, e.g. A(2:4,:); a plain colon selects all the rows or columns. A colon alone as a single index selects all of the elements unraveled row-by-row to form a single row. The vector generator operator, ':', may only be used when indexing a variable, inside brackets when creating a matrix, or in the argument list of a function. [e1:e2] creates the row vector [e1, e1+1, e1+2, ..., e2] if e2 > e1, or [e1, e1-1, e1-2, ..., e2] if e1 > e2. e1 and e2 must be scalars. A colon passed as an argument to a function passes a NULL, and can be used for arguments which would normally be created by a function, but whose value you do not want, e.g. svd(a,:,s) returns the rank of A and creates the matrix s of singular values, but does not create u or v. The asterisk operator, '*', performs matrix multiplication, and as such, the dimensions of it operands must be compatible, i.e. A * B is valid if A is m-by-n and B is n-by-p, the result is of size m-by-p. The array multiply operator, '.*', as well as all other dyadic operators, performs its operation element-by-element, so both of the operands must have the same dimensions or be scalar. Scalars may be used in combination with matrices in any expressions, e.g. 5 + A adds 5 to every element of A if A is a matrix or vector. The reduction operators come from APL (A Programming Language) and `reduce' a matrix to a row vector, or a row vector to a scalar. +/A produces a row vector containing the row sums of A if A is a matrix. If A is a row vector, it produces the sum of the elements of A. Similiarly, -/ reduces by an alternating summation, */ by multiplication, and // by division. The operator +\ produces a cumulative row summation. The result is the same size as the argument. For X = +\A, X(i,j) = A(i,1) + ... + A(i,j). +/A would be the last column of X transposed. The operator *\ produces a cumulative row product. The result is the same size as the argument. For X = *\A, X(i,j) = A(i,1) * A(i,2) * ... A(i,j). */A would be the last column of X transposed. User functions are declared as in ANSI C. The data types available for the function type are: void, matrix, vector, string, int, double. These data types, except for void, are also available for declaring arguments and local variables. Additionally, declarations of local variables may specify a storage class of extern, static, or auto (the default is auto) and an initialization. The default data type of arguments is matrix. Functions must be declared before they are used in the definitions of other functions. Examples: void f(double x); /* just declares f */ int g( matrix a, int m, n) /* defines g */ { matrix x; int i, j; ... } Arguments declared as int or double are passed by value. Arguments declared as matrix, vector, or string are passed by address. Functions declared as int or double return a value. Functions declared as matrix, vector, or string can return a variable or a value. Declared types do not affect the type of data a variable can hold. int a = [1.0 2.0 3.0] is legal but not recommended. The variable narg and the built-in functions null() and undef() are useful in writing functions which take a variable number of arguments. narg is a local scalar variable which exists during execution of a function. Its value is the number of arguments which were passed to the function. null( a, b, ...) returns a row vector which contains a 1 for each argument which is NULL, and 0 for non-NULL arguments. For example, null( a, :, b) returns [0 1 0]. undef( a, b, ...) returns a row vector which contains a 1 for each argument which is an undefined variable or NULL, and 0 for arguments which are defined. M contains the following built-in math functions which operate element-by- element on their array argument(s): abs(A) returns the absolute value of its argument. acos(A) returns the inverse cosine of its argument. asin(A) returns the inverse sine of its argument. atan(A) returns the inverse tangent of its argument. atan2(Y,X) returns the four-quadrant equivalent of atan(Y/X). ceil(A) returns the elements of A rounded towards the least integral values greater than or equal to each element. cos(A) returns the cosine of its argument. cosh(A) returns the hyperbolic cosine of its argument. erf(x) returns the error function of its argument. erfc(x) returns 1.0-erf(x). erf(x) is defined by ${2 over sqrt(pi)} int from 0 to x e sup {-t sup 2} dt$ erfc() is provided because of the extreme loss of relative accuracy if erf(x) is called for large x and the result subtracted from 1. (e.g. for x=10, 12 places are lost). exp(A) returns the exponential function of its argument. fabs(A) returns the absolute value of its argument. floor(A) returns the elements of A rounded towards the greatest integral values less than or equal to each element. log(A) returns the natural logarithm of its argument. log10(A) returns the base 10 logarithm of its argument. sin(A) returns the sine of its argument. sinh(A) returns the hyperbolic sinh of its argument. sqrt(A) returns the square-root of its argument. tan(A) returns the tangent of its argument. tanh(A) returns the hyperbolic tangent of its argument. Other built-in functions are: ----------------------------- IO(n) sets the index origin to n and returns the former value of the index origin. The default index origin is 1, i.e. A(1,1) is the first element in A. IO(0) changes the index origin to 0, so A(0,0) would be the first element in A. IO with no arguments just returns the current index origin. all(X) returns 1 if all of the elements of X are non-zero, otherwise it returns 0. any(X) returns 1 if any of the elements of X are non-zero, otherwise it returns 0. cleanup(n) sets the cleanup period to its integer argument n and returns the former value of the cleanup period. cleanup with no arguments just returns the current cleanup period. The cleanup period is the number of loop iterations which must occur before temporary data is cleared. The default value is 10. Increasing the cleanup period causes loops to execute faster at the expense of more memory usage. If you have large amounts of temporary data and run out of memory during loop execution, try cleanup(0). cols(A) returns the number of columns in A. diag(A) returns the diagonal elements of a matrix A. diag(x) puts the vector x on the diagonal of a zero matrix. eps returns the machine precision, the smallest floating point number for which 1 + eps > 1 is true. eye(m,n) returns a m-by-n identity matrix. feval Execute function specified by a string. If fname is a string containing the name of a function then feval(fname,x1,...,xn) evaluates that function at the given arguments. For example, feval("cos",3.2) is the same as cos(3.2). The function to be evaluated can be built-in or user-defined. find(X) returns a row vector containing the indices of elements of X which are non-zero. The indices are based on the current index origin, and if X is a matrix, apply to X(:) format(s) sets the printing format to its string argument s and returns the former value of the printing format. format with no arguments just returns the current value of the printing format. max(A) is a reduction operator. If A is a matrix, it returns a row vector containing the maximum values from each row of A. If A is a row vector or scalar, it returns a scalar containing the maximum value in A. max(A,B) returns an array containing the element-by-element maximums. If both arguments are vectors or matrices, they must be the same size. min(A) is a reduction operator. If A is a matrix, it returns a row vector containing the minimum values from each row of A. If A is a row vector or scalar, it returns a scalar containing the minimum value in A. min(A,B) returns an array containing the element-by-element minimums. If both arguments are vectors or matrices, they must be the same size. norm(A) returns the square-root of the sum of the squares of all the elements of A. ones(m,n) returns an m-by-n matrix filled with 1's. prnum(n) sets the maximum number of array columns printed on each line and returns the former value of the number. prnum with no arguments just returns the current value of this number. prod(A) produces a row vector containing the row products of A if A is a matrix. If A is a row vector, it produces the product of the elements of A. prtol(t) sets the tolerance for printing zero to the absolute value of its scalar argument t and returns the former value of the tolerance. prtol with no arguments returns the current value of the tolerance. When arrays are printed, values less than prtol in absolute value are printed as zero. prtol(0) turns off this effect so all values are always printed no matter how small. rand(m,n) returns a m-by-n matrix of pseudo-random numbers from a uniform distribution in the interval 0.0 <= ... < 1.0. rand(m,n,"name") uses the Gaussian distribution, with mean 0 and standard deviation 1, if "name" is "gauss" or "normal". If "name" is "exp" it uses the exponential distribution with mean 1. rand(m,n,"int",k) returns uniformly distributed integers in the interval 1 .. k. reshape(A,m,n) returns a m-by-n matrix produced from the values in A. A may be any size and is scanned repeatedly if necessary, row-by-row, until m*n values are obtained. reshape(1,m,n) is the same as ones(m,n) reshape([1 0 0 0],3,3) is the same as eye(3,3) round(A,n) returns the elements of A rounded to a precision of n significant decimal digits. A and/or n can be arrays; if they are both arrays their dimensions must be the same. round2(A,n) returns the elements of A rounded to a precision of n significant binary digits. A and/or n can be arrays; if they are both arrays their dimensions must be the same. rows(A) returns the number of rows in A. sizeof(A) returns a 1-by-2 matrix containing the number of rows and columns of A. sizeof(A) is the same as [rows(A),cols(A)] sort(X) returns a row vector containing the indices which would select elements of X in increasing order. The indices are based on the current index origin, and if X is a matrix, apply to X(:). sum(A) produces a row vector containing the row sums of A if A is a matrix. If A is a row vector, it produces the sum of the elements of A. svd( A, U, S, V) computes the Singular Value Decomposition of A and returns the rank of A. For an m-by-n matrix A, U*S*V' = A, where U is m-by-m orthogonal, S is m-by-n diagonal containing the singular values in decreasing order, and V is n-by-n orthogonal. trunc(A,n) returns the elements of A truncated to a precision of n significant decimal digits. A and/or n can be arrays; if they are both arrays their dimensions must be the same. trunc2(A,n) returns the elements of A truncated to a precision of n significant binary digits. A and/or n can be arrays; if they are both arrays their dimensions must be the same. zeros(m,n) returns an m-by-n matrix filled with 0's. The built-in procedures are: ---------------------------- debug(n) controls the printing of debugging information. If n is zero, all debuging is turned off. If n is positive, debugging level n is turned on, if n is negative, debugging level n is turned off. The debugging levels are: n debug - ----- 1 yydebug, for the yacc parser. 2 stack_debug, for stack push() and pop(). 3 prog_debug, for program execution, displays generated code before executing it. 4 stack_dump, for dumping the stack. 5 exe, for displaying generated code without executing it. If debug(5) is set, it can not be turned off, and no commands will be executed. 6 trace, displays generated code as it's being executed. dump dumps the symbol table. exit(n) in a file being loaded, exits the loading of that file. exit() used from the keyboard or within a function exits from M. hplot( y, x, title) tabulates and plots y vs. x in histogram style. The title must be a string, and x and y must have the same number of elements. The values of x must be in either increasing or decreasing order for the plot to make sense. x and the title are optional. plot( y, x, title) tabulates and plots y vs. x. The title must be a string, and x and y must have the same number of elements. The values of x must be in either increasing or decreasing order for the plot to make sense. x and the title are optional. plot2d( y, x, title) plots y vs. x. The title must be a string, and x and y must have the same number of elements. x and the title are optional. print( a, b, ...) prints the values of the specified variables or expressions a, b, etc. printf( format, ...) is the C printf function. The first argument must be a string. Further arguments must be scalars. qr( A, Q, R) computes the QR decomposition of A. For an m-by-n matrix A, Q*R = A, where Q is m-by-m orthogonal and R is m-by-n upper-triangular. srand(s) resets the random number generator seed to the scalar s. If the argument s is missing, the seed is initialized using the C library time() routine. The built-in commands are: -------------------------- cd dir changes the working directory to dir. If no argument is given, the working directory is changed to your home directory. clear by itself clears all user variables, functions, and procedures from the current M workspace. clear a b c ... removes just a, b, c, etc. diary on turns on the diary, `diary off' turns it off. The default diary file is "diary" but output can be redirected using >file or >>file. diary with no arguments just tells you whether the diary is on or off. When the diary is on, a copy of all input/output that appears on your screen is also written to the diary file. disasm f1 f2 ... disassembles the user functions f1, f2, etc.. echo on turns on the echoing of lines read from files being loaded. echo off turns it off. echo with no arguments just tells you whether echoing is on or off. help topic1 topic2 ... prints help on topic1, topic2, etc. Help is available for all of the built-in functions, procedures, and commands. Type `what' to get a list of these. Help is also available for topics: array function index intro matrix news narg operators reduce transpose vector history n displays the n most recent lines read by M. With no arguments, all the lines remembered by M are displayed. If output redirection is used (via > or >>), the lines are written without leading numbers. This is useful for producing files suitable for re- execution by M. Lines can be recalled using ! as the first character on a line similiar to history substitution in the Unix csh. !! recalls the previous line. Lines may be recalled by specifying their number as shown by `history' or by their starting string of characters. list f1 f2 ... lists the definitions (source code) of user functions f1, f2, etc. load f1 f2 ... loads and executes files f1.m, f2.m, etc. which should be files of M commands or function definitions. If a file name contains non-alphanumeric characters, enclose it in "quotes". M looks for the specified files in the current directory, or, if not found, looks in the M library (/opt/m/lib/). If no files are specified, load tries to load "save.m". Input can be redirected from a file also, e.g. load file, or >> file to append. With no arguments (other than possible output redirection) save save's all user variables, functions, and procedures. what lists the names of built-in functions, procedures, and commands. who lists the names of user variables, functions, and procedures. write a b c ... saves the specified user variables in Matlab binary format to the file "matlab.mat". Output can be redirected using > file, or >> file to append. With no arguments (other than possible output redirection) write save's all user variables. News ---- The news help topic contains current information related to M updates and bug fixes. The oldnews help topic contains old news. 2014-09-07 New library function added: rref 2014-08-14 New library functions added: charpoly, polymul, polyval 2014-07-10 New library function added: det Created HTML documentation for the library functions. 2014-05-20 Removed map() function (used old SunOS mallocmap()). Added -b (batch mode) command-line argument. Bug fix in printing help. 1998-06-23 Bug fix related to cleanup of temporary data. 1998-06-04 New function added: feval New library function added: integrate 1998-04-24 New function added: sort 1998-04-04 M is now Y2K compliant! Various fixed array sizes were increased so that larger programs can be handled. Some minor code cleanup was performed, with no change in functionality, just to prevent compiler warnings. The version number was changed from "01/25/95" to "1995-01-25". 1995-01-25 Minor MSDOS update. Help and library subdirectory locations are now found at run-time based on location of m.exe executable 1993-02-18 New functions added: sum, equivalent to +/ prod, equivalent to */ 1993-02-25 New function added: find 1993-04-21 New function added: printf 1993-10-06 New function added: write Oldnews ------- The oldnews help topic contains old information related to M updates and bug fixes. See news help topic for current news. 02/25/92 fixed bad memory management bug. map command added, calls mallocmap() for debugging. 02/07/92 dyadic capability (two arguments) added to min() and max(). srand(void) now sets the random seed from the C library routine time(). 07/15/91 plot argument syntax changed. *\ cumulative product operator added (see `help reduce'). 07/11/91 plot(), hplot(), and plot2d() procedures added. +\ cumulative summation operator added (see `help reduce'). qrp.m added to M library. 06/27/91 cond.m, norm2.m, lup.m, and solve.m added to M library. New commands: cd, pwd, history. ! is used for command recall. system() is now invoked using $ instead of !. debug(6) now allows tracing of program execution. 06/10/91 lu.m, for Doolittle LU reduction, was added to the M library. Built-in function cleanup() added. 05/31/91 Initial release.