Mathematics

Output Functions

An output function is a function that an optimization function calls at each iteration of its algorithm. Typically, you might use an output function to generate graphical output, record the history of the data the algorithm generates, or halt the algorithm based on the data at the current iteration. You can create an output function as an M-file function, a subfunction, or a nested function.

You can use the OutputFcn option with the following MATLAB optimization functions:

• fminbnd
• fminsearch
• fzero

This section covers the following topics:

• Creating and Using an Output Function
• Structure of the Output Function
• Example of a Nested Output Function
• Fields in optimValues
• States of the Algorithm
• Stop Flag

Creating and Using an Output Function

The following is a simple example of an output function that plots the points generated by an optimization function.

• function stop = outfun(x, optimValues, state)
  stop = false;
  hold on;
  plot(x(1),x(2),'.');
  drawnow
  

You can use this output function to plot the points generated by fminsearch in solving the optimization problem

To do so,

1. Create an M-file containing the preceding code and save it as outfun.m in a directory on the MATLAB path.
2. Enter the command

• options = optimset('OutputFcn', @outfun);
  

1. to set the value of the Outputfcn field of the options structure to a function handle to outfun.

3. Enter the following commands:

• hold on
  objfun=@(x) exp(x(1))*(4*x(1)^2+2*x(2)^2+x(1)*x(2)+2*x(2));
  [x fval] = fminsearch(objfun, [-1 1], options)
  hold off
  

This returns the solution

• x =
  
      0.1290   -0.5323
  
  
  fval =
  
     -0.5689
  

and displays the following plot of the points generated by fminsearch:

Structure of the Output Function

The function definition line of the output function has the following form:

• stop = outfun(x, optimValues, state)
  

where

• stop is a flag that is true or false depending on whether the optimization routine should quit or continue. See Stop Flag.
• x is the point computed by the algorithm at the current iteration.
• optimValues is a structure containing data from the current iteration. Fields in optimValues describes the structure in detail.
• state is the current state of the algorithm. States of the Algorithm lists the possible values.

The optimization function passes the values of the input arguments to outfun at each iteration.

Example of a Nested Output Function

The example in Creating and Using an Output Function does not require the output function to preserve data from one iteration to the next. When this is the case, you can write the output function as an M-file and call the optimization function directly from the command line. However, if you want your output function to record data from one iteration to the next, you should write a single M-file that does the following:

• Contains the output function as a nested function -- see Nested Functions in the online MATLAB documentation for more information.
• Calls the optimization function.

In the following example, the M-file also contains the objective function as a subfunction, although you could also write the objective function as a separate M-file or as an anonymous function.

Since the nested function has access to variables in the M-file function that contains it, this method enables the output function to preserve variables from one iteration to the next.

The following example uses an output function to record the points generated by fminsearch in solving the optimization problem

and returns the sequence of points as a matrix called history.

To run the example, do the following steps:

1. Open a new M-file in the MATLAB editor.
2. Copy and paste the following code into the M-file.

• function [x fval history] = myproblem(x0)
      history = [];
      options = optimset('OutputFcn', @myoutput);
      [x fval] = fminsearch(@objfun, x0,options);
          
      function stop = myoutput(x,optimvalues,state);
          stop = false;
          if state == 'iter'
            history = [history; x];
          end
      end
      
      function z = objfun(x)
        z = exp(x(1))*(4*x(1)^2+2*x(2)^2+x(1)*x(2)+2*x(2));
      end
  end
  

3. Save the file as myproblem.m in a directory on the MATLAB path.
4. At the MATLAB prompt, enter

• [x fval history] = myproblem([-1 1])
  

The function fminsearch returns x, the optimal point, and fval, the value of the objective function at x.

• x =
  
      0.1290   -0.5323
  
  
  fval =
  
     -0.5689
  

In addition, the output function myoutput returns the matrix history, which contains the points generated by the algorithm at each iteration, to the MATLAB workspace. The first four rows of history are

• history(1:4,:)
  
  ans =
  
     -1.0000    1.0000
     -1.0000    1.0500
     -1.0750    0.9000
     -1.0125    0.8500
  

The final row of points is the same as the optimal point, x.

• history(end,:)
  
  ans =
  
      0.1290   -0.5323
  
  objfun(history(end,:))
  
  ans =
  
     -0.5689
  

Fields in optimValues

The following table lists the fields of the optimValues structure that are provided by all three optimization functions, fminbnd, fminsearch, and fzero. The function fzero also provides additional fields that are described in its reference page.

The "Command-Line Display Headings" column of the table lists the headings, corresponding to the optimValues fields that are displayed at the command line when you set the Display parameter of options to 'iter'.

optimValues Field (optimValues.field)	Description	Command-Line Display Heading
funcount	Cumulative number of function evaluations.	Func-count
fval	Function value at current point.	min f(x)
iteration	Iteration number -- starts at 0.	Iteration
procedure	Procedure messages	Procedure

States of the Algorithm

The following table lists the possible values for state:

State	Description
'init'	The algorithm is in the initial state before the first iteration.
'interrupt'	The algorithm is performing an iteration. In this state, the output function can interrupt the current iteration of the optimization. You might want the output function to do this to improve the efficiency of the computations. When state is set to 'interrupt', the values of x and optimValues are the same as at the last call to the output function, in which state is set to 'iter'.
'iter'	The algorithm is at the end of an iteration.
'done'	The algorithm is in the final state after the last iteration.

The following code illustrates how the output function might use the value of state to decide which tasks to perform at the current iteration.

• switch state
      case 'init'
            % Setup for plots or guis
      case 'iter'
            % Make updates to plot or guis as needed.
      case 'interrupt'
            % Check conditions to see whether optimization 
            % should quit.
          case 'done'
            % Cleanup of plots, guis, or final plot
  otherwise
  end
  

Stop Flag

The output argument stop is a flag that is true or false. The flag tells the optimization function whether the optimization should quit or continue. The following examples show typical ways to use the stop flag.

Stopping an Optimization Based on Data in optimValues.   The output function can stop an optimization at any iteration based on the current data in optimValues. For example, the following code sets stop to true if the objective function value is less than 5:

• function stop = myoutput(x, optimValues, state)
  stop = false;
  % Check if objective function is less than 5.
  if optimValues.fval < 5
      stop = true;
  end 
  

Stopping an Optimization Based on GUI Input.   If you design a GUI to perform optimizations, you can make the output function stop an optimization when a user clicks a Stop button on the GUI. The following code shows how to do this, assuming that the Stop button callback stores the value true in the optimstop field of a handles structure called hObject stored in appdata.

• function stop = myoutput(x, optimValues, state)
  stop = false;
  % Check if user has requested to stop the optimization.
  stop = getappdata(hObject,'optimstop');
  

Setting Minimization Options

Finding Zeros of Functions

© 1994-2005 The MathWorks, Inc.