MATLAB Tutorial Chapter 6. Writing and calling functions In this chapter we discuss how to structure a program with multiple source code files. First, an explanation of how code files work in MATLAB is presented. In compiled languages such as FORTRAN, C, or C++, code can be stored in one or more source files that are linked together to form a single executable at the time of compilation. MATLAB, being an interpreted language, deals with multiple source files in a more open-ended manner. MATLAB code is organized into ASCII files carrying the extension .m (also known as m-files). MATLAB 6 has an integrated word processing and debugging utility that is the preferred mode of editing m-files, although other ASCII editors such as vi or emacs may also be used. There are two different kinds of m-files. The simplest, a script file, is merely a collection of MATLAB commands. When the script file is executed by typing its name at the interactive prompt, MATLAB reads and executes the commands within the m-file just as if one were entering them manually. It is as if one were cutting and pasting the m-file contents into the MATLAB command window. The use of this type of m-file is outlined in section 6.1. The second kind of m-file, discussed in section 6.2, contains a single function that has the same name as that of the m-file. This m-file contains an independent section of code with a clearly defined input/output interface; that is, it can be invoked by passing to it a list of dummy arguments arg1, arg2, ... and it returns as output the values out1, out2, .... The first non-commented line of a function m-file contains the function header, which is of the form : function [out1,out2,...] = filename(arg1,arg2,...); The m-file ends with the command return, which returns the program execution to the place where the function was called. The function code is executed whenever, either at the interactive command prompt or within another m-file, it is invoked with the command : [outvar1,outvar2,...] = filename(var1,var2,...) with the mapping of input to dummy arguments : arg1 = var1, arg2 = var2, etc. Within the function body, output values are assigned to the variables out1, out2, etc. When return is encountered, the current values of out1, out2, ... are mapped to the variables outvar1, outvar2, ... at the point where the function was called. MATLAB allows much latitude in writing functions with variable length argument and output variable lists. For example, the function could also be invoked by the command : outvar1 = filename(var1,var2,...) in which case only a single output variable is returned, containing on exit the value of the function variable out1. The input and output arguments may be strings, scalar numbers, vectors, matrices, or more advanced data structures. Why use functions? As is well known from every computer science course, splitting a large program into multiple procedures that perform each a single well defined and commented task, results in programs that are easier to read, easier to modify, and that are more resistant to error. In MATLAB, one writes first a master file for the program, either a script file or better yet a function m-file that returns a single integer (that might return 1 for program success, 0 for incomplete program execution, or a negative value to indicate a run-time error), that is the point of entry to the program. This program file then calls upon code in other m-files by invoking them as functions. But if there is no compilation process to link all of the source code files together, how does MATLAB know where to look for a function when it is called? MATLAB's program memory contains a search path list, the contents of which can be viewed with the command path, that stores the names of the directories it has been told contain function m-files. Initially, the path lists only the directories that hold the built-in MATLAB functions such as sin(), exp(), etc.. As demonstrated in section 6.2, one uses the command addpath to add to this list the name of each directory that contains a m-file for the present project. Then, when the MATLAB code interpreter encounters a function, say with the name filename, it starts at the top of the path list and works its way down searching in each directory for a file filename.m. When it finds it, it executes the file's code in the mannerdescribed above. For this reason, it is imperative that the names of the m-file and of the function agree; in fact it is only the filename that counts. 6.1. Writing and running m-files While MATLAB can be run interactively from the command line, you can write a MATLAB program by composing a text file that contains the commands you want MATLAB to perform in the order in which they appear in the file. The standard file suffix for a text file containing a MATLAB program is .m. In the MATLAB command window, selecting the pull-down menu File -> New -> M-file opens the integrated MATLAB text editor for writing a m-file. This utility is very similar to word processors, so the use of writing and saving m-files is not explained in detail here. As an example, use this secion as a file "MATLAB_tutorial_c6s1.m" that has only the following executable commands. file_name = 'MATLAB_tutorial_c6s1.m'; disp(['Starting ' file_name ]); j = 5; for i=1:5 j = j - 1; disp([int2str(i) ' ' int2str(j)]); end disp(['Finished ' file_name]); We can run this m-file from the prompt by typing its name >> MATLAB_tutorial_c6s1 If we type "whos" now, we see that the variables that are in the memory at the end of the program also remain in memory after the m-file is done running. This is because we have written the m-file as a script file where we have simply collected together several commands in a file, and then the code executes them one-by-one when the script is run, as if we were merely typing them into the interactive session window. A more common use for m-files is to isolate a series of commands in an independent function, as explained in the following section. 6.2. Structured programming with functions Unstructured programming approach File unstructured.m In this section, let us demonstrate the use of subroutines to write structured, well-organized programs. We do so for a particularly simple and familiar case, the simple 1-D PDE problem that we encounted in section 4.1. First, in this m-file, we solve the problem with a program the combines all of the commands into a single file. This "unstructured" approach is