\documentstyle[11pt,epsf]{article} \setlength{\topmargin}{-1in} \setlength{\oddsidemargin}{0.0in} \setlength{\evensidemargin}{0.0in} \setlength{\textheight}{9in} \setlength{\textwidth}{6.5in} \newcommand{\PSbox}[3]{\mbox{\special{psfile=#1}\hspace{#2}\rule{0pt}{#3}}} \begin{document} \newcommand{\til}{\mbox{$\sim$}} \newcommand{\crt}{\mbox{$\hat{\ }$}} \newcommand{\prompt}{\raisebox{.2ex}{$>>$} } \newcommand{\kprompt}{K\raisebox{.2ex}{$>>$}} \newcommand{\prettynewpage}{\newpage} \newcommand{\hs}{\hspace*{.5cm}} \newcommand{\vs}{\vspace{.25cm}} \newcommand{\lab}[1]{\noindent \hs\hs{\tt #1}} \newcommand{\com}[1]{\lab{\raisebox{.1ex}{$>>$} {\bf #1}}} \newcommand{\ans}[1]{\lab{\hs #1}} \newcommand{\alab}[1]{\vs \lab{#1} \vs} \newcommand{\acom}[1]{\vs \com{#1} \vs} \newcommand{\re}[1]{{\bf \ref{#1}~#1}} \newcommand{\See}[1]{See~\re{#1}} \newcommand{\see}[1]{see~\re{#1}} \newcommand{\lsection}[1]{\section{#1} \label{#1}} \newcommand{\lsubsection}[1]{\subsection{#1} \label{#1}} \newcommand{\lsubsubsection}[1]{\subsubsection{#1} \label{#1}} \begin{center} \PSbox{/afs/sipb.mit.edu/project/doc/current/cover-owl.PS}{200pt}{200pt} \vspace{1in} {\Huge Inessential MATLAB on Athena\footnote{Copyright \copyright\ 1996 Student Information Processing Board of the Massachusetts Institute of Technology}} \vspace{.1in} {\huge Version 1.02} \vspace{.1in} /afs/sipb.mit.edu/project/doc/current/imatlab.dvi \vspace{.5in} The Student Information Processing Board Jamie Morris jemorris@mit.edu \vspace{.25in} June 29, 1997 \end{center} \pagestyle{empty} \newpage \pagestyle{plain} \tableofcontents \pagenumbering{roman} \newpage \pagenumbering{arabic} \section{Introduction} \subsection{What is MATLAB?} MATLAB (MATrix LABoratory) is an interactive system for matrix-based computation designed for scientific and engineering use. It is good for many forms of numeric computation and visualization. Besides dealing with explicit matrices in linear algebra, it can handle differential equations, polynomials, signal processing, and other applications. Results can be made available both numerically and as excellent graphics. Some classes at MIT require the use of MATLAB; it is also useful for many that don't. It may not be most suitable tool for your needs; e.g. Maple and Mathematica are better for symbolic math (MATLAB's symbolic math draws on part of Maple), Xess for spreadsheet work. This document is intended partially as a MATLAB tutorial and partially as a reference. \subsection{Getting into MATLAB} As you use MATLAB you will create data files, function files, and script files. While you can arrange for these files to be found by MATLAB no matter where you put them (\see{Paths}), it is simplest to use the default behavior by putting all these files in a directory called {\tt\bf matlab} in your home directory. To create this directory, do (only once ever): \vs \hs athena\% \ {\tt\bf mkdir \ \til/matlab} \vs \noindent MATLAB will then use this directory for files unless you tell it not to. (\See{M-files}.) If you created this directory {\em after} starting a MATLAB session, you will need to do {\bf addpath('\til/matlab')} in MATLAB that session to tell it the directory exists; future sessions will notice it upon startup. % While many users won't need to do the addpath thing, and certainly % not after their first reading, there will be a lot starting MATLAB % for the first time as they read this; thus the note re addpath % needs to be in the text, not a footnote, to ensure that they see it. To get a session of MATLAB, do \vs \hs athena\% \ {\tt\bf add matlab} \\ \indent \hs athena\% \ {\tt\bf matlab \&} \vs \noindent (if you have already done {\bf add matlab} in that login session, you need not repeat it). MATLAB may also be started from the {\bf Dash} bar; it is in the ``Numerical/Math'' menu, under the ``Analysis and Plotting'' submenu. When you start MATLAB, it creates a new {\bf xterm}, with the MATLAB header and MATLAB \prompt prompt. As you create graphics in MATLAB, it will pop up additional windows for them. \subsection{Demos} The MATLAB demo is very instructive if you've never used MATLAB. To get it, do \acom{demo} \noindent or to skip directly into the {\bf MATLAB Expo Main Map} section (menus of expositions), \acom{expomap} \noindent Also see {\bf help~demo} for a list of demostration facilities. \lsubsection{Help} MATLAB has several internal help features. To get a listing of help topics, do \acom{help} \noindent To get more help on a specific topic, \acom{help {\em topic}} \noindent In particular, {\bf help~general} will give you a table of contents listing many of the available functions by category. Topics also include every individual function, so you can do \acom{help {\em function}} \noindent You may also search for functions whose descriptions contain a keyword. To use this, do \acom{lookfor {\em keyword}} \noindent The MATLAB on Athena Homepage, which you can get to with {\bf add matlab} and then the URL {\bf file://localhost/mit/matlab/www/home.html}, and has pointers to lots of information about MATLAB. Type {\bf doc} at the MATLAB prompt to start up a web browser on this page. The Athena public cluster documentation racks have the {\bf MATLAB User's Guide}, the {\bf MATLAB Reference Guide}, and the {\bf MATLAB External Interface Guide}. Complete documentation on MATLAB, including the {\bf MATLAB New Features Guide}, {\bf MATLAB Release Notes}, and the {\bf SIMULINK User's Guide}, are available for reference in the Athena Consulting Office (11-115) and in Barker and Hayden Libraries. \section{The Basics} \subsection{Fundamentals of Use} Your interaction with MATLAB is in the form of you giving MATLAB a statement, possibly followed by MATLAB giving you a result, then back to you giving a statement. A statement is usually of the form of either \acom{{\em variable} = {\em expression}} \noindent or just \acom{{\em expression}} \noindent The result (which is almost always a matrix --- \see{Building Matrices}) of evaluating {\em expression} is immediately displayed. To suppress display, end the line with a semicolon; this will greatly speed up calculations resulting in large matrices. If no variable is given in which to store the result of {\em expression}, it is automatically stored in the variable {\em ans}. \vs \com{x = 3 + 2} \\ \lab{x =}\\ \ans{5} \\ \com{y = 4 + 6;}\\ \com{y} \\ \lab{y =}\\ \ans{10} \\ \com{5 + 3}\\ \lab{ans =} \\ \ans{8} \vs \noindent To put more than one statement on a single line, separate them by commas or semicolons. To have a single statement span several lines, end each line before the last with a space followed by three or more periods. \vs \com{a = 1 + 1, b = 2 + 2} \\ \lab{a = } \\ \ans{2} \\ \lab{b = } \\ \ans{4} \\ \com{c = 1 + 2 + 3 ...} \\ \com{+ 4 + 5 + 6 + ...} \\ \com{7 + 8 + 9 + 10} \\ \lab{c = } \\ \ans{55} \vs A function may have more than one output, and moreover, all the outputs may depend on how many outputs you request. For example, {\bf [val vec] = eig($matrix$)} gives a (diagonal) matrix of eigenvalues of $matrix$ and a matrix of the eigenvectors of $matrix$; however, {\bf v = eig($matrix$)} gives a vector of eigenvalues --- which is not the same as either of the former two outputs. See the {\bf help} on a function for details; it is generally wise to look at the {\bf help} before first using any function. MATLAB is, by default, case-sensitive to names, so {\tt myvar} and {\tt myVAR} are distinct. Typing {\bf casesen} toggles this sensitivity on and off. Normal scalar arithmetic works; you can use MATLAB as a basic calculator. The arithmetic functions are +, -, $\ast$, /, and \^\ (exponentiation). Use parentheses as usual to specify precedence. Also see {\bf help~arith}. MATLAB always does complex math, though it will display purely real results intelligently by omitting the imaginary part. Both {\tt i} and {\tt j} are equal to the square root of -1. If you happen to overwrite both of these (by using them as variables for something else), you can recreate with, e.g. \acom{myi = sqrt(-1)} \noindent or do {\bf clear i} to remove your definitions of {\bf i}, leaving it with its original meaning. A complex number is specified in the form {\em 1+2i} or {\em 1-2i}, where there are no spaces inside the number. Spaces can cause complex numbers in vectors and matrices to seem like two numbers, which will produce errors or at least undesired results. \vs \com{x = (1+2i)\crt2} \\ \lab{x = }\\ \ans{-3.0000 + 4.0000i} \vs Mathematical functions will accept complex arguments and, in general, give complex answers (e.g. the trigonometric functions and arcfunctions are defined over the complex plane). Specifically complex manipulations are available in the form of {\bf real} and {\bf imag} (giving the real and imaginary parts of their argument), {\bf conj} for complex conjugation, {\bf abs} for absolute value, and {\bf angle} for the phase (in radians; also see {\bf help~unwrap}). See {\bf help~elfun} for a list of trigonometric, exponential, complex, and numeric elementary scalar functions. For more specialized functions see {\bf help~specfun}. There are several commands to help with variable assignments; {\bf who} will list the variables currently in use in this session, and {\bf whos} lists the variables along with their sizes and whether they are purely real. Use {\bf clear {\em variable}} to remove {\em variable} from those currently in use; {\bf clear} by itself removes all variables. The MATLAB-defined constant {\bf eps} gives the machine unit roundoff, typically about $10^{-16}$; this is useful in specifying tolerances. The constant {\bf pi} exists. Some other predefined constants are {\bf realmax} and {\bf realmin} for largest and smallest (positive) floating point numbers, {\bf inf} for infinity, {\bf NaN} for Not-a-Number, and {\bf version} for the MATLAB version number. To halt a runaway computation, use Control-C. Use {\bf more on}, {\bf more off}, and {\bf more($n$)} to have MATLAB scroll as the UNIX {\tt more}, turn off such scrolling, and set the number of lines per page (default~23). This is useful with calculations giving long results and with long {\bf help} entries. Use {\bf clc} to clear the command window, and {\bf home} to send the cursor to the upper left without clearing. Line editing in MATLAB will Do The Right Thing: you can use the up and down arrows to get at old command lines, left and right arrows to move in and edit these lines, etc. For more details see {\bf help~cedit} or {\bf type~cedit} in MATLAB. \lsubsection{Building Matrices} Everything in MATLAB is a matrix. A vector is a 1xN or Nx1 matrix; a scalar is a 1x1 matrix. The most straightforward way to make a vector or matrix is to write it out: \acom{v = [1 2 3 4 5]} \noindent creates the obvious vector (the spaces may be replaced with commas); the statements \acom{m = [1 2 3; 4 5 6; 7 8 9]} \noindent and \begin{tabbing} \com{m = [}\={\bf 1 2 3} \\ \> {\bf 4 5 6} \\ \> {\bf 7 8 9]} \end{tabbing} \noindent both create the obvious $3 \times 3$ matrix. Note that semicolons are used to separate the rows of the matrix in the one-line square bracket notation. It can be convenient to enter a complex-valued matrix or vector in the form \acom{m = [1 2; 3 4] + i $\ast$ [4 3; 2 1]} \noindent instead of the equivalent \acom{m = [1+4i 2+3i; 3+2i 4+i]} \noindent There are a number of useful functions to create a matrix from scratch. Specifically, {\bf zeros($M$, $N$)} and {\bf ones($M$, $N$)} create $M \times N$ all-zero and all-one matrices respectively, {\bf eye($N$)} the size-$N$ identity matrix, {\bf rand($M$, $N$)} a uniformly random matrix, {\bf randn($M$, $N$)} a normally distributed one, and {\bf hilb(N)} a Hilbert matrix, among others. Some more specialized matrix generators are listed by {\bf help~specfun}. Those that take arguments $(M, N)$ will create a square matrix if given only $(N)$. The function {\bf size} takes a matrix and returns the vector [{\em width height}]; this can be used with other functions to build matrices the same size as existing ones, e.g. \acom{emptym = zeros(size(m))} \noindent The {\bf length} function gives the maximum of $width$ and $height$. \prettynewpage \noindent Matrices and vectors may be built out of smaller ones; \vs \com{va = [1 2 3]; vb = [4 5 6]; vc = [7 8 9];} \\ \com{m = [va; vb; vc]} \vs \noindent produces the same $3 \times 3$ matrix as before. Similarly, matrices can be built in blocks: \vs \com{ma = [1 2; 3 4]} \\ \lab{ma =} \\ \ans{1 2} \\ \ans{3 4} \\ \com{mb = [5 6; 7 8];} \\ \com{mwide = [ma mb]} \\ \lab{mwide =} \\ \ans{1 2 5 6} \\ \ans{3 4 7 8} \\ \com{mtall = [ma ; mb]} \\ \lab{mtall =} \\ \ans{1 2} \\ \ans{3 4} \\ \ans{5 6} \\ \ans{7 8} \vs \noindent Since the size of a matrix can be changed at any time (and can be zero), things like this are valid: \vs \com{x = [ ];} \\ \com{x = [x 1]} \\ \lab{x =} \\ \ans{1} \\ \com{x = [x 2]} \\ \lab{x =} \\ \ans{1 2} \\ \com{x = [x 3 x]} \\ \lab{x =} \\ \ans{1 2 3 1 2} \vs \noindent Note that resizing a matrix does take time; doing it ten thousand times in a loop can be noticeable. A way to avoid this is to start with a matrix of zeros (or ones, as appropriate) of the eventual largest size, and then to use only part of the matrix at a time. There are operations specifically to let you get a new object from an existing one; {\bf triu} and {\bf tril} take a matrix and produce its upper and lower triangular matrices. {\bf Diag} takes a matrix and produces the vector of its diagonal entries, or takes a vector and produces a diagonal matrix with those entries. {\bf fliplr} and {\bf flipud} take a matrix and flip it left-right or up-down; {\bf rot90} takes a matrix and rotates it counterclockwise 90 degrees (an optional integer second argument specifies repetition). The operator {\bf '} takes the conjugate transpose of a matrix; the operator {\bf .'} takes the transpose. The {\bf reshape} function rearranges matrix elements into a new shape. \vs \com{[1 2+i]'} \\ \lab{ans =}\\ \ans{1}\\ \ans{2-i} \vs \noindent Elements of a matrix are referenced as $m(row, column)$ (or $v(n)$ for a vector); this can be used to access elements, or to build a matrix. Indexing starts at one, not at zero, so it looks like \vs \begin{tabular}{ccc} (1, 1) & (1, 2) & ... \\ (2, 1) & (2, 2) & ... \\ ... & ... & ... \\ \end{tabular} \vs \noindent You could, painfully, build a matrix like \vs \com{m(1, 1) = 1; m(1, 2) = 2; m(2, 1) = 3; m(2, 2) = 4} \\ \lab{m =} \\ \ans{1 2} \\ \ans{3 4} \vs \noindent but this is more useful used in conjuction with {\bf for} and {\bf while} statements (\see{Flow}). On the other hand, submatrices can often be done this way quickly: \vs \com{m = [1 2 3; 4 5 6; 7 8 9]; s = m([1 2], [2 3])} \\ \lab{s =} \\ \ans{2 3} \\ \ans{5 6} \vs The colon operator is critical to efficient use of MATLAB. The expression $a:b$ evaluates to a row vector with values starting at $a$ and incrementing by one as long as they are no greater than $b$. The expression $a:s:b$ uses increments of $s$ instead of one. A colon by itself as a matrix index, e.g. $m(1, :)$ or $m(:, 5)$, yields the entire row or column, while a colon used as the {\em only} index to a matrix turns it into a vector by stringing the columns together. Also see {\bf help~colon}. \vs \com{v = 1:5} \\ \lab{v =}\\ \ans{1 2 3 4 5} \\ \com{w = 5:-1:1} \\ \lab{w =}\\ \ans{5 4 3 2 1} \\ \com{m = [1 2 3; 4 5 6; 7 8 9];} \\ \com{s = m(1:2, 2:3)} \\ \lab{s =} \\ \ans{2 3} \\ \ans{5 6} \\ \com{t = m(1:2, 3:-1:2)}\\ \lab{t =}\\ \ans{3 2}\\ \ans{6 5}\\ \com{m(1:2, :)}\\ \lab{ans = } \\ \ans{1 2 3} \\ \ans{4 5 6} \\ \com{m(:)'}\\ \lab{ans =} \\ \ans{1 4 7 2 5 8 3 6 9} \vs In a similar fashion, {\bf linspace(low, high, n)} gives a linearly evenly spaced vector of $n$ points from $low$ to $high$; $n$ is 100 if omitted. Further, {\bf logspace(low, high, n)} gives a logarithmically evenly spaced points between $10^{low}$ and $10^{high}$ ($n$ defaults to 50); however, if $high$ is {\bf pi}, the high end is $\pi$ itself and not $10^\pi$. Finally, matrices can be loaded from a disk file created via MATLAB or some other application (e.g. a text editor); this is the fastest method for large matrices. If a file named {\em base.extension} contains a series of rows of numbers (no other formatting) defining a matrix, {\bf load {base.extension}} will assign that matrix to the variable {\em base}. E.g. {\bf load values.txt} takes data from the file {\bf values.txt} and puts it into {\bf values}. Don't use a {\bf .mat} extension, since that will make {\bf load} assume it is a MATLAB-saved file. Since {\bf load} is frequently used for very large matrices, it does not echo the input. \subsection{Matrix and Element-wise Operations} Some operations are intended for matrices in particular. These include the conjugate and non-conjugate transpose operators {\bf '} and {\bf .'}, the matrix multiplication operator {\bf $\ast$}, and the left and right matrix ``division'' operators {\bf $\backslash$} and {\bf /}. For instance, if {\bf A} is a matrix and {\bf x} and {\bf b} are vectors, then the lines \vs \com{A'} \\ \com{A\crt2} \\ \com{A * x = b} \\ \com{x = A$\backslash$b} \\ \com{x * A = b} \\ \com{x = A/b} \vs \noindent respectively take the conjugate transpose of A, take the square of A, give a typical matrix equation involving matrix multiplication, give the solution for that equation, give another matrix equation, and give the solution for the second equation. Such solutions to matrix equations are solved exactly (with Gaussian elimination) if the matrix is square; others are solved in a least-squares sense (with Householder orthogonalization). Also see {\bf help~slash}. To get inner and outer products of vectors, remember their formal definitions. The inner product is given by {\bf x' * y = y' * x}, and the outer products by {\bf x * y'} and {\bf y * x' = (x * y')'}. \noindent MATLAB understands multiplication and division between a matrix and a scalar in the normal sense; \vs \com{10 * [1 2; 3 4]} \\ \lab{ans = } \\ \ans{10 20} \\ \ans{30 40} \vs If you want to take two matrices (or vectors) and multiply or divide them element by element, or if you want to exponentiate each element of a matrix, place a period before the operator. These are {\em array operations} as opposed to matrix operations. \vs \com{[1 2; 3 4].\crt2} \\ \lab{ans = }\\ \ans{1 4} \\ \ans{9 16} \vs Exponentiation also has both matrix and array forms. If $x$ and $y$ are scalars and $A$ and $B$ are matrices, $y$\crt$x$, $A$\crt$x$, and $x$\crt$A$ have their usual mathematical meanings. Array exponentiation is available with $A$.\crt$x$ to raise each element to a power, and $A$.\crt$B$ to raise each element of $A$ to the power of the corresponding element of $B$. MATLAB also has a large number of matrix functions to implement common mathematical operations, such as finding eigenvalues and eigenvectors. For instance, {\bf kron} will give the (Kronecker) tensor product. See {\bf help~matfun}. If you apply a function that operates on scalars to a matrix or vector, or if you apply a function that operates on vectors to a matrix, MATLAB performs the operation {\em element-wise}. Scalar functions will be applied to each element of the matrix, and the result will be a matrix of the same size. Vector functions will be applied to each column of the matrix, and the result will be a row vector of the same width. (Use the transpose operators to effect row-by-row application.) See {\bf help~funm} if you want to use the matrix and not the array version of a function. Lastly, functions defined strictly on the real line are applied separately to the real and imaginary parts of a complex number. \vs \com{sin([0 (pi/6) (pi/2) pi])} \\ \lab{ans = }\\ \ans{0 .5 1 0} \\ \com{max([1 10; 20 2])} \\ \lab{ans =}\\ \ans{20 10} \\ \com{max(max([1 10; 20 2]))} \\ \lab{ans =} \\ \ans{20} \\ \com{round(1.7+3.2i)}\\ \lab{ans =} \\ \ans{2 + 3i} \vs Certain functions are particularly useful for this. The functions {\bf max}, {\bf min}, {\bf median}, {\bf mean}, {\bf std}, {\bf sum}, and {\bf prod} take a vector and return its maximum, minimum, median, arithmetic mean, standard deviation, element sum, and element product (respectively). Applied to a matrix, they return a row vector of the result on each column. {\bf sort} sorts a vector (or each column of a matrix) in ascending order. Also see {\bf help~datafun}. Applying operations element-wise is a powerful feature of MATLAB and using it is the fastest and best way to accomplish most things. \prettynewpage \lsubsection{Flow} \subsubsection{Relations} MATLAB provides these logical operators: \vs \begin{tabular}{cl} \& & and \\ $\mid$ & or \\ \til & not \\ xor & exclusive or \\ \end{tabular} \vs \noindent and these boolean relations: \vs \begin{tabular}{cl} $<$ & less than \\ $>$ & greater than \\ $<=$ & less than or equal to \\ $>=$ & greater than or equal to \\ $==$ & is equal to \\ \til= & is not equal to \\ \end{tabular} \vs The result of applying any of these to a scalar or pair of scalars (as appropriate) is always a 1 (True) or a 0 (False). They operate element-wise on matrices; there are no ``full matrix'' versions. To test whether a relation holds over an entire matrix, or whether it holds anywhere in the matrix, the commands {\bf any} and {\bf all} are useful. Each takes a vector; {\bf any} ORs the elements (true iff any are true) and {\bf all} ANDs the elements (true iff all are true). They operate column-by-column on a matrix to produce a vector. So, for instance, \vs \com{all(all(A == B))} \\ \com{any(any(A \til= B))} \vs \noindent both test for whether the matrices A and B are entirely equal, the former returning 1 if so (because every element in every column matches), the latter returning 1 if not (because some element in some column did not match). The function {\bf find} will return the indices of the non-zero (True) elements of a matrix; this is useful for selective indexing. There are also a number of boolean tests for various characteristics; see {\bf help~ops} for most of them. \subsubsection{Control} You can do normal programming things in MATLAB. The explicit looping operators are {\bf while} and {\bf for}. The syntax of {\bf while} is \vs \noindent \hs {\bf while} {\em relation}\\ \hs\hs {\em statements} \\ \hs {\bf end} \vs \noindent The indentation is customary but not required. As long as {\em relation} holds true, {\em statements} will be executed repeatedly. The {\bf end} is mandatory. When {\em relation} evaluates to False (0), execution resumes after {\bf end}. \vs \noindent \hs {\bf for} {\em variable} {\bf =} {\em matrix} \\ \hs\hs {\em statements} \\ \hs {\bf end} \vs \noindent causes {\em variable} to assume the value of each column of {\em matrix} in succession, and execute {\em statements} for each, then resume after the mandatory {\bf end}. Frequently {\em matrix} will be a vector, e.g. \\ \hs {\bf for n = 1:5} \\ will run {\bf n} from 1 to 5. If MATLAB encounters the command {\bf break} inside a {\bf for} or {\bf while} loop, it immediately jumps to the {\bf end}. If there are nested loops, only the innermost is broken out of. Conditional control and branching are accomplished with {\bf if}, whose most general syntax is \vs \noindent \hs {\bf if} {\em relation} \\ \hs\hs {\em statements} \\ \hs {\bf elseif} {\em another relation} \\ \hs\hs {\em more statements} \\ \hs {\bf elseif} {\em a third relation} \\ \hs\hs {\em a third set of statements} \\ \hs {\bf else} \\ \hs\hs {\em last statements} \\ \hs {\bf end} \vs \noindent There can be any number of {\bf elseif}s, and the final {\bf else} is optional; the {\bf end} is mandatory as usual. The first {\em relation} of an {\bf if} or {\bf elseif} that evaluates to True (anything non-zero) is used; its {\em statements} are executed and control then passes to after the {\bf end}. If no {\em relation} is True, the {\bf else} {\em statements}, if any, are executed. All control structures can be nested. Control structures are relatively slow and inefficient in MATLAB; what MATLAB is good at is matrices. Instead of applying {\bf for} over a vector, you can usually apply your function(s) to the vector directly so it operates element-wise; this will be much faster. Instead of {\bf for} with {\bf if}, to test over the elements of a vector, you can and should use selective indexing (see below). \subsubsection{Selective Indexing} The syntax $M(row,\ column)$ to examine or change a specific element of matrix $M$ has already been explained (\re{Building Matrices}). This can be generalized by replacing $row$ and/or $column$ with vectors of the same height and/or width (respectively) as $M$ with entries all 1 (True) or 0 (False). This specifies a matrix with entries corresponding to those in $M$ whose indices are specified as True in the vectors. \vs \com{x = [1 2 3 4 5];} \\ \com{x([1 0 1 0 1])}\\ \lab{ans =}\\ \ans{1 3 5}\\ \com{m = [1 2 3; 4 5 6; 7 8 9];}\\ \com{m([1 0 1], [1 1 0])}\\ \lab{ans = }\\ \ans{1 2}\\ \ans{7 8}\\ \com{m(3, [1 0 1])}\\ \lab{ans =} \\ \ans{7 9} \vs One rarely enters the indexing vectors by hand this way. Since a relation operator applied to a matrix results in a matrix of 1s and 0s, it is naturally useful to index a matrix of the same size. \vs \com{x = 3:7} \\ \lab{x =}\\ \ans{3 4 5 6 7} \\ \com{big = x $>$ 4} \\ \lab{big =} \\ \ans{0 0 1 1 1} \\ \com{x(big)} \\ \lab{ans = } \\ \ans{5 6 7} \\ \com{x(x $>$ 3 \& x $<$ 6)}\\ \lab{ans =}\\ \ans{4 5} \vs This is even more useful when specifying elements, or specifying {\em changes} to elements, rather than merely viewing them. \vs \com{disp(x)} \\ \ans{3 4 5 6 7}\\ \com{x(x $>$ 4) = x(x $>$ 4) + 10}\\ \lab{x = }\\ \ans{3 4 15 16 17} \\ \com{x = 1:5;} \\ \com{x(x $>$ 2) = x(x $<$ 4) + 10}\\ \lab{x =}\\ \ans{1 2 11 12 13} \\ \com{x = 1:5; y = x.\crt2}\\ \lab{y =}\\ \ans{1 4 9 16 25}\\ \com{x(y $>$ 8) = x(y $>$ 8) + y(y $>$ 8)}\\ \lab{x =}\\ \ans{1 2 12 20 30} \vs Let us examine the second example in more detail. We make $x$ [1 2 3 4 5]. The relation $x~>~2$ is then the vector [0 0 1 1 1]; therefore $x(x > 2)$ is the last three elements of $x$, which currently hold [3 4 5]. On the other side, $x < 4$ is [1 1 1 0 0], so $x(x < 4)$ is the first three elements of $x$, which currently hold [1 2 3]. To this matrix is added the scalar 10; adding a scalar to a matrix is always elementwise, so the right-hand side becomes [11 12 13]. Since this is a 1x3 vector and the left-hand side is also a 1x3 vector, the assignment is valid, and the left-hand side (i.e. the last three elements of $x$) becomes [11 12 13]. MATLAB then prints the entirety of the vector $x$, including the parts that have not changed: [1 2 11 12 13]. The first and third examples, $x(x > 2) = x(x > 2) + 10$ and $x(y > 8) = x(y > 8) + y(y > 8)$, are perhaps less general but more typical. They could each be replaced with a {\bf for} loop over the vectors with an {\bf if} to perform the test. The selective indexing method is {\em much, much faster}, because MATLAB is specifically built to do this sort of thing. The code is also more readable. Therefore, you should use MATLAB in this form whenever possible. Between selective indexing and the colon operator, most procedures can be ``vectorized.'' %(Such procedures are so common that one could wish for the C operators %+= and so on, as in ``x~+=~y'' to mean ``x~=~x~+~y,'' rather than having %to write the selectively-indexed matrix explicitly on each side. MATLAB %seems to lack these; presumably it has a good reason.) \section{Graphics} Also see {\bf help~graphics}. \subsection{2-D Graphics} The {\bf plot} command suffices for basic 2-D graphics. If $x$ and $y$ are equal-length vectors, {\bf plot(x, y)} will plot the values of $y$ on the y-axis versus those of $x$ on the x-axis. If the first argument is omitted, it will be taken to be the indices of $y$ --- that is, 1:$n$ where $n$ is the length of y. Since graphs usually begin at zero, and MATLAB indexes from one, this is rarely wanted. If $y$ has $n$ elements, {\bf plot(0:$n-1$, y)} may be more appropriate. A frequent usage is the form {\bf x = 0:.01:1, y = sin(2 * pi *x), plot(x, y)}. Parametrics, e.g. {\bf t = 0:.01:1, x = sin(t), y = cos(t), plot(x, y)} work well, since the arguments just expand into the same vector. To change the style of the lines, put in a third argument, in single quotes. E.g. {\bf plot(x, y, '-')} specifies a solid line (the default). {\tt '--'} is a dashed line, {\tt ':'} dotted, {\tt '-.'} alternating dots and dashes. To plot only the data points and not draw lines between them, put {\tt '.'} (points), {\tt '+'} (crosses), {\tt '$\ast$'} (stars), {\tt 'o'} (circles), or {\tt 'x'} (x's). To specify a color, give the appropriate letter in single quotes as a third argument. To specify both color and line style, give both (in that order) as a single single-quoted argument, with no spaces; e.g. {\tt 'b:'} is a blue dashed line. Available colors are white (w), black (k), red (r), green (g), blue (b), cyan (c), magenta (m), and yellow (y). To put multiple pictures in the same graph window, simply give all their arguments to a single {\bf plot}. E.g. {\bf plot(x1, y1, x2, y2)} plots $x1$ versus $y1$ and $x2$ versus $y2$. {\bf plot(x1, y1, 'b:', x2, y2)} does the same, but with the former as a dotted blue curve. For multiple nonoverlapping plots in one window, use {\bf subplot({\em x, y, n})}, where $x$ and $y$ are each 1 or 2, to break the figure window into an $x$ by $y$ set of subgraphs, selecting the $n$th as the current subplot. MATLAB will rotate the current subplot clockwise by default (\see{Handles} and use {\bf axes} to override this; subplot 1 is in the upper left). Use {\bf subplot} with no arguments to regain the single-plot figure window. For multiple figure windows, {\bf figure {\em n}} will make the $n$th figure window current, creating it if necessary; {\bf figure} by itself creates the next figure window. Use {\bf gcf} to see which figure is current. Use {\bf clf} and {\bf cla} to clear the current figure or axes. Replacing {\bf plot} with {\bf loglog}, {\bf semilogx}, or {\bf semilogy} produces a plot that is logarithmic in both axes, the x axis, or the y axis, respectively (non-logarithmic axes remaining linear). For other kinds of plots, use {\bf help} on {\bf polar}, {\bf bar}, {\bf hist}, {\bf quiver}, {\bf compass}, {\bf feather}, {\bf rose}, {\bf stairs}, {\bf fill}. Both {\bf xlabel} and {\bf ylabel} take a text string (in single quotes) and use it to label the appropriate axis. Similarly {\bf title} uses its text string argument as the graph's title. To place text arbitrarily, use {\bf gtext} to place via mouse and {\bf text} to place via specifying coordinates --- {\bf help} for details. Use {\bf grid} to get gridlines. Stylized versions are available as {\bf stext}, {\bf sxlabel}, {\bf stitle}, etc (see {\bf help}). You can {\em find} the coordinates of a series of points with {\bf ginput} by clicking with the mouse. MATLAB will auto-scale the axes by default, using the minimum and maximum values of the data given to it for each axis. To examine or change this behavior, use {\bf axis}. {\bf axis({\em xmin, xmax, ymin, ymax})} sets the limits. {\bf v = axis} returns in $v$ the current limits, in the same order. {\bf axis(axis)} prevents the graph from rescaling when you make a new plot, {\bf axis auto} returns to auto-scaling, {\bf axis square} uses the same scaling for both axes, {\bf axis equal} uses the same scaling and ticmarks for both, and {\bf axis on} and {\bf axis off} turn scaling and ticmarks on and off. See {\bf help~axis} and {\bf help~hold} for details. Given a function, {\bf fplot('{\em function name'}, [{\em xmin xmax}])} will plot the function in the given range; this can offer a more convenient way to view a MATLAB-defined or M-file function than constructing vectors of values by hand. See {\bf help~fplot}. (Remember that MATLAB isn't big on symbolic things like this, though; a problem set asking you to plot a function probably wants it evaluated on a vector of points.) Also see {\bf help~plotxy}. \lsubsection{Handles} A {\em handle} is a special MATLAB object attached to part of a plot that lets you find and change the properties of that part. The boolean {\bf ishandle} tests whether something is a handle. A plot always has at least two parts with handles, the figure and the axis. The former has general characteristics of the entire window; the latter has characteristics of the axes. The special constant {\bf gcf} (for {\bf g}et {\bf c}urrent {\bf f}igure) is a handle to the current plot's figure; {\bf gca} ({\bf g}et {\bf c}urrent {\bf a}xis) is a handle to the current plot's axis; and {\bf gco} ({\bf o}bject) is a handle to the last piece of the plot you clicked on with the mouse. Various graphics commands return handles; generally a handle is returned by any function that creates or adds something to a plot. {\bf figure}, {\bf axes}, and {\bf text} all do this. See the help entries for specific other functions for their return values. Objects with handles have {\em properties}. Each property has a name, which is a text string. The value of a property of an object is given by {\bf get({\em handle}, {\em propertyname})}; if the property name is omitted, all properties are listed (with their names). You change these values with {\bf set}, whose most general format is {\bf set({\em vector of handles}, {\em property name}, {\em property value}, {\em another property name}, {\em value for that property}, {\em a third property name}, {\em value for third property}, ...)}. For each handle in the vector (a single handle is fine), each given property is set to the specified value. Omitting the property values will display the possible values for the specified property, with curly braces \{\} around the current value. Also omitting the property names gives such a list for all the object's properties. Some objects have {\em children}, which are objects under them; you can get handles to these objects from their parent by {\bf get}ting the 'Children' property. You can tell a parent that you want its children to have certain defaults unless they override; {\bf set} on the parent the property of 'Default' followed by the name fo the object type (given by the 'Type' property) followed by the defaulting property name (e.g. 'DefaultTextColor'). Three special property values can be given for any property. Giving 'default' resets the property to its default value as affected by any parental defaults; giving 'factory' sets to the default value ignoring any parental defaults. The 'remove' value removes the default value. To return all properties (except position) to the factory defaults use {\bf reset}. An object can be destroyed with {\bf delete({\em handle})}. The {\bf findobj} function can be used to seek for objects with given property values. A typical strategy is to get handles to the top objects, look through their children for the object you want, look through its properties for the one you want, see what possible values it has, and set the one you want. \subsection{Graphics Hardcopy} The {\bf print} command, by itself, sends the current graphics figure to the printer. See {\bf help~printopt} about setting default options in an M-file. MATLAB will print in portrait orientation (vertical longest, in the middle of the page, 4/3 aspect ratio) unless you specify otherwise with {\bf orient} prior to printing. {\bf orient landscape} changes to landscape (horizontal longest), {\bf portrait} to the default, and {\bf tall} to full-page portrait; with no argument, {\bf orient} returns the current orientation. To save the picture, {\bf print {\em filename}} will save the current graphics figure; if {\em filename} does not have an appropriate suffix (e.g. {\bf .ps}, {\bf .eps}, {\bf .jet}), the default mode will be used and the default suffix added. Specify {\bf -append} to append to an existing file instead of overwriting it (the default). To save a non-current figure, specify {\bf -f{\em number}}; to save in a specific format, specify {\bf -d{\em device}}. See {\bf help~print}. \subsection{3-D} Also see {\bf help~plotxyz}. \subsubsection{Line Plots} A one-dimensional curve in 3-D is produced by {\bf plot3}, which is completely analogous to {\bf plot}; {\bf plot3(x, y, z)} plots the curve, {\bf plot3(x, y, z, 'b:')} makes it a blue dotted line, etc. As with {\bf plot}, including more than one triplet (or quadruplet) of values in a single call overlays the plots. There exists {\bf zlabel} exactly like {\bf xlabel} and {\bf ylabel}, and {\bf axis} actually has six arguments, the last two being for z. \subsubsection{Surface Plots} Both {\bf surf} and {\bf mesh} plot a two-dimensional curve in 3-D; {\bf surf} facets the surface, while {\bf mesh} plots the facet outlines only. They are identical otherwise, including in taking arguments. There are variants; {\bf surfc} and {\bf meshc} include a contour plot (see {\bf help~contour}), {\bf surfl} provides lighting, {\bf meshz} provides a reference plane, and {\bf waterfall} gives a mesh without column lines. The most general argument to {\bf surf} is a vector of four matrices, e.g. {\bf surf(X, Y, Z, C)}. The first three matrices give the 3-D coordinates of each point on the surface, and the last gives its color as per the current colormap. Omitting the last, e.g. {\bf surf(X, Y, Z)}, uses {\bf C} = {\bf Z}, i.e. color is proportional to height. The {\bf X} and {\bf Y} matrices can be replaced by vectors of the width and height of {\bf Z}; both or neither must be replaced. A {\bf X} matrix is then used with the {\bf x} vector as each row, and a {\bf Y} matrix with the {\bf y} vector as each column. If {\bf X} and {\bf Y} are omitted entirely, the vectors 1:width and 1:height are used instead. To evaluate a function that can be performed elementwise on a matrix over a grid of points on the plane and plot it at even intervals, use {\bf meshgrid} to create {\bf X} and {\bf Y} matrices from vectors with {\bf [X, Y] = meshgrid(x, y)} (all the rows of {\bf X} are {\bf x}, all the columns of {\bf Y} are {\bf y}). Then e.g. {\bf Z = X.$\ast$Y} and {\bf mesh(Z)} will display (in this case) the coordinate products, but at evenly spaced intervals as the {\bf x} and {\bf y} vectors did not directly reach {\bf mesh}. Portions of a surface plot may be hidden behind others. One method of dealing with this is to change the viewpoint; see {\bf help~view}. Alternatively, since MATLAB does not plot values of NaN and Inf, you can make ``cutouts'' in a plot by setting the color value on some region of facets to one of those. Other features of 3-D plots can be set with {\bf caxis}, {\bf colormap}, {\bf shading}, and {\bf view}, and various {\bf color} functions, for all of which see the {\bf help} entries, as well as the commands described above for 2-D plots. \subsection{Animation} MATLAB provides simple animation capabilities with three movie functions: {\bf moviein}, {\bf getframe}, and {\bf movie}. A movie consists of a series of frames, a frame being a special MATLAB object that holds a copy of the current picture, based on the current axis. A movie is a matrix whose columns are frames. Because of the way MATLAB handles matrix resizing, you will suffer if you do not preallocate the movie matrix. Use {\bf $mov$ = moviein(\mbox{\it nframes})} to make $mov$ a matrix capable of holding \mbox{\it nframes} frames of the current axis and contents. If you will be getting frames (see below) for a specific object, and perhaps in a specific position rectangle, allocate the matrix as {\bf $mov$ = moviein(\mbox{\it nframes}, \mbox{\it handle}, \mbox{\it rectangle})} or {\bf $mov$ = moviein(\mbox{\it nframes}, \mbox{\it handle})}. Build your movie matrix out of columns provided by {\bf getframe}. By itself {\bf getframe} gets a frame of the current axis and contents. As {\bf getframe(\mbox{\it handle})} (or {\bf getframe(\mbox{\it handle}, \mbox{\it rectangle})}) it gets a frame from the object specified by \mbox{\it handle} (in the \mbox{\it rectangle} region, from the lower left corner, in the 'Units' property units). The calls to {\bf getframe} to build a movie should be consistent with each other and the {\bf moviein} preallocation call. The function {\bf movie(\mbox{\it handle}, \mbox{\it mov}, $n$)} plays the movie $mov$ in the object given by \mbox{\it handle} (or in the current figure if \mbox{\it handle} is omitted) $n$ times (once if $n$ is omitted). A negative $n$ plays the movie back and forth each time. A vector $n$ gives the repetitions in the first element and the frames to play, in order, in succeeding elements. An optional extra argument specifies the frames per second (defaulting to 12), limited by machine capabilities. An optional further extra argument specifies the location to play at, from the lower left corner, in the 'Units' property units. \section{The Session} \subsection{Recording and Retrieving} To store and retrieve the state of your session, {\bf save {\em filename}} and {\bf load {\em filename}} write and read {\bf {\em filename}.mat}. The file matlab.mat will be used if {\em filename} is omitted. Default {\bf .mat} files are not human-readable; see {\bf help~save} and {\bf help~load} for other uses, including ASCII formats and partial-state operations. If you want to keep a record of your session, {\bf diary {\em filename}} will store in {\em filename} (using the file ``diary'' if {\em filename} is omitted) everything that appears in the MATLAB xterm afterwards. (Graphics are not recorded.) {\bf diary off} will turn off this recording until restored with {\bf diary on}. (Or plain {\bf diary} to toggle between these.) The diary is plain text, so your favorite text editor can be used on it. \subsection{Shell Escapes} MATLAB provides ways to deal with the shell from within MATLAB. {\bf pwd} and {\bf cd} give the current directory path, {\bf cd {\em directory}} changes the current directory. {\bf dir} and {\bf ls} give a directory listing; {\bf what} lists the M-files. {\bf type~{\em filename}} shows the contents of text file {\em filename} or {\em filename}{\bf .m}. {\bf delete {\em filename}} will {\em remove} the file --- it acts as the UNIX command ``rm,'' not the UNIX ``delete.'' To send an arbitrary command to your shell, prefix it with ``!''; \acom{!emacs \&} \noindent will start up an emacs in the background just as from an athena prompt. This is frequently helpful for managing M-files (\see{M-files}). The command \\ \hs {\bf [status result] = unix('{\em unix command string}')} \\ also executes an arbitrary command in the operating system, returning the command status (zero for success, nonzero for failure) and standard output. \lsubsection{M-files} An m-file is a plain text file (created with your favorite text editor) in a format MATLAB understands. They must end in {\bf .m} or MATLAB won't accept them. Experience shows (but documentation is silent on) that m-file names may not have periods in them other than the {\bf .m}, nor may they have any hyphens (apparently MATLAB wants to think they're minuses). Underscores are acceptable. Any m-files in any directory in your {\em path} (\see{Paths}) can be used, as can m-files in the current directory. Use {\bf clash} to test if your m-file name will collide with an existing one. M-files can reference each other and themselves recursively. To see what an m-file says, {\bf type {\em file}.m}. This works for MATLAB's built-in m-files as well as for those you create. Use {\bf what {\em directoryname}} or {\bf help~{\em directoryname}} to see what m-files (and mat-files and mex-files) are available; {\bf what} by itself looks in the current directory. {\bf exist('{\em thingy}')} will return zero if {\em thingy} is undefined, and nonzero otherwise; the exact value specifies the nature of {\em thingy} (see {\bf help~exist}). \See{Paths} about where MATLAB will look for m-files. In theory, MATLAB only loads in an m-file script or function the first time you refer to it; it caches the contents and refers to the contents thereafter. This would mean changes in the file would not affect MATLAB's actions. In practice, MATLAB (at least on Athena) does read the m-file each time, and uses the cache only if it can no longer find the m-file in question. To force MATLAB to reread the file, use {\bf clear($filename$)} to remove the cached meaning. If all you want to do is supply some data, \see{Building Matrices}. \subsubsection{Script and Data Files} A script is a list of commands that you might give to MATLAB directly. Typing {\tt {\em script}} in MATLAB will execute, in order, the commands in the {\tt script.m} file. As usual, the result of each will be printed out unless it ends with a semicolon; putting a semicolon at the end of the script invocation will {\em not} suppress these results. To see the commands themselves as well as their results, use {\bf echo on} and {\bf echo off}. Variables in a script file are automatically global; that is, if there is a variable of the same name in the workplace, it is what will be used and/or changed by the script. \subsubsection{Function Files} You may define your own functions in m-files named {\bf {\em functionname}.m}. \begin{quotation} {\tt function s = squares(high) \%SQUARES Make a vector of squares. \%\hs squares(high) returns (1:high) temp = 1:high; s = temp.$\ast$temp; } \end{quotation} \noindent This (in {\bf squares.m}) may then be used as any function; \vs \com{sq = squares(5)}\\ \lab{sq = }\\ \ans{1 4 9 16 25} \vs You will note that {\bf squares.m} puts semicolons after each line; if it did not, every time it was called it would echo the result of each line of computation, which is extremely annoying. A more sophisticated version of such a function could be \begin{quotation} {\tt function [y x] = powers(high, p) \%POWERS Table of some power of n versus n. \% \hs powers(high, p) returns [1:high] to the pth (elementwise) \% \hs powers(high) returns the square if nargin < 2, p = 2; end; y = [1:high].\crt p; if nargout > 1, x = 1:high; end } \end{quotation} \vs \com{[y x] = powers(4, 3)} \\ \lab{y = }\\ \ans{1 8 27 64}\\ \lab{x =}\\ \ans{1 2 3 4}\\ \com{y = powers(4, 3)}\\ \lab{y = }\\ \ans{1 8 27 64}\\ \com{[y x] = powers(4)}\\ \lab{y =}\\ \ans{1 4 9 16}\\ \lab{x =}\\ \ans{1 2 3 4} \vs \noindent This function would be placed in the file {\bf powers.m}; a function must always be in an m-file of the same name ({\bf .m}). In this example, more than one argument can be given, but the second is optional; the special variable {\bf nargin} is consulted to see how many arguments were passed to the function, and the second is given a default value if omitted. There may also be more than one output value, and the special value {\bf nargout} is checked to see how many assignments should be carried out. Use {\bf nargchk} to confirm that {\bf nargin} is in a valid specified range. The character \% at the beginning of a line indicates a comment. The set of commented lines after the {\bf function} line is returned by {\bf help~{\em functionname}}, so it is important that they exist and document the function's behavior. The first line is what {\bf lookfor} examines, so it should be the name and a concise summary. A function need not return anything; many plotting functions do not. For these the first line is of the form {\bf function {\em functionname}({\em arguments})}. Encountering the {\bf return} command causes the function to terminate and sends control back to what invoked the function. Variables within a function exist only within the function; changing them does not affect any variables of the same name in the workspace, nor does referencing them reference variables of the same name in the workspace (or in other functions). This is not always the desired behavior. If you wish some variable to be used in more than one area, {\bf global {\em variable1 variable2...}} in each such area. Any assignment to a variable declared {\bf global} in one area affects the value of that variable in all areas in which it is declared {\bf global}. {\bf isglobal} will test if a given variable is global in an area; {\bf who}({\bf s}) {\bf global} will list the global variables. If you wish your function to be able to take a {\em function} as argument, you should take its name and apply {\bf feval('{\em functionname}', {\em arguments for function})}, which will evaluate the function of that name with those arguments. Useful operations for functions include {\bf pause}, which waits {\em argument} seconds, or for the user to strike any key given no argument ({\bf pause off} and {\bf pause on} change whether {\bf pause} should be ignored); {\bf keyboard}, which passes control to the keyboard (using a \kprompt prompt as indication) until {\bf RETURN} is entered; and {\bf error} and {\bf input} for which \see{Text}. As with scripts, {\bf echo} can be used to have the text of a function file be echoed when the function is invoked. {\bf echo {\em functionname} on} and {\bf echo {\em functionname} off} will turn echoing on and off for a single file, while {\bf echo {\em functionname}} will toggle. {\bf echo on all} and {\bf echo off all} affect echoing of all function files. \lsubsubsection{Paths} MATLAB cannot search the entire filesystem for m-files. The places MATLAB looks, and the order in which it searches them, are defined by the {\em path}. The command {\bf path} will list them from first to last as a vector of strings. On Athena, the initial path will consist of a set of directories in the matlab locker, and your {\bf \til/matlab} directory if it exists; the directory where you run MATLAB does {\em not} get put in the path, but the current directory always gets searched for m-files. Giving {\bf path} an argument of one or more strings will set the path to that list. Usually one merely wants to extend the current path and therefore does {\bf path(path, '/mit/foo')} or {\bf path('/mit/foo', path)} to retain the current path but add /mit/foo to its end or beginning, respectively. The function {\bf addpath('{\em new path}')} simplifies this operation; the function {\bf rmpath} simplifies the reverse. These are both in the {\bf contrib/names} toolbox, which is primarily for name collision testing; see {\bf help~contrib/names} or just {\bf help~names}. To see the source of a given function or m-file, {\bf which} gives the path followed to find its argument, while {\bf where} gives all paths with a file matching the argument. If you are seeking a function to do some job, but whose name you do not know, use {\bf lookfor} to search for a keyword. When MATLAB wants to know what you mean by a name, it first looks for a variable of that name, then for a built-in function, then for an m-file in the current directory, and finally for an m-file in the path. Use {\bf clash} to see what m-files will collide with a particular name. \subsection{Numerical Formats} MATLAB always keeps track of numbers to double precision regardless of the output format. To alter the display of numbers, use {\bf format}. The argument {\bf short} gives five digits (the default) and {\bf long} fifteen digits; a second argument of {\bf e} to either switches to floating-point. Further, {\bf format hex} gives hexadecimal, {\bf format +} gives signs {\em only}, {\bf format bank} uses dollars and cents, and {\bf format rat} uses ratios of small integers as approximations. Finally, {\bf format compact} and {\bf format loose} can be set independantly of all the other formatting, and supress or allow, respectively, extra linefeeds in output. \section{Further MATLAB} \subsection{Debugging} MATLAB has special functions for debugging m-file functions (but not scripts). You establish breakpoints within the m-file; when these are encountered control passes to the keyboard as with the {\bf keyboard} command, giving a {\bf \kprompt} prompt. You may then examine (or change) the variables with normal MATLAB commands. Breakpoints are established with {\bf dbstop}, in four ways. {\bf dbstop in {\em m-file}} puts a breakpoint at the first executable line. {\bf dbstop at {\em line} in {\em m-file}} puts one at the specified line number. {\bf dbstop if error} causes a stop (in any m-file function) when a runtime error occurs; execution may not be continued after a runtime error. Finally, {\bf dbstop if naninf} and {\bf dbstop if infnan} cause stops (in any m-file function) when a value is noted to be Inf (infinite) or Not-a-Number (NaN). In all of these, the keywords {\bf at}, {\bf in}, and {\bf if} are optional. The command {\bf dbtype} is similar to {\bf type}, but it gives the line number of each line of the m-file, for setting breakpoints. It also takes as an optional third argument a vector of lines to display (instead of all of them). A list of all breakpoints is available with {\bf dbstatus}. Use {\bf dbclear} to remove breakpoints; {\bf dbclear at {\em line} in {\em m-file}}; {\bf dbclear all in {\em m-file}}; {\bf dbclear in {\em m-file}} (removes a breakpoint set at the first executable line); {\bf dbclear all}; {\bf dbclear if error}; and {\bf dbclear if naninf} and {\bf dbclear if infnan} (clear the breakpoints set by the corresponding forms of {\bf dbstop}). As with {\bf dbstop}, the keywords {\bf at}, {\bf in}, and {\bf if} are optional. Having finished exercising keyboard control at a breakpoint, use {\bf dbcont} to resume execution after the breakpoint. Note that when the debugger prints out a line, that is the {\em next} line to be executed; it has not yet been executed. Instead of letting execution continue to the next breakpoint, you can use {\bf dbstep {\em number}} to execute the next $number$ lines (one if $number$ is omitted). This lets you examine the state everywhere without making every line a breakpoint. If the m-file being debugged is about to itself call an m-file function, {\bf dbstep in} steps the debugger into the latter line by line instead of executing it as a single line. To track which m-files called which, use {\bf dbstack}. To change the scope of the local workspace --- that is, to have the variables you refer to at the {\bf \kprompt} prompt be those of the m-file function or those of the function caller --- user {\bf dbdown} and {\bf dbup} respectively. The command {\bf dbquit} aborts execution of the m-file (returning nothing) and leaves debugging mode. \subsection{Efficiency Testing, Times and Dates} Most of the time spent in an algorithm is consumed by floating-point operations; integer operations are relatively instantaneous. The special function {\bf flops} tracks the number of floating-point operations performed. It begins at zero, and {\bf flops(0)} will reset it. Therefore, {\bf flops(0); {\em operation(s)}; flops} gives a reasonable measure of the effort spent in {\em operation(s)}. Alternatively, you may wish to time your operations. Use {\bf tic} to start a stopwatch and {\bf toc} to read it. So {\bf tic; {\em operation(s)}; toc} gives the number of seconds during {\em operation(s)}. However, since your computer was probably doing other things during that time, this is not a very reliable indication of the operations' efficiency; repeat it and see. A better method of measuring time consumption is given by {\bf cputime}, which is a non-resettable counter giving the CPU time used by MATLAB since it started: \\ \hs {\bf cpu = cputime; {\em operation(s)}; disp(cputime - cpu)}. If you simply wish to see the time, {\bf clock} offers a wall clock giving a [{\em year month day hour minute second}] vector, and {\bf etime} gives the time elapsed between two such vectors. A day-month-year string is returned by {\bf date}. \subsection{Polynomials} A polynomial is represented by a vector of the coefficients, constant last. E.g. $2x^3 +8 x^2 - 7x$ becomes {\bf [2~8~-7~0]}. Polynomial multiplication is performed by {\bf conv(p, q)} (which convolves the vectors). Division is available with {\bf [q, r] = deconv(denom, numer)}, which sets the quotient $q$ and remainder $r$ such that $denom = q * numer + r$. Polynomials of equal degree can be added with {\bf +}, but polynomials of unequal degree cannot be add directly; the lesser must be padded with zeros in front. {\bf polyfit(x, y, n)} finds the polynomial $p$ in $x$ of degree $n$ that best fits $y = p(x)$ in the least-squares sense. {\bf polyval(p, x)} evaluates the polynomial $p$ at the point $x$, elementwise, if $x$ is a matrix. These functions can also give error estimates; see the {\bf help} entries. {\bf polyvalm(p, m)} performs polynomial evaluation on a matrix (i.e. as a matrix, not elementwise). For some other curve-fitting capabilities see {\bf curvefit}. You can find the roots of a polynomial with {\bf roots} and its derivative with {\bf polyder}. The characteristic polynomial of a matrix $M$ (i.e. det(M - lambda)) is given by {\bf poly(M)}. See {\bf help~polyfun} for further polynomial and interpolation functions. \lsubsection{Text} Text strings are given in single quotes, e.g. {\bf 'a test string'}. A string is a row vector of characters. \vs \com{s = 'a string'};\\ \com{s(5)}\\ \lab{ans =}\\ \ans{r} \vs Normal vector manipulation carries over into strings; resultant vectors will frequently be of numbers, especially if the manipulation wouldn't make sense as a string. This is done with normal ASCII converson. Both {\bf real(vector)} and {\bf abs(vector)} force ASCII decimal representation, while {\bf setstr(vector)} forces character representation if possible. You can use {\bf isstr} to test whether a vector is a string. (And {\bf isletter} and {\bf isspace} to test individual characters.) \vs \com{s - 1}\\ \lab{ans =}\\ \ans{96 31 114 115 113 104 109 102} \\ \com{[s ' which is longer than it was']}\\ \lab{ans =}\\ \ans{a string which is longer than it was} \vs \noindent The {\bf help~strfun} entry gives a nice summary of string functions. A string (like anything else) can be displayed with {\bf disp}; this can be useful in M-files. Prompted input is available with {\bf input}. In the form {\bf input('give me an answer: ')}, it prints its string argument without a carriage return and waits for the user to respond; the response is evaluated in the workspace and the result returned. In the form {\bf input('give me an answer: ', 's')}, the response is not evaluated, but is returned as a literal string. Advanced prompted input is available with {\bf menu}, and beyond that with {\bf uimenu} and {\bf uicontrol}. To execute a string as a MATLAB expression, use {\bf eval}. Given a single string argument, it attempts to evaluate it as if it had been entered in the current workspace. The results are returned in a vector. If {\bf eval} is given a second string argument, and the execution of the first generates an error, it will attempt to evaluate the second. The function {\bf error} takes a single string argument, displays it, and exits from any m-file it occurs within (unless the argument is an empty string, in which case nothing happens). The last error message generated is recalled by {\bf lasterr}. It is reset to an empty string by {\bf lasterr('')}. It is most often used when giving {\bf eval} two arguments, as the second can examine its contents to see how the first failed. There are a number of other useful string functions. Case conversion is done by {\bf upper} and {\bf lower}. Sequences of spaces are generated by {\bf blanks} (the transpose then acts as a sequence of newlines), and trailing spaces are removed by {\bf deblank}. Comparison is done with {\bf strcmp}, searching with {\bf findstr}, search and replace with {\bf strrep}, and parsing by delimiters with {\bf strtok}. Conversions between strings and integer, real, and hex representations of numbers are available with {\bf num2str}, {\bf int2str}, {\bf str2num}, {\bf hex2num}, {\bf hex2dec}, and {\bf dec2hex}. Matrix conversations are handled by {\bf str2mat} and {\bf mat2str}. For more general conversions, see {\bf help} for {\bf sprintf} and {\bf sscanf}; for use with files see {\bf help} for {\bf fprintf} and {\bf fscanf}. \subsection{Sparse Matrices} MATLAB has two matrix storage modes. {\em Full} storage is the default and stores the value of each element; it is appropriate for matrices with many nonzero elements. {\em Sparse} storage is used only when you explicitly invoke it (though it propagates somewhat thereafter); it stores only the values of the nonzero elements (and their integer indices, of course). It is therefore appropriate for matrices with few nonzero elements, i.e. sparse matrices. The advantages of sparse matrices are size and speed. A 5000 by 5000 matrix in full storage requires space for 25 million complex numbers even if only 50,000 are nonzero. The same 50,000-nonzero element matrix, in sparse storage, would store 50,000 complex numbers and 50,000 pairs of integer indices, less than .5\% the space (less than one megabyte, instead of 200 meg). Similarly, solving $Ma=b$ where $M$ is such a matrix would take most of a day in full storage, and less than half a minute in sparse. Obviously if you are dealing with large, sparse matrices, you should take advantage of these features. Some sparsity functions are useful for other purposes, as sparsity is connected to graph and tree theory. See {\bf help~sparse} for a description of sparse storage mode, and {\bf help~sparfun} for a list of the sparse matrix functions. The {\bf MATLAB User's Guide} (\see{Help}) has (as usual) a much fuller description of the nature, uses, and manipulation of sparse matrices. \subsection{Calculus} \subsubsection{Differential Equations} For exact (symbolic) differentiations and solutions, \see{Symbolic Math}. The function {\bf ode23} is used to solve ordinary differential equations with 2nd and 3rd order Runge-Kutta formulas. The variant {\bf ode23p} also plots the results. The function {\bf ode45} uses 4th and 5th order Runge-Kutta formulas and so is slower but more accurate; it otherwise acts as {\bf ode23}. A simple demo is available with {\bf odedemo}. The basic format is {\bf [t, y] = ode23($'mysystem', t_0, t_f, y_0$)}. Here $t$ is the single independent variable and $y$ is a vector (or scalar) of the dependent variables. The scalars $t_0$ and $t_f$ specify the initial and final times; $y_0$ is a vector with the initial state of the dependent variables. The system of equations to be solved is in the m-file {\bf $mysystem$.m}. (An optional fifth argument can specify the tolerance, which defaults to $10^{-3}$; an optional boolean sixth argument specifies whether to give status displays while integrating, defaulting to 0 (False).) The results are a vector $t$ of times and a matrix $y$ in which the $n$th column gives the values of the $n$th dependent variable ($y_n$) at those positions. Thus {\bf plot(t, y)} suffices for basic display. (See {\bf ode23p} for automatic phase plane plots.) The m-file defines a function with the same name as the system of equations, with one output (a vector of derivatives) and two inputs (a scalar time, and a vector holding the variables whose derivatives are returned). It is important to realize that $y$, $\dot{y}$, and $\ddot{y}$ are independent variables as far as MATLAB is concerned until you define their relationships. This means that the $y$ vector will typically contain some intermediate derivatives of your basic dependent variables. The output vector is defined to be the derivative vector of the input vector; the process by which you specify this defines the system. As an example, consider the system of equations \begin{eqnarray} \ddot{x} + \dot{y} - 2\dot{x} &=& 3 \\ \dot{y} &=& 3x + 5 \\ \end{eqnarray} Here $x$ and $y$ are our basic dependent variables, and $t$ is our independent variable (since we used time derivatives). Since the system is second-order in $x$, we must consider $\dot{x}$ as a necessary part of the state of the system and include it in our vectors of dependent variables. Thus we want a function that takes a scalar $t$ and a vector holding (in whatever order) $x, y, \dot{x}$, and returns a vector holding {\em in the same order} $\dot{x}, \dot{y}, \ddot{x}$, i.e. the derivative of the input vector. \begin{verbatim} function der = mysystem(t, state) % MYSYSTEM to solve the system x'' + y' - 2x' = 3, y' = 3x + 5. % mysystem(t, [x(t) y(t) x'(t)]) % returns [x'(t) y'(t) x''(t)] % Suitable for use with ode23, ode45. % First assign the input values to variables with names that % make what they are easier to remember. x = state(1); y = state(2); xdot = state(3); % Now calculate the output values. % The first, the derivative of x, is trivial since we require % it as an input value. We'll put a line to do it anyway as a reminder. xdot = xdot; % We can get the second derivative of x in terms of x' and y' from % our first equation, but we need y' first. We'll use the second for that. ydot = 3*x + 5; % Now we can get the second derivative of x. xdoubledot = 3 - 2*xdot - ydot; % Construct the vector of derivatives in the same order as % the inputs. We took them as x, y, x', so we must return x', y', x''. der = [xdot, ydot, xdoubledot]; \end{verbatim} With this function in the file {\bf mysystem.m}, we can solve the system over any stretch of time with any initial values: \vs \com{t0 = 0;} \\ \com{tf = 10;} \\ \com{x0 = 0;} \\ \com{y0 = 1;} \\ \com{xdot0 = -1;} \\ \com{state0 = [x0 y0 xdot0];} \\ \com{[t state] = ode23('mysystem', t0, tf, state0);} \\ \com{x = state(:, 1); y = state(:, 2); xdot = state(:, 3);} \\ \com{figure(1); plot(t, x); title('x(t)')}\\ \com{figure(2); plot(t, y); title('y(t)')}\\ \com{figure(3); plot(t, xdot); title('xdot(t)')}\\ \com{figure(4); plot(x, y); title('phase plot')} \vs \noindent While we have considered the independent variable to be time, it is obvious no such interpretation is required. MATLAB does not have built-in functionality to solve systems with multiple independent variables. \subsubsection{Numerical Integration} For exact (symbolic) integrations and solutions, \see{Symbolic Math}. There are three functions available for numerical integration. The functions {\bf quad} and {\bf quad8} use adaptive, recursive rules, the low order Simpson's and the higher order Newton Cotes 8 panel respectively; other than the rule used, they act identically. The basic format is {\bf quad('{\em function}', {\em start}, {\em finish})} to get the integral of {\em function} from {\em start} to {\em finish}. The {\em function} must take a single vector as input (of the length of {\em start} and {\em finish}) and return a single vector of output. If the integration requires too much recursion (e.g. if the integral is singular), the value {\bf Inf} is returned. An optional fourth argument may be specified to give the tolerance (default $10^{-3}$. An optional boolean fifth argument may then be given to specify whether the evalutions should be traced in a point plot automatically (False if 0, True otherwise). An empty matrix may be passed for either of these to keep the defaults. If {\em function} takes more than one argument, the others may be specified as constant (for the integration) parameters by {\bf quad('{\em function}', {\em start}, {\em finish}, {\em tolerance}, {\em trace}, {\em first parameter}, {\em second parameter...})}. This integrates {\bf {\em function}(x, {\em first parameter}, {\em second parameter...})} over $x$ = $start$ to $finish$. Alternatively, {\bf trapz} may be used for trapezoidal numerical integration; the format is {\bf trapz(x, y)}. Here $x$ is a vector and $y$ is a matrix of any number of columns, but as many rows as the length of $x$. Each column of $y$ is considered to be a function over $x$ and is integrated with the trapezoidal approximation. The result is a vector of the column integrations. If $x$ is omitted, unit spacing between points is assumed. \subsection{Optimizing} The function {\bf fmin('{\em function}', {\em start}, {\em finish})} will attempt to return the minimum of $function$ (a scalar function of a scalar argument) in the interval [$start$, $finish$]. Of course, no numeric method can guarentee a minimum for a function that varies too rapidly. An optional fourth argument may be given; this is a vector of options (see {\bf help~foptions}). The relevant options for {\bf fmin} are the first, second, and fourteenth elements in the vector. If and only if element 1 is nonzero, the intermediate steps are displayed (default is 0). Element 2 gives the termination tolerance in the function argument (default $10^{-4}$). Element 14 gives the maximum number of steps (default 500). The other elements of the options vector are ignored. If {\em function} takes more than one argument, the others may be specified as constant parameters by {\bf fmin('{\em function}', {\em start}, {\em finish}, {\em options}, {\em first parameter}, {\em second parameter...})}. This minimizes {\bf {\em function}(x, {\em first parameter}, {\em second parameter...})} over $x \in [start, finish]$. A function of more than one variable may be similarly minimized with {\bf fmins}, which uses a simplex search. The basic form is {\bf fmins('{\em function}', $v$)}, which looks for a local minimum near the vector $v$. The function must still return a scalar. A vector of options may be passed to {\bf fmins} exactly as to {\bf fmin}, with the same meanings and defaults. Parameters may also be passed to {\bf fmins} as to {\bf fmin}, except that there is a mandatory empty matrix argument between the options vector and the first parameter. To maximize a function, minimize its negative. The function {\bf fzero('{\em function}', x)} seeks a zero of {\em function} with $x$ as a starting point. The function must take and return a scalar; there is no vector-argument form of {\bf fzero}. The value of the function at the returned point may not be exactly zero, but the function will change sign near that point. An optional third argument may be given to specify the convergence tolerance; an optional fourth boolean argument may be given to cause (if nonzero) intermediate printing. See {\bf help~optim} for the contents of the Optimization Toolbox. \lsubsection{Symbolic Math} MATLAB obtains some basic symbolic math capabilities by using the Maple kernel. If you want to do a lot of symbolic math, you probably want to use Maple directly. An expression is a text string (\see{Text}). Isolated lower case characters of the alphabet (other than the imaginary constants $i$ and $j$) are taken to be variables. Function names and operator symbols are usually interpreted correctly. For many purposes, only one variable in an expression can be used as a free variable --- for instance, when doing a single differentiation or integration. This is referred to as ``the'' symbolic variable of the expression. Use {\bf symvar} on an expression to see what variable will be taken as the free variable by default; you will usually be able to override the default when using a symbolic function. A symbolic matrix is a matrix of text characters, intepreted row by row. Each row begins with '[' and ends with ']'; the individual elements are substrings separated by commas. Rather than give exhaustive descriptions here, we will list most of the symbolic functions with short descriptions based on their {\bf help} entries, which you may see for full details: \begin{tabular}{ll} {\bf sym} & Create, access, or modify a symbolic matrix \\ {\bf symop} & Symbolic operations; general arithmetic strings \\ {\bf symadd} & Symbolic addition \\ {\bf symsub} & Symbolic subtraction \\ {\bf symmul} & Symbolic multiplication \\ {\bf symdiv} & Symbolic division \\ {\bf sympow} & Symbolic exponentation \\ {\bf inverse} & Symbolic matrix inverse \\ {\bf diff} & Symbolic differentiation \\ {\bf int} & Symbolic integration \\ {\bf factor} & Factor elements of symbolic matrix \\ {\bf simplify} & Simplify elements of symbolic matrix \\ {\bf simple} & Search for simplest form of a symbolic expression \\ {\bf expand} & Expand elements of symbolic matrix \\ {\bf collect} & Collect powers of free variables in symbolic expression \\ {\bf taylor} & Taylor series expansion in symbolic variable \\ {\bf solve} & Symbolic solution of algebraic equations \\ {\bf dsolve} & Symbolic solution of ordinary differential equations \\ \end{tabular} \noindent A special constant, {\bf Digits}, determines the numeric accuracy of symbolic computations. Use {\bf digits} to find the current accuracy and {\bf digits($d$)} to set the accuracy. The function {\bf vpa}, for ``variable precision arithmetic,'' numerically evaluates (to $Digits$ precision) a symbolic expression. A symbolic expression with a single free variable can be plotted with {\bf ezplot($function$)}. \subsection{SIMULINK} SIMULINK is a special interactive toolbox for simulating dynamic systems in block diagrams with a graphical (mouse-driven) interface. It can handle nonlinear systems of many variables and rates, in discrete or continuous time. The results can be further analyzed in the MATLAB workspace. SIMULINK is available on DECstations, IBM RS/6000s, and Suns. It cannot be accessed from within a regular MATLAB session, but must be started by itself. \vs \noindent \hs athena\% \ add matlab \\ \hs athena\% \ simulink \& \vs \noindent This will generate a MATLAB window named SIMULINK. All MATLAB functionality is present as are SIMULINK functions, for which full {\bf help} information should be available. Use {\bf simdemo} for demonstrations. Copies of the {\bf SIMULINK User's Guide} are available for reference in the Athena Consulting Office (11-115), and in Barker and Hayden Libraries. \prettynewpage \subsection{Other Features} Type {\bf help} by itself to list categories of MATLAB functions. Among those that we have not gone into in detail are \begin{tabular}{ll} matlab/datafun & Data analysis and Fourier transform functions.\\ matlab/sounds & Sound processing functions.\\ matlab/iofun & Low-level file I/O functions.\\ toolbox/uitools & User Interface Utilities.\\ toolbox/control & Control System Toolbox.\\ toolbox/ident & System Identification Toolbox.\\ toolbox/local & Local function library.\\ mutools/commands & Mu-Analysis and Synthesis Toolbox.: Commands directory\\ mutools/subs & Mu-Analysis and Synthesis Toolbox -- Supplement\\ toolbox/optim & Optimization Toolbox.\\ toolbox/robust & Robust Control Toolbox.\\ toolbox/signal & Signal Processing Toolbox.\\ toolbox/splines & Spline Toolbox.\\ toolbox/stats & Statistics Toolbox.\\ toolbox/images & Image Processing Toolbox.\\ toolbox/symbolic & Symbolic Math Toolbox.\\ nnet/nnet & Neural Network Toolbox.\\ nnet/nndemos & Neural Network Demonstrations and Applications.\\ toolbox/pde & Partial Differential Equation Toolbox.\\ \end{tabular} \end{document}