2.8. MATLAB Functions

Reading Assignment

Please read chapter 5 of Physical Modeling in MATLAB, by Allen B. Downey [DOWNEY11].

MATLAB Scripts are nice because they let us edit our code until we get it right and save the code in files for future use. But we really need something more. We have used many functions that are part of MATLAB’s library of functions, now we need to write our own functions.

  • Functions have a private workspace, so there is less concern of name conflicts.
  • A function is a neat and tidy way to invoke code that is called multiple times. Functions allows common code to be called with different parameters or data, which is easier than replicating code.
  • Knowing when to divide a program into separate functions versus keeping the code together is somewhat an art form which is best perfected by practice. Two questions will help with the design decisions.
    1. Does the code need to be executed more than once, especially with different values?
    2. Does the code provide a specific task? If so, putting it in a function may help to draw attention to the task and thus improve the clarity of the program.
  • Functions may be placed either inside a script file or in their own file. Functions inside a script are good for functions that would only be used in that script. Place a function in its own file to make it generally available for other scripts and functions that you might develop.

2.8.1. Syntax of a Function

In MATLAB, the returned value(s) from a function are specified by their local variable name on the function definition line. The returned values are the values of those variables at the end of the function. If there is more than one return value, they are listed like a vector.

The word function is a keyword.

Function with one return values and two input arguments
function outPut = my1stFunction(input1, input2)
% MY1STFUNCTION - Help documentation

    code

end
Function with two return values and two input arguments
function [outPut1, outPut2] = my2ndFunction(input1, input2)
% MY2NDFUNCTION - Help documentation

    code

end

Note

Create help text by inserting comments at the beginning of your program. If your program includes a function, position the help text immediately below the function definition line (the line with the function keyword). https://www.mathworks.com/help/matlab/matlab_prog/add-help-for-your-program.html

Warning

Public functions in their own file have two important constraints.

  1. Only one function per file.
  2. The name of the file must match the name of the file.

2.8.2. Calling a Function

[out1, out2] = my2ndFunction(in1, in2);

The values of the input arguments and outputs are copied between where the function is called from and the function. Thus, the variable names between the two are completely independent. They may be the same name with no name space conflict, or they may be completely different names. It does not matter.

The only important thing about the values and variables is the order in the list of arguments and return values.

Self Quiz

(Select all that apply) Which of the following are valid ways to call a function called myFunction that takes three inputs and returns two outputs?

  • [out1,out2] = myFunction(in1,in2,in3)
  • out1 = myFunction(in1,in2,in3)
  • myFunction(in1,in2,in3)

Answer All of the syntaxes shown are valid. The function call returns only outputs that are requested. If no outputs are requested, the function still runs and the first output is saved to ans.

2.8.3. Example Function

A short example function follows. Notice how the return value is set as the last value of the return variable at the end of the function. The function calculates the sum of a sequence of numbers according to the equation that Johann Carl Friedrich Gauss reportedly discovered when he was a young boy. His teacher wanted to keep the students busy with a tedious assignment so the students were instructed to find the sum of the digits from 1 to 100. Gauss surprised the teacher by finding the answer very quickly. He recognized that pairs of numbers had the same sum. The sum of 1 and 100 is the same as 2 and 99, as for 3 and 98, etc. In the sequence from 1 to 100, there are 50 such pairs. In this example, we generalize the equation to work with any sequence with consistent spacing between the numbers.

function ssum = sequenceSum(sequence)
% SEQUENCESUM - The sum of a sequence of numbers. The
%               spacing between numbers in the sequence
%               must be consistent.
    start = sequence(1);
    stop = sequence(end);
    n = length(sequence);
    if mod(n, 2) == 0    % n is even
        ssum = n*(start + stop)/2;
    else                 % n is odd
        ssum = (n-1)*(start + stop)/2 + sequence(ceil(n/2));
    end
end

We can test the function including the help information from the Command Window. We can use the sum function to verify the results.

>> help sequenceSum
sequenceSum - The sum of a sequence of numbers. The
              spacing between numbers in the sequence
              must be consistent.

>> sequenceSum(1:100)
ans =
        5050
>> sum(1:100)
ans =
        5050
>> sequenceSum(50:3:100)
ans =
        1258
>> sum(50:3:100)
ans =
        1258
Quick Practice

The MATLAB function isequal compares two arrays and returns true if they are identical and false otherwise. In some situations, two numbers which are slightly different could be treated as ‘close enough’ for the purposes of a particular application. For example, a variable x with value 2.1 and another variable y with value 2.100000009 differ by a small value on the order of 10^{-9}.

Write a function which takes three scalar inputs, x, y, and a tolerance tol. It should return true if x and y differ by a number less than tol and false otherwise. Add the function to the bottom of a script that tests the function.

2.8.4. Function Handles

MATLAB has a shortcut way of expressing simple functions that can be expressed with one single statement. In the following example, f is the name of the function handle. The argument(s) passed to the function are inside the parenthesis after the at symbol, @.

%% An example of a function handle

f = @(x) exp(-x) .* sin(x);

t = linspace(0, 3*pi);
plot(t, f(t));

Another import application of function handles is to pass a function to another function.

Function Handles and Anonymous Functions

These two terms are often confused and interchanged, which as a practical matter is not really a problem. An anonymous function is the definition of the function that is not given a name. It can be either part of a function handle or an argument to a function, such as fplot(@(x) x.^2, [0 5]). The fplot function makes a plot of a function over the specified range of the x-axis. An anonymous function becomes a function handle when it is assigned to a variable name, as in f = @(x) x.^2.

See also

MATLAB Function Handle Documentation.

Note

Now work on Practice with Vectors and Functions, which we will work on together in class. Then work on Element-wise Arithmetic, which is a larger programming assignment.