1. Advanced Topics- Functions Introduction to MATLAB 7 Engineering 161

2. Functions Functions were introduced in Chapter 6 of our text. Remember that functions can be thought of as a black box that excepts some inputs, makes some calculations and returns results. MATLAB contains hundreds of built in functions, there are auxiliary toolboxes with specialized functions, and you the user have the ability to write your own functions and use them over and over again. In the next set of slides we review and discuss in more detail the rules governing functions and how to set up your own toolboxes.

3. Functions: Construction Rules The function M-file name and the function name that appears in the first line of the function must be identical. Function M-file names can have up to 63 characters but they must adhere to the rules governing MATLAB variable names. Function M-file names are case sensitive. Function names must begin with a letter, then any combination or letters, numbers or the underscore character. They must not contain spaces.

4. Functions: Construction Rules II The first line of a function M-file is called the function declaration line and must contain the word function followed by the calling syntax for that function. The input and output variables identified in the first line are variables local to the function. The input variables contain data passed to the function, the output variables, data passed back to the main program. A set of contiguous comment lines after the function declaration are the help text for the function.

5. Functions: Construction Rules III Comments lines should describe possible calling sequences, the function’s purpose, algorithms used, and some simple examples as appropriate. Function names appearing in the help text of a function are normally capitalized to give them some visual distinction. All statements following the first set of contiguous comment lines compose the body of the function. These statements operate on the input variables to produce output results.

6. Functions: Construction Rules IV A function M-file terminates after the last line in the file is executed or when a return statement is encountered. A function can abort operation and return control back to the Command Window by calling the error function, for example, if length (v) > 1; error (‘v must be a scalar’) end aborts the function when v is not a scalar.

7. Functions: Construction Rules V A function can report a warning and continue execution by calling the warning function. The syntax is the same as for the error function. Function M-files can contain calls to other script M- files. Multiple functions can appear in a single function M- file, but the sub-functions can not be called from outside the M-file. It is suggested that sub-functions in an M-file be given a name beginning with the word local like local_myfun to improve readability.

8. Functions: Input and Output MATLAB functions can have any number of input and output arguments. Function M-files can have zero input and zero output arguments. Function M-files may have one or more input arguments and one or more output arguments. The built in function nargin and nargout can be used to determine the number of input and output arguments a function has.

9. Functions: Input and Output II MATLAB provides the ability to pass a variable number of input and output arguments to-from a function by using the varargin and varargout functions. This is more advanced so for our purposes we’ll define our input and output arguments. In general a function declaration line will have the form, function [a, b, c] = function_name(w, x, y, z) where a,b and c are the output arguments, and w,x,y and z are the input arguments. They may be scalars, vectors, or matrices.

10. Function Workspaces Since functions are black boxes all the variables created in a function including the input and output arguments are local to the function and are not known to the outside calling program. Moreover each function when it executes has its own temporary workspace that is created when the function is called and cleared when the function completes. It is possible to share variables between functions and other functions by declaring the variable to be a global variable within each workspace where the variable will be referenced. This is discouraged, but it is possible to do it if needed. It is recommended to pass variables via the input and output arguments for consistency as we have discussed.

11. Creating your own toolbox It is common to organize a group of related function M-files into a subdirectory of your MyMatlabfiles folder that is on the MATLAB search path. When you have completed the functions you can create a toolbox subdirectory and include two additional script M-files in the folder, namely the Contents.m and the Readme.m script M-files, both containing only comments. Mytoolbox should be used as the name of the directory containing the group of M-file.

12. Creating your own toolbox The script file Readme.m contains comment lines that describe the features of the toolbox, any late breaking news items, undocumented features, etc. The script file Contents.m contains comment lines that list all the M-files in the toolbox. Additionally, the first two lines should be %Toolbox Description %Version xxx dd-mmm-yyyy %List all M-files in the toolbox by name.

13. Functions: An Example Let’s put this all together with an example. Suppose we want to create a function called lengthv that computes the length of a row vector. Remember the length of a vector is determined by computing the sqrt of the sum of the squares of the elements. | x | = sqrt ( x 1 2 + x 2 2 +... x n 2 ) Remember length is the name of a built in function, so we will call our function lengthv. Our function has one input argument and one output argument.

14. Functions: An Example II We will use the built in length function to determine if the input variable is indeed a vector with length greater than 1. If it isn’t, our function will stop and return with an error message. Name of function will be lengthv Input argument is x Output argument is len Error message, ‘Error: Input is not a vector.’

15. Functions: An Example III Consider, function len = lengthv(x) if length(x) > 1; len = sqrt(sum(x.^2)); else error(‘Error: Input is not a vector.’) end

16. Functions: An Example V Here when the function is called, the input argument is tested to see if it is indeed a vector. length(x) > 1 indicates that x is a vector and its length can be computed. When length(x) = 1, then x is a scalar and the function returns an error message. To use this function in any main program, simply call the function as you do with any built in function, e.g., >>a = [1 2 -1 -3 1]; >>result = lengthv(a) result = 4

17. Functions: An Example VI Consider, >>b = 3; >>result = lengthv(b) Error: Input is not a vector. Here, the input to the function lengthv when it is called is a scalar, the function returns the error message. Control returns to the Command Window and the program stops. Remember, when you save your function you must use the file name lengthv.

18. Functions: Final Thoughts When should one consider using a user defined function? When you find yourself repeating a set of statements several times in a larger program. Define and replace the set of statements as a user defined function and make your program shorter and more readable. When you are writing a number of programs in some field of study, consider developing a set of functions to facilitate your study. Breaking larger programs into a set of smaller ones utilizing functions may make the process of debugging easier.